🎯 今日核心问题
- 幂等键该由谁生成——模型、你的代码、还是调用方?
- 去重表用「插入成功=首次执行」,并发下会不会两个请求都以为自己是首次?
- 模型这一轮说要退 100,下一轮又说要退 100,这两次是同一次意图吗?
📖 精读提纲
【一】幂等键绝不能交给模型
让模型在参数里带 requestId 是典型的错法:同一个意图,模型重试时会生成新 UUID,幂等立刻失效。正确来源只有两个——调用方的业务标识(订单退款用 orderId + ":" + decisionVersion),或你自己的执行上下文(会话 id + 本轮意图摘要的 hash)。前者最稳,因为它天然跨会话、跨重试保持不变。
如果做不到业务标识,就用「参数规范化后求 hash」:把 {amount, orderId, reason} 排序序列化后 SHA-256 取前 16 位。这样即使模型换了措辞,只要业务参数一致就是同一个 key。关键词是规范化:BigDecimal 要 stripTrailingZeros,字符串要 trim + 小写,null 与空串要统一。
【二】去重表的核心是唯一索引,不是先查后插
「先 select 再 insert」在并发下必然穿透:两个线程都查不到,都去插。唯一正确姿势是把判断交给数据库:唯一索引上的 insert 成功即获得执行权,DuplicateKeyException 即视为已执行。这是整个幂等设计的支点。
表结构要能区分三种状态,否则你只能知道「重复」,不知道「上次到底成功了没」:
PROCESSING:抢到了执行权,正在调下游。此时重复请求应该等(短轮询)或直接返回 409「处理中」,不能插进去再执行一次。SUCCESS:完成,重复请求直接回放存储的结果(这一步让接口真正幂等,返回体都一致)。FAILED:确定失败(下游明确拒绝),允许同 key 重新执行一次,但要累加 attempt 并设上限。
另外,PROCESSING 是会有僵尸的:进程在调用下游时被 kill,记录永远停在 PROCESSING。必须有过期机制(如 updated_at 超过 60s 允许接管),接管时用 UPDATE ... WHERE status='PROCESSING' AND updated_at < NOW()-INTERVAL 60 SECOND 保证只有一个线程抢到。
【三】结果回放,不只防重复,还防「用户看不到结果」
很多人只做到「不重复执行」就停了,结果用户重试时拿到 500,以为没成功。存 result_json 并在命中 SUCCESS 时直接返回原始响应体,才是完整体验。这也是审计要求:一条 refund_order 记录能回答「这次退款是谁、什么时候、基于什么决策触发的」。
去重表的保留策略也要想清楚:不能永久存(会无限膨胀),也不能 7 天就删(跨月对账就断了)。通常按业务窗口保留(退款类 180 天)+ 分区表,并把历史归档到冷存储。
【四】常见误区
- ❌ 用 Redis
SETNX当唯一权威。Redis 主从切换可能丢 key,只能当「快速挡板」,权威判断必须在 MySQL 唯一索引。 - ❌ 幂等键里包含时间戳。每次都不同,等于没有幂等。
- ❌ 只在 Controller 层做幂等。Agent 内部的工具调用不经过 Controller,必须下沉到工具执行器。
- ❌ 把「同 key 不同参数」当成幂等命中。必须比对参数指纹,不一致直接报冲突,防止模型改金额后复用旧 key。
💻 代码示例
去重表:唯一索引 + 状态机 + 结果回放。
CREATE TABLE agent_idempotency (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
idem_key VARCHAR(128) NOT NULL,
tool_name VARCHAR(64) NOT NULL,
args_hash CHAR(32) NOT NULL,
status VARCHAR(16) NOT NULL, -- PROCESSING / SUCCESS / FAILED
result_json JSON NULL,
attempts INT NOT NULL DEFAULT 1,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
UNIQUE KEY uk_idem (idem_key),
KEY idx_status_updated (status, updated_at)
) ENGINE=InnoDB;
Java 侧:抢锁靠 DuplicateKeyException,不是靠 select。
@Service
@RequiredArgsConstructor
public class IdempotentExecutor {
private static final String Q3 = String.valueOf((char) 34).repeat(3);
private final JdbcTemplate jdbc;
private final ObjectMapper mapper;
private static final Duration STALE = Duration.ofSeconds(60);
private static final int MAX_ATTEMPTS = 3;
public IdemResult run(String idemKey, String tool, Object args, Supplier<String> action) {
String hash = argsHash(args);
Claim claim = tryClaim(idemKey, tool, hash);
switch (claim.state()) {
case FRESH_LOCK -> { /* 抢到,继续执行 */ }
case SUCCESS -> {
String stored = jdbc.queryForObject(
"SELECT result_json FROM agent_idempotency WHERE idem_key = ?",
String.class, idemKey);
return IdemResult.replayed(stored);
}
case CONFLICT ->
throw new BusinessRuleException("幂等键参数不一致,拒绝执行:" + idemKey);
case IN_PROGRESS ->
throw new ConflictException("处理中,请稍后用同一 idemKey 重试");
case FAILED_READY -> { /* 上次确定失败,允许再跑 */ }
}
try {
String result = action.get();
jdbc.update(Q3
UPDATE agent_idempotency
SET status='SUCCESS', result_json=?, updated_at=NOW(3)
WHERE idem_key=?
Q3, result, idemKey);
return IdemResult.executed(result);
} catch (Exception e) {
jdbc.update("UPDATE agent_idempotency SET status='FAILED', updated_at=NOW(3) WHERE idem_key=?",
idemKey);
throw e;
}
}
private Claim tryClaim(String key, String tool, String hash) {
try {
jdbc.update(Q3
INSERT INTO agent_idempotency (idem_key, tool_name, args_hash, status)
VALUES (?, ?, ?, 'PROCESSING')
Q3, key, tool, hash);
return Claim.FRESH_LOCK;
} catch (DuplicateKeyException dup) {
Map<String, Object> row = jdbc.queryForMap(
"SELECT args_hash, status, attempts, updated_at FROM agent_idempotency WHERE idem_key=?",
key);
if (!hash.equals(row.get("args_hash"))) return Claim.CONFLICT;
String status = (String) row.get("status");
if ("SUCCESS".equals(status)) return Claim.SUCCESS;
if ("FAILED".equals(status)) {
int attempts = ((Number) row.get("attempts")).intValue();
return attempts >= MAX_ATTEMPTS ? Claim.CONFLICT : Claim.FAILED_READY;
}
// PROCESSING:只允许接管过期的僵尸记录
int taken = jdbc.update(Q3
UPDATE agent_idempotency
SET updated_at=NOW(3), attempts=attempts+1
WHERE idem_key=? AND status='PROCESSING' AND updated_at < ?
Q3, key, Timestamp.valueOf(LocalDateTime.now().minus(STALE)));
return taken == 1 ? Claim.FAILED_READY : Claim.IN_PROGRESS;
}
}
private String argsHash(Object args) {
try {
String normalized = mapper.writeValueAsString(
new TreeMap<>(mapper.convertValue(args, Map.class)));
return DigestUtils.md5DigestAsHex(normalized.getBytes(StandardCharsets.UTF_8));
} catch (JsonProcessingException e) {
throw new IllegalStateException(e);
}
}
public enum Claim { FRESH_LOCK, SUCCESS, CONFLICT, IN_PROGRESS, FAILED_READY }
public record IdemResult(boolean replayed, String payload) {
static IdemResult replayed(String p) { return new IdemResult(true, p); }
static IdemResult executed(String p) { return new IdemResult(false, p); }
}
}
Agent 侧的 key 生成——用业务标识,不用时间戳:
String idemKey = "refund:" + decision.orderId() + ":" + traceId;
// 同一会话同一订单,无论模型重试几次、循环几轮,key 都不变
return idempotentExecutor.run(idemKey, "createRefund", decision, () -> refundClient.create(decision));
✏️ 今日动手
给 createCompensation 加上幂等:① 建表、加唯一索引,用 JdbcTemplate 走通 FRESH_LOCK→SUCCESS 路径;② 用 20 个线程并发同一个 key,确认只有 1 次真实发券、其余 19 次回放同一结果;③ 故意在 action 里 sleep 90 秒,让记录过期成为僵尸,验证接管逻辑只有一个线程成功;④ 用不同 amount 复用同一 key,确认抛 CONFLICT 而不是静默回放。
🔖 明日预告
幂等解决「重复执行」,但解决不了「执行不该执行的事」。明天讲权限与边界:工具级 RBAC、参数级数据范围、以及怎么在一块代码里同时挡住「模型越权调用」和「提示注入诱导的越权」。