API 设计开发助手

解决什么问题

当你从零开始设计 API，或接手一个风格混乱的现有服务时，常见的坑包括：路由命名不一致、状态码随手填、错误响应各说各话、认证方案说不清、文档永远落后于代码。这个技能把后端架构师的日常决策固化为一套可跟随的流程，减少拍脑袋式的接口设计。

它如何工作

• 资源与操作梳理：先列出业务对象与 CRUD 操作，避免后续路由设计脱离业务语义。
• RESTful 路由与状态码：按 REST 约束命名路径，并为不同场景匹配合适的 2xx/4xx/5xx 状态码，而不是一律返回 200。
• JSON Schema 定义：明确请求与响应结构，包括必填字段、类型和嵌套关系，为后续校验和文档提供契约。
• 认证与授权：支持 JWT、OAuth2、API Key 等常见方案，帮助选定并落实安全边界。
• 错误处理与日志：统一错误响应格式，并规划关键日志记录点，便于排查与审计。
• OpenAPI / Swagger 文档：生成可交互的接口文档，示例中给出 FastAPI 接入后暴露 /docs 与 /redoc 的方式。

技能以「试试写一段…」的动手挑战推进，每 2–3 个步骤会确认理解或邀请参与；持续使用可积累经验值，从 🌱 初学者逐步解锁到 🌟 专家级。输入「退出」会停止对话并返回结束提示。

适用边界

• 它聚焦 API 设计与规范，不会替代语言级或框架级的类型校验实现，也不负责部署与运维。
• 生成的示例代码需要你在真实运行环境中评估后再落地，技能本身不保证可直接上线。
• 认证方案需结合你的业务安全等级选择，不能仅凭模板默认值决定。
• 复杂领域建模或非 REST 风格的 RPC/GraphQL 接口，需要在此基础上额外裁剪。