SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 10-15 20:31

技能介绍

用途:在创建或评审 REST/JSON 端点、路由与 API 契约时,提供一致的 HTTP API 设计规范,让接口契约清晰、稳定,避免临时拼凑的端点。

主要能力:

  • 契约:可预测的 GET/POST/PATCH/DELETE 资源与动词;资源名用复数、ID 不透明、查询参数有文档;请求/响应带 Schema(如 Zod)并派生 TypeScript 类型;不泄露内部字段(密码哈希、令牌、非必要 PII);公开或外部消费的 API 用路径(/v1)或 Header 做版本化。
  • 错误:使用正确 HTTP 状态码(400、401、403、404、409、422、429、500);错误体稳定为 { code, message, details? },code 机器可读、message 对用户安全;生产环境不暴露堆栈;区分客户端校验错误与服务端内部故障。
  • 分页与过滤:大列表优先游标分页,偏移仅在简单有限时用;限制 page size 并拒绝过大值;排序确定;文档化支持的过滤器。
  • 幂等与变更:PUT/DELETE 在合适时保持幂等;关键 POST(支付、任务)接受 Idempotency-Key;复合写入用事务;返回更新后的资源,或 202 加 location 表示异步。
  • 授权:区分认证与授权,认证不等于已授权;敏感路由在服务端校验归属/角色;认证与昂贵端点做限流;显式配置 CORS 与 Cookie,遵循最小权限;服务商 Webhook 用 HMAC 校验而非开放 POST。
  • 可观测性:记录 request id、user id(如有)、路由、状态、延迟;不记录密钥或完整敏感载荷;按端点统计错误与延迟指标。

反模式:一个端点做所有事;200 状态却把错误放在 body 且无约定;未版本化就破坏客户端;仅前端校验;简单 GET 背后隐藏 N+1。

完成标准:输入/输出 Schema 已定义;错误与状态码一致;敏感路由覆盖授权;分页与限流安全;契约可被仓库中至少一个真实客户端使用。

限制:资料未提供具体安装命令、代码示例、价格与平台支持信息。