Api Designer

核心功能与定位

API Designer 是一款面向企业级 API 架构设计的专业工具，专注于帮助开发者创建可扩展、易维护的 REST 与 GraphQL 接口系统。该 Skill 扮演资深 API 架构师角色（10+ 年以上经验），核心能力覆盖资源建模、OpenAPI 3.1 规范生成、版本控制策略、分页模式设计及标准化错误处理。

显著优势

1. 规范完整性：强制遵循 REST 设计原则，输出包含完整认证流程、错误目录、请求/响应示例的 OpenAPI 3.1 规范文档
2. 工程化思维：内置版本演进策略与弃用政策，确保 API 生命周期管理的可持续性
3. 多协议支持：同时覆盖 REST 与 GraphQL 两大主流范式，适配不同团队技术栈
4. 安全内置：集成 OAuth 2.0、JWT、速率限制等安全要素于设计阶段

潜在局限

• 输出侧重设计规范层面，具体实现需配合 FastAPI、NestJS、Spring Boot 等关联 Skill 完成代码生成
• 高度依赖输入的业务需求质量，复杂领域建模仍需人工领域专家介入
• 参考文档（rest-patterns.md、versioning.md 等）为按需加载，离线环境可能受限

适用人群

• 后端架构师与 Tech Lead：进行 API 顶层设计评审
• 全栈开发者：快速产出标准化接口契约供前后端协作
• 技术写作者：生成可直接用于开发者门户的 OpenAPI 文档

常规风险提示

• 兼容性风险：版本策略执行不当可能导致破坏性变更
• 安全疏漏：虽内置安全考量，但生产环境仍需配合 Security Reviewer Skill 进行专项审计
• 过度设计：简单场景下完整的 OpenAPI 规范可能增加维护成本，需权衡投入产出

核心用法

api-designer 是一款面向 API 架构设计的纯文档型 Skill，采用「领域分析 → 资源建模 → 端点设计 → 契约规范 → 演进规划」五步工作流。用户触发关键词（如"API design""OpenAPI""REST API"）后，Skill 将提供 REST/GraphQL 双栈设计能力，输出资源关系图、URI 模式、HTTP 方法映射、完整 OpenAPI 3.1 规范（YAML/JSON）、认证流程、错误响应目录、分页策略及版本控制方案。

显著优点

• 权威规范：深度整合 OpenAPI 3.1、RFC 7807 Problem Details、JSON:API、HATEOAS 等工业标准
• 完整交付物：不止于设计建议，直接输出可执行的规范文档与代码契约
• 演进友好：内置版本控制、弃用策略、向后兼容设计，避免技术债务
• 安全前置：强制要求认证授权文档、速率限制考量，将安全左移至设计阶段

潜在局限

• 纯文档无执行：需配合具体实现 Skill（如 FastAPI Expert、NestJS Expert）才能落地代码
• 标准更新滞后：API 设计规范随技术演进（如 gRPC 崛起、AsyncAPI 兴起），需人工维护 references/ 目录
• 场景覆盖偏向：侧重 REST/GraphQL，对新兴协议（tRPC、gRPC-Web）支持有限

适合人群

• 后端架构师设计新 API 系统
• 技术负责人制定团队 API 规范
• 前后端团队协作前的契约先行（Contract First）实践者
• 需要生成 OpenAPI 文档以驱动 SDK 生成、Mock 服务的工程团队

常规风险

• 设计过度工程：严格遵循 REST 层级可能在小规模场景中引入不必要的复杂度
• 版本策略冲突：团队若未就版本控制（URL vs Header vs 媒体类型）达成共识，易导致实现分裂
• 示例代码陷阱：文档中的代码示例为演示用途，直接复制到生产环境可能缺少边界处理

使用建议

建议与实现层 Skill 组合使用：先用 api-designer 完成契约设计，再交由 FastAPI/NestJS/Spring Boot Engineer 生成可运行代码，最后经 Security Reviewer 审计后上线。