mcpField
A
api-platform-versioning

api-platform-versioning

github.com/dev-toolings开发22775 次安装3 周前更新
代码仓库

关于 api-platform-versioning

面向 Symfony 的技能，用于选择并实施 API Platform 版本策略。它优先采用弃用机制，再考虑并行版本，并涵盖 sunset 通知、响应头、文档和测试。

主要功能

  1. 01配置资源和操作的弃用信息
  2. 02添加 sunset 日期和响应头
  3. 03必要时设置并行 URI 版本
  4. 04记录文档并测试有效版本

适用场景

  1. 01重命名或移除 API 字段与操作
  2. 02公告 API 移除时间表
  3. 03管理表示形式的破坏性变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dev-toolings/superpowers-symfony --skill api-platform-versioning

安装后在 Claude Code 中输入/api-platform-versioning确认已加载。

附带文件reference.md

详细介绍

API 平台版本控制（Symfony）

适用场景

  • 字段、操作或资源即将重命名或移除，需要给使用者留出迁移时间。
  • 使用 Sunset 和 Deprecation 标头通知客户端移除日期。
  • 决定采用弃用方案，还是并行提供 /v1 和 /v2 接口。
  • 弃用机制和分组无法表达具有破坏性的表示形式变更。

默认工作流

  1. 优先尝试弃用：在资源、操作或 #[ApiProperty] 上设置 deprecationReason。
  2. 添加带日期的 sunset:，并在 v4 中添加 headers，包含 Deprecation（RFC 9745）以及带有 rel="successor-version" 的 Link。
  3. 在 v4 之前，通过 KernelEvents::RESPONSE 监听器发送这些标头。
  4. 只有在仍有破坏性变更时，才使用不同的分组并行公开 uriTemplate 值（/v1、/v2），或使用输出 DTO，并为每个版本配置一个提供程序。
  5. 在 OpenAPI 中将旧操作标记为已弃用，按版本记录变更，并测试每个仍在使用的版本。

注意事项

  • 优先采用弃用方案：路径版本控制是备用方案，而非默认选择。
  • 始终设置日落日期，并且最多同时保留 2 或 3 个活跃版本。
  • deprecationReason 和 sunset 在 v3 和 v4 中均稳定可用，但 RFC 9745 的 headers 选项属于 v4 时代的功能：请确认其适用于你安装的版本。
  • 对于次要的增量变更，使用分组，而不是创建新版本。

渐进式展开

  • 使用此文件了解执行方式和风险控制。
  • 需要深入了解实现细节时，打开参考资料。

输出约定

  • 选择的弃用或版本控制策略及其原因。
  • 已弃用的元素及其日落日期和后续版本链接。
  • 针对每个活跃版本以及相关标头的测试。

参考资料

  • reference.md

评论

支持 Markdown