SuperAPI AI 工具集

api-contract

编程与开发

查看项目

更新于 10-15 19:49

技能介绍

用途:在 FastAPI 后端与 Next.js 前端之间建立类型安全的 API 契约,确保每个接口都有后端 Pydantic 响应模型、前端 Zod 响应 schema 以及文档化的错误响应,避免 schema 漂移和未类型化响应。

主要能力:以“契约三角”为核心,后端 Pydantic response_model 对应前端 Zod schema,并生成 OpenAPI 文档;统一使用 snake_case 字段命名;提供分页包装(PaginationInfo、PaginatedResponse)与错误响应契约(ErrorResponse);支持 URL 版本化与弃用响应头;给出检测契约违规的 rg 命令,如查找缺少 response_model 的路由、返回 dict 的路由、未用 .parse() 校验的前端调用。

使用方式:后端每个路由装饰器声明 response_model、summary、tags 和 responses={};共享 schema 放在 apps/backend/src/api/schemas/{domain}.py,路由专用 schema 内联,领域模型放在 apps/backend/src/models/。前端在 apps/web/lib/api/schemas/ 下创建镜像 Zod schema,类型用 z.infer 推断,API 调用通过 schema.parse(raw) 校验。

适用场景:创建或修改 FastAPI 路由、添加前端 API 调用、审查前后端类型安全、记录 API 错误响应、规划 API 版本化或弃用。

限制:不用于表单输入校验(应使用 data-validation)、错误码分类(error-taxonomy)、重试逻辑或 WebSocket 实时协议。资料未提供安装命令、收费、价格或平台信息。