架构与系统设计 / 系统课时
回调验签与幂等
回调验签与幂等
仅接收到回调并不代表通知可信,也不代表它只会到达一次。本课建立固定处理顺序:先校验时间窗口和签名,再用数据库唯一键抢占处理权,最后按订单状态机执行一次业务更新。
学习目标
- 基于原始请求字节验证 HMAC 签名并防止时序重放
- 设计稳定的回调幂等键和数据库唯一约束
- 在同一事务中控制订单状态迁移与重复通知响应
固定安全处理顺序
正确顺序是:读取原始字节,检查时间戳与随机数,执行签名验证,计算幂等键,插入幂等处理表,锁定订单并更新状态。签名失败应直接拒绝;唯一键冲突表示此前已接收,可返回渠道成功而不重复执行业务。

不要先解析 JSON 再重新序列化后验签。字段顺序、空格、转义方式或小数格式只要改变,签名字节就可能不同。业务解析与签名验证可以使用同一请求,但验签输入必须保留渠道实际发送的原始字节。
实现原始字节验签
下面的 JDK 17 示例使用 HmacSHA256。签名原文由时间戳、随机数和请求体组成,三部分用换行符连接;真实项目必须严格按渠道文档规定的字段顺序、编码和摘要格式实现。
import java.io.ByteArrayOutputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Duration;
import java.time.Instant;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public final class HmacSignatureVerifier {
private static final String ALGORITHM = "HmacSHA256";
public static String sign(
String secret, String timestamp, String nonce, byte[] rawBody) throws Exception {
ByteArrayOutputStream canonical = new ByteArrayOutputStream();
canonical.write(timestamp.getBytes(StandardCharsets.UTF_8));
canonical.write('\n');
canonical.write(nonce.getBytes(StandardCharsets.UTF_8));
canonical.write('\n');
canonical.write(rawBody);
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), ALGORITHM));
return HexFormat.of().formatHex(mac.doFinal(canonical.toByteArray()));
}
public static boolean isTimestampFresh(
String timestamp, Instant now, Duration maxSkew) {
long callbackEpochSecond = Long.parseLong(timestamp);
long difference = Math.abs(now.getEpochSecond() - callbackEpochSecond);
return difference <= maxSkew.toSeconds();
}
public static boolean verify(
String secret,
String timestamp,
String nonce,
byte[] rawBody,
String providedSignature) throws Exception {
byte[] expected = HexFormat.of().parseHex(sign(secret, timestamp, nonce, rawBody));
byte[] provided = HexFormat.of().parseHex(providedSignature);
// 使用常量时间比较,避免普通字符串比较暴露前缀匹配时间差。
return MessageDigest.isEqual(expected, provided);
}
public static void main(String[] args) throws Exception {
byte[] body =
"{\"notificationId\":\"N1001\",\"status\":\"SUCCESS\"}"
.getBytes(StandardCharsets.UTF_8);
String signature = sign("demo-secret", "1722528000", "n-1001", body);
System.out.println(signature);
System.out.println(verify(
"demo-secret", "1722528000", "n-1001", body, signature));
System.out.println(isTimestampFresh(
"1722528000",
Instant.ofEpochSecond(1722528120),
Duration.ofMinutes(5)));
}
}执行示例
javac HmacSignatureVerifier.java && java HmacSignatureVerifier预期输出
3dc1dcfaa174a7e419950f22ee6d4b6ed3a269e55faad91689e09c77d89d20ab
true
true示例最后一行表示通知时间与服务器时间相差两分钟,仍处于五分钟窗口。生产环境还应把已使用的随机数或通知编号纳入幂等控制。密钥应从密钥管理服务或受保护配置读取,不能写入代码和日志。
用唯一键控制一次处理
建立唯一约束
幂等键优先使用渠道提供的全局通知编号;没有通知编号时,可对“渠道号、渠道订单号、通知类型”等稳定字段做规范化后计算摘要。不要使用接收时间或随机 UUID,因为相同通知重试时这些值会变化。
CREATE TABLE callback_process_guard (
id BIGINT NOT NULL AUTO_INCREMENT,
channel VARCHAR(32) NOT NULL,
dedup_key VARCHAR(160) NOT NULL,
process_status VARCHAR(16) NOT NULL DEFAULT 'PROCESSING',
created_at DATETIME(3) NOT NULL,
processed_at DATETIME(3) NULL,
last_error VARCHAR(500) NULL,
PRIMARY KEY (id),
UNIQUE KEY uk_channel_dedup (channel, dedup_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO callback_process_guard
(channel, dedup_key, created_at)
VALUES ('demo', 'notification:N1001', NOW(3));
INSERT INTO callback_process_guard
(channel, dedup_key, created_at)
VALUES ('demo', 'notification:N1001', NOW(3));预期结果
第一次插入成功,受影响行数为 1。
第二次插入触发 MySQL 1062 重复键错误,唯一索引 uk_channel_dedup 拒绝重复记录。应用捕获 DuplicateKeyException 后,应把它解释为“该通知已经取得过处理权”,直接返回渠道要求的成功响应。不要先执行 SELECT COUNT(*) 再插入,因为两个并发请求可能同时查到不存在,仍会重复进入业务逻辑。
在事务中推进订单状态
下面是片段示例,依赖 Spring 事务、幂等处理仓储和订单仓储。验签应在进入业务事务前完成;事务内部先插入幂等记录,再使用 SELECT ... FOR UPDATE 锁定订单,并只允许合法状态迁移。
@Transactional
public CallbackResult processVerifiedCallback(VerifiedCallback callback) {
try {
callbackGuardRepository.insert(
callback.channel(),
callback.dedupKey());
} catch (DuplicateKeyException duplicate) {
return CallbackResult.DUPLICATE_ACCEPTED;
}
PaymentOrder order =
paymentOrderRepository.findByChannelOrderNoForUpdate(
callback.channelOrderNo());
if (order == null) {
// 抛出异常使事务回滚,释放幂等键,允许渠道稍后重试。
throw new IllegalStateException("order not found");
}
if (order.status() == PaymentStatus.PAID) {
callbackGuardRepository.markProcessed(
callback.channel(), callback.dedupKey());
return CallbackResult.DUPLICATE_ACCEPTED;
}
if (order.status() != PaymentStatus.PAYING) {
throw new IllegalStateException(
"illegal transition: " + order.status() + " -> PAID");
}
paymentOrderRepository.markPaid(order.id(), callback.paidAt());
callbackGuardRepository.markProcessed(
callback.channel(), callback.dedupKey());
return CallbackResult.PROCESSED;
}订单更新、交易流水和幂等处理状态应处于同一事务。若任一步失败,事务整体回滚,刚插入的幂等记录也会撤销,渠道重试时仍可重新取得处理权。原始报文应由独立接收层保留,避免业务事务回滚后丢失审计证据。
验收至少覆盖正确签名、错误签名、过期时间戳、相同通知并发两次、订单已成功后再次通知,以及非法状态迁移。并发测试的最终结果应是幂等处理表只有一条唯一记录,订单只发生一次状态更新,其他请求得到可重复的成功确认。
常见错误包括对解析后的 JSON 验签、用普通字符串比较签名、先查后插实现幂等、在事务提交前向商户发送不可撤销通知,以及把“重复通知”当成系统错误返回失败。这些做法会分别造成误判、侧信道风险、竞态条件和重复重试。