核心用法
该Skill作为API设计原则的知识库，主要服务于以下场景：设计新的REST或GraphQL API、评审API规范、建立团队设计标准、重构现有API以及进行架构范式迁移。内容采用决策框架驱动，首先通过对比矩阵帮助用户在REST与GraphQL之间做出技术选型，随后分别提供两套完整的设计规范体系。
对于REST API，Skill覆盖了资源命名规则（复数名词、最大两级嵌套）、HTTP方法与状态码语义映射、分页策略（偏移式与游标式）、过滤排序语法以及统一的错误响应格式。特别提供了FastAPI生产级实现示例，包含Pydantic模型定义、依赖注入、异常处理和分页逻辑。对于GraphQL，则涵盖Relay风格的分页模式、DataLoader模式解决N+1查询问题、查询深度与复杂度限制等高级主题。
Skill还纳入了API治理的关键维度：版本化策略（URL版本与Header版本的权衡）、速率限制的实现方案、以及包含40余项检查点的预发布清单。所有规范均配有"NEVER"反模式警示，帮助开发者规避常见设计陷阱。
显著优点
决策框架的实用性：通过"Choose REST when... / Choose GraphQL when..."的对比表格，将抽象的技术选型转化为可操作的决策标准，降低团队讨论成本。
规范的可落地性：不仅提供设计原则，还包含可直接运行的FastAPI代码模板，涵盖身份验证、分页、错误处理等企业级需求，实现从规范到代码的无缝衔接。
覆盖维度的完整性：从资源命名、HTTP语义到版本治理、速率限制，构建了API全生命周期的设计知识体系，适合作为团队Wiki或入职培训材料。
安全示例设计：代码模板中主动标注安全注意事项（如CORS配置的"Configure for production"注释），体现安全左移的设计理念。
潜在缺点与局限性
技术栈偏向性：示例代码以Python/FastAPI为主，Node.js、Java、Go等生态的开发者可能需要额外适配；GraphQL部分依赖Python的graphene或strawberry-graphql生态，对其他语言支持有限。
版本时效风险：API设计领域持续演进（如gRPC的兴起、JSON Schema 2020-12的更新），Skill基于静态Markdown维护，缺乏自动更新机制，建议用户结合官方RFC和框架最新文档交叉验证。
深度场景的覆盖不足：对于OAuth 2.0/OIDC集成、Webhook设计、事件驱动架构中的API模式、以及超媒体API（HATEOAS）的完整实现等进阶主题，内容相对简略。
无交互式验证：作为纯文档型Skill，无法提供OpenAPI规范实时校验、GraphQL Schema在线测试等交互功能，需配合Swagger UI、GraphQL Playground等外部工具使用。
适合的目标群体
- 后端开发工程师：需要系统性学习API设计规范，或寻求FastAPI项目模板参考
- 技术架构师：评估REST与GraphQL选型，制定团队API设计标准
- 技术Lead/Engineering Manager：建立代码评审Checklist，统一团队交付质量
- 全栈开发者：理解前后端协作接口规范，优化GraphQL查询性能
- API产品经理：理解技术约束，撰写更合理的PRD接口定义
使用风险
性能风险：Skill提供的代码示例为教学性质，未针对高并发场景做优化（如未展示连接池配置、异步数据库驱动选型、缓存策略等），直接用于生产需补充压测和调优。
依赖风险：FastAPI示例依赖Pydantic、Starlette等库的版本兼容性，Skill未锁定依赖版本，建议使用pip freeze或Poetry锁定后使用。
安全合规风险：模板中的CORSallow_origins=["*"]配置若被误用于生产将造成安全隐患；JWT示例若未配置正确的算法白名单（如禁用none算法）可能引入漏洞。
知识固化风险：REST/GraphQL设计存在多种流派（如JSON:API规范、Microsoft REST API Guidelines、Google API Design Guide等），Skill仅代表其中一种实践，关键决策建议结合组织现有技术栈和行业标准多方参考。