API 设计与 GraphQL/BFF 聚合层：Schema 设计、N+1、聚合与缓存

客户端(App/Web)
    ↓  GraphQL / BFF 聚合接口（按端定制）
BFF 聚合层（GraphQL Schema / REST 聚合）
    ↓  领域服务 RPC
领域服务（用户、内容、互动、关系）
    ↓
存储（MySQL / Redis / ES）

反模式提醒：
✗ 用 GraphQL 包一切（内部 RPC 也上 GraphQL，徒增复杂度）
✗ BFF 里写业务逻辑（BFF 应只做编排与裁剪，不做业务规则）
✗ 客户端直连领域服务（绕过聚合层，取数碎片化回归）

type Post {
  id: ID!
  author: User!
  content: String!
  images: [Image!]!
  stats: PostStats!
  createdAt: DateTime!
}

type PostStats {
  likeCount: Int!
  commentCount: Int!
  shareCount: Int!
  likedByMe: Boolean!
}

演进规则：
✓ 加字段、加类型、加枚举值（向后兼容）
✗ 删字段、改类型、改必填性（破坏性变更）
△ 弃用字段：标 @deprecated(reason: "...") 保留观察期

串行编排（差）：
用户 → 内容 → 互动 → 关系   总延迟 = 各段之和

并行编排（好）：
        ┌→ 内容
用户 →  ├→ 互动     总延迟 ≈ max(各段)
        └→ 关系

func (r *Resolver) Post(ctx context.Context, id string) (*Post, error) {
    g, ctx := errgroup.WithContext(ctx)
    var p *Post
    var s *Stats
    g.Go(func() error {
        var err error
        p, err = r.postSvc.Get(ctx, id)
        return err
    })
    g.Go(func() error {
        var err error
        s, err = r.statsSvc.Get(ctx, id)
        return err
    })
    if err := g.Wait(); err != nil {
        return nil, err
    }
    p.Stats = s
    return p, nil
}

关键原则：主数据必须成功，附属数据可降级。
用「部分成功」而非「全失败」，避免一个次要下游拖垮整个页面。

N+1 示例：
查询 20 条动态，每条都要 author
→ 1 次查动态列表 + 20 次查作者 = 21 次查询

DataLoader 机制：
1. resolve author 时调用 loader.Load(userID)
2. Load 不立即查询，而是把 userID 放入批次队列
3. 同一 tick 结束后，一次性 LoadBatch([id1..idN])
4. 结果按 key 拆分回填给各调用方

loader := dataloader.NewBatchedLoader(func(ctx context.Context, keys []string) []*dataloader.Result {
    users, err := userSvc.BatchGet(ctx, keys)   // 一次批量查
    results := make([]*dataloader.Result, len(keys))
    m := indexByID(users)
    for i, k := range keys {
        if u, ok := m[k]; ok {
            results[i] = &dataloader.Result{Data: u}
        } else {
            results[i] = &dataloader.Result{Error: ErrNotFound}
        }
    }
    return results
})

cache_key = post:10086:stats
TTL = 30s（统计类）
失效：内容更新时精确删除对应键

指纹 = hash(query, variables, viewer_id, locale)
缓存仅用于「公共字段」查询；含 viewer 字段的走字段级缓存

三层鉴权：
网关层：身份认证（JWT 校验）、IP 限流、查询体积限制
聚合层：字段级授权（@auth 指令 / resolver 内校验）
数据层：租户隔离（行级过滤，防越权）

type User {
  id: ID!
  nickname: String!
  email: String @auth(requires: OWNER)
  phone: String @auth(requires: OWNER)
}

授权规则：
- 公开字段：任何人可读
- 本人字段：viewer == owner 才可读
- 管理字段：viewer.role in [ADMIN] 才可读
- 敏感操作：额外二次校验（如改手机号需验证码）

{
  "data": { "post": { "id": "1", "stats": null } },
  "errors": [
    { "message": "stats unavailable", "path": ["post", "stats"], "extensions": { "code": "DEGRADED" } }
  ]
}

每个 resolver 埋点：
  - 调用次数、P50/P95/P99 延迟
  - 错误率、降级率
  - 下游依赖调用次数（发现 N+1）

演进流程：
1. 新字段上线，老字段保留
2. 老字段标 @deprecated(reason: "use newField")
3. 监控老字段调用量（按客户端/版本）
4. 调用量归零后删除（观察期通常 2~4 个客户端发布周期）

type Post {
  likeCount: Int! @deprecated(reason: "use stats.likeCount")
  stats: PostStats!
}

成本模型：
cost(query) = Σ 字段基础成本 × 分页倍数 × 关联放大系数

示例：
post(first: 20) { comments(first: 50) { author { ... } } }
成本 ≈ 20 × 50 = 1000（乘法放大，需拦截）

持久化查询流程：
1. 构建期：客户端查询文本注册到服务端，得到 hash
2. 运行期：客户端发 hash + 变量
3. 服务端：查白名单 → 命中则执行，未命中报错
好处：零解析开销、防注入、可预审成本