API 设计 / 系统课时
实现事务与幂等 Mutation
实现事务与幂等 Mutation
Mutation 只保证写入入口,不会自动提供数据库原子性或重试安全。本节把事务边界、幂等键和业务冲突放进同一实现路径,使客户端因超时重试时不会重复创建数据,也不会把不同请求误判为同一次操作。
学习目标
- 能把业务写入与幂等记录放进同一个数据库事务。
- 能用调用方范围、幂等键和请求摘要识别安全重放与键冲突。
- 能区分可缓存的业务结果、应回滚的系统异常和事务外副作用。
先确定事务边界
GraphQL 会按顺序执行同一次操作中的顶层 Mutation 字段,但这不等于数据库自动开启事务,更不代表多个字段天然具有跨 Resolver 原子性。每个需要一致性的业务动作仍应在服务端明确建立事务边界。
以创建订单为例,库存扣减、订单写入和幂等记录如果属于同一数据库,应尽量在一个事务中提交。发送邮件、调用第三方支付等外部副作用不要假装能被数据库事务回滚;需要可靠投递时可把 outbox 记录与业务数据同事务写入,再在提交后异步发送。

为幂等记录建立唯一约束
幂等键不能只按一串字符串全局去重。通常至少要把调用方或租户、Mutation 名称与客户端提供的 key 组成作用域,并保存请求摘要 request_hash。这样同一调用方用同一个 key 重试相同输入时可以重放结果,而同一个 key 被用于不同输入时可以明确报冲突。
下面是 PostgreSQL 的最小表结构。唯一约束负责并发竞争,response_json 保存已经完成的 GraphQL 业务结果。
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)
);预期结果
CREATE TABLE实际项目还应给记录设置保留期限,并通过定时清理控制表规模;保留时间至少要覆盖客户端可能发生重试的窗口。
在同一事务中认领、写入并保存结果
核心流程是“先认领幂等键,再执行业务写入,最后保存可重放结果”。下面是片段示例:假设数据库访问层提供 db.transaction、tx.queryOneOrNull、tx.execute 等方法,且 hashBusinessInput 会对业务输入做稳定序列化后计算摘要。
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 应保持一致。
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预期输出
{"data":{"createOrder":{"order":{"id":"<ID>","status":"CREATED"},"userErrors":[]}}}
{"data":{"createOrder":{"order":{"id":"<ID>","status":"CREATED"},"userErrors":[]}}}两行中的 <ID> 应是同一个实际订单 ID;实际端口和 ID 可能不同。最后再查订单表或业务计数,确认只新增了一条记录,才能证明“响应一致”背后的写入也确实是幂等的。