version-api

版本 API

为 Rails API 实现版本控制策略。

快速参考

关注点	文件
路由命名空间	config/routes.rb
请求头版本控制	app/controllers/concerns/api_versioning.rb
弃用请求头	app/controllers/concerns/deprecatable.rb
兼容性测试	spec/requests/api/backward_compatibility_spec.rb

硬性门槛

GENERATED CODE SAFETY:
- NEVER generate code that constantizes or evaluates caller-supplied version strings
  (e.g. "V#{params[:version]}".constantize is forbidden — use an explicit allowlist).
- NEVER generate code that passes request headers or paths unsanitized into class
  instantiation, eval, or dynamic dispatch.
- Allowlist-only version resolution: generated routing/concern code MUST resolve
  version identifiers from a fixed set (V1, V2, ...), not from free-form input.

ALWAYS maintain backward compatibility for at least one major version
NEVER remove endpoints without deprecation period
ALWAYS version in URL path (/api/v1/) or Accept header, never in body

核心流程

1. 选择策略 — 公共 API 使用 URL 路径（/api/v1/）；内部／私有 API 使用 Accept 请求头。有关基于请求头的版本控制详情和权衡，请参阅 strategies.md。
2. 添加路由命名空间 — 在 config/routes.rb 中使用 namespace :v2 代码块包装新版本的资源：

   namespace :v1 do
     resources :users
   end
   
   namespace :v2 do
     resources :users
   end
   

3. 创建控制器 — 继承自上一版本的控制器，仅重写发生变化的操作：

   module V2
     class UsersController < V1::UsersController
       def index
         render json: User.all, only: [:id, :name, :email, :phone]
       end
     end
   end
   

   有关其他继承模式，请参阅 EXAMPLES.md。
4. 应用弃用策略 — 在旧版本控制器中引入 Deprecatable，通过 before_action 自动添加 Sunset 和 Deprecation 响应请求头：

   module V1
     class UsersController < ApplicationController
       include Deprecatable
       # Override sunset_date on the class to set the retirement date:
       # def self.sunset_date = Date.new(2025, 6, 1)
     end
   end
   

5. 运行兼容性测试 — 执行 bundle exec rspec spec/requests/api/backward_compatibility_spec.rb，确认合并前没有回归。
6. 更新文档 — 记录弃用端点的停止服务日期和迁移指南。完整的弃用通知工作流请参阅 workflow.md。

输出风格

在收到实现 API 版本控制的请求时，输出必须包含：

1. 版本控制策略 — 明确说明使用 URL 路径（/api/v1/）还是 Accept 请求头版本控制
2. 继承策略 — 说明新版本控制器如何继承自上一版本
3. 路由定义 — 展示 config/routes.rb 中的命名空间路由配置
4. 弃用请求头 — 包含 Deprecatable concern 和停止服务日期配置
5. 兼容性测试 — 包含运行向后兼容性测试的命令
6. 语言 — 除非另有明确要求，否则必须使用英文

扩展资源（渐进式披露）

仅在需要相应内容时加载这些文件：

• EXAMPLES.md — 需要完整的 API 版本控制示例（包含路由定义和控制器继承）时使用
• references/strategies.md — 比较版本控制策略（URL 路径、请求头或查询参数）时使用
• references/workflow.md — 实施弃用通知工作流并安排停止服务时间时使用

集成

技能	何时衔接
generate-api-collection	生成更新后的 API 端点时
test-engine	验证测试是否存在回归时