架构与系统设计 / 系统课时
下单幂等控制
下单幂等控制
支付请求可能因网络超时、客户端重试或并发提交被重复发送。本课建立“幂等键校验、数据库唯一约束、重复请求复用原订单”的完整方案,确保同一业务订单只创建一次,同时能识别参数被篡改的重复请求。
学习目标
- 区分商户订单号与请求编号的职责
- 使用唯一索引阻断并发重复写入
- 为相同请求和冲突请求设计稳定返回策略
重复订单从哪里产生
支付接口返回超时时,商户通常会使用相同参数重试;用户连续点击、网关重放和消息重复消费也可能让多个请求同时到达服务端。仅在代码中“先查询、再插入”并不安全,因为两个线程可能同时查不到记录,随后各自完成插入。
幂等控制必须同时覆盖业务语义和数据库并发。业务层判断“是不是同一次请求”,数据库负责保证“最终只能写入一条记录”。

设计幂等键
merchantNo + merchantOrderNo 表示商户业务订单的唯一身份,适合长期去重;merchantNo + requestId 表示某次接口调用,适合识别网络重试。两组键都应由服务端强制非空,并分别建立唯一索引。
还应保存请求指纹,例如对金额、币种、支付方式和通知地址等稳定字段进行规范化后计算摘要。重复请求命中原订单时,只有指纹一致才能复用原结果;若订单号相同但金额不同,应返回冲突,而不是静默覆盖。下面的 MySQL 脚本可直接验证唯一约束:
DROP TABLE IF EXISTS pay_order;
CREATE TABLE pay_order (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
merchant_no VARCHAR(32) NOT NULL,
merchant_order_no VARCHAR(64) NOT NULL,
request_id VARCHAR(64) NOT NULL,
request_fingerprint CHAR(64) NOT NULL,
amount DECIMAL(18, 2) NOT NULL,
status VARCHAR(20) NOT NULL,
UNIQUE KEY uk_merchant_order (merchant_no, merchant_order_no),
UNIQUE KEY uk_merchant_request (merchant_no, request_id)
);
INSERT INTO pay_order
(merchant_no, merchant_order_no, request_id, request_fingerprint, amount, status)
VALUES
('M10001', 'MO202608030001', 'REQ-001',
'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
100.00, 'PENDING');
INSERT INTO pay_order
(merchant_no, merchant_order_no, request_id, request_fingerprint, amount, status)
VALUES
('M10001', 'MO202608030001', 'REQ-002',
'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
200.00, 'PENDING');预期结果:
第一条 INSERT 成功,影响 1 行。
第二条 INSERT 失败,错误包含:Duplicate entry ... for key 'uk_merchant_order'正确的受理流程
应用层不要把“查询不到”当成最终结论,而应把插入动作作为并发竞争点。推荐流程如下:
- 校验幂等字段并计算请求指纹。
- 先按商户订单号或请求编号查询,命中后直接进入一致性校验。
- 未命中时尝试插入待支付订单。
- 插入发生唯一键冲突时,立即按唯一键回查,而不是再次创建。
- 指纹一致则返回原订单;指纹不一致则返回明确的幂等冲突。
下面是 Spring 服务层的片段示例,依赖已有的 PayOrderRepository、事务配置和统一异常体系:
@Transactional
public PayOrder createOrder(CreateOrderCommand command) {
String fingerprint = fingerprintService.calculate(command);
PayOrder existing = repository.findByMerchantOrder(
command.merchantNo(), command.merchantOrderNo());
if (existing != null) {
return verifyAndReuse(existing, fingerprint);
}
try {
PayOrder order = PayOrder.pending(command, fingerprint);
repository.insert(order);
return order;
} catch (DuplicateKeyException ex) {
// 并发失败方回查获胜请求创建的订单
PayOrder winner = repository.findByMerchantOrder(
command.merchantNo(), command.merchantOrderNo());
return verifyAndReuse(winner, fingerprint);
}
}
private PayOrder verifyAndReuse(PayOrder order, String fingerprint) {
if (!order.getRequestFingerprint().equals(fingerprint)) {
throw new IdempotencyConflictException("订单号已存在,但请求参数不一致");
}
return order;
}该片段的生效行为是:首次请求创建订单;相同参数重试返回同一订单号;并发请求中只有一个事务插入成功;相同幂等键但参数不同的请求返回冲突。可通过并发测试确认数据库中始终只有一条记录。
返回与异常边界
相同请求命中原订单时,应返回原订单当前状态,而不是重新发起支付。若原订单仍处于处理中,接口可以返回处理中状态,并引导商户通过查询接口获取最终结果。
推荐将参数冲突映射为 HTTP 409 Conflict,并返回稳定业务错误码。数据库异常不应直接暴露给调用方;唯一键冲突只是内部并发控制手段,最终响应应由业务语义决定。
订单创建与外部通道调用最好分开处理:先可靠落库,再异步或在独立步骤发起通道请求。这样即使通道超时,重试仍能复用已存在的本地订单。