Echo v5 迁移清单：Context 变结构体、Logger 换 slog，v4 还能撑到 2026-12-31
- 仓库：labstack/echo
- 公开 API 变更说明：API_CHANGES_V5.md
- 发布讨论：Discussion #2861
- 泛型参数绑定：PR #2856
版本时间线
- v5.0.0 于 2026-01-18 发布。
- 到 2026-03-31 之前，如果出现必须改动 API 的严重问题，官方会在 v5 上直接修，即使这违反语义化版本。
- 生产环境建议等到 2026-03-31 之后 再升级。
- v4 继续提供安全更新和缺陷修复，支持到 2026-12-31。
破坏性变更逐条
1. Context：interface → 具体结构体
这是影响面最大的一条：echo.Context 从接口变成结构体，所有 handler 的签名都要从 echo.Context 改成 *echo.Context。
// v4
func getUser(c echo.Context) error
// v5
func getUser(c *echo.Context) error
改成结构体之后，官方可以在 minor 版本里继续往 Context 上加方法，而不必再动接口。
2. Logger：自研接口 → log/slog
v5 里 Echo 的结构体直接持标准库 logger：
type Echo struct {
Logger *slog.Logger
}
func (c *Context) Logger() *slog.Logger
func (c *Context) SetLogger(logger *slog.Logger)
原来的 Logger 接口被移除，日志代码全部要跟着改。中间件层面，middleware.Logger 已在 v4.14.0（2025-12-11） 弃用，请求日志改用 middleware.RequestLogger 或 middleware.RequestLoggerWithConfig。
middleware.RequestLogger 基于标准库 slog。旧版本默认输出 JSON，新版本默认跟随 slog 的默认设置。想保持 JSON 输出：
slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
e.Use(middleware.RequestLogger())
3. Router：抽出接口，新增并发实现
- 新增
Router接口，为将来替换路由实现留口子。 DefaultRouter是默认的具体实现。NewRouter()的入参从*Echo变成RouterConfig。- 新增
NewConcurrentRouter(r Router) Router，用于线程安全的路由场景。 - 路由相关返回类型也调整了，新增显式的
RouteInfo、Routes类型。
4. Response：返回 http.ResponseWriter
Context.Response() 现在返回 http.ResponseWriter 而不是 *Response；Response 内嵌 http.ResponseWriter；NewResponse 收 *slog.Logger 而不是 *Echo。
中间件里如果要读 Size / Status / Committed，得先解包：
resp, err := echo.UnwrapResponse(c.Response())
resp.Size
resp.Status
resp.Committed
5. 其他
HTTPError 做了简化，HTTPErrorHandler 签名随之变化；新增 echotest 包作为测试辅助。
泛型取值助手
PR #2856 给参数提取加了一套泛型函数，签名都接收 *Context，原来的 form 系列改名为 FormValue*：
PathParam[T]、PathParamOr[T]、QueryParam[T]、QueryParamOr[T]、QueryParams[T]、QueryParamsOr[T]、FormParam[T]、FormParamOr[T]、FormParams[T]、FormParamsOr[T]、ContextGet[T]、ContextGetOr[T]。
支持的类型：基础类型（bool / string / int / uint / float）、time.Duration、time.Time（自定义 layout 和 Unix 时间戳），以及实现了 BindUnmarshaler / TextUnmarshaler / JSONUnmarshaler 的自定义类型。
id, err := echo.PathParam[int](c, "id")
page, err := echo.QueryParamOr[int](c, "page", 1)
自定义 context 的取法也跟着变。v4 是类型断言：
cc, _ := c.(MyCustomContext)
v5 改成走泛型助手：
cc, _ := echo.ContextGet[CustomContext](c, "my_custom_context")
好处是不会因为断言失败而 panic。另外 PathValues 取代了原来的 ParamNames / Values。
迁移 sed 与测试代价
Linux 下 Discussion #2861 给的批量替换：
find . -type f -name "*.go" -exec sed -i 's/ echo.Context/ *echo.Context/g' {} +
find . -type f -name "*.go" -exec sed -i 's/echo\/v4/echo\/v5/g' {} +
也就是把 " echo.Context" 替换成 " *echo.Context"，把 "echo/v4" 替换成 "echo/v5"。这能解决大部分问题，但 sed 只是取巧手段，边界情况必须人工复查，比如注释里的字符串、泛型参数、以及本来就带 * 的地方。
真正麻烦的是测试。Context 以前是接口，测试里往往得实现一大堆方法；现在变成结构体，反而会推着你在实现附近定义小的接口。这部分没法靠 sed 解决。
实操建议
官方在 Discussion 里说得很直白：如果 v5 最终被证明是重大失误，会把 v4 的扩展支持期给到 2026-12-31。生产环境用 Echo 的团队不必急着迁移。
结合前面几条：非必要不急着升；要升就先升到 v4 最新版，处理掉 middleware.Logger 的弃用告警，把测试梳理清楚，再整体切 v5。