> 版本前提：OpenJDK 17.0.20.1（Temurin / Windows），源码片段引自本机 `lib/src.zip` 中 `java.base/java/util/concurrent/ConcurrentHashMap.java`。运行方式 `javac -encoding UTF-8 *.java` 后 `java <类名>`。数据库唯一索引、Redis、消息队列部分只做机制说明，**本轮未连库、未起 Redis、未接 MQ 实测**。
>
> 一句话结论：`putIfAbsent` 能把同一个幂等键的重复请求挡在**单个 JVM 内**，靠的是「空桶 CAS + 冲突时锁桶头节点」；但只要请求可能落到另一个实例、或进程重启丢掉内存状态，这道防线就不成立——最终兜底必须落在共享存储的唯一约束上。

---

## 起点：一行代码

快递柜的取件码只能开一次柜：刷第二次不会掉出第二个包裹，因为柜门后面有一本「这个码开过没」的登记本。接口幂等（同一个请求执行多次，业务结果和执行一次相同）就是给请求发这样的取件码，而 `ConcurrentHashMap` 常被拿来当那本登记本。

这个类比不太准确的地方很关键：快递柜的码由中心系统统一发放，全网只有一本登记本；而 `ConcurrentHashMap` 只是**当前 JVM 堆里的一本登记本**，另一个实例有另外一本，进程重启还会换一本新本。「一个码只能用一次」在单机成立，在系统层不成立。后面三组实验会把这条边界量出来。

先看最小的一行——它要证明的是：第一次写入返回 `null`，第二次写入返回旧值，业务据此决定创建还是拒绝。

```java
// JDK 17：用 putIfAbsent 的返回值判断「这个 requestId 是不是第一次来」
static String submit(ConcurrentHashMap<String, String> seen, String requestId) {
    String prev = seen.putIfAbsent(requestId, "order-for-" + requestId);
    return prev == null ? "CREATED " + requestId : "REJECT duplicate " + requestId;
}
// main: submit(seen,"req-1001") 调两次
// retry-1            : CREATED req-1001
// retry-2            : REJECT duplicate req-1001
```

为什么「返回 `null` 就等于第一次」这件事可以信？我们跟进去看。

## 第一层：`putIfAbsent` 的入口做了什么

白话结论先行：这个入口什么都没做，只是把 `onlyIfAbsent` 开关拨成 `true`，然后交给真正干活的 `putVal`。

```java
// JDK 17.0.20.1 src.zip · ConcurrentHashMap.java
public V putIfAbsent(K key, V value) {
    return putVal(key, value, true);
}
```

`onlyIfAbsent=true` 的含义是「key 已经存在时，不要覆盖旧值」。于是 `putVal` 的返回值就有了双重语义：**写入成功返回 `null`，命中已有 key 返回旧值**。上面那行 `prev == null` 的判断，本质是在读这个返回值契约，而不是在「先查后写」——后者是两步操作，中间会插进别的线程。

## 第二层：进入 `putVal`

白话结论：`putVal` 先算哈希、定位桶，然后在一个无限循环里按桶的状态分三条路走，每条路都保证「同一个 key 的写入是原子的」。

```java
// JDK 17.0.20.1 src.zip · putVal 开头（省略无关声明）
final V putVal(K key, V value, boolean onlyIfAbsent) {
    if (key == null || value == null) throw new NullPointerException();
    int hash = spread(key.hashCode());          // ① 用 key 的 hashCode 定位
    for (Node<K,V>[] tab = table;;) {
        Node<K,V> f; int n, i, fh; K fk; V fv;
        if (tab == null || (n = tab.length) == 0)
            tab = initTable();                  // 懒初始化表
        else if ((f = tabAt(tab, i = (n - 1) & hash)) == null) {
            ...
```

`spread(key.hashCode())` 把哈希再扰动一次，`(n - 1) & hash` 决定落在哪个桶。所以「两个请求是不是同一个」最终由 **`hashCode` 与 `equals`** 判定：`fk == key || key.equals(fk)`。用 `String` 当幂等键没问题，用没重写 `hashCode` 的自定义对象当键，两次重试会被当成两个不同请求——这是幂等键设计里最容易踩的坑之一。

## 第三层：三个关键分支

白话结论：空桶走 CAS，首节点命中走免锁快速返回，其余情况锁住桶头节点再遍历。三条路都不会让两个线程同时「创建成功」。

```java
// JDK 17.0.20.1 src.zip · putVal 关键分支（按原文次序摘录，加中文注释）
else if ((f = tabAt(tab, i = (n - 1) & hash)) == null) {
    if (casTabAt(tab, i, null, new Node<K,V>(hash, key, value)))
        break;                   // 分支 A：空桶，CAS 写入，不加锁
}
else if ((fh = f.hash) == MOVED)
    tab = helpTransfer(tab, f);  // 扩容中，先帮忙迁移
else if (onlyIfAbsent            // 分支 B：首节点就是要找的 key
         && fh == hash
         && ((fk = f.key) == key || (fk != null && key.equals(fk)))
         && (fv = f.val) != null)
    return fv;                   // 不拿锁，直接把旧值交回去
else {
    V oldVal = null;
    synchronized (f) {           // 分支 C：只锁桶头节点，不锁整张表
        ...
        if (e.hash == hash && ((ek = e.key) == key || key.equals(ek))) {
            oldVal = e.val;
            if (!onlyIfAbsent) e.val = value;   // true 时不覆盖
            break;
        }
    }
    if (oldVal != null) return oldVal;
}
```

- **分支 A**：桶是空的，`casTabAt`（compare and swap，先比再换——改之前确认没别人动过）只有一个线程能成功，失败的线程回到循环重读。
- **分支 B**：`onlyIfAbsent` 的第一节点快速路径，命中就连锁都不拿，直接返回旧值。这正是 `retry-2` 走的路。
- **分支 C**：哈希冲突或链表/树里还有别的节点时，锁住桶头节点 `f` 遍历；命中已有 key 时因为 `onlyIfAbsent=true`，只记 `oldVal` **不覆盖**，循环结束后返回它。

三组源码行为对应三组实测。下面这段要证明的是：8 个线程同时提交同一个 `requestId`，只有一个能赢。

```java
// JDK 17：8 个线程从同一起跑线提交同一个 key
ConcurrentHashMap<String, String> shared = new ConcurrentHashMap<>();
AtomicInteger wins = new AtomicInteger();
CountDownLatch start = new CountDownLatch(1), done = new CountDownLatch(8);
for (int i = 0; i < 8; i++) {
    new Thread(() -> {
        try { start.await(); } catch (InterruptedException e) { return; }
        if (submit(shared, "req-2002").startsWith("CREATED")) wins.incrementAndGet();
        done.countDown();
    }).start();
}
start.countDown(); done.await();
System.out.println("concurrent winners : " + wins.get());
```

```bash
# javac -encoding UTF-8 IdempotencyLab.java && java IdempotencyLab
concurrent winners : 1
final value        : order-for-req-2002
instance-A         : CREATED req-3003
instance-B         : CREATED req-3003
```

`wins=1` 说明 CAS 与桶锁确实把同一 key 的写入串行化了。但紧跟着的两行才是本文的重点：`instance-A` 与 `instance-B` 各持一份 Map，**同一个 `req-3003` 各建了一单**。原子性只在一份 Map 内成立。

## 设计者的取舍

- **空桶无锁、冲突才锁桶**：用 `synchronized(f)` 而不是整表锁，是为了让落在不同桶上的写入完全并行；代价是代码要处理扩容迁移（`MOVED`）和树化，复杂度明显高过 `HashMap`。
- **首节点免锁快速路径**：`onlyIfAbsent` 场景（幂等、缓存填充）读多写少，命中就直接返回，省掉一次加锁。
- **不覆盖旧值**：`putIfAbsent` 保留首次写入的结果，这正是幂等要的「返回首次结果」语义。
- **最关键的代价**：`putVal` 只保证 **Map 状态** 的原子性，**不保证业务副作用的原子性**。业务先创建订单、再写幂等记录，中间进程崩了，记录没落、订单已落，重试还会再建一单。这不是 JDK 的缺陷，是「内存登记本」这个角色的边界。

**它和幂等的关系**：`ConcurrentHashMap` 是单 JVM 内最轻的快闸门；**它和唯一索引的关系**是因果关系——本地防线的这块软肋，正是数据库唯一约束必须存在的原因。

## 一路上的关键角色

- **CAS（`casTabAt`）**：`putIfAbsent` 的机制地基——没有它，空桶并发写入就会两个都成功。
- **`hashCode` / `equals`**：前置知识——它们决定「两个请求算不算同一个」，幂等键用 `String` 最省事。
- **桶级 `synchronized`**：进阶机制——哈希冲突时的串行化手段，锁粒度是桶而非整表。
- **`HashMap`**：对比 + 因果——非线程安全，正是 `ConcurrentHashMap` 被选中的原因；用 `containsKey` 再 `put` 的两步写法即使换成并发容器也不是原子的。
- **幂等键设计**：组合依赖——Map 只负责判定，键的生成时机与粒度决定判定有没有意义。
- **数据库唯一索引**：因果衍生——多实例、重启两个漏洞引出的最终兜底，把「插入冲突」翻译成「返回首次结果」。
- **Redis `SET ... NX`**：同级对比——把登记本搬到共享存储，代价是多一跳网络与过期策略要对齐重试窗口。
- **MQ 重复投递 / 消费端幂等**：应用场景——消息至少一次投递天然产生重复，消费端常用同一套键 + 唯一约束。
- **网关与客户端重试**：因果问题——超时重试、用户连点、消息重投是重复请求的三个主要来源。
- **`computeIfAbsent`**：同级对比——把创建订单的副作用塞进映射函数，映射函数可能被执行不止一次，不适合幂等落单。

## 换个入口会怎样

白话结论：把「登记本」放在哪里，决定了防线的有效范围。

| 方案 | 生效范围 | 进程重启后 | 主要代价 |
| --- | --- | --- | --- |
| `ConcurrentHashMap.putIfAbsent` | 单个 JVM | 失效 | 多实例各自建单 |
| `synchronized` + `HashMap` | 单个 JVM | 失效 | 整表串行，吞吐差 |
| Redis `SET key val NX EX` | 所有实例共享 | 仍有效 | 多一跳网络，过期窗口要 ≥ 最大重试窗口 |
| 数据库唯一索引 | 所有实例共享 | 仍有效 | 需要把冲突转成「回查首次结果」 |

数据库这条路的机制示意（**本轮未连库实测**，仅说明唯一约束如何兜底；MySQL 8.0 语法）：

```sql
ALTER TABLE t_order ADD UNIQUE KEY uk_request_id (request_id);
INSERT INTO t_order (request_id, amount) VALUES ('req-1001', 99);  -- 第一次：成功
INSERT INTO t_order (request_id, amount) VALUES ('req-1001', 99);  -- 第二次：ERROR 1062 Duplicate entry
```

注意唯一索引给的是**原子判定**，不是「先查再插」：`SELECT` 查不到再 `INSERT`，两个并发请求会一起查不到。选型建议很直接：本地 Map 可以作为挡掉大部分重复点击的快闸门，但**落库这一步必须让唯一约束来判**，二者不是二选一。

## 前置知识：读懂这条路需要什么

- **哈希与桶**：Map 用 `hashCode` 把 key 分到数组格子里，冲突时同一格里串成链表或树。
- **CAS**：一条 CPU 级的「比较并交换」指令，失败就重试，是无锁写入的基础。
- **HTTP 重试语义**：超时不等于没执行，客户端重试会自然产生第二个一模一样的请求。
- **数据库唯一约束**：由存储引擎在写入时判定冲突，不受应用并发影响。

## 实践映射

**第一组实验：幂等键必须在重试前生成，并在跨重试时保持不变。** 下面这段要证明的是：每次重试都换新 id，等于没做幂等。

```java
// JDK 17：前半段每次重试换 id，后半段复用同一个业务键
String[] regenerated = {"req-a1", "req-b2", "req-c3"};
for (String id : regenerated) {
    String prev = seen.putIfAbsent(id, "order-for-" + id);
    System.out.println(id + " -> " + (prev == null ? "CREATED" : "REJECT"));
}
String bizKey = "u-7|sku-42|2026-11-13T11:50";   // 用户 + 业务对象 + 时间窗
for (int retry = 1; retry <= 3; retry++) {
    String prev = seen.putIfAbsent(bizKey, "order-1");
    System.out.println("bizKey retry-" + retry + " -> " + (prev == null ? "CREATED" : "REJECT"));
}
```

```bash
# javac -encoding UTF-8 KeyScopeLab.java && java KeyScopeLab
req-a1 -> CREATED
req-b2 -> CREATED
req-c3 -> CREATED
bizKey retry-1 -> CREATED
bizKey retry-2 -> REJECT
bizKey retry-3 -> REJECT
```

**三条落地规则**：

1. 幂等键由调用方在**第一次发起请求时**生成并随每次重试原样带上；由服务端按请求内容临时生成，会被重试体的细微差异打散。
2. 本地 `putIfAbsent` 只做「挡住连点」的快闸门，不要把它当成幂等实现本身；两个实例各建一单的实测输出就是反证。
3. 落库时用唯一约束做原子判定，捕获冲突后**回查首次结果并返回**，让重试拿到与首次相同的响应，而不是抛一个「重复请求」错误。

**常见坑，一句话答案**：

- *Q：用了 `ConcurrentHashMap` 为什么线上还是重复下单？* A：因为它是 JVM 内的登记本，多实例和重启都会让它失效。
- *Q：`containsKey` 再 `put` 哪里不对？* A：两步之间能插进别的线程，不是原子判定。
- *Q：幂等记录该存多久？* A：至少覆盖最大重试窗口，短于窗口等于给重开了一个口子；具体时长按业务重试策略定，本文未做时长实测。
- *Q：本地 Map 判重成功但业务执行失败怎么办？* A：记录要在「成功」之后落，并配状态机/事务处理中间态，这是本地方案最麻烦的一环。

## 收尾：一张调用链路图

```mermaid
graph TD
    A[客户端重试 同一 requestId] --> B[网关 / 服务入口]
    B --> C[putIfAbsent 本地快闸门]
    C -->|返回 null 首次| D[执行业务 创建订单]
    C -->|返回旧值 命中| E[回查并返回首次结果]
    D --> F[写库 唯一索引原子判定]
    F -->|插入成功| G[落幂等记录]
    F -->|ERROR 1062 冲突| E
    G --> H[返回首次结果]
    C -.多实例/重启失效.-> F
```

三条结论带走：

1. `putIfAbsent` 的原子性来自「空桶 CAS + 桶级锁」，`onlyIfAbsent=true` 保证命中旧 key 时返回旧值且不覆盖，这是单 JVM 内可靠的去重原语。
2. 幂等键必须在重试前生成、跨重试保持不变，并表达业务唯一性；每次重生成等于没做幂等。
3. 本地 Map 只是第一道快闸门，跨实例与重启后的最终防线必须放在共享存储的唯一约束上。

## 延伸阅读

`HashMap` 扩容与哈希扰动 → `ConcurrentHashMap` 桶级锁与扩容迁移 → CAS 与 `AtomicInteger` → 数据库唯一索引与冲突处理 → 事务边界与状态机 → 消息队列至少一次投递与消费端幂等 → 网关重试与幂等键透传。

以上实验是最小复现场景，不是真实事故原始记录；数据库与中间件部分为机制说明，未做端到端验证。欢迎在评论区交流你的排查路径，也欢迎指正。


版本前提：OpenJDK 17.0.20.1（Temurin / Windows），源码片段引自本机 lib/src.zip 中 java.base/java/util/concurrent/ConcurrentHashMap.java。运行方式 javac -encoding UTF-8 *.java 后 java <类名>。数据库唯一索引、Redis、消息队列部分只做机制说明，本轮未连库、未起 Redis、未接 MQ 实测。

【Java·并发】跟着一次重复请求走完全程：putIfAbsent 源码分支与幂等边界

把重试建两单读成一条调用链：putIfAbsent → putVal(key,value,true) → 空桶 CAS / 首节点免锁返回 / 桶锁内不覆盖。附 JDK 17.0.20.1 三组实测：8 线程只有 1 个赢、两个实例各建一单、幂等键跨重试复用才拦得住，并说明唯一索引为何是最终防线。

人工智能

深入剖析JDK17 ConcurrentHashMap putIfAbsent的幂等机制：基于CAS与桶级锁实现单JVM原子去重，8线程并发测试仅一个成功。但多实例与重启场景下防线失效，需以数据库唯一索引作为最终兜底。文章通过源码解析、对比实验与选型建议，揭示本地Map与共享存储的边界，指导幂等键设计与系统级幂等实现。

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【Java·并发】跟着一次重复请求走完全程：putIfAbsent 源码分支与幂等边界-腾讯云开发者社区-腾讯云

【Java·并发】跟着一次重复请求走完全程：putIfAbsent 源码分支与幂等边界

【Java·并发】跟着一次重复请求走完全程：putIfAbsent 源码分支与幂等边界

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐