@umacloud/knowledge 1.0.1

package/api/02-playbooks/graphql-production-playbook.md

@@ -0,0 +1,176 @@
+---
+id: graphql-production-playbook
+title: GraphQL 生产实战手册
+domain: api
+category: 02-playbooks
+difficulty: advanced
+tags: [graphql, api, schema-design, n-plus-1, dataloader, security, introspection, complexity, federation, apollo, enterprise]
+quality_score: 93
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# GraphQL 生产实战手册
+
+> 基于 [GraphQL Conf 2025 Schema Design](https://the-guild.dev/graphql/hive/blog/schema-design-best-practices-part-1) + [StackHawk Security](https://www.stackhawk.com/blog/graphql-security/) + [Zuplo API Design](https://zuplo.com/learning-center/graphql-api-design)
+
+## Schema 设计原则
+
+### 类型设计
+```graphql
+# ✅ 语义化命名，面向能力而非数据库结构
+type Order {
+  id: ID!
+  number: String!          # 订单编号（面向用户）
+  status: OrderStatus!     # 枚举而非 String
+  total: Money!            # 自定义标量（带货币）
+  items: [OrderItem!]!
+  customer: Customer!
+  createdAt: DateTime!
+}
+
+enum OrderStatus {
+  PENDING
+  PAID
+  SHIPPED
+  DELIVERED
+  CANCELLED
+}
+
+# ✅ Money 类型（不用 Float！）
+scalar Money  # { amount: 99.50, currency: "USD" }
+```
+
+### Nullability 策略
+```graphql
+# ✅ 有意识地标 nullable/non-null
+type User {
+  id: ID!              # 必有
+  email: String!       # 必有
+  avatarUrl: String    # 可选（可能没头像）
+  phone: String        # 可选
+}
+# 非必要不用 ! —— 客户端要处理 null，但不会因 null 崩溃
+```
+
+### 分页（Connection 模式）
+```graphql
+type Query {
+  products(first: Int = 20, after: String): ProductConnection!
+}
+
+type ProductConnection {
+  edges: [ProductEdge!]!
+  pageInfo: PageInfo!
+}
+
+type ProductEdge {
+  node: Product!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  endCursor: String
+}
+```
+
+## N+1 问题 + DataLoader
+
+```typescript
+// ❌ N+1：查 100 个订单 → 100 次查客户
+const resolvers = {
+  Order: {
+    customer: (order) => db.query('SELECT * FROM customers WHERE id = ?', order.customerId),
+    // 100 个订单 = 100 次 DB 查询
+  }
+};
+
+// ✅ DataLoader：批量查询（1 次查 100 个客户）
+import DataLoader from 'dataloader';
+const customerLoader = new DataLoader(async (customerIds) => {
+  // 一次性查所有 customerIds
+  const customers = await db.query('SELECT * FROM customers WHERE id IN (?)', [customerIds]);
+  return customerIds.map(id => customers.find(c => c.id === id));
+});
+
+const resolvers = {
+  Order: {
+    customer: (order) => customerLoader.load(order.customerId),
+    // 100 个订单 = 1 次 DB 查询（batch）
+  }
+};
+```
+
+## 安全
+
+### 生产关闭 Introspection
+```typescript
+// ❌ 生产开放 introspection（泄露完整 schema）
+const server = new ApolloServer({ typeDefs, resolvers });
+
+// ✅ 生产关闭（客户端已有 schema）
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  introspection: process.env.NODE_ENV !== 'production',
+});
+```
+
+### 查询复杂度限制
+```typescript
+import { createComplexityRule } from 'graphql-query-complexity';
+
+const server = new ApolloServer({
+  validationRules: [
+    createComplexityRule({
+      maximumComplexity: 1000,    // 最大复杂度
+      variables: {},               // 传入变量计算
+    }),
+  ],
+});
+// 恶意查询 { users { orders { items { product { reviews } } } } } → 拒绝
+```
+
+### 字段级授权
+```typescript
+const resolvers = {
+  User: {
+    email: (user, _, context) => {
+      // 只有本人或 admin 能看 email
+      if (context.userId !== user.id && !context.isAdmin) return null;
+      return user.email;
+    },
+    ssn: (user, _, context) => {
+      // 只有 admin 能看社保号
+      if (!context.isAdmin) throw new ForbiddenError('No access');
+      return user.ssn;
+    },
+  },
+};
+```
+
+### Persisted Queries（减少攻击面）
+```typescript
+// 客户端只发 query hash，不发完整 query
+// 未注册的 query 直接拒绝
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  persistedQueries: {
+    cache: new RedisCache(),
+  },
+});
+```
+
+## 生产检查清单
+- [ ] 生产关闭 Introspection
+- [ ] 查询复杂度限制（防深度/广度攻击）
+- [ ] DataLoader 解决 N+1
+- [ ] 字段级授权（每个 resolver 检查权限）
+- [ ] Persisted Queries（减少攻击面）
+- [ ] 速率限制（按用户/IP）
+- [ ] 错误信息不泄露内部结构
+- [ ] 分页用 Connection 模式（不用全量数组）
+- [ ] Subscription 有连接管理（断线清理）

package/api/03-checklists/api-review-checklist.md

@@ -0,0 +1,55 @@
+---
+id: api-review-checklist
+title: API 代码审查清单
+domain: api
+category: 03-checklists
+difficulty: beginner
+tags: [api, review, checklist, validation, error, security, pagination, openapi, contract]
+quality_score: 88
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# API 代码审查清单
+
+## 契约一致性
+- [ ] OpenAPI 契约与实现一致（路径、方法、状态码）
+- [ ] 每个 operationId 在代码中有对应 handler
+- [ ] 请求/响应 schema 与契约定义匹配
+- [ ] 破坏性变更已版本化（/v2/）
+
+## 输入验证
+- [ ] 每个字段有类型校验
+- [ ] 字符串有长度限制
+- [ ] 数值有范围限制
+- [ ] email/url/uuid 有格式校验
+- [ ] 枚举值在白名单内
+- [ ] 文件上传有大小 + 类型限制
+
+## 错误处理
+- [ ] 每个端点返回标准错误信封
+- [ ] 错误含 code + message + requestId
+- [ ] 400（校验）/401（未认证）/403（无权限）/404（不存在）/409（冲突）/500（服务器）全覆盖
+- [ ] 500 错误不泄露堆栈/SQL
+- [ ] 校验错误列出所有字段问题（不只第一个）
+
+## 安全
+- [ ] 公开端点（login/register）有速率限制
+- [ ] 写操作需要 CSRF token（如适用）
+- [ ] 用户只能访问自己的数据（authorization check）
+- [ ] 敏感字段不返回（password_hash / internal_id）
+- [ ] SQL 注入防护（参数化查询）
+- [ ] CORS 配置正确（不使用 *）
+
+## 性能
+- [ ] list 端点有分页（默认 limit + 上限）
+- [ ] N+1 查询已消除（eager loading）
+- [ ] 响应字段可选择（`?fields=id,name`）
+- [ ] 大响应有缓存头（ETag / Cache-Control）
+- [ ] 慢查询有索引
+
+## 可观测性
+- [ ] 每个请求有 requestId（贯穿日志）
+- [ ] 请求耗时记录
+- [ ] 错误率告警
+- [ ] 结构化日志（JSON 格式）

package/api/04-antipatterns/api-antipatterns.md

@@ -0,0 +1,112 @@
+---
+id: api-antipatterns
+title: API 设计反模式（避坑指南）
+domain: api
+category: 04-antipatterns
+difficulty: intermediate
+tags: [api, antipattern, rest, error, validation, security, n-plus-1, pagination]
+quality_score: 87
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# API 设计反模式（避坑指南）
+
+## 1. 动词路径
+```
+❌ POST /api/createUser
+❌ GET /api/getOrdersByUser?userId=123
+✅ POST /api/users
+✅ GET /api/users/123/orders
+```
+
+## 2. 返回内部错误细节
+```json
+// ❌ 泄露数据库结构
+{
+  "error": "psycopg2.errors.UniqueViolation: duplicate key value violates users_email_key"
+}
+
+// ✅ 标准错误信封
+{
+  "error": {
+    "code": "CONFLICT",
+    "message": "A user with this email already exists",
+    "details": [{"field": "email", "issue": "already registered"}]
+  }
+}
+```
+
+## 3. N+1 查询
+```python
+# ❌ 每个用户单独查订单（N+1）
+for user in users:
+    user.orders = db.query(Order).filter_by(user_id=user.id).all()
+
+# ✅ 一次查全部（eager loading）
+users = db.query(User).options(joinedload(User.orders)).all()
+```
+
+## 4. 不分页的 list 端点
+```python
+# ❌ 返回全部数据
+@app.get("/products")
+def list_products():
+    return db.query(Product).all()  # 10 万行！
+
+# ✅ 强制分页
+@app.get("/products")
+def list_products(page: int = 1, limit: int = Field(default=20, le=100)):
+    return db.query(Product).offset((page-1)*limit).limit(limit).all()
+```
+
+## 5. 缺少幂等性
+```python
+# ❌ POST 不幂等 → 网络重试导致重复创建
+@app.post("/orders")
+def create_order(data):
+    return db.insert(Order(**data))
+
+# ✅ 幂等键防止重复
+@app.post("/orders")
+def create_order(data, idempotency_key: str = Header(...)):
+    existing = db.query(Order).filter_by(idempotency_key=idempotency_key).first()
+    if existing:
+        return existing  # 幂等返回
+    return db.insert(Order(**data))
+```
+
+## 6. 过度暴露字段
+```python
+# ❌ 返回所有字段包括敏感数据
+return user.to_dict()  # 含 password_hash, internal_notes
+
+# ✅ 显式选择返回字段
+return {"id": user.id, "name": user.name, "email": user.email}
+```
+
+## 7. 版本化缺失
+```
+# ❌ 破坏性变更直接改 /api/users
+# 旧客户端在无警告下崩溃
+
+# ✅ 新版本走 /api/v2/users
+# 旧版本至少维护 6 个月 + Sunset 头
+```
+
+## 8. 同步阻塞处理
+```python
+# ❌ 请求内发邮件（阻塞 5 秒）
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    send_welcome_email(user)  # 阻塞！
+    return user
+
+# ✅ 异步队列
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    enqueue_job("send_welcome_email", user.id)  # 非阻塞
+    return user
+```