mcpField
L
laravel:api-surface-evolution

laravel:api-surface-evolution

github.com/jpcaparas开发157106 次安装17 周前更新
代码仓库

关于 laravel:api-surface-evolution

一项介绍如何在 Laravel 中演进 API 并维持已发布客户端契约的技能，涵盖版本管理、DTO 转换、弃用流程和兼容性测试。

主要功能

  1. 01基于 URI 或请求头的版本管理
  2. 02版本化 DTO 与转换器
  3. 03弃用时间表与使用指标
  4. 04契约及向后兼容测试

适用场景

  1. 01新增 API 字段且不破坏客户端
  2. 02管理不同 API 版本中的弃用字段
  3. 03验证请求与响应契约

安装

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

$npx skills add https://github.com/jpcaparas/superpowers-laravel --skill laravel:api-surface-evolution

安装后在 Claude Code 中输入/laravel:api-surface-evolution确认已加载。

详细介绍

API 表面演进

面向变化进行设计，同时不破坏客户端。

版本策略

  • 选择明确的版本控制方式（URI /v1/... 或通过请求头协商）
  • 默认采用增量式变更；绝不破坏已发布的契约

DTO 与转换器

  • 定义带版本号的 DTO；通过转换器从模型/服务映射
  • 保持控制器精简——校验 → 转换 → 响应

弃用

  • 在文档和响应中（例如请求头）将字段标记为已弃用
  • 提供停用时间表；添加指标以了解仍在使用的情况

测试

  • 每个版本都进行契约测试（请求/响应结构）
  • 针对常用流程进行向后兼容性测试

评论

支持 Markdown