Echo

Echo is a fast and unfancy web framework for Go (Golang). Up to 10x faster than the rest.

This package need >= go 1.25

Features

Optimized HTTP router which smartly prioritize routes.
Build robust and scalable RESTful APIs.
Run with standard HTTP server or FastHTTP server.
Group APIs.
Extensible middleware framework.
Define middleware at root, group or route level.
Handy functions to send variety of HTTP responses.
Centralized HTTP error handling.
Template rendering with multiple engine support (standard, Jet, SSE, etc).
Define your format for the logger.
Highly customizable.
Business error code system.
Form data filtering and binding.
Transaction support.
Reverse proxy with load balancing (random, round-robin).
URL rewriting with reverse/unrewrite support.
Rate limiting (with memory and Redis backends).
Request queue for concurrency control.
IP filtering.
Distributed tracing (OpenTracing).
Server-Sent Events (SSE).

Quick Start

Installation

$ go get github.com/webx-top/echo

Hello, World!

Create server.go

package main

import (
	"net/http"
	"github.com/webx-top/echo"
	"github.com/webx-top/echo/engine/standard"
)

func main() {
	e := echo.New()
	e.Get("/", func(c echo.Context) error {
		return c.String("Hello, World!", http.StatusOK)
	})
	e.Run(standard.New(":1323"))
}

Start server

$ go run server.go

Browse to http://localhost:1323 and you should see Hello, World! on the page.

Routing

e.Post("/users", saveUser)
e.Get("/users/:id", getUser)
e.Put("/users/:id", updateUser)
e.Delete("/users/:id", deleteUser)
e.Get("/user/<id:[\\d]+>", getUser)

Support two parameter syntaxes: :param and <param:regexp>.

Path Parameters

func getUser(c echo.Context) error {
	// User ID from path `users/:id`
	id := c.Param("id")
	// or id := c.Paramx("id").Uint64()
}

Query Parameters

/show?team=x-men&member=wolverine

func show(c echo.Context) error {
	// Get team and member from the query string
	team := c.Query("team")
	member := c.Query("member")
	age := c.Queryx("age").Uint()
}

Form `application/x-www-form-urlencoded`

POST /save

name	value
name	Joe Smith
email	joe@labstack.com

func save(c echo.Context) error {
	// Get name and email
	name := c.Form("name")
	email := c.Form("email")
	age := c.Formx("age").Uint()
}

Form `multipart/form-data`

POST /save

name	value
name	Joe Smith
email	joe@labstack.com
avatar	avatar

func save(c echo.Context) error {
	// Get name and email
	name := c.Form("name")
	email := c.Form("email")

	//------------
	// Get avatar
	//------------
	_, err := c.SaveUploadedFile("avatar","./")
	return err
}

Handling Request

Bind JSON or XML payload into Go struct based on Content-Type request header.
Render response as JSON or XML with status code.

type User struct {
	Name  string `json:"name" xml:"name"`
	Email string `json:"email" xml:"email"`
}

e.Post("/users", func(c echo.Context) error {
	u := new(User)
	if err := c.MustBind(u); err != nil {
		return err
	}
	return c.JSON(u, http.StatusCreated)
	// or
	// return c.XML(u, http.StatusCreated)
})

Form Data Filter (FormFilter)

Filter and transform form data before binding.

import "github.com/webx-top/echo/formfilter"

ff := formfilter.New()
ff.Add(
    formfilter.StringToSlice("ids", ","),
    formfilter.DateRange("created", "2006-01-02"),
)

// Pass filter to Bind/MustBind directly
u := new(User)
c.MustBind(u, ff.Build())

Static Content

Serve any file from static directory for path /static/*.

e.Use(mw.Static(&mw.StaticOptions{
	Root:"static", // static file root directory
	Path:"/static/", // URL path for static files
	Browse:true, // show file list
}))

Embedded File Handler

Serve embedded files with index.html support via embed.FileSystems.

import "github.com/webx-top/echo/handler/embed"

//go:embed www/*
var wwwFS embed.FS

fs := embed.NewFileSystems()
fs.Register(wwwFS)
e.Get("/*", embed.File(fs))

Embedded Static Content (Bindata)

Serve go-bindata generated embedded static files as middleware.

import (
	"github.com/admpub/go-bindata-assetfs"
	"github.com/webx-top/echo/middleware/bindata"
)

//go:generate go-bindata -o=bindata_assetfs.go -pkg=main static/...
//go:generate go-bindata-assetfs -o=bindata_assetfs.go -pkg=main static/...

func NewAssetFS() *assetfs.AssetFS {
	return &assetfs.AssetFS{
		Asset:     Asset,     // generated by go-bindata
		AssetDir:  AssetDir,  // generated by go-bindata
		AssetInfo: AssetInfo, // generated by go-bindata
		Prefix:    "",
	}
}

e.Use(bindata.Static("/static/", NewAssetFS()))

Captcha

Image and audio captcha support.

import "github.com/webx-top/echo/handler/captcha"

captcha.DefaultOptions.Wrapper(e)
// Browse to /captcha/<id>.png

Middleware

// Root level middleware
e.Use(middleware.Log())
e.Use(middleware.Recover())

// Group level middleware
g := e.Group("/admin")
g.Use(middleware.BasicAuth(func(username, password string) bool {
	if username == "joe" && password == "secret" {
		return true
	}
	return false
}))

// Route level middleware
track := func(next echo.HandlerFunc) echo.HandlerFunc {
	return func(c echo.Context) error {
		println("request to /users")
		return next.Handle(c)
	}
}
e.Get("/users", func(c echo.Context) error {
	return c.String("/users", http.StatusOK)
}, track)

Cookie

e.Get("/setcookie", func(c echo.Context) error {
	c.SetCookie("uid","1")
	return c.String("/setcookie: uid="+c.GetCookie("uid"), http.StatusOK)
})

Session

Session engine supports cookie-based and file-based storage.

...
import (
	...
	"github.com/webx-top/echo/middleware/session"
	cookieStore "github.com/webx-top/echo/middleware/session/engine/cookie"
)
...
sessionOptions := &echo.SessionOptions{
	Engine: `cookie`,
	Name:   `SESSIONID`,
	CookieOptions: &echo.CookieOptions{
		Path:     `/`,
		Domain:   ``,
		MaxAge:   0,
		Secure:   false,
		HttpOnly: true,
	},
}

cookieStore.RegWithOptions(&cookieStore.CookieOptions{
	KeyPairs: [][]byte{
		[]byte(`123456789012345678901234567890ab`),
	},
})

e.Use(session.Middleware(sessionOptions))

e.Get("/session", func(c echo.Context) error {
	c.Session().Set("uid",1).Save()
	return c.String(fmt.Sprintf("/session: uid=%v",c.Session().Get("uid")))
})

Transaction

Supports database transaction through context.

// Transaction interface
type Transaction interface {
	Begin(ctx context.Context) error
	Rollback(ctx context.Context) error
	Commit(ctx context.Context) error
	End(ctx context.Context, succeed bool) error
}

// Use in handler
c.Begin()
// ... operations
c.Commit()

Websocket

...
import (
	...
	"github.com/admpub/websocket"
	"github.com/webx-top/echo"
	ws "github.com/webx-top/echo/handler/websocket"
)
...

e.AddHandlerWrapper(ws.HanderWrapper)

e.Get("/websocket", func(c *websocket.Conn, ctx echo.Context) error {
	//push(writer)
	go func() {
		var counter int
		for {
			if counter >= 10 {
				return
			}
			time.Sleep(5 * time.Second)
			message := time.Now().String()
			ctx.Logger().Info(`Push message: `, message)
			if err := c.WriteMessage(websocket.TextMessage, []byte(message)); err != nil {
				ctx.Logger().Error(`Push error: `, err.Error())
				return
			}
			counter++
		}
	}()

	//echo
	ws.DefaultExecuter(c, ctx)
	return nil
})

More...

Sockjs

...
import (
	...
	"github.com/webx-top/echo"
	"github.com/admpub/sockjs-go/v3/sockjs"
	ws "github.com/webx-top/echo/handler/sockjs"
)
...

options := ws.Options{
	Handle: func(c sockjs.Session) error {
		//push(writer)
		go func() {
			var counter int
			for {
				if counter >= 10 {
					return
				}
				time.Sleep(5 * time.Second)
				message := time.Now().String()
				log.Info(`Push message: `, message)
				if err := c.Send(message); err != nil {
					log.Error(`Push error: `, err.Error())
					return
				}
				counter++
			}
		}()

		//echo
		ws.DefaultExecuter(c)
		return nil
	},
	Options: &sockjs.DefaultOptions,
	Prefix:  "/websocket",
}
options.Wrapper(e)

More...

Server-Sent Events (SSE)

import (
	_ "github.com/webx-top/echo/middleware/render/sse"
	"github.com/webx-top/echo/middleware/render"
)

e.Use(render.Middleware(render.New(`sse`, ``)))

e.Get("/events", func(c echo.Context) error {
	return c.SSEvent("message", listener)
})

Reverse Proxy

Built-in reverse proxy with load balancing support (Random, Round-Robin).

import "github.com/webx-top/echo/middleware"

// Round-Robin balancer
targets := []middleware.ProxyTargeter{
	&middleware.ProxyTarget{
		Name: "api-1",
		URL:  mustParseURL("http://localhost:8081"),
	},
	&middleware.ProxyTarget{
		Name: "api-2",
		URL:  mustParseURL("http://localhost:8082"),
	},
}
balancer := middleware.NewRoundRobinBalancer(targets)
e.Use(middleware.Proxy(balancer))

URL Rewrite

e.Use(middleware.Rewrite(map[string]string{
	"/old":              "/new",
	"/api/*":            "/$1",
	"/users/:id":        "/user/$1",
	"/users/*/orders/*": "/user/$1/order/$2",
}))

Request Queue

Limit concurrent request processing with queue timeout.

config := middleware.QueueConfig{
	QueueSize:     100,
	Workers:       10,
	QueueTimeout:  30 * time.Second,
	WorkerTimeout: 10 * time.Second,
}
e.Use(middleware.QueueWithConfig(config))

Request ID

e.Use(middleware.RequestID())
// Each response gets X-Request-ID header

IP Filter

import "github.com/webx-top/echo/middleware/ipfilter"

e.Use(ipfilter.IPFilter(ipfilter.Config{
	Options: ipfilter.Options{
		AllowedIPs: []string{"192.168.0.0/24"},
		BlockedIPs: []string{"0.0.0.0/0"},
	},
}))

OpenTracing

import "github.com/webx-top/echo/middleware/opentracing"

e.Use(opentracing.Trace(tracer))

Other Example

package main

import (
	"net/http"

	"github.com/webx-top/echo"
	// "github.com/webx-top/echo/engine/fasthttp"
	"github.com/webx-top/echo/engine/standard"
	mw "github.com/webx-top/echo/middleware"
)

func main() {
	e := echo.New()
	e.Use(mw.Log())

	e.Get("/", func(c echo.Context) error {
		return c.String("Hello, World!")
	})
	e.Get("/echo/:name", func(c echo.Context) error {
		return c.String("Echo " + c.Param("name"))
	})
	
	e.Get("/std", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte(`standard net/http handleFunc`))
		w.WriteHeader(200)
	})

	// FastHTTP
	// e.Run(fasthttp.New(":4444"))

	// Standard
	e.Run(standard.New(":4444"))
}

See other examples...

Middleware list

Root middleware (github.com/webx-top/echo/middleware)

Middleware	Import path	Description
BasicAuth	github.com/webx-top/echo/middleware	HTTP basic authentication
KeyAuth	github.com/webx-top/echo/middleware	API key authentication (header/query/form)
BodyLimit	github.com/webx-top/echo/middleware	Limit request body size
Gzip	github.com/webx-top/echo/middleware	Send gzip HTTP response
Secure	github.com/webx-top/echo/middleware	Protection against XSS, clickjacking, etc
CORS	github.com/webx-top/echo/middleware	Cross-Origin Resource Sharing
CSRF	github.com/webx-top/echo/middleware	Cross-Site Request Forgery
Log	github.com/webx-top/echo/middleware	Log HTTP requests
MethodOverride	github.com/webx-top/echo/middleware	Override request method via header
Recover	github.com/webx-top/echo/middleware	Recover from panics
HTTPSRedirect	github.com/webx-top/echo/middleware	Redirect HTTP to HTTPS
HTTPSWWWRedirect	github.com/webx-top/echo/middleware	Redirect HTTP to WWW HTTPS
WWWRedirect	github.com/webx-top/echo/middleware	Redirect non-WWW to WWW
NonWWWRedirect	github.com/webx-top/echo/middleware	Redirect WWW to non-WWW
AddTrailingSlash	github.com/webx-top/echo/middleware	Add trailing slash to URI
RemoveTrailingSlash	github.com/webx-top/echo/middleware	Remove trailing slash from URI
Static	github.com/webx-top/echo/middleware	Serve static files
MaxAllowed	github.com/webx-top/echo/middleware	Limit simultaneous requests
NoCache	github.com/webx-top/echo/middleware	Set no-cache headers
Rewrite	github.com/webx-top/echo/middleware	URL path rewriting
Proxy	github.com/webx-top/echo/middleware	Reverse proxy with load balancing
Queue	github.com/webx-top/echo/middleware	Request concurrency queue
RequestID	github.com/webx-top/echo/middleware	X-Request-ID header
Validate	github.com/webx-top/echo/middleware	Request validator injection
FuncMap	github.com/webx-top/echo/middleware	Template function map
AJAX	github.com/webx-top/echo/middleware	AJAX operation handler
Language	github.com/webx-top/echo/middleware/language	Multi-language (i18n) support
RateLimit	github.com/webx-top/echo/middleware/ratelimit	Rate limiting HTTP requests
RateLimiter	github.com/webx-top/echo/middleware/ratelimiter	Rate limiter (supports memory & Redis)
Session	github.com/webx-top/echo/middleware/session	Session manager
JWT	github.com/webx-top/echo/middleware/jwt	JWT authentication
Markdown	github.com/webx-top/echo/middleware/markdown	Markdown rendering
Render	github.com/webx-top/echo/middleware/render	HTML template rendering (standard, Jet, SSE)
IPFilter	github.com/webx-top/echo/middleware/ipfilter	IP address filtering
OpenTracing	github.com/webx-top/echo/middleware/opentracing	Distributed tracing
Bindata Static	github.com/webx-top/echo/middleware/bindata	Serve embedded static files
ReverseProxy	github.com/webx-top/reverseproxy	External reverse proxy

Handler Wrapper list

Wrapper	Import path	Description
Websocket	github.com/webx-top/echo/handler/websocket	Example
Sockjs	github.com/webx-top/echo/handler/sockjs	Example
Oauth2	github.com/webx-top/echo/handler/oauth2	Example
Pprof	github.com/webx-top/echo/handler/pprof	Go pprof profiler
Captcha	github.com/webx-top/echo/handler/captcha	Image & audio captcha
Embed	github.com/webx-top/echo/handler/embed	Embedded file system file server
SSE	github.com/webx-top/echo/middleware/render/sse	Server-Sent Events render driver

Template Func docs

Template Function Documentation

Template Data

When using the Render middleware, the data passed to c.Render(data) is wrapped into *echo.RenderData. In Go templates, call its exported methods via $.XXX:

{{$.Now}}           {{/* 当前时间 */}}
{{$.UnixTime}}      {{/* 当前时间戳 */}}
{{$.Site}}          {{/* 网站URL */}}
{{$.SiteRoot}}      {{/* 网站根路径 */}}
{{$.URL}}           {{/* 当前请求URL */}}
{{$.URI}}           {{/* 当前请求URI */}}
{{$.Path}}          {{/* 当前请求路径 */}}
{{$.Domain}}        {{/* 当前域名 */}}
{{$.Port}}          {{/* 当前端口 */}}
{{$.Scheme}}        {{/* http/https */}}
{{$.Lang}}          {{/* 当前语言 */}}
{{$.Referer}}       {{/* 来源地址 */}}
{{$.Query "key"}}   {{/* 获取查询参数 */}}
{{$.Form "key"}}    {{/* 获取表单参数 */}}
{{$.Param "key"}}   {{/* 获取路径参数 */}}
{{$.Get "key"}}     {{/* 获取Context中存储的值 */}}
{{$.Cookie}}        {{/* Cookie操作 */}}
{{$.Session}}       {{/* Session操作 */}}
{{$.Flash "key"}}   {{/* Flash消息 */}}
{{$.T "你好%v" "世界"}}  {{/* 多语言翻译 */}}
{{$.LangURI "zh"}}  {{/* 生成语言链接 */}}
{{$.URLByName "routeName" "param1"}}  {{/* 根据路由名生成URL */}}
{{$.CaptchaForm}}   {{/* 验证码表单 */}}
{{$.TimeAgo $time}} {{/* 时间友好显示 */}}
{{$.TsHumanize $time}}{{/* 时间区间友好显示 */}}
{{$.DurationFormat $t}}{{/* 持续时间格式化 */}}
{{$.Fetch "subtmpl" .}}{{/* 渲染子模板并嵌入 */}}
{{$.MakeURL "handler" "arg"}}{{/* 生成URL */}}
{{$.Ext}}           {{/* 默认扩展名 */}}
{{$.ThemeColor}}    {{/* 主题色 */}}
{{$.Prefix}}        {{/* 当前路由前缀 */}}
{{$.RootPrefix}}    {{/* 根路由前缀 */}}
{{$.UploadURL "subdir"}}{{/* 上传文件URL */}}
{{$.FullURL "/path"}}{{/* 生成完整URL */}}
{{$.HasAnyRequest}} {{/* 是否有任何请求数据 */}}
{{$.GetNextURL}}    {{/* 获取跳转URL */}}
{{$.ReturnToCurrentURL}}{{/* 返回当前URL */}}

$.Data is the original data passed to c.Render(), and $.Stored is read-only data set via c.Set("key",any).

Additional Packages

formfilter - Form data filtering utilities
subdomains - Subdomain routing utilities (with SafeMap)
code - Business error code system
code/register - Error code registration
encoding/dbconfig - Database configuration encoding
param - Parameter type utilities (StringSlice, StringMap, Store)
testing - HTTP testing utilities
mockcontext - Mock context for unit testing
defaults - Default configuration utilities
logger - Logger integrations

Cases

Nging

Credits

Vishal Rana - Author
Hank Shen - Author
Nitin Rana - Consultant
Contributors

License

Apache 2

Name		Name	Last commit message	Last commit date
Latest commit History 2,271 Commits
.github/workflows		.github/workflows
code		code
defaults		defaults
encoding		encoding
engine		engine
formfilter		formfilter
handler		handler
logger		logger
middleware		middleware
mockcontext		mockcontext
param		param
subdomains		subdomains
testing		testing
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.travis.yml		.travis.yml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
binder.go		binder.go
binder_errors.go		binder_errors.go
binder_filter.go		binder_filter.go
binder_formatter.go		binder_formatter.go
binder_stringer.go		binder_stringer.go
binder_test.go		binder_test.go
binder_toform.go		binder_toform.go
binder_tostruct.go		binder_tostruct.go
constant.go		constant.go
context.go		context.go
context_accept.go		context_accept.go
context_accept_test.go		context_accept_test.go
context_store.go		context_store.go
context_x_base.go		context_x_base.go
context_x_request.go		context_x_request.go
context_x_response.go		context_x_response.go
context_x_session.go		context_x_session.go
context_x_store.go		context_x_store.go
context_x_transaction.go		context_x_transaction.go
cookie.go		cookie.go
data.go		data.go
data_kv.go		data_kv.go
data_kv_option.go		data_kv_option.go
data_kv_test.go		data_kv_test.go
data_kv_x.go		data_kv_x.go
data_kv_x_option.go		data_kv_x_option.go
echo.go		echo.go
echo_host.go		echo_host.go
echo_test.go		echo_test.go
error.go		error.go
error_test.go		error_test.go
event.go		event.go
go.mod		go.mod
go.sum		go.sum
group.go		group.go
hashmap.go		hashmap.go
hashmap_test.go		hashmap_test.go
helper.go		helper.go
helper_test.go		helper_test.go
host.go		host.go
host_test.go		host_test.go
meta.go		meta.go
meta_test.go		meta_test.go
middleware.go		middleware.go
register.go		register.go
render_data.go		render_data.go
router.go		router.go
router_test.go		router_test.go
sessioner.go		sessioner.go
transaction.go		transaction.go
transaction_test.go		transaction_test.go
translator.go		translator.go
validator.go		validator.go
variable.go		variable.go
variable_default.go		variable_default.go
wrapper.go		wrapper.go

Folders and files

Latest commit

History

Repository files navigation

Echo

Echo is a fast and unfancy web framework for Go (Golang). Up to 10x faster than the rest.

Features

Quick Start

Installation

Hello, World!

Routing

Path Parameters

Query Parameters

Form application/x-www-form-urlencoded

Form multipart/form-data

Handling Request

Form Data Filter (FormFilter)

Static Content

Embedded File Handler

Embedded Static Content (Bindata)

Captcha

Middleware

Cookie

Session

Transaction

Websocket

Sockjs

Server-Sent Events (SSE)

Reverse Proxy

URL Rewrite

Request Queue

Request ID

IP Filter

OpenTracing

Other Example

Middleware list

Root middleware (github.com/webx-top/echo/middleware)

Handler Wrapper list

Template Func docs

Template Data

Additional Packages

Cases

Credits

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 161

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Form `application/x-www-form-urlencoded`

Form `multipart/form-data`

Packages