README
¶
Echo 
Echo is a fast HTTP router (zero memory allocation) and micro web framework in Go.
Features
- Fast 🚀 HTTP router which smartly prioritize routes.
- Extensible middleware/handler, supports:
- Middleware
echo.MiddlewareFuncfunc(echo.HandlerFunc) echo.HandlerFuncecho.HandlerFuncfunc(*echo.Context) *echo.HTTPErrorfunc(http.Handler) http.Handlerhttp.Handlerhttp.HandlerFuncfunc(http.ResponseWriter, *http.Request)
- Handler
echo.HandlerFuncfunc(*echo.Context) *echo.HTTPErrorhttp.Handlerhttp.HandlerFuncfunc(http.ResponseWriter, *http.Request)
- Middleware
- Sub routing with groups.
- Handy encoding/decoding functions.
- Serve static files, including index.
- Centralized HTTP error handling.
- Use a customized function to bind request body to a Go type.
- Register a view render so you can use any HTML template engine.
Benchmark
Based on [julienschmidt/go-http-routing-benchmark] (https://github.com/vishr/go-http-routing-benchmark), April 1, 2015
Echo: 42728 ns/op, 0 B/op, 0 allocs/op
BenchmarkAce_GithubAll 20000 65328 ns/op 13792 B/op 167 allocs/op
BenchmarkBear_GithubAll 10000 241852 ns/op 79952 B/op 943 allocs/op
BenchmarkBeego_GithubAll 3000 458234 ns/op 146272 B/op 2092 allocs/op
BenchmarkBone_GithubAll 1000 1923508 ns/op 648016 B/op 8119 allocs/op
BenchmarkDenco_GithubAll 20000 81294 ns/op 20224 B/op 167 allocs/op
BenchmarkEcho_GithubAll 30000 42728 ns/op 0 B/op 0 allocs/op
BenchmarkGin_GithubAll 20000 69373 ns/op 13792 B/op 167 allocs/op
BenchmarkGocraftWeb_GithubAll 10000 370978 ns/op 133280 B/op 1889 allocs/op
BenchmarkGoji_GithubAll 3000 542766 ns/op 56113 B/op 334 allocs/op
BenchmarkGoJsonRest_GithubAll 5000 452551 ns/op 135995 B/op 2940 allocs/op
BenchmarkGoRestful_GithubAll 200 9500204 ns/op 707604 B/op 7558 allocs/op
BenchmarkGorillaMux_GithubAll 200 6770545 ns/op 153137 B/op 1791 allocs/op
BenchmarkHttpRouter_GithubAll 30000 56097 ns/op 13792 B/op 167 allocs/op
BenchmarkHttpTreeMux_GithubAll 10000 143175 ns/op 56112 B/op 334 allocs/op
BenchmarkKocha_GithubAll 10000 147959 ns/op 23304 B/op 843 allocs/op
BenchmarkMacaron_GithubAll 2000 724650 ns/op 224960 B/op 2315 allocs/op
BenchmarkMartini_GithubAll 100 10926021 ns/op 237953 B/op 2686 allocs/op
BenchmarkPat_GithubAll 300 4525114 ns/op 1504101 B/op 32222 allocs/op
BenchmarkRevel_GithubAll 2000 1172963 ns/op 345553 B/op 5918 allocs/op
BenchmarkRivet_GithubAll 10000 249104 ns/op 84272 B/op 1079 allocs/op
BenchmarkTango_GithubAll 300 4012826 ns/op 1368581 B/op 29157 allocs/op
BenchmarkTigerTonic_GithubAll 2000 975450 ns/op 241088 B/op 6052 allocs/op
BenchmarkTraffic_GithubAll 200 7540377 ns/op 2664762 B/op 22390 allocs/op
BenchmarkVulcan_GithubAll 5000 307241 ns/op 19894 B/op 609 allocs/op
BenchmarkZeus_GithubAll 2000 752907 ns/op 300688 B/op 2648 allocs/op
Installation
$ go get github.com/labstack/echo
##Examples
package main
import (
"net/http"
"github.com/labstack/echo"
mw "github.com/labstack/echo/middleware"
)
// Handler
func hello(c *echo.Context) *echo.HTTPError {
return c.String(http.StatusOK, "Hello, World!\n")
}
func main() {
// Echo instance
e := echo.New()
// Middleware
e.Use(mw.Logger())
e.Use(mw.Recover())
// Routes
e.Get("/", hello)
// Start server
e.Run(":1323")
}
###CRUD
package main
import (
"net/http"
"strconv"
"github.com/labstack/echo"
mw "github.com/labstack/echo/middleware"
)
type (
user struct {
ID int
Name string
}
)
var (
users = map[int]*user{}
seq = 1
)
//----------
// Handlers
//----------
func createUser(c *echo.Context) *echo.HTTPError {
u := &user{
ID: seq,
}
if he := c.Bind(u); he != nil {
return he
}
users[u.ID] = u
seq++
return c.JSON(http.StatusCreated, u)
}
func getUser(c *echo.Context) *echo.HTTPError {
id, _ := strconv.Atoi(c.Param("id"))
return c.JSON(http.StatusOK, users[id])
}
func updateUser(c *echo.Context) *echo.HTTPError {
u := new(user)
if he := c.Bind(u); he != nil {
return he
}
id, _ := strconv.Atoi(c.Param("id"))
users[id].Name = u.Name
return c.JSON(http.StatusOK, users[id])
}
func deleteUser(c *echo.Context) *echo.HTTPError {
id, _ := strconv.Atoi(c.Param("id"))
delete(users, id)
return c.NoContent(http.StatusNoContent)
}
func main() {
e := echo.New()
// Middleware
e.Use(mw.Logger())
e.Use(mw.Recover())
// Routes
e.Post("/users", createUser)
e.Get("/users/:id", getUser)
e.Patch("/users/:id", updateUser)
e.Delete("/users/:id", deleteUser)
// Start server
e.Run(":1323")
}
###Website
package main
import (
"io"
"net/http"
"html/template"
"github.com/labstack/echo"
mw "github.com/labstack/echo/middleware"
"github.com/rs/cors"
"github.com/thoas/stats"
)
type (
// Template provides HTML template rendering
Template struct {
templates *template.Template
}
user struct {
ID string `json:"id"`
Name string `json:"name"`
}
)
var (
users map[string]user
)
// Render HTML
func (t *Template) Render(w io.Writer, name string, data interface{}) *echo.HTTPError {
if err := t.templates.ExecuteTemplate(w, name, data); err != nil {
return &echo.HTTPError{Error: err}
}
return nil
}
//----------
// Handlers
//----------
func welcome(c *echo.Context) *echo.HTTPError {
return c.Render(http.StatusOK, "welcome", "Joe")
}
func createUser(c *echo.Context) *echo.HTTPError {
u := new(user)
if err := c.Bind(u); err != nil {
return err
}
users[u.ID] = *u
return c.JSON(http.StatusCreated, u)
}
func getUsers(c *echo.Context) *echo.HTTPError {
return c.JSON(http.StatusOK, users)
}
func getUser(c *echo.Context) *echo.HTTPError {
return c.JSON(http.StatusOK, users[c.P(0)])
}
func main() {
e := echo.New()
// Middleware
e.Use(mw.Logger())
e.Use(mw.Recover())
//------------------------
// Third-party middleware
//------------------------
// https://github.com/rs/cors
e.Use(cors.Default().Handler)
// https://github.com/thoas/stats
s := stats.New()
e.Use(s.Handler)
// Route
e.Get("/stats", func(c *echo.Context) *echo.HTTPError {
return c.JSON(http.StatusOK, s.Data())
})
// Serve index file
e.Index("public/index.html")
// Serve favicon
e.Favicon("public/favicon.ico")
// Serve static files
e.Static("/scripts/", "public/scripts")
//--------
// Routes
//--------
e.Post("/users", createUser)
e.Get("/users", getUsers)
e.Get("/users/:id", getUser)
//-----------
// Templates
//-----------
t := &Template{
// Cached templates
templates: template.Must(template.ParseFiles("public/views/welcome.html")),
}
e.Renderer(t)
e.Get("/welcome", welcome)
//-------
// Group
//-------
// Group with parent middleware
a := e.Group("/admin")
a.Use(func(c *echo.Context) *echo.HTTPError {
// Security middleware
return nil
})
a.Get("", func(c *echo.Context) *echo.HTTPError {
return c.String(http.StatusOK, "Welcome admin!")
})
// Group with no parent middleware
g := e.Group("/files", func(c *echo.Context) *echo.HTTPError {
// Security middleware
return nil
})
g.Get("", func(c *echo.Context) *echo.HTTPError {
return c.String(http.StatusOK, "Your files!")
})
// Start server
e.Run(":1323")
}
func init() {
users = map[string]user{
"1": user{
ID: "1",
Name: "Wreck-It Ralph",
},
}
}
###Middleware
package main
import (
"net/http"
"github.com/labstack/echo"
mw "github.com/labstack/echo/middleware"
)
// Handler
func hello(c *echo.Context) *echo.HTTPError {
return c.String(http.StatusOK, "Hello, World!\n")
}
func main() {
// Echo instance
e := echo.New()
// Debug mode
e.Debug(true)
//------------
// Middleware
//------------
// Logger
e.Use(mw.Logger())
// Recover
e.Use(mw.Recover())
// Basic auth
e.Use(mw.BasicAuth(func(u, p string) bool {
if u == "joe" && p == "secret" {
return true
}
return false
}))
//-------
// Slash
//-------
e.Use(mw.StripTrailingSlash())
// or
// e.Use(mw.RedirectToSlash())
// Gzip
e.Use(mw.Gzip())
// Routes
e.Get("/", hello)
// Start server
e.Run(":1323")
}
##Guide
Contribute
Use issues for everything
- Report problems
- Discuss before sending pull request
- Suggest new features
- Improve/fix documentation
Credits
- Vishal Rana - Author
- Nitin Rana - Consultant
- Contributors
License
Documentation
¶
Index ¶
- Constants
- Variables
- func NewRouter(e *Echo) (r *router)
- type BindFunc
- type Context
- func (c *Context) Bind(i interface{}) *HTTPError
- func (c *Context) Error(he *HTTPError)
- func (c *Context) Get(key string) interface{}
- func (c *Context) HTML(code int, html string) *HTTPError
- func (c *Context) JSON(code int, i interface{}) *HTTPError
- func (c *Context) NoContent(code int) *HTTPError
- func (c *Context) P(i uint8) (value string)
- func (c *Context) Param(name string) (value string)
- func (c *Context) Redirect(code int, url string)
- func (c *Context) Render(code int, name string, data interface{}) *HTTPError
- func (c *Context) Set(key string, val interface{})
- func (c *Context) String(code int, s string) *HTTPError
- type Echo
- func (e *Echo) Binder(b BindFunc)
- func (e *Echo) Connect(path string, h Handler)
- func (e *Echo) Debug(on bool)
- func (e *Echo) Delete(path string, h Handler)
- func (e *Echo) Favicon(file string)
- func (e *Echo) Get(path string, h Handler)
- func (e *Echo) Group(pfx string, m ...Middleware) *Echo
- func (e *Echo) HTTPErrorHandler(h HTTPErrorHandler)
- func (e *Echo) Head(path string, h Handler)
- func (e *Echo) Index(file string)
- func (e *Echo) MaxParam(n uint8)
- func (e *Echo) Options(path string, h Handler)
- func (e *Echo) Patch(path string, h Handler)
- func (e *Echo) Post(path string, h Handler)
- func (e *Echo) Put(path string, h Handler)
- func (e *Echo) Renderer(r Renderer)
- func (e *Echo) Run(addr string)
- func (e *Echo) RunServer(server *http.Server)
- func (e *Echo) RunTLS(addr, certFile, keyFile string)
- func (e *Echo) RunTLSServer(server *http.Server, certFile, keyFile string)
- func (e *Echo) ServeFile(path, file string)
- func (e *Echo) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (e *Echo) Static(path, root string)
- func (e *Echo) Trace(path string, h Handler)
- func (e *Echo) URI(h Handler, params ...interface{}) string
- func (e *Echo) URL(h Handler, params ...interface{}) string
- func (e *Echo) Use(m ...Middleware)
- type HTTPError
- type HTTPErrorHandler
- type Handler
- type HandlerFunc
- type Middleware
- type MiddlewareFunc
- type Renderer
- type Response
- func (r *Response) CloseNotify() <-chan bool
- func (r *Response) Flush()
- func (r *Response) Header() http.Header
- func (r *Response) Hijack() (net.Conn, *bufio.ReadWriter, error)
- func (r *Response) Size() int64
- func (r *Response) Status() int
- func (r *Response) Write(b []byte) (n int, err error)
- func (r *Response) WriteHeader(code int)
Constants ¶
View Source
const ( // CONNECT HTTP method CONNECT = "CONNECT" // DELETE HTTP method DELETE = "DELETE" // GET HTTP method GET = "GET" // HEAD HTTP method HEAD = "HEAD" // OPTIONS HTTP method OPTIONS = "OPTIONS" // PATCH HTTP method PATCH = "PATCH" // POST HTTP method POST = "POST" // PUT HTTP method PUT = "PUT" // TRACE HTTP method TRACE = "TRACE" ApplicationJSON = "application/json" ApplicationProtobuf = "application/protobuf" ApplicationMsgpack = "application/msgpack" TextPlain = "text/plain" TextHTML = "text/html" ApplicationForm = "application/x-www-form-urlencoded" MultipartForm = "multipart/form-data" Accept = "Accept" AcceptEncoding = "Accept-Encoding" ContentDisposition = "Content-Disposition" ContentEncoding = "Content-Encoding" ContentLength = "Content-Length" ContentType = "Content-Type" Authorization = "Authorization" )
Variables ¶
View Source
var ( UnsupportedMediaType = errors.New("echo ⇒ unsupported media type") RendererNotRegistered = errors.New("echo ⇒ renderer not registered") )
Functions ¶
Types ¶
type Context ¶
type Context struct {
Request *http.Request
Response *Response
// contains filtered or unexported fields
}
Context represents context for the current request. It holds request and response objects, path parameters, data and registered handler.
func NewContext ¶ added in v0.0.13
func (*Context) Bind ¶
Bind binds the request body into specified type v. Default binder does it based on Content-Type header.
func (*Context) NoContent ¶ added in v0.0.10
NoContent sends a response with no body and a status code.
func (*Context) Render ¶ added in v0.0.5
Render invokes the registered HTML template renderer and sends a text/html response with status code.
type Echo ¶
type Echo struct {
Router *router
// contains filtered or unexported fields
}
func (*Echo) Binder ¶ added in v0.0.9
Binder registers a custom binder. It's invoked by Context.Bind API.
func (*Echo) Group ¶ added in v0.0.4
func (e *Echo) Group(pfx string, m ...Middleware) *Echo
Group creates a new sub router with prefix. It inherits all properties from the parent. Passing middleware overrides parent middleware.
func (*Echo) HTTPErrorHandler ¶ added in v0.0.10
func (e *Echo) HTTPErrorHandler(h HTTPErrorHandler)
HTTPErrorHandler registers an HTTP error handler.
func (*Echo) MaxParam ¶
MaxParam sets the maximum number of path parameters allowed for the application. Default value is 5, good enough for many use cases.
func (*Echo) Renderer ¶ added in v0.0.7
Renderer registers an HTML template renderer. It's invoked by Context.Render API.
func (*Echo) RunTLSServer ¶ added in v0.0.5
RunTLSServer runs a custom server with TLS configuration.
type HTTPErrorHandler ¶ added in v0.0.10
HTTPErrorHandler is a centralized HTTP error handler.
type HandlerFunc ¶
type Middleware ¶
type Middleware interface{}
type MiddlewareFunc ¶
type MiddlewareFunc func(HandlerFunc) HandlerFunc
type Renderer ¶ added in v0.0.7
Renderer is the interface that wraps the Render method.
Render renders the HTML template with given name and specified data. It writes the output to w.
type Response ¶ added in v0.0.13
type Response struct {
Writer http.ResponseWriter
// contains filtered or unexported fields
}
func (*Response) CloseNotify ¶ added in v0.0.13
CloseNotify wraps response writer's CloseNotify function.
func (*Response) Flush ¶ added in v0.0.13
func (r *Response) Flush()
Flush wraps response writer's Flush function.
func (*Response) WriteHeader ¶ added in v0.0.13
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.