🎯 今日核心问题

  1. 幂等键该由谁生成——模型、你的代码、还是调用方?
  2. 去重表用「插入成功=首次执行」,并发下会不会两个请求都以为自己是首次?
  3. 模型这一轮说要退 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 是会有僵尸的:进程在调用下游时被 kill,记录永远停在 PROCESSING。必须有过期机制(如 updated_at 超过 60s 允许接管),接管时用 UPDATE ... WHERE status='PROCESSING' AND updated_at < NOW()-INTERVAL 60 SECOND 保证只有一个线程抢到。

【三】结果回放,不只防重复,还防「用户看不到结果」

很多人只做到「不重复执行」就停了,结果用户重试时拿到 500,以为没成功。存 result_json 并在命中 SUCCESS 时直接返回原始响应体,才是完整体验。这也是审计要求:一条 refund_order 记录能回答「这次退款是谁、什么时候、基于什么决策触发的」。

去重表的保留策略也要想清楚:不能永久存(会无限膨胀),也不能 7 天就删(跨月对账就断了)。通常按业务窗口保留(退款类 180 天)+ 分区表,并把历史归档到冷存储。

【四】常见误区

💻 代码示例

去重表:唯一索引 + 状态机 + 结果回放。

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、参数级数据范围、以及怎么在一块代码里同时挡住「模型越权调用」和「提示注入诱导的越权」。