REST 到 GraphQL 的渐进迁移：绞杀者模式与双栈并存

// GraphQL 字段 → 调用既有 REST 服务（迁移期最常见）
const resolvers = {
  Query: {
    user: async (_p, { id }, ctx) => {
      const res = await ctx.rest.get(`/api/v1/users/${id}`);
      return normalizeUser(res);   // REST DTO → GraphQL 类型
    },
  },
};

# 边缘路由规则：按客户端版本分流
routes:
  - match: { header: { x-client: "web/2.*" } }
    backend: graphql-gateway
  - match: { header: { x-client: "web/1.*" } }
    backend: rest-legacy
  - match: { path_prefix: "/api/v1" }
    backend: rest-legacy

// 写法 A：字段级 resolver 直接调 REST
const resolvers = {
  Order: {
    items: (order, _a, ctx) => ctx.rest.get(`/api/v1/orders/${order.id}/items`),
  },
};

// 写法 B：用 DataLoader 批量调 REST，避免 N+1
new DataLoader<string, OrderItem[]>(async (orderIds) => {
  const res = await ctx.rest.post('/api/v1/orders/batch-items', {
    ids: [...orderIds],
  });
  return groupByOrderId(res, orderIds);
});

// REST DTO 与 GraphQL 类型往往不一致，需要显式映射
interface RestOrderDTO {
  order_id: string;      // 下划线命名
  total_amount: number;  // 分为单位
  buyer: { uid: string; name: string };
}

function normalizeOrder(dto: RestOrderDTO): Order {
  return {
    id: dto.order_id,
    total: dto.total_amount / 100,   // 分 → 元，注意精度
    buyerId: dto.buyer.uid,
  };
}

/**
 * @migration rest-orders
 * @remove_after 2026-12-31
 * @owner team-commerce
 * REST 端点 /api/v1/orders 下线后删除此适配器
 */

// 客户端：用特性开关控制数据源
const useGraphQL = flags.isEnabled('graphql-orders', { userId });

const { data } = useGraphQL
  ? useGraphQLQuery(GetOrderDocument, { variables: { id } })
  : useRestQuery(`/api/v1/orders/${id}`);

# 灰度配置：按用户百分比放量
flag: graphql-orders
rollout:
  - stage: 1
    percent: 5
    duration: 2d
  - stage: 2
    percent: 25
    duration: 3d
  - stage: 3
    percent: 100

// 迁移期：并行调用双栈，比对响应是否等价（影子流量）
async function shadowCompare(orderId: string) {
  const [rest, gql] = await Promise.all([
    restClient.get(`/api/v1/orders/${orderId}`),
    gqlClient.query({ query: GetOrderDocument, variables: { id: orderId } }),
  ]);
  const diff = compareDeep(normalizeOrder(rest), gql.data.order);
  if (diff) metrics.migrationMismatch.inc({ field: diff.field });
}

// 边缘中间件：打标并上报
function tagAndReport(req, res, next) {
  const source = req.path.startsWith('/graphql') ? 'graphql' : 'rest';
  const client = req.headers['x-client'] ?? 'unknown';
  metrics.requestTotal.inc({ source, client });
  res.on('finish', () => {
    metrics.latency.observe({ source }, res.getHeader('x-response-time'));
  });
  next();
}

-- 按客户端统计 REST 与 GraphQL 的流量占比
SELECT
  client_version,
  COUNT(*) FILTER (WHERE source = 'rest')    AS rest_calls,
  COUNT(*) FILTER (WHERE source = 'graphql') AS gql_calls,
  ROUND(100.0 * COUNT(*) FILTER (WHERE source = 'graphql') / COUNT(*), 1) AS gql_pct
FROM request_log
WHERE ts > now() - interval '7 days'
GROUP BY client_version
ORDER BY client_version;

// 关键：GraphQL 路径必须与 REST 路径读同一份数据
// 迁移期禁止"双写"——双写是不一致的最大来源
// ✅ 读双栈、写单栈
// ❌ 写双栈（除非有事务保障）

# 写操作迁移必须最谨慎：一次只迁一个 mutation
mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    status
  }
}

## 迁移事故预案（orders 领域）

- **触发条件**：GraphQL 路径错误率 > 1% 或 P95 > 500ms 持续 5 分钟
- **第一动作**：关闭特性开关 `graphql-orders`，回退到 REST
- **通知**：值班 + 迁移负责人 + 业务方
- **复盘**：24 小时内产出不一致数据清单与修复方案

# 迁移看板（每个领域一张卡）
domain: orders
status: migrating
rest_endpoints_total: 8
rest_endpoints_migrated: 5
gql_traffic_pct: 62
blocking_clients: ["mobile/3.1", "partner-api"]
target_date: 2026-12-15

# 1. 确认零流量（按客户端、按端点）
grep 'GET /api/v1/orders' access.log | wc -l   # 应为 0

# 2. 确认无内部依赖（服务间调用）
rg -l '/api/v1/orders' services/

# 3. 确认无定时任务/脚本依赖
rg -l '/api/v1/orders' scripts/ cron/ jobs/

// 清理后：删除适配层，Schema 直接映射领域模型
// 从"REST DTO → 适配 → GraphQL 类型"简化为"领域模型 → GraphQL 类型"