findscripter 何时使用
- 从零设计 REST 或 GraphQL API、为既有 API 做易用性重构、制定团队接口规范时使用。
- 在实现前评审 API 规格（OpenAPI/GraphQL SDL），或在范式间迁移（REST↔GraphQL）时使用。
- 针对特定场景（移动端、第三方集成）优化接口形态时使用。
不该用的边界：
- 写具体业务逻辑/数据库实现代码 → 这是落地编码，本技能只产出接口契约与规范。
- 框架运维、网关部署、容量压测 → 属运维范畴，不在此。
- 接口鉴权漏洞渗透/安全审计 → 交安全类技能；本技能只给出鉴权/限流的设计约定。
步骤 / 指令
1. 选范式
- 资源 CRUD、强缓存、第三方易消费、需 HTTP 语义 → REST。
- 客户端字段差异大、聚合多源、需精确取数避免 over/under-fetch → GraphQL。
2. 建资源/类型模型（先名词，后动作）
- REST：资源用复数名词（/users 不是 /user 或 /getUser），动作交给 HTTP 方法。
- GraphQL：先写 Schema（types/Query/Mutation/Subscription），再写 resolver。
3. 定核心契约
- HTTP 方法语义：GET(安全幂等)/POST(建)/PUT(整体替换,幂等)/PATCH(部分更新)/DELETE(删,幂等)。
- 状态码：2xx 成功 / 4xx 客户端错 / 5xx 服务端错（见示例对照表）。
- 统一错误体：{code,message,details[],timestamp,path}，全站一致。
4. 定分页/过滤/版本
- 分页：小数据集偏移分页(page/page_size)；大数据集/无限滚动用游标(cursor / Relay Connection)。
- 过滤排序：?status=&sort=-created_at&fields=id,name；搜索 ?search=。
- 版本化：优先 URL 版本（/api/v1/...）；或 Accept 头；或 ?version=。第一天就规划破坏性变更。
5. 加保护与可观测
- 限流：返回 X-RateLimit-* 头，超限 429 + Retry-After。
- 文档：REST 用 OpenAPI/Swagger；GraphQL 自带 introspection。
- 健康检查 /health 与 /health/detailed（依赖项探活）。
6. GraphQL 专项
- 输入用 input 类型，变更返回 payload（含 errors 数组）。
- 关系字段一律用 DataLoader 批量加载，防 N+1。
- 加查询深度/复杂度上限防昂贵查询；字段弃用用 @deprecated 不删字段。
规则：
- API 结构不要照搬数据库表结构（避免紧耦合）。
- 别用 POST 做幂等操作，破坏 HTTP 语义预期。
- 错误格式、分页约定、命名风格全站统一，不一处一个样。
示例
REST 资源端点（名词 + 方法，避免动作式 URL）：
GET /api/users # 列表(分页) → 200
POST /api/users # 创建 → 201 + Location 头
GET /api/users/{id} # 取单个 → 200 / 404
PUT /api/users/{id} # 整体替换(含全字段) → 200 / 404
PATCH /api/users/{id} # 部分更新 → 200 / 404
DELETE /api/users/{id} # 删除 → 204 / 404 / 409
GET /api/users/{id}/orders # 浅层嵌套(避免深嵌套)
# 反例(勿用)：POST /api/createUser、POST /api/getUserById
状态码对照：200 GET/PATCH/PUT · 201 POST · 204 DELETE · 400 格式错 · 401 未认证 · 403 无权限 · 404 不存在 · 409 冲突(如邮箱重复) · 422 校验失败 · 429 限流 · 500 服务端错。
统一错误体：
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [{"field":"email","message":"Invalid email format","value":"not-an-email"}],
"timestamp": "2025-10-16T12:00:00Z",
"path": "/api/users"
}
}
GraphQL Schema（Relay 游标分页 + input/payload + 枚举）：
type User {
id: ID!
email: String!
orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
}
type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! }
type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }
enum OrderStatus { PENDING CONFIRMED SHIPPED DELIVERED CANCELLED }
type Mutation { createUser(input: CreateUserInput!): CreateUserPayload! }
input CreateUserInput { email: String! name: String! password: String! }
type CreateUserPayload { user: User errors: [Error!] }
type Error { field: String message: String! }
DataLoader 防 N+1（按 user 批量取 orders）：
from aiodataloader import DataLoader
class OrdersByUserLoader(DataLoader):
async def batch_load_fn(self, user_ids):
orders = await fetch_orders_by_user_ids(user_ids)
grouped = {}
for o in orders:
grouped.setdefault(o["user_id"], []).append(o)
return [grouped.get(uid, []) for uid in user_ids] # 必须按输入顺序返回
# resolver 内：loader = info.context["loaders"]["orders_by_user"]; await loader.load(user["id"])
注意事项
- 集合命名用复数且全站一致；嵌套保持浅层，深层关系改用独立资源（/order-items/{id}/reviews）。
- PUT 必须带全字段（整体替换）；PATCH 只带变更字段；二者语义别混。
- 大集合一律分页；无分页 + 无限流的接口易被滥用拖垮。
- GraphQL 可空性从「可空」起步，确有保证再升为非空；字段弃用走 @deprecated 渐进迁移，不直接删。
- GraphQL 命名：字段 camelCase、类型 PascalCase；自定义标量(Email/DateTime/Money)表达领域类型。
- 幂等写操作（创建订单）支持 Idempotency-Key，重复请求返回缓存结果。
- 缓存用 Cache-Control + ETag/If-None-Match（命中返 304）。
互见
- requires：无。
- related：
code-reviewer（接口规格实现后的代码层正确性审查）；mcp-builder（同属协议/接口契约设计，可借鉴 Schema 与工具定义思路）。 - combines_with：无。
本条采编自 wshobson/agents（MIT）。