应使用扁平化分组(如e.group("/api/v1/users"))隔离api模块,强制包含版本前缀,为各分组独立配置中间件,禁止嵌套分组,子分组继承父级中间件但不继承路径前缀。

你需要把不同业务模块的API接口按路径前缀隔离,避免所有路由挤在根实例上导致权限错配、中间件重复挂载、版本混乱等问题。
创建基础分组并挂载路由
用 e.Group("/api/v1/users") 创建用户域分组,路径前缀自动拼接,后续注册的路由只写相对路径即可。
调用 userGroup.GET("/list", listUsers) 注册列表接口,实际访问路径是 /api/v1/users/list,不是 /list。
这一步必须写对前缀,【/api/v1/users 中的 v1 是强制要求的版本标识,不能省略或挪到 query 或 header 里】,否则 CDN、网关、客户端缓存都会失效。
给分组单独配置中间件
方法一:JWT 鉴权只作用于用户相关接口
authGroup := e.Group("/api/v1/auth") → authGroup.Use(middleware.JWT()) → authGroup.POST("/login", loginHandler)
方法二:日志中间件只记录订单操作
orderGroup := e.Group("/api/v1/orders") → orderGroup.Use(middleware.LoggerWithConfig(...)) → orderGroup.GET("/:id", getOrder)
注意:不要把 CORS 或 Recovery 全部塞进顶层 e 实例——它们该挂哪就挂哪,混挂会导致非预期拦截或漏拦截。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
禁止嵌套分组的典型错误写法
第一步:apiGroup := e.Group("/api")
第二步:v1Group := apiGroup.Group("/v1")
第三步:usersGroup := v1Group.Group("/users")
这样写会让路径前缀变成三层拼接,调试时容易漏掉某一层中间件,且路由树冗余难维护。正确做法是直接写 e.Group("/api/v1/users"),一气呵成。
嵌套写法还会让 usersGroup.Use(...) 实际生效位置难以追溯,尤其当某层中间件被覆盖或未显式调用时,问题排查成本陡增。
分组继承与中间件作用域
子分组默认继承父分组中间件,但不继承父分组的路径前缀——这是常见误解。
比如 e.Use(middleware.Recover()) 后再建 userGroup := e.Group("/api/v1/users"),Recover 就会作用于 userGroup 下所有路由。
但若你在 userGroup 内又调用 userGroup.Use(middleware.JWT()),它不会影响 e.Group("/api/v1/products") 的行为。
中间件链是洋葱模型,执行顺序严格按 Use() 调用顺序,先注册的在外层,后注册的在内层。










