SuperAPI AI 工具集

api-design-standards

编程与开发

查看项目

更新于 10-15 21:55

技能介绍

用途:在 Grey Haven 项目中创建 API 端点、定义模式和处理错误时遵循统一的 RESTful 设计标准,适用于 FastAPI 后端与 TanStack Start 服务端函数。

主要能力:

  • 资源设计:URL 用复数小写名词与连字符,如 /api/v1/users、/api/v1/organizations/{org_id}/teams;禁止动词和下滑线。HTTP 动词 GET/POST/PUT/PATCH/DELETE 各司其职。
  • 状态码:成功用 200/201/204;客户端错误用 400/401/403/404/409/422;服务端错误用 500/503。
  • 多租户隔离:从 JWT 提取 tenant_id 传入仓库构造器,所有查询自动按租户过滤,防止跨租户数据泄露。
  • FastAPI 路由:使用 APIRouter 前缀与标签,配合 response_model、status_code 和依赖注入。
  • Pydantic 模式:定义 {Model}Create、{Model}Read、{Model}Update,响应绝不返回密码哈希等敏感字段。
  • TanStack Start:用 createServerFn 与 zod 校验器编写服务端函数。
  • 错误格式:统一返回 error、detail、status_code 字段。
  • 分页:支持 offset 分页与游标分页,大数据集推荐游标。
  • OpenAPI:为端点添加 docstring、summary、description,文档位于 /docs 与 /redoc。
  • 限流与 CORS:公共端点用 rate_limit 依赖(默认 100 请求/分钟,Upstash Redis 实现);CORS 允许来源从环境变量读取,生产环境禁止硬编码。

使用方式:按需查阅 examples/(CRUD、模式、TanStack、分页、测试)、reference/(FastAPI 配置、OpenAPI、错误处理、JWT、CORS 与限流)、templates/ 与 checklists/。测试可用 FastAPI TestClient 配合 doppler run --config test -- pytest。

适用场景:新建端点、设计资源层级、编写校验模式、实现分页过滤排序、配置错误格式、设置 OpenAPI、限流与 CORS、多租户隔离、API 测试及 PR 评审。

限制:资料未提供具体版本要求、依赖安装命令、价格或平台信息;部分实现细节需参考对应示例与参考文件。