API 设计 / 系统课时

实现事务与幂等 Mutation

实现事务与幂等 Mutation

Mutation 只保证写入入口,不会自动提供数据库原子性或重试安全。本节把事务边界、幂等键和业务冲突放进同一实现路径,使客户端因超时重试时不会重复创建数据,也不会把不同请求误判为同一次操作。

学习目标

  • 能把业务写入与幂等记录放进同一个数据库事务。
  • 能用调用方范围、幂等键和请求摘要识别安全重放与键冲突。
  • 能区分可缓存的业务结果、应回滚的系统异常和事务外副作用。

先确定事务边界

GraphQL 会按顺序执行同一次操作中的顶层 Mutation 字段,但这不等于数据库自动开启事务,更不代表多个字段天然具有跨 Resolver 原子性。每个需要一致性的业务动作仍应在服务端明确建立事务边界。

以创建订单为例,库存扣减、订单写入和幂等记录如果属于同一数据库,应尽量在一个事务中提交。发送邮件、调用第三方支付等外部副作用不要假装能被数据库事务回滚;需要可靠投递时可把 outbox 记录与业务数据同事务写入,再在提交后异步发送。

事务与幂等 Mutation 的提交与重放流程

为幂等记录建立唯一约束

幂等键不能只按一串字符串全局去重。通常至少要把调用方或租户、Mutation 名称与客户端提供的 key 组成作用域,并保存请求摘要 request_hash。这样同一调用方用同一个 key 重试相同输入时可以重放结果,而同一个 key 被用于不同输入时可以明确报冲突。

下面是 PostgreSQL 的最小表结构。唯一约束负责并发竞争,response_json 保存已经完成的 GraphQL 业务结果。

sql
CREATE TABLE idempotency_record (
  scope text NOT NULL,
  key text NOT NULL,
  request_hash text NOT NULL,
  status text NOT NULL CHECK (status IN ('in_progress', 'completed')),
  response_json jsonb,
  created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (scope, key)
);

预期结果

text
CREATE TABLE

实际项目还应给记录设置保留期限,并通过定时清理控制表规模;保留时间至少要覆盖客户端可能发生重试的窗口。

在同一事务中认领、写入并保存结果

核心流程是“先认领幂等键,再执行业务写入,最后保存可重放结果”。下面是片段示例:假设数据库访问层提供 db.transaction、tx.queryOneOrNull、tx.execute 等方法,且 hashBusinessInput 会对业务输入做稳定序列化后计算摘要。

ts
async function createOrder(input: CreateOrderInput, viewerId: string) {
  const scope = `${viewerId}:createOrder`;
  const requestHash = hashBusinessInput({
    sku: input.sku,
    quantity: input.quantity,
  });

  return db.transaction(async (tx) => {
    const claimed = await tx.queryOneOrNull(
      `INSERT INTO idempotency_record(scope, key, request_hash, status)
       VALUES ($1, $2, $3, 'in_progress')
       ON CONFLICT DO NOTHING
       RETURNING scope`,
      [scope, input.idempotencyKey, requestHash],
    );

    if (!claimed) {
      const existing = await tx.queryOne(
        `SELECT request_hash, status, response_json
         FROM idempotency_record
         WHERE scope = $1 AND key = $2`,
        [scope, input.idempotencyKey],
      );

      if (existing.request_hash !== requestHash) {
        return conflictPayload("IDEMPOTENCY_KEY_REUSED");
      }
      if (existing.status === "completed") {
        return existing.response_json;
      }
      return conflictPayload("REQUEST_IN_PROGRESS");
    }

    const order = await insertOrder(tx, input);

    const payload = { order, userErrors: [] };
    await tx.execute(
      `UPDATE idempotency_record
       SET status = 'completed', response_json = $3::jsonb
       WHERE scope = $1 AND key = $2`,
      [scope, input.idempotencyKey, JSON.stringify(payload)],
    );

    return payload;
  });
}

这里的关键不是某个数据库库的 API 名称,而是原子性:如果订单写入失败,幂等记录也应随事务回滚;如果事务已经提交但客户端没收到响应,下一次同 key 重试就返回之前保存的 payload,而不是再次创建订单。

处理冲突与失败结果

相同 key、相同请求摘要表示重试,可以安全重放;相同 key、不同摘要则是调用方错误,应返回稳定的业务冲突码。对于库存不足这类确定性的业务失败,可以把失败 payload 也标记为 completed 并保存,使客户端重试得到一致结果。

数据库断连、死锁重试耗尽、进程崩溃等系统异常不应伪装成已完成业务结果。让事务回滚,并允许客户端在相同 key 下再次尝试。若保留 in_progress 状态超过事务生命周期,则还需要租约或超时恢复机制,避免记录永久卡住。

验证重复请求只产生一次写入

假设 CreateOrderInput 包含 sku、quantity 和 idempotencyKey,并且 Resolver 已按上述规则实现。连续发送两次完全相同的 Mutation,两次响应中的订单 ID 应保持一致。

bash
for i in 1 2; do
  curl -s http://localhost:<PORT>/graphql \
    -H 'content-type: application/json' \
    --data-binary '{"query":"mutation CreateOrder($input: CreateOrderInput!) { createOrder(input: $input) { order { id status } userErrors { code message } } }","variables":{"input":{"sku":"sku-42","quantity":1,"idempotencyKey":"req-1001"}}}'
  echo
done

预期输出

text
{"data":{"createOrder":{"order":{"id":"<ID>","status":"CREATED"},"userErrors":[]}}}
{"data":{"createOrder":{"order":{"id":"<ID>","status":"CREATED"},"userErrors":[]}}}

两行中的 <ID> 应是同一个实际订单 ID;实际端口和 ID 可能不同。最后再查订单表或业务计数,确认只新增了一条记录,才能证明“响应一致”背后的写入也确实是幂等的。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现事务与幂等 Mutation

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

登录哪都通