概述
api-development 是一个元技能（meta-skill），旨在通过协调多个专业子技能、代理和命令，将 API 开发的完整生命周期（设计→构建→测试→文档→部署）整合为无缝的工作流。它不是单一工具，而是编排层，确保开发者在每个阶段都能调用正确的专业能力。
核心用法
该技能遵循严格的七步编排流程：
1. 设计阶段：调用 api-design 技能定义资源模型、URL 结构、HTTP 语义、错误格式和分页策略
2. 生成 OpenAPI 规范：基于设计产出机器可读的 OpenAPI 3.x 文件
3. 脚手架搭建：生成路由文件、类型定义和验证模式
4. 业务逻辑实现：编写服务层代码，保持控制器精简，核心逻辑下沉至服务层
5. 三层测试：单元测试（服务逻辑、验证、错误处理）、集成测试（端点+真实数据库）、契约测试（响应匹配 OpenAPI 规范）
6. 文档生成：产出包含用例示例和 SDK 代码片段的可读文档
7. 版本管理与部署：应用版本策略、打标签、更新变更日志、流水线部署
显著优点
- 端到端覆盖：首次将 API 开发的碎片化环节整合为统一工作流
- 决策支持：提供 REST/GraphQL/gRPC 的详细对比决策表，帮助选择正确范式
- 强制性检查：包含 40+ 项检查清单，覆盖认证、限流、分页、错误处理、CORS、安全、监控等维度
- 技能路由表：清晰映射 8 类专业技能（版本管理、认证模式、限流、缓存、数据库迁移等）
- 明确的反模式警示：6 条"NEVER"规则直接规避常见致命错误
潜在缺点与局限性
- 抽象成本：作为编排层，实际执行依赖底层子技能的成熟度；若子技能缺失或质量参差，整体体验下降
- 框架绑定隐忧：脚手架生成和代码结构建议隐含特定技术栈假设，跨框架迁移可能需额外适配
- 学习曲线：七步流程对简单 CRUD API 可能显得繁重，更适合中大型项目
- 实时协作缺失：未明确提及多人协作时的冲突解决、代码评审集成或设计评审流程
适合人群
- 全栈开发者：需要系统化指导 API 从 0 到 1 的构建
- 技术负责人：需要标准化团队 API 开发规范，确保输出一致性
- 后端工程师：正在重构遗留 API 或规划新版本迁移策略
- DevOps/SRE 工程师：关注部署流水线、监控、健康检查等运维就绪要求
常规风险
- 过度设计风险：严格遵循七步流程可能导致简单 API 开发周期延长
- 子技能依赖风险：若
api-design、auth-patterns等子技能未就绪或版本不兼容，编排流程中断 - 安全合规风险：尽管检查清单全面，但"认证必须存在"等强制项仍需人工审核确认，无法完全自动化保障
- 版本漂移风险：OpenAPI 规范与实现代码若未严格执行契约测试，易出现文档与行为不一致