Revel 框架推荐用 /api/v1/ 路径前缀而非 Header 实现 API 版本控制，因其在移动端更稳定、可观测、易灰度；需按版本分组路由、分离控制器、共享 service 层并隔离数据转换逻辑，下线前须验证缓存 Key、数据库索引及监控维度是否已按版本隔离。
Revel 框架本身不内置 API 版本控制机制，但它的路由设计和中间件能力足够支撑清晰、可维护的版本隔离方案。对移动端 APP 来说，最稳妥的做法是采用 /api/v1/xxx 这类 URL 路径前缀方式，而不是依赖 Header 或 Query 参数——因为 APP 发版周期长、客户端行为不可控，URL 路径是最易观测、最不易被漏传或覆盖的载体。
为什么 Revel 里优先用路由前缀（/v1）而不是 X-API-Version 头
移动端 APP 的网络层封装程度高，很多 SDK（比如 Retrofit、AFNetworking、uni-app 的 uni.request）默认不自动带自定义 Header；即使加了，也容易被代理、CDN 或网关清洗掉。而 URL 是端到端可见、日志里直接可 grep、Nginx 也能按路径做灰度分流的唯一稳定锚点。Revel 的 routes 文件天然支持路径前缀分组，不用改框架源码就能实现物理隔离。
常见错误现象：
- 用
X-API-Version: 2做判断，但 iOS 客户端某次热更新后忘了重设 Header，结果 v2 接口返回 v1 数据结构，前端解析崩溃 - 测试环境用 Postman 手动加 Header 测试正常，上线后发现 Flutter 插件底层 HTTP client 默认不透传自定义 Header
Revel 中怎么配置 /api/v1 和 /api/v2 的路由分发
在 conf/routes 里按版本显式声明路由组，避免“同一 Controller + if version == 2”这种耦合写法：
GET /api/v1/users App.UsersV1 GET /api/v1/orders App.OrdersV1 GET /api/v2/users App.UsersV2 GET /api/v2/orders App.OrdersV2
对应控制器要严格分离命名空间：
-
app/controllers/users_v1.go实现UsersV1类，只处理 v1 字段规则、废弃字段兼容逻辑、旧版分页格式 -
app/controllers/users_v2.go实现UsersV2类，可自由调整响应结构，比如把avatar改为 CDN 全路径、增加role_name字段
不要复用同一个 Controller 方法加参数判断版本——那会快速演变成难以测试、无法下线的“if-else 泥潭”。
如何让 v1 和 v2 共享业务逻辑但隔离数据契约
Revel 没有 Laravel 那样的 Service Provider 或 Symfony 的 DTO 自动映射，所以得手动做一层解耦：
- 核心业务逻辑（查 DB、校验权限、发消息）抽到
app/services/user_service.go，它只返回原始 struct 或 map，不涉及 HTTP 响应格式 - v1/v2 Controller 各自调用该 service，再用自己专属的
transformUserForV1()或transformUserForV2()函数做字段裁剪、重命名、类型转换 - 例如 v1 要求金额单位是“分”，v2 改为“元”，这个转换必须在 Controller 层完成，不能让 service 返回带单位的值
这样做的好处是：当某天要下线 v1，删掉 UsersV1 控制器和 transform 函数即可，业务逻辑层完全不动。
v1 下线前最容易被忽略的三个检查点
很多团队以为改完路由、发个公告就完事，结果线上出问题：
- 缓存 Key 是否含版本号？比如 Redis 里存的是
user:123，v1/v2 都读这个 key，但 v2 期望字段更多，就会出现“字段缺失却无报错”的静默失败 - 数据库查询是否因 v2 的新索引拖慢 v1？比如 v2 加了
idx_user_status_created，但 v1 的慢查询恰好命中这个索引导致回表变多 - 第三方 SDK（如 Sentry、Datadog）上报的 trace 是否还包含 v1 路径？如果监控没按版本拆维度，你根本看不出 v1 请求量正在归零还是卡在某个异常节点
真正安全的下线，不是删代码，而是先确认 v1 的请求量已趋近于零、所有缓存 Key 已按版本隔离、监控告警已能独立观察每个版本的 P99 延迟——这些都得在 Revel 的中间件或日志埋点里提前准备好。否则，你以为的“平滑过渡”，可能只是还没被用户点出来而已。
