定位

Echo 是 Go 的 HTTP 框架，和 Gin 定位最接近但 API 设计更统一。核心特点是中间件接口规范、参数绑定和校验做得整齐。

选它而不是 Gin 的理由通常有两个：想要更严格的参数校验，或者受不了 Gin 的 interface{} 绑定。

安装

go mod init example.com/echo-demo
go get github.com/labstack/echo/v4

最小可运行示例

package main

import (
    "net/http"
    "github.com/labstack/echo/v4"
)

func main() {
    e := echo.New()

    e.GET("/", func(c echo.Context) error {
        return c.String(http.StatusOK, "Hello")
    })

    e.GET("/users/:id", func(c echo.Context) error {
        id := c.Param("id")
        return c.JSON(http.StatusOK, map[string]string{"id": id})
    })

    e.Logger.Fatal(e.Start(":8080"))
}

核心概念

1. Context 贯穿请求

echo.Context 同时承载请求、响应、路径参数、查询参数、表单和自定义数据（c.Set / c.Get）。所有 handler 都接收它，中间件也接收它。

2. 绑定与校验是两步

Echo 不内置校验器——不注册就直接调 c.Validate，得到的是 ErrValidatorNotRegistered。标准流程是两步：Bind 按 Content-Type 解码，Validate 显式校验，校验器要自己实现 echo.Validator 接口注册：

type CreateUser struct {
    Name  string `json:"name"  validate:"required,min=2"`
    Email string `json:"email" validate:"required,email"`
}

// 1. 注册校验器（全局一次）
// import "github.com/go-playground/validator/v10"
type CustomValidator struct{ v *validator.Validate }

func (cv *CustomValidator) Validate(i interface{}) error { return cv.v.Struct(i) }

e := echo.New()
e.Validator = &CustomValidator{validator.New()}

// 2. handler 里显式两步：先解码，再校验
e.POST("/users", func(c echo.Context) error {
    u := new(CreateUser)
    if err := c.Bind(u); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
    }
    if err := c.Validate(u); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
    }
    return c.JSON(http.StatusCreated, u)
})

校验规则来自 go-playground/validator——和 Gin 用的是同一个库，区别在于 Gin 把校验揉进了绑定那一步，Echo 要求你显式调用、自己装配校验器。换来的是流程透明：错在解码还是校验，一眼可辨。

3. 分组路由

// v4.13 起 middleware.JWT 已从核心移除，改用独立包：
// import echojwt "github.com/labstack/echo-jwt/v4"
api := e.Group("/api")
api.Use(echojwt.JWT([]byte("secret")))       // 只作用于 /api 下

v1 := api.Group("/v1")
v1.GET("/users", listUsers)

4. 中间件返回 error

Echo 的中间件签名是 func(next echo.HandlerFunc) echo.HandlerFunc，返回 error。错误会走统一的自定义错误处理器：

e.HTTPErrorHandler = func(err error, c echo.Context) {
    if he, ok := err.(*echo.HTTPError); ok {
        c.JSON(he.Code, map[string]string{"error": fmt.Sprint(he.Message)})
        return
    }
    c.JSON(500, map[string]string{"error": "internal error"})
}

常见坑

① :id 和 * 的区别

/users/:id 匹配单段；/files/* 匹配剩余全部路径。两者可以和静态路由在同一层共存：/users/me 和 /users/:id 一起注册并不会冲突，匹配优先级是静态路由 > 参数路由 > 通配路由，与注册顺序无关——/users/me 永远命中静态那条，其余才落到 :id。

② Bind 不区分 Content-Type

c.Bind() 会根据请求头自动选择 JSON / form / XML。行为分两种情况：body 为空时解码无事可做、返回 nil，你拿到的是零值结构体（不报错）；body 非空但 Content-Type 不被支持时返回 415 Unsupported Media Type。所以「静默空结构体」只出现在空 body 的场景，需要严格时先检查 Content-Type / Content-Length 再 Bind。

③ 忘记自定义 HTTPErrorHandler

默认错误响应是 {"message":"Not Found"}，格式和你的 API 不一致。项目一开始就该设置。

什么时候选它

• 需要严谨的入参校验
• 团队喜欢显式错误处理（handler 返回 error 而不是自己写响应）
• 项目规模中等，不需要微服务治理

不选它的场景：需要最广的第三方中间件生态（那时选 Gin），或者追求极致性能（那时选 Fiber）。

延伸阅读

• Go 生态与框架选型——Echo 在 Go 框架全景里的位置
• Gin 框架入门——定位最接近的对照框架
• Fiber 框架入门——追求极致吞吐时的替代选项
• go-zero 微服务入门——从 Web 框架走向微服务的下一站
• Kratos 微服务入门——gRPC 优先的微服务路线