接口幂等性设计实战：原理、五大方案与代码落地

接口幂等性这事儿，做后端的朋友迟早要正面撞上。我自己的经历是，第一回碰上是在一个支付回调联调现场，对方网关重试了三次，我这边订单状态被翻来覆去地改，最后账对不上，排错排到凌晨。从那以后我就学乖了，任何写接口上线前，先问自己一句：同一笔请求被重复发过来，系统还能不能保证结果一致？这个问题想不清楚，生产环境迟早给你上一课。

这篇文章我就好好拆一拆接口幂等性，从原理讲到方案，再讲到我实际落地时踩过的坑和最终选型。内容面向正在做服务端开发的工程师，也适合刚接触分布式系统、想搞明白“为什么支付接口必须幂等”的新手。我会把那套“唯一索引 + 状态机 + 分布式锁”的组合拳完整讲透，包括每一步的设计理由和代码写法，保证你看完能直接照着做。

1. 什么是接口幂等性，为什么所有后端都绕不开它

1.1 先理解幂等性的数学原意和业务映射

幂等（Idempotent）这个词原本来自数学和抽象代数，说的是某个操作执行一次和执行多次得到的结果是相同的。比如在整数运算里，f(x) = x 就是一个典型的幂等函数，你调用多少次，输入是什么，输出就是什么，不会因为重复调用而产生额外影响。

把这个概念映射到接口层面，含义就变成了：客户端发起同一笔业务请求，无论因为网络超时重试、消息队列重复消费、还是用户手滑双击按钮，服务端处理多次的结果，必须和处理一次保持一致。注意这里说的“结果一致”，不光是返回值一样，更重要的是业务数据的最终状态一致。比如创建订单这笔操作，重复调用十次，数据库里也只能有一条订单；扣减库存的操作，重复执行，库存也只能被扣一次。

很多刚接触这个概念的同学容易把幂等和“返回相同结果”画等号，其实不对。举个例子，查询接口 GET /order/123，每次返回的可能是“待支付”“已支付”“已发货”等不同状态，因为数据本身在变化，但这不叫不幂等。真正的不幂等是，一笔扣款请求被重复执行，账户被扣了两次，或者一个订单被重复创建了两条记录，那才是灾难。

这么说吧，幂等性保护的不是“返回一模一样的响应”，而是“每一次重复请求都不会改变系统的关键业务状态”。这个理解到位了，后面看所有方案都会很通透。

1.2 哪些接口天然幂等，哪些天生有风险

HTTP 协议本身其实是定义了幂等语义的，虽然很多人日常写接口时并不在意，但理解这个基础能帮你快速判断一个接口是否需要做额外防护。

从 HTTP 方法的角度看，GET、PUT、DELETE 在语义上是幂等的。GET 是查询，不改变数据，天然幂等；PUT 是全覆盖更新，你拿同一个报文去更新同一条记录，无论执行多少次，最终数据都是一样的，因为 PUT 是把整个资源替换成请求里指定的样子；DELETE 也一样，删除一个不存在的资源，服务端返回一个“资源不存在”的提示，并不会产生副作用。

真正天生非幂等的是 POST，语义是“新建资源”。同一个 POST 请求被重复发送，理论上就会创建多条资源。而现实业务里，几乎所有高风险操作——创建订单、发起支付、提交审批、发放优惠券——都是 POST 接口。这就是为什么幂等性设计几乎总是和 POST 接口绑定在一起。

但我要提醒一点，语义上的幂等只是协议层面给的标准答案，业务领域里情况更复杂。比如 UPDATE 类操作，如果 SQL 写的是 UPDATE account SET balance = balance + 100 WHERE id = 1，这个操作就不是幂等的，因为每次执行都会让余额增加 100。而如果写成 UPDATE account SET balance = 100 WHERE id = 1，那它就是幂等的。所以，判断一个接口是否幂等，要看具体业务动作的语义，而不是只看请求方法。

1.3 最容易踩进幂等坑的三个真实场景

场景一：支付回调。第三方支付平台通知你的服务器“这笔单支付成功了”，这类回调通常有重试机制，可能同一订单在几十秒内被通知五六次。如果服务端不做幂等处理，每收到一次回调就给用户账户加一次余额，那系统离资金事故就不远了。

场景二：前端重复提交。用户在电商 App 上下单，点了“提交订单”按钮后网络卡顿，页面没有及时跳转，用户又点了一下。此时如果第一个请求其实已经到达服务端并且创建了订单，只是响应没回来，第二个请求又带着同样的商品信息进来，很容易生成两笔完全相同的订单。

场景三：消息队列重复消费。很多人用 MQ 做订单异步处理或库存扣减，但消息队列的“At Least Once”投递语义决定了，在极端情况下同一条消息可能被投递多次。你写消费者逻辑时如果没有幂等处理，重复消费一次就是多扣一次库存，这在电商大促场景里就是资损事故了。

这三个场景是我实际中遇到最多的，也是面试里考察幂等性最常问的场景。它们的共同特征是：业务动作本身不是幂等的，而触发方式天然具备重复性。这类接口，必须在设计和编码阶段就把幂等保护做进去。

2. 五大主流幂等方案横评与选型思路

2.1 方案一：数据库唯一索引/防重表

数据库唯一索引是落地最朴素、也最可靠的一种方案。思路是给业务数据表加一个唯一索引字段，比如订单号、支付流水号、业务唯一键，然后在写入时依赖数据库的唯一约束来挡住重复插入。

举个例子，订单表里加一个 biz_id 字段，并建立唯一索引。创建订单的接口在处理请求时，直接拿着客户端传来的 biz_id 往表里插入。如果这个 biz_id 之前已经存在，插入就会报 DuplicateEntry 异常，程序捕获到这个异常就知道这是一次重复请求，直接返回“订单已存在”的提示即可，不会产生新数据。

防重表的做法是在业务主表之外，单独建一张表，专门记录“哪些请求已经处理过”。这张表只存业务唯一键和请求时间，主业务流程先往防重表里插入一条数据，插入成功说明这是首次请求，继续往下走；插入失败说明重复请求，直接拦截。

数据库方案的优点是绝对可靠，数据库的约束是最终的兜底，任何并发情况下都不会误判。缺点是性能受限于数据库，每一次写操作都要多一次数据库交互；而且防重表如果设计不好，数据会无限增长，需要定期清理。

提示：用防重表时，唯一索引字段建议用 varchar 类型，并控制好长度。主键用自增 ID 就行，不要用业务唯一键做主键，避免以后业务调整时需要改主键结构。另外防重表和业务表的写入操作要在同一个事务里，否则防重记录写进去了业务数据没落库，下次请求还是会被挡住，就闹出“幽灵拦截”了。

2.2 方案二：Token 预申请机制

Token 方案是防重操作里非常常见的一种策略，核心思想是“先领券，再消费”。服务端提供两个接口，第一个接口负责生成一个全局唯一的 Token，并把它存储起来（通常放 Redis，设置过期时间），返回给前端；前端在真正提交业务请求时，必须带上这个 Token。服务端在处理业务请求时，先校验 Token 是否存在——存在就删除它并执行业务逻辑，不存在就判定为重复请求并拒绝。

这个方案的本质是把“防重判断”前置到业务操作之前，并且通过“删除即消费”的机制保证同一个 Token 只能被使用一次。Redis 的 SET key value NX EX 指令可以轻松实现原子性的“检查并删除”效果，或者直接用 Lua 脚本保证“删除”和“执行业务”之间的原子性。

Token 方案的好处是能有效拦截绝大多数重复请求，而且对业务入侵小，业务代码里加一个参数校验就行。坏处是它不是绝对可靠，因为客户端完全可以不走你的 Token 接口，直接伪造请求打过来；而且 Token 的生成和校验本身也有成本。所以我在生产环境里，通常不把 Token 方案作为唯一的防线，而是把它当作拦截“正常用户重复操作”的第一道门槛。

2.3 方案三：乐观锁与版本号

乐观锁方案适用于“更新”类操作的幂等控制，核心是引入版本号（version）字段，更新数据时带上版本号条件，只有版本号匹配时才更新成功。

具体实现是这样的：读取订单数据时，拿到 version = 1；更新订单状态时，执行 UPDATE order SET status = 'PAID', version = 2 WHERE id = 123 AND version = 1。如果这个更新影响的行数大于 0，说明操作成功；如果影响行数为 0，说明在读取和更新之间，数据已经被别人改过了，这次更新就是无效的，直接返回失败或者重新读取重试。

乐观锁解决的典型问题是“ABA 问题”和“丢失更新”。在幂等场景里，它的作用尤为突出：假设支付回调带着 version = 1 进来，第一次更新成功把版本号改成了 2，第二次重复回调再拿 version = 1 来更新，因为版本号不匹配，影响行数为 0，自然就不会重复修改状态。

乐观锁的优点是性能损耗极低，不需要额外加数据库锁。缺点是只适用于有限次预期内的并发修改，如果并发量特别大，很多请求会因版本冲突而失败，用户体验不佳。另外，它需要数据库表里有版本字段，对已有表结构的老系统来说，改造成本稍高。

2.4 方案四：状态机流转校验

状态机方案是很多资深工程师做订单、审批、任务流类系统时一定会考虑的方向。思路是把业务对象的生命周期定义为一系列状态，并规定好状态之间允许的流转路径。处理请求时，先校验当前状态是否允许迁移到目标状态，不允许就直接拒绝。

拿订单来举例，订单状态可以定义为：待支付 -> 已支付 -> 已发货 -> 已完成，以及一个终态：已取消。已支付的订单不能被再次支付，所以支付回调进来后，更新逻辑可以写成 UPDATE order SET status = 'PAID' WHERE id = 123 AND status = 'PENDING_PAY'。这条 SQL 天然带有状态条件，重复回调时，订单状态已经是 PAID 了，status = 'PENDING_PAY' 这个条件不满足，更新影响行数为 0，重复请求就被挡住了。

状态机的强大之处在于它不只是防重，还规范了整个业务的生命周期，防止业务逻辑乱跳状态。比如你不可能让一个已取消的订单变成已发货，这在代码层面就约束死了。坏处是它要求你对业务状态有非常清晰的定义，前期设计成本高，而且不够灵活——如果产品突然要加一个状态，改动会波及所有状态流转判断逻辑。

在幂等性方案组合中，状态机主要用于“更新状态类操作”的保障，和数据库唯一索引配合起来，一个防插入重复，一个防状态乱跳，覆盖了绝大多数幂等需求。

2.5 方案五：分布式锁兜底

前面几种方案在不同层面提供了幂等保障，但有些场景里你会发现它们还不够。比如在集群环境下，多个服务实例同时处理同一笔业务请求，防重表虽然能靠唯一索引挡，但防重表本身的写入也会遇到热点争用；状态机能挡大部分，但两个请求同时进来时，可能都读到同一个旧状态，然后都去更新，虽然 SQL 层面可能挡住了，但业务代码层面已经造成了重复操作。

这时候就需要一把“分布式锁”来做互斥控制。常见的实现是基于 Redis 的 SET lock_key value NX EX，或者基于 ZooKeeper/etcd 的分布式锁。在关键业务操作开始前，先尝试获取锁，获取成功才继续执行，执行完后释放锁；获取失败说明有并发请求正在处理同一笔业务，当前请求直接返回“处理中”或丢弃。

分布式锁的优点是简单直接，能挡住并发绕过，适合高并发下的并发控制。但它的局限性也很明显：锁的粒度、过期时间这些参数需要结合具体业务反复调整。过期时间设短了，业务还没执行完锁就过期了，别的请求就进来了；设长了，如果持有锁的节点挂了，锁要等到超时才能释放，会造成短暂的请求阻塞。

2.6 方案对比速查表与应用建议

到这里，五种主流的幂等方案就都过了一遍。在实际工程项目里，它们一般不是互斥的关系，而是组合使用的关系。我根据自己的实践，把它们放在一张表里做一个横向对比：

选型建议我给个很朴素的思路：创建型接口优先用唯一索引防重表，更新型接口优先用版本号或状态机，用户交互频繁的接口叠加 Token 机制，整个链路如果有并发穿透风险，再在最外层套分布式锁。 这套组合拳我一个一个场景试下来的结论是，任何单打独斗的方案都有死角，组合起来才能做到既可靠又高效。

3. 支付回调与订单创建场景的完整落地实战

3.1 需求背景与整体设计

说了这么多理论，我拿一个具体的生产级案例来把整套方案串一遍。假设你现在要接一个第三方支付平台的支付回调，业务是电商订单支付。支付平台会以异步通知的形式告诉你“订单 12345 已经支付成功”，而且这个通知可能重复发送，间隔从几秒到几分钟不等，直到你返回“成功”给第三方，他们才会停止通知。

这个场景下的幂等目标很明确：同一笔订单，无论支付成功通知来几次，订单状态只能从“待支付”变成“已支付”一次，用户账户余额只能增加一次，支付流水表里只能有一条支付记录。

我的整体设计分三层：

第一层是 Redis 分布式锁，用 lock 键做粗粒度互斥，防止同一订单的并发回调同时进入业务逻辑；第二层是数据库层面的防重表/唯一索引，保证支付流水表里同一个支付单号只能插入一条；第三层是状态机 SQL，保证订单表里“待支付 -> 已支付”的状态流转只能成功执行一次。

这三层各司其职，第一层挡并发穿透，第二层挡数据重复，第三层挡状态错乱。即便某一层失效了，下面的一层还能兜住，整体可靠性远高于单方案。

3.2 幂等键的生成规则与选择

做幂等设计的第一步，是确定幂等键。所谓幂等键，就是标识“这一笔业务请求唯一身份”的字段，所有防重手段都围绕这个键展开。选错幂等键是整个设计里最容易犯的错误。

在支付回调场景里，第三方支付平台会回传一个交易流水号，比如微信支付的 transaction_id，支付宝的 trade_no。这个流水号是支付平台侧生成的全局唯一标识，天然适合做幂等键。

但有个细节要留心：同一个商户订单号，在支付平台侧可能对应多笔支付流水。比如用户付了一次没成功，取消后又重新发起支付，最终支付平台为同一个商户订单生成了两个不同的交易流水号。这时候，如果你把防重键设计成“商户订单号”，第二次回调就会被当作重复请求挡掉，但实际业务上用户确实发生了两笔资金变动，这就出大事了。所以正确做法是，防重键应该用支付平台的交易流水号，而不是商户订单号。

另外，如果是在前端防重复提交场景里，幂等键通常由客户端生成，比如 UUID 或雪花算法生成的 ID，服务端创建订单时把它作为一个 biz_id 字段存储，并建立唯一索引。这个幂等键在业务里除了防重之外，还能当作用户查询这笔业务记录的凭证，一举两得。

3.3 核心代码与关键流程

下面我给出一个简化版但真实的实现代码，注释里写清每一步的意图。

首先是接收支付回调的 Controller 层，这里的核心是获取幂等键、加分布式锁、再进入业务处理：

java复制@PostMapping("/api/payment/notify")
public String paymentNotify(@RequestBody Map<String, String> params) {
    // 从回调参数里取支付平台的交易流水号，这是本场景的幂等键
    String transactionId = params.get("transaction_id");
    String orderNo = params.get("out_trade_no");
    String amount = params.get("total_fee");

    // 前置参数校验，略过……

    String lockKey = "lock:payment:" + transactionId;
    // 尝试获取分布式锁，设置5秒有效期，拿不到锁直接返回“处理中”，让支付平台稍后重试
    boolean locked = redisTemplate.opsForValue()
            .setIfAbsent(lockKey, "1", Duration.ofSeconds(5));
    if (!locked) {
        return "processing";
    }
    try {
        handlePaymentSuccess(transactionId, orderNo, amount);
        return "success";
    } finally {
        redisTemplate.delete(lockKey);
    }
}

然后是核心业务处理方法，这里要同时操作支付流水表和订单表，而且必须在同一个数据库事务里：

java复制@Transactional(rollbackFor = Exception.class)
public void handlePaymentSuccess(String transactionId, String orderNo, String amount) {
    // 第一步：尝试插入支付流水记录，流水号带有唯一索引
    int insertCount = paymentFlowMapper.insertIgnore(transactionId, orderNo, amount);
    // 如果插入影响行数为 0，说明这条流水已经存在，是重复回调，直接返回
    if (insertCount == 0) {
        return;
    }

    // 第二步：用状态机条件更新订单状态
    int updateCount = orderMapper.updateStatusWithCondition(
            orderNo, 
            "PAID", 
            "PENDING_PAY",   // 期望的当前状态
            LocalDateTime.now());
    if (updateCount == 0) {
        // 走到这里意味着流水已入账但订单状态更新失败，需要抛出异常回滚
        throw new IllegalStateException("订单状态流转异常，orderNo=" + orderNo);
    }

    // 第三步：账户余额变更，这里同样用版本号乐观锁避免并发问题
    int balanceUpdate = accountMapper.increaseBalanceWithVersion(
            orderNo, 
            new BigDecimal(amount), 
            version);
    if (balanceUpdate == 0) {
        throw new IllegalStateException("账户余额更新失败，orderNo=" + orderNo);
    }
}

这段代码的三个步骤联动关系是这样的：第一步通过唯一索引挡重复回调，第二步通过状态条件挡状态乱跳，第三步通过版本号挡余额并发更新。每一步都带有自己的幂等保障，而它们又组合在同一事务里，任何一步失败都会整体回滚，不会出现“流水没插进去、订单状态却改了”这种半截账。

对应的 SQL 我贴一下关键部分，防重表的唯一索引和订单状态更新条件：

sql复制-- 支付流水表建表时定义唯一索引
ALTER TABLE payment_flow
    ADD UNIQUE INDEX uk_transaction_id (transaction_id);

-- 插入时使用 INSERT IGNORE，重复插入时影响行数为 0
INSERT IGNORE INTO payment_flow (transaction_id, order_no, amount, create_time)
VALUES (#{transactionId}, #{orderNo}, #{amount}, now());

-- 订单状态机条件更新，status 为当前状态条件
UPDATE `order` 
SET status = 'PAID', pay_time = now() 
WHERE order_no = #{orderNo} 
  AND status = 'PENDING_PAY';

3.4 事务边界与异常处理的细节

这个案例里最容易出错的地方不是方案不会用，而是事务边界掌握不好。我见过不止一个同事，把 Redis 分布式锁的释放放在事务提交之前，结果事务还在处理中锁就没了，并发请求直接穿透进来；也有人把事务注解加在了 Controller 层的方法上，导致事务范围过大，数据库连接持有时间太长，高并发下单时连接池被拖垮。

我的建议是，事务只覆盖业务数据落库的逻辑，也就是 handlePaymentSuccess 这个方法。分布式锁的获取和释放放在事务外层，而且释放锁的操作必须放在 finally 块里，确保任何异常情况下锁都能被释放。Redis 锁的过期时间也别拍脑袋定，需要预估一下事务操作最慢可能耗时多久，我一般设置 5~10 秒，并留出一倍余量。

还有一个异常细节值得重点说：支付流水插入成功、订单状态更新失败时，事务会回滚，流水也会回滚掉。这时候等到第三方支付平台再次回调，流水重新插入，事务重新执行，结果依然正确。这是“事务回滚和幂等设计必须配合”的经典例子——如果流水表插入不放在同一个事务里，而是先插入了不回滚，那下次回调就真的会被当成重复请求挡住，白白丢了这笔支付。

注意：INSERT IGNORE 这种方式只适用于“流水数据已经存在就当成功处理”的场景。如果业务要求重复请求必须给出明确的错误提示，那么用 INSERT 加捕获 DuplicateKeyException 的方式更合适。两种方式的本质逻辑一样，但前者静默丢弃重复，后者可以记录日志、返回特定错误码，需要按业务诉求取舍。

4. 生产环境常见幂等问题排查实录

4.1 问题一：防重表数据无限膨胀

防重表做幂等拦截很可靠，但用久了你会发现一个问题：每天几千万次请求，几乎全是重复的，防重表里塞了上亿条数据，插入性能肉眼可见地下降，磁盘也撑不住。

我当时的处理方式是给防重表加一个“处理时间”字段，每天凌晨跑一个定时任务，删除7天之前的数据。为什么是7天？因为我统计过业务里最长的重试间隔不超过5天，留两天余量刚好。另外更彻底的做法是使用 Redis 的 Set 或 String 来记录已处理的幂等键，设置7天过期时间，天然自动清理，性能也更高。但纯 Redis 方案在极端情况下（Redis 宕机、数据丢失）可能丢失幂等记录，所以核心资金类业务我仍然保留了数据库防重表作为兜底。

4.2 问题二：分布式锁失效导致双重提交

分布式锁本身也会出问题，我踩过一次特别经典的：某次大促期间，Redis 主从切换，锁还没来得及同步到从节点，主节点就挂了，新的主节点上根本没有这把锁，结果同一订单的并发请求全部穿过锁，兵分两路进入业务逻辑。幸好当时业务库里有唯一索引兜底，才没有造成数据重复，但也给我提了个醒——分布式锁不是可靠性的终点，它只是性能屏障，数据库层必须有最终防线。

现在我用 Redisson 的开源实现替代了手写的 SETNX 锁，因为它是基于 Redlock 算法的，对主从切换场景的处理更完善。同时我在所有关键写路径上，依然保留数据库唯一索引和状态机校验，绝不把分布式锁当成唯一保障。

4.3 问题三：补偿逻辑导致状态倒流

状态机校验挡得住重复流转，但挡不住业务补偿逻辑里的“状态倒流”。有一次订单超时未支付，定时任务把订单状态从“待支付”改成了“已取消”。结果用户在此之前其实已经完成了支付，只是支付回调延迟了，等回调到达时发现订单状态是“已取消”，按状态机规则无法流转到“已支付”。

当时的修复方案是，状态机不搞单向死板的流转，而是允许“已取消”在特定条件下回退到“已支付”，但必须附加额外的校验条件——比如支付平台明确返回了成功的交易流水号，且实际金额和订单金额完全匹配，而且流水从未被处理过。这套规则写清楚后，才算真正完成状态机设计。很多人在设计阶段容易忽略这种业务补偿场景，我建议在定义状态流转图时，把所有可能的状态变化路径都列出来，包括异常、超时、人工介入的状况，别怕麻烦，这里想得越细，线上越稳。

4.4 问题四：消息队列重复消费

另外一个高频场景是消息队列的重复消费。很多时候幂等设计做在了 HTTP 接口层，却忽略了 MQ 消费者。比如订单创建成功后发送一条“扣减库存”的消息，消费者从 MQ 里取出来去执行库存扣减，如果消费者在执行业务后还没提交 ACK 就挂了，那这条消息会被重新投递，消费者再次执行，库存就被扣了两次。

MQ 场景的幂等处理和接口场景没有本质区别，同样是使用业务唯一键加唯一索引来防重。我当时为库存扣减操作单独建了一张“库存扣减流水表”，以业务幂等键（比如订单号加商品编码组合）作为唯一索引，消费消息时先尝试插入流水，插入成功才真正执行库存扣减；插入失败说明这条消息已处理过，直接提交 ACK 丢弃即可。这套方案上线后，再也没有出现过因为 MQ 重投导致的重复扣库存问题。

4.5 排查思路五步法

如果线上真的出了幂等相关的数据问题，别慌，我一般按下面这个顺序排查：

第一步，确认现象是不是幂等问题。先看日志里有没有同一笔请求进来了多次，如果没有，那可能是业务逻辑本身的 bug，跟幂等无关。

第二步，定位幂等键的取值。看序列化的日志，确认请求里的幂等键（订单号、交易流水号、业务唯一键）是否稳定，有没有因为字段取值变化而生成不同的幂等键。

第三步，检查防重表/唯一索引是否生效。看数据库里有没有重复数据，如果没有，说明防重逻辑生效了；如果有，说明防重逻辑有漏洞，查代码里是不是漏掉了某条路径的幂等校验。

第四步，看事务边界。核对插入流水的操作和业务状态更新的操作是否在同一个事务里，事务是否正常提交或回滚。

第五步，查并发控制。看同一笔请求是否有并发进入的可能，检查 Redis 锁的过期时间、获取和释放的位置是否合理。

这套排查法我用了很多年，每次都能快速定位到问题出在“幂等键选错”“漏加约束”“事务边界错乱”还是“并发穿透”这四个根因上，效率比瞎翻日志高得多。

写在最后：一点实战心得

接口幂等性这种事，属于“平时不起眼，出事就是大事”的领域。我个人做了这么多年后端，最大的体会是，幂等设计不能靠某一个招式包打天下，必须把唯一索引、状态机、分布式锁、Token 这些手段当成一套组合拳来用。每个方案都有它的优势和死角，只有组合起来，才能在保障可靠性的同时，把性能损耗控制在可接受范围。

一个小小的建议：写代码的每一步都问自己一句“如果这个请求被重放一遍，会不会出问题”。这个习惯养成以后，很多线上故障其实是可以在代码评审阶段就被提前拦下来的。我还喜欢在项目的接口文档里专门列一个“幂等性说明”小节，写清楚每个接口的幂等键是什么、重复请求会返回什么、调用方应该如何处理。这既是对自己系统的负责，也能减少和前端、第三方对接时的沟通成本，值得每个团队都推广一下。