联邦 Router 运维与查询计划调优：Apollo Router 实战

# router.yaml —— 最小可用配置
supergraph:
  listen: 0.0.0.0:4000
  introspection: false           # 生产关闭
  query_planning:
    cache:
      in_memory:
        limit: 512MB

health_check:
  listen: 0.0.0.0:8088
  enabled: true

query GetOrderWithUser {
  order(id: "o-1") {
    id
    total
    buyer {
      id
      fullName      # 来自 users 子图
    }
  }
}

# 通过 Router 的 dev 模式或 Apollo Studio 查看 plan
router --dev --config router.yaml

# 或使用 rover 在本地组合并查询
rover supergraph compose --config supergraph.yaml > supergraph.graphql

# router.yaml —— 开启 query plan 日志（谨慎，量大）
plugins:
  experimental.expose_query_plan: true
telemetry:
  instrumentation:
    spans:
      router:
        attributes:
          graphql.plan.node_count: true

# Router 发给 users 子图的实际请求
query ($representations: [_Any!]!) {
  _entities(representations: $representations) {
    ... on User {
      fullName
    }
  }
}

{
  "representations": [
    { "__typename": "User", "id": "u-1" },
    { "__typename": "User", "id": "u-2" }
  ]
}

// users 子图的 __resolveReference 必须批量，否则 N+1
const resolvers = {
  User: {
    // ✅ 用 DataLoader 批量
    __resolveReference: (ref: { id: string }, { loaders }: Context) =>
      loaders.userById.load(ref.id),
  },
};

# router.yaml
health_check:
  listen: 0.0.0.0:8088
  enabled: true
  path: /health

# 子图级别的超时与重试
traffic_shaping:
  all:
    timeout: 10s
    global_rate_limit:
      capacity: 20000
      interval: 1s
  subgraphs:
    orders:
      timeout: 5s

# 用 @override / 熔断实现子图故障时的降级
override_subgraph_url:
  # 灰度：把 users 子图切到降级实例
  users: http://users-canary:4001/graphql

# router.yaml —— 计划缓存，最便宜的优化
supergraph:
  query_planning:
    cache:
      in_memory:
        limit: 512MB
    # 预热高频查询
    warmed_up_queries:
      - query: "query WarmUp { __typename }"

# 实体缓存：跨请求复用实体解析结果
preview_entity_cache:
  enabled: true
  subgraph:
    all:
      enabled: true
      ttl: 30s
    subgraphs:
      users:
        ttl: 60s        # 用户信息变化少，可长缓存
      orders:
        ttl: 5s         # 订单变化频繁，短缓存

# router.yaml —— 导出到 OTLP
telemetry:
  exporters:
    tracing:
      otlp:
        enabled: true
        endpoint: http://otel-collector:4317
  instrumentation:
    spans:
      mode: spec_compliant
      router:
        attributes:
          graphql.operation.name: true
          graphql.operation.type: true
      subgraph:
        attributes:
          subgraph.name: true

# ❌ 深层串行：order → buyer → company → address
# ✅ 用 @key 让字段就近解析，减少跨图依赖
type Order @key(fields: "id") {
  id: ID!
  buyer: User! @provides(fields: "fullName")   # 就近提供，避免额外往返
}

type User @key(fields: "id") {
  id: ID!
  fullName: String! @external
  company: Company!
}

# router.yaml —— 并发与连接
limits:
  http_max_request_bytes: 200000
  parser_max_tokens: 15000
  parser_max_recursion: 500

traffic_shaping:
  all:
    deduplicate_query: true      # 相同子图查询去重
    compression: gzip

# 压测：用 hey 或 k6 观察 Router 在不同并发下的尾延迟
hey -z 60s -c 50 -m POST \
  -H "Content-Type: application/json" \
  -d '{"query":"query { order(id:\"o-1\"){ id total } }"}' \
  http://localhost:4000/

# 子图发布：先 check 再 publish
- name: Subgraph check
  run: |
    rover subgraph check my-graph@current \
      --schema ./subgraph.graphql \
      --name orders

- name: Subgraph publish
  run: |
    rover subgraph publish my-graph@current \
      --schema ./subgraph.graphql \
      --name orders \
      --routing-url https://orders.internal/graphql

# 灰度：新旧 Router 并存，按权重切流
# 通过上层 LB（如 Envoy）配置权重
# 90% → router-v1 (旧 supergraph)
# 10% → router-v2 (新 supergraph)