API 设计 / 系统课时

构建请求级 Context

构建请求级 Context

GraphQL Resolver 不应自行读取全局用户状态或临时创建请求资源。本篇把身份、数据源、日志器和请求级缓存集中到 Context,并验证同一次操作共享一个 Context、不同请求彼此隔离。

学习目标

  • 说明 Context 的生命周期,以及它为什么不能承载跨请求可变状态
  • 构造包含用户身份、数据源、日志器和请求级资源的 Context
  • 在 Resolver 中只通过 Context 访问请求依赖,并验证请求之间不会串数据

Context 的边界

Context 是一次 GraphQL 操作执行时传给 Resolver 的共享对象。一个操作里的多个 Resolver 应看到同一个 Context;下一次请求则要创建新的 Context。Schema、数据库连接池等可长期复用的对象可以被 Context 引用,但用户身份、DataLoader、事务、追踪 Span、请求缓存等必须按请求创建或绑定。

请求进入 Context 工厂并被多个 Resolver 共享

真正需要避免的是把 Context 当成“全局依赖容器”。如果把当前用户或请求缓存放到模块级变量,并发请求就可能互相覆盖。相反,长期资源负责复用连接,请求级对象负责隔离状态,这两个生命周期应明确分开。

构造并使用 Context

下面的完整示例使用 GraphQL.js。假设当前 Node.js ESM 项目已经安装 graphql 包;两个模拟请求分别以不同 Bearer Token 创建 Context。dataSources 引用可复用的数据访问对象,而 requestCache 和日志事件数组每次都会重新创建。

js
import { buildSchema, graphql } from "graphql";

const schema = buildSchema(`
  type User { id: ID!, name: String! }
  type Post { id: ID!, title: String! }
  type Query {
    me: User!
    post(id: ID!): Post
  }
`);

const users = new Map([
  ["u1", { id: "u1", name: "Alice" }],
  ["u2", { id: "u2", name: "Bob" }],
]);
const posts = new Map([
  ["p1", { id: "p1", title: "Request Context" }],
]);

// 长生命周期对象可以复用,但不要在这里保存“当前用户”等请求状态。
const dataSources = {
  users: { findById: (id) => users.get(id) ?? null },
  posts: { findById: (id) => posts.get(id) ?? null },
};

let requestSequence = 0;

function authenticate(authHeader) {
  const token = authHeader.replace(/^Bearer\s+/, "");
  if (token === "alice-token") return { id: "u1" };
  if (token === "bob-token") return { id: "u2" };
  throw new Error("UNAUTHENTICATED");
}

function createContext(authHeader) {
  const requestId = `req-${++requestSequence}`;
  const events = [];

  return {
    requestId,
    viewer: authenticate(authHeader),
    dataSources,
    logger: { info: (message) => events.push(message) },
    events,
    requestCache: new Map(),
  };
}

function loadPost(context, id) {
  if (context.requestCache.has(id)) {
    context.logger.info(`post:${id}:cache-hit`);
    return context.requestCache.get(id);
  }

  context.logger.info(`post:${id}:db-read`);
  const post = context.dataSources.posts.findById(id);
  context.requestCache.set(id, post);
  return post;
}

const rootValue = {
  me(_args, context) {
    context.logger.info("Query.me");
    return context.dataSources.users.findById(context.viewer.id);
  },
  post({ id }, context) {
    return loadPost(context, id);
  },
};

async function executeRequest(authHeader) {
  const contextValue = createContext(authHeader);
  const result = await graphql({
    schema,
    source: `{
      me { id name }
      first: post(id: "p1") { id title }
      second: post(id: "p1") { id title }
    }`,
    rootValue,
    contextValue,
  });

  return {
    requestId: contextValue.requestId,
    cacheEntries: contextValue.requestCache.size,
    logs: [...contextValue.events].sort(),
    data: result.data,
  };
}

console.log(JSON.stringify(await executeRequest("Bearer alice-token")));
console.log(JSON.stringify(await executeRequest("Bearer bob-token")));

预期输出

text
{"requestId":"req-1","cacheEntries":1,"logs":["Query.me","post:p1:cache-hit","post:p1:db-read"],"data":{"me":{"id":"u1","name":"Alice"},"first":{"id":"p1","title":"Request Context"},"second":{"id":"p1","title":"Request Context"}}}
{"requestId":"req-2","cacheEntries":1,"logs":["Query.me","post:p1:cache-hit","post:p1:db-read"],"data":{"me":{"id":"u2","name":"Bob"},"first":{"id":"p1","title":"Request Context"},"second":{"id":"p1","title":"Request Context"}}}

两个请求都只读取一次 p1,说明一次操作内共享请求缓存;第二个请求仍然重新发生一次数据库读取,说明缓存没有跨请求泄漏。真实服务通常会把 requestId 换成 UUID 或网关传入的追踪 ID,因此实际值可能不同。

放什么进 Context

Context 适合放“Resolver 需要、且与本次请求有关”的能力或信息。用户身份应来自可信的认证结果,而不是直接相信客户端传入的用户 ID;日志器应预先绑定请求 ID;DataLoader、请求缓存和事务要按请求创建,避免批处理结果或事务状态跨用户复用。

数据库连接池、HTTP Client、静态配置这类线程安全或并发安全的长生命周期对象不必每次重建,可以由 Context 持有引用。反过来,也不要在每个 Resolver 中创建新的 DataLoader 或事务,否则同一请求内部无法共享批处理、缓存和提交边界。

处理创建失败与清理

认证失败最好在创建 Context 时尽早终止,这样后续 Resolver 不会拿到半初始化状态。若 Context 绑定了需要释放的资源,例如请求级事务或追踪 Span,应由承载 GraphQL 的服务器框架在操作完成或异常结束时统一提交、回滚或关闭,而不是把清理逻辑分散到各个 Resolver。

稳定的做法是:长期资源在进程级复用,请求状态在 Context 工厂中创建,Resolver 只消费 Context。这样既能保持依赖清晰,也能把用户隔离、日志关联和请求级缓存放在同一个生命周期边界内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建请求级 Context

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通