API版本前缀必须硬编码进路由路径，如/api/v1/users，并通过常量统一管理；需用前置中间件校验版本前缀并返回404；禁用Group实现版本隔离，改用动态路由或底层替换；旧接口冻结标注但不删除，确保兼容性。
API版本前缀必须硬编码进路由路径
Buffalo 默认不强制版本控制，app.GET("/users", UsersList) 这种写法会让所有请求直通 v0，后续加 v1 就只能改代码、发版。企业级 API 要求版本变更不破坏旧客户端，所以每个路由 path 必须显式带版本前缀，比如 /api/v1/users。
别指望靠中间件动态拼接——Buffalo 的路由匹配发生在中间件之前，没匹配到 route 就直接 404，根本进不到中间件里。
- 统一定义常量：在
app.go或单独的routes/consts.go中声明const UserListPath = "/api/v1/users" - 所有
app.GET()、app.POST()都用该常量，禁止字符串字面量散落各处 - 升级时新增
UserListPathV2 = "/api/v2/users"，旧路由保留不动，不删不改
用中间件拦截非法版本请求并返回 404
光写对路径还不够。客户端可能误发 /api/v3/users 或 /api/users（缺版本），这类请求不能落到 handler 里再判断，得在路由匹配后、handler 执行前就拦截掉。
Buffalo 的中间件链是顺序执行的，所以要在 app.Use() 中尽早注册版本校验中间件：
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
app.Use(func(c buffalo.Context) error {
path := c.Request().URL.Path
if !strings.HasPrefix(path, "/api/v1/") && !strings.HasPrefix(path, "/api/v2/") {
return c.Error(404, errors.New("API version not supported"))
}
return nil
})
- 这个中间件必须放在所有业务中间件之前，否则可能被日志或 auth 中间件先处理
- 不要用正则匹配版本号——
strings.HasPrefix更快、更安全，避免回溯爆炸 - 返回
c.Error(404, ...)而不是手动写 status+body，确保走 Buffalo 统一错误格式
避免用 Buffalo 内置路由器做“版本路由分发”
有人想用 app.Group("/api/v1", func(r buffalo.Router) { ... }) 来隔离版本，这看似合理，但实际埋雷：
-
app.Group只是路径前缀封装，不提供运行时路由切换能力 - 无法实现灰度：比如只让 5% 流量走 v2，其余走 v1——Group 是编译期静态结构
- 无法审计：v1 和 v2 的路由定义分散在不同 Group 里，排查时要翻多个文件
真正需要动态分发时，应替换底层 router（如用 gorilla/mux），把 /api/{version}/users 注册为变量路由，再在 handler 里根据 c.Param("version") 分支处理。Buffalo 的 Context 仍可用，只是路由注册方式变了。
迁移旧版接口时，别删老代码，而是冻结 + 标注
v1 接口下线不是删 UsersList 函数，而是把它标记为 deprecated 并保留在原位置：
func UsersList(c buffalo.Context) error {
// DEPRECATED: v1 will be removed on 2027-06-01
// Use UsersListV2 instead
...
}
- 保留老路由和 handler，确保存量调用不断
- 在函数注释里写明废弃时间，CI 可扫描警告
- 日志中打标：在 handler 开头加
log.Printf("[DEPRECATED] /api/v1/users called")，用于监控淘汰进度
版本兼容最难的不是技术实现，而是让所有人接受“旧代码永远比新代码多”。只要还有一台设备在调 v1，它就得活着——删代码永远比加代码容易，但线上稳定比开发爽更重要。
