SuperAPI AI 工具集

fastapi-rest-api-design

编程与开发

查看项目

更新于 10-16 02:39

技能介绍

用途:在设计和评审 FastAPI 的 REST 端点时,提供一套可执行的 REST 设计规范与实现质量检查,覆盖资源命名、HTTP 语义、Schema 质量、依赖边界、安全校验,并输出简洁的评审结果。

主要能力与设计规则:路径使用名词而非动作动词,集合名用复数(如 /projects、/users),单项用稳定标识(如 /projects/{project_id}),名称保持小写一致,嵌套通常不超过两层(如 /projects/{project_id}/models),不暴露内部存储结构;方法语义为 GET 读取、POST 创建、PUT 全量替换、PATCH 部分更新、DELETE 删除,创建返回 201、常规成功 200、无需响应体返回 204,错误码选用 400、401、403、404、409、422、500 并保持跨端点一致;请求与响应使用 JSON 与 Pydantic 模型,字段约束明确(枚举、长度、范围、格式),优先显式响应模型与统一错误体。

架构模式:按资源/领域用 APIRouter 组织路由,用 Depends(...) 注入依赖、避免隐藏全局状态,处理器保持轻薄、业务逻辑放入服务/用例层,服务层抛领域异常并在 API 边界映射为 HTTP 错误,需要出现在 OpenAPI 文档中的自定义错误用 responses={...} 显式声明。

安全与可运维:部署环境强制 HTTPS,逐路由/用例做认证授权与最小权限检查,错误详情不泄露敏感内部信息,大集合端点提供过滤、排序、分页,破坏性变更前引入版本(如 /v1/...)。

评审流程:将端点归类为集合、单项或嵌套资源,核对动词与动作映射、状态码与错误语义、Pydantic Schema 与响应模型、依赖注入与分层边界、认证授权与最小权限,按检查清单报告重要问题。

输出风格:给出端点方案(路由+方法)、契约说明(请求/响应与校验)、安全检查(认证授权与敏感数据处理)、检查清单结论(通过/失败要点)、按优先级排列的修复项。另附检查清单文件 REST_API_CHECKLIST.md。具体安装命令、收费与平台信息暂未提供。