用途:在 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 评审。
限制:资料未提供具体版本要求、依赖安装命令、价格或平台信息;部分实现细节需参考对应示例与参考文件。