SpringBoot項目保證接口冪等的五種方法！
1. 冪等概述
1.1 深入理解冪等性
在計算機領域中，冪等（Idempotence）是指任意一個操作的多次執(zhí)行總是能獲得相同的結果，不會對系統(tǒng)狀態(tài)產(chǎn)生額外影響。在Java后端開發(fā)中，冪等性的實現(xiàn)通常通過確保方法或服務調(diào)用的結果具有確定性，無論調(diào)用次數(shù)如何，結果都是可預期的。
上面的定義是目前大多數(shù)文章和書籍對冪等的描述，然而，在實際的互聯(lián)網(wǎng)服務開發(fā)中，冪等性的理論定義與業(yè)務邏輯間的沖突是常見的。
例如，考慮查詢操作，當A系統(tǒng)調(diào)用B系統(tǒng)的查詢接口時，如果首次調(diào)用由于B系統(tǒng)中的程序錯誤而導致業(yè)務邏輯失敗，即使在程序修復后系統(tǒng)A重新使用相同參數(shù)進行重試，B系統(tǒng)可能仍然返回相同的失敗響應。盡管這符合冪等性的定義，卻與實際業(yè)務邏輯不符。同樣，以訂單支付為例，首次調(diào)用由于賬戶余額不足而返回“余額不足”提示，用戶充值后再次使用相同參數(shù)發(fā)起支付請求，服務仍然返回“余額不足”響應，也符合冪等性的定義，但同樣不符合業(yè)務邏輯。
因此，在實現(xiàn)冪等性方案時，應該遵循冪等性方案的目標，而不僅僅是嚴格遵循冪等性的定義。尤其是涉及寫操作的服務，應當更關注防止重復請求帶來的不良副作用，例如重復扣款或退款。
1.2 冪等性的必要性
在微服務和分布式架構中，一個請求可能需要多個服務協(xié)作才能完成。在這個過程中，網(wǎng)絡抖動、系統(tǒng)運行異常等不確定因素使得請求的成功率不可能達到100%，一旦發(fā)生失敗或未知異常，最常見的處理方式就是重試，而重試必然會導致重復請求問題。
冪等設計主要是為了處理重復請求而生的，好的冪等方案可以保證重復請求獲得預期結果，而不產(chǎn)生副作用。 在實際開發(fā)中，以下場景會產(chǎn)生重復請求：
- 用戶不可靠：用戶通過客戶端發(fā)起請求，由于手抖或有意重復點擊，很容易造成導致極短時間內(nèi)發(fā)起多次重復請求。
- 網(wǎng)絡不可靠：網(wǎng)絡抖動、網(wǎng)關內(nèi)部抖動有可能觸發(fā)重試機制，這個在使用消息隊列投遞消息時經(jīng)常會遇到。
- 服務不可靠：在需要保證數(shù)據(jù)一致性的場景中，如果調(diào)用下游服務超時，在無法確認執(zhí)行結果的情況下，常用的處理方法是重試。
在我的SpringCloud微服務專欄《使用RocketMQ實現(xiàn)分布式事務》一文中就遺留了個冪等導致的bug，由于消費端沒做冪等處理，所以在整個消息鏈路中，如果broker沒有收到消費者發(fā)送的ack響應就會發(fā)起重試，從而產(chǎn)生數(shù)據(jù)一致性問題。
1.3 冪等與并發(fā)的關系
在具有并發(fā)寫操作的場景下，通常需要考慮冪等問題。例如，當用戶在極短時間內(nèi)多次提交表單或者使用特殊手段同時提交多個表單時，這就是典型的并發(fā)場景，需要進行冪等性處理。為了防止重復請求被執(zhí)行，服務端需要實施冪等性控制，以避免產(chǎn)生不符合預期的結果。
雖然并發(fā)場景大都存在冪等問題，但冪等問題卻并非并發(fā)場景所特有。冪等設計是為了識別并處理重復請求，而并發(fā)僅僅是重復請求的一種特殊情況。 事實上，只要重復請求涉及寫操作，無論是否并發(fā)，都需要做好冪等處理。舉個例子，用戶在pc端同時開了兩個窗口，間隔10分鐘分別提交表單，所有參數(shù)完全相同，這顯然不屬于并發(fā)，但仍需要進行冪等處理。
在互聯(lián)網(wǎng)領域，并發(fā)處理與冪等性問題緊密相關，這也導致了一些人認為解決冪等性就是解決高并發(fā)的問題。
2. 冪等號的設計
冪等性設計的目的是確保即使在多次接收相同請求的情況下，也只執(zhí)行一次操作，防止重復處理。要實現(xiàn)這一點，通常需要事先約定一個具有唯一性的標識符，如Token或業(yè)務流水號，我們稱之為冪等號(Idempotency Key）。
冪等號有三個關鍵特性：唯一性、不變性和傳遞性。
唯一性確保每個請求都能被準確識別，不變性保證在請求處理期間冪等號保持不變，傳遞性則確保在多系統(tǒng)處理同一請求時，冪等號能夠被傳遞和保持。
冪等號通常有兩種設計方式：
- 非業(yè)務冪等號：通過唯一標識符（如UUID、時間戳或業(yè)務流水號）在調(diào)用方和被調(diào)用方之間明確實現(xiàn)冪等性。由于非業(yè)務冪等號難以通過業(yè)務上下文追溯，因此調(diào)用雙方都必須將其持久化，從而保證請求與冪等號的關系有跡可循。
例如，在DailyMart案例中，訂單服務在調(diào)用庫存服務時會傳遞訂單流水號作為冪等號，以便在多次請求時識別重復操作。 - 業(yè)務冪等號：由業(yè)務元素組合構成的冪等號，如“用戶ID+活動ID”。使用此方法時，調(diào)用方無需單獨持久化冪等號，被調(diào)用方可以根據(jù)請求參數(shù)和業(yè)務上下文直接獲取并組合這些參數(shù)。例如，通過設置“用戶ID”和“活動ID”的聯(lián)合唯一索引來實現(xiàn)冪等性。
3. 冪等的實現(xiàn)方案
冪等性的實現(xiàn)關鍵在于確保相同的請求僅被處理一次，這通?？梢酝ㄟ^設置唯一性約束和檢查來實現(xiàn)。實踐中有六種常見的方案：唯一索引、Token機制、悲觀鎖、樂觀鎖、分布式鎖和狀態(tài)機。
3.1 唯一索引方案機制
唯一索引方案依賴于數(shù)據(jù)庫表中不允許存在具有相同索引值的重復行。這種策略在關系型數(shù)據(jù)庫中廣泛支持，并且能有效利用唯一性約束來確保冪等性。在高并發(fā)場景中，唯一索引能保證當多個線程嘗試同時插入相同記錄時，只有一個線程能成功執(zhí)行，而其他線程將會因違反唯一性約束而拋出異常。
通常，業(yè)務流水表的建立是基于以下核心字段：
id（bigint 類型）：作為主鍵，唯一標識每條記錄。gmt_create（datetime 類型）：記錄的創(chuàng)建時間。gmt_modified（datetime 類型）：記錄的最后修改時間。user_id（varchar(32) 類型）：用戶ID，這個字段也可以作為分表的依據(jù)。out_biz_no（varchar(64) 類型）：外部業(yè)務流水號，即調(diào)用方的冪等號。biz_no（varchar(64) 類型）：內(nèi)部業(yè)務流水號，用于系統(tǒng)內(nèi)部追蹤。status（char(1) 類型）：記錄執(zhí)行狀態(tài)。
在這種設計中，user_id和out_biz_no通常會組合成一個聯(lián)合索引，這樣做能有效避免在并發(fā)情況下的數(shù)據(jù)重復插入問題，從而保障了業(yè)務操作的冪等性。
3.2 Token機制
Token機制是用于防止客戶端重復提交的一種特殊機制，特別適用于客戶端創(chuàng)建訂單等提交表單場景。其執(zhí)行流程如下：
1）當用戶訪問表單頁面時，客戶端請求服務端接口以獲取唯一的Token（可以是UUID或全局ID），服務端生成的Token會被存儲在Redis或數(shù)據(jù)庫中。
2）用戶首次提交表單時，將Token與表單一起發(fā)送至服務端，服務端會驗證Token的存在性，如果Token存在，則執(zhí)行業(yè)務邏輯，并在完成后銷毀Token。
3）用戶再次提交表單時，同樣攜帶Token一起發(fā)送至服務端。但由于Token已被銷毀，服務端無法找到對應的Token，從而拒絕重復提交請求。
3.3 悲觀鎖機制
悲觀鎖依賴數(shù)據(jù)庫提供的鎖機制來實現(xiàn)，整個數(shù)據(jù)處理過程中，數(shù)據(jù)處于鎖定狀態(tài)，并與事務機制配合，能夠有效實現(xiàn)業(yè)務冪等性。操作示例如下：
// 1. 開啟事務
begin；
// 2. 基于冪等號查詢
record = select * from tbl_xxx where out_biz_no = 'xxx' for update;
// 3. 根據(jù)狀態(tài)進行決策
if(record.getStatus() != 預期狀態(tài)){
return;
}
// 4. 更新記錄
update tbl_xxx set status = '目標狀態(tài)' where out_biz_no = 'xxx';
// 5. 提交事務
commit；悲觀鎖主要適用于更新場景，通過串行化請求處理來確保冪等性，但需要小心使用，因為在并發(fā)場景下，重復請求可能會導致線程長時間處于等待狀態(tài)，浪費資源且降低性能。
3.4 樂觀鎖機制
樂觀鎖主要依靠"帶條件更新"（update with condition）來確保多次外部請求的一致性。在系統(tǒng)設計中，可以在數(shù)據(jù)表中添加版本號字段，用于標識當前數(shù)據(jù)的版本。每次對該數(shù)據(jù)表的記錄進行更新時，都需要提供上一次更新的版本號，示例操作如下：
//1. 取出要更新的對象，帶有版本versoin
select * from tablename where id = xxx
//2. 更新數(shù)據(jù)
update tableName set sq = sq-#{quantity},version = #{version}+1 where id = xxx and versinotallow=#{version}樂觀鎖主要適用于更新場景，確保多次更新不會影響結果的一致性。
3.5 分布式鎖機制
分布式鎖與悲觀鎖本質(zhì)上相似，都通過串行化請求處理來實現(xiàn)冪等性。與悲觀鎖不同的是，分布式鎖更輕量。在系統(tǒng)接收請求后，首先嘗試獲取分布式鎖。如果成功獲取鎖，則執(zhí)行業(yè)務邏輯；如果獲取失敗，則立即拒絕請求。
分布式鎖的核心是識別重復請求，實現(xiàn)串行化處理。但要注意，獲取鎖成功后，業(yè)務邏輯的執(zhí)行并沒有可靠保證。因此，在實際應用中，分布式鎖需要結合事務機制和重試機制，以形成完整的冪等性解決方案。
3.6 狀態(tài)機機制
在許多業(yè)務單據(jù)中，存在有限數(shù)量的狀態(tài)，并且這些狀態(tài)之間的流轉(zhuǎn)順序是固定的。如果狀態(tài)已經(jīng)處于下一個狀態(tài)，那么再次應用上一個狀態(tài)的變更邏輯是不會產(chǎn)生任何效果的，這就確保了有限狀態(tài)機的冪等性。
例如，庫存狀態(tài)通常包括"預扣中"、"扣減中"、"占用中"和"已釋放"等狀態(tài)。如果系統(tǒng)重復調(diào)用扣減接口，而庫存狀態(tài)已經(jīng)是"扣減中"，則可以直接返回結果。
狀態(tài)機可以與樂觀鎖機制結合使用，示例操作如下：
update tableName set sq=sq-#{quantity},status=#{udpate_status} where id =#{id} and status=#{status}3.7 小結
上面介紹了冪等方式的6種實現(xiàn)方案并簡單介紹了每周方案的適合場景，這些方案的技術路線可以總結成三條：唯一索引、唯一數(shù)據(jù)、狀態(tài)機約束。
唯一索引是指數(shù)據(jù)庫唯一索引，唯一索引大部分是基于業(yè)務流水表建立，也可單獨建表實現(xiàn)；唯一數(shù)據(jù)是指悲觀鎖、樂觀鎖、分布式鎖等機制；狀態(tài)機約束，對于存在狀態(tài)流轉(zhuǎn)的業(yè)務，通過狀態(tài)機的流轉(zhuǎn)約束，可以實現(xiàn)有限狀態(tài)機的冪等。
需要注意的是：在實際開發(fā)中，這些方案單獨使用很難奏效，比如悲觀鎖、分布式鎖只是將請求串行化處理，對于出現(xiàn)異常后的重試并沒有什么抵御能力，需要搭配唯一索引才能形成完整的冪等方案。而在唯一索引方案中也還需要搭配事務機制才能生效。所以需要結合具體的業(yè)務場景靈活運用上面的實現(xiàn)方案。
以上介紹了六種實現(xiàn)冪等性的方式，每種方式的適用場景和關鍵信息。這些方式可以總結為三個技術路線：唯一索引、唯一數(shù)據(jù)和狀態(tài)機約束。
需要注意的是，在實際開發(fā)中，單獨使用這些方式可能無法完全解決問題。例如，悲觀鎖和分布式鎖只將請求串行化處理，沒有處理異常后的重試，因此需要結合唯一索引來實現(xiàn)完整的冪等性解決方案。同樣，因此，在實際應用中，需要根
以上介紹了六種實現(xiàn)冪等性的方式，并簡要介紹了每種方式適用的場景和關鍵信息。這些方式可以總結為三個技術路線：唯一索引、唯一數(shù)據(jù)和狀態(tài)機約束。
- 唯一索引指的是數(shù)據(jù)庫的唯一索引，通?；跇I(yè)務流水表創(chuàng)建，也可以單獨創(chuàng)建表來實現(xiàn)。
- 唯一數(shù)據(jù)包括悲觀鎖、樂觀鎖、分布式鎖等機制。
- 狀態(tài)機約束適用于具有狀態(tài)流轉(zhuǎn)的業(yè)務，通過狀態(tài)機的流轉(zhuǎn)約束，可以實現(xiàn)有限狀態(tài)機的冪等性。
然而，需要注意的是，在實際開發(fā)中，單獨使用這些方法往往效果有限。 例如，悲觀鎖和分布式鎖只是將請求串行處理，對于異常情況的重試并沒有足夠的防御能力，因此需要結合唯一索引來實現(xiàn)完整的冪等性解決方案。同樣，唯一索引方案也需要與事務機制結合使用。因此，在實際應用中，需要根據(jù)具體的業(yè)務場景靈活選擇、合理的運用上述實現(xiàn)方法。
4. 代碼實現(xiàn)
在Dailymart項目中，實現(xiàn)了除悲觀鎖以外的五種冪等方案。為了方便使用，我將分布式鎖機制和Token機制封裝在一個單獨的冪等組件dailymart-idempotent-spring-boot-starter中。
在業(yè)務模塊中，只需在pom文件中引入依賴即可使用封裝好的冪等功能。
<dependency>
<groupId>com.jianzh5</groupId>
<artifactId>dailymart-idempotent-spring-boot-starter</artifactId>
<version>${project.version}</version>
</dependency>冪等組件的核心是利用Spring的AOP機制實現(xiàn)。在使用時，只需在需要實現(xiàn)冪等的方法上添加自定義注解@Idempotent，并指定冪等方案IdempotentTypeEnum。
在自定義冪等組件中，分布式鎖方案依賴于Redis。因此，在SpringBoot配置文件中需要加上Redis的相關配置，并添加一些自定義配置，如Redis key的自定義前綴以及分布式鎖key的前綴。
spring:
data:
redis:
host: xxx.xx.xx.xx
port: 29359
dailymart:
cache:
redis:
prefix: "inventory:"
idempotent:
token:
prefix: "token-"
timeout: 30000接下來，結合具體應用場景，演示在DailyMart中如何實現(xiàn)這些冪等方案。
4.1 基于唯一索引實現(xiàn)
用戶下單時需要調(diào)用庫存預扣接口，在這種新增場景下，可以使用唯一索引結合事務機制實現(xiàn)冪等方案。
1、在扣減流水表中給業(yè)務流水字段transactionId加上唯一索引。
2、在Service層讓庫存扣減和庫存修改在同一個事務中，確保出現(xiàn)重復請求時事務回滾，從而保證冪等性。
這部分代碼已在上篇文章中展示，源碼位于com/jianzh5/dailymart/module/inventory/application/service/impl/InventoryServiceImpl.java
4.2 基于樂觀鎖實現(xiàn)
用戶付款時會調(diào)用庫存扣減接口，這種更新場景可以使用樂觀鎖機制來實現(xiàn)冪等方案。在Dailymart中，有兩種實現(xiàn)方式。
4.2.1 基于原生SQL實現(xiàn)
public interface InventoryItemMapper extends BaseMapper<InventoryItemDO> {
/**
* 基于樂觀鎖實現(xiàn)更新
* @param inventoryItemDO 庫存實體
*/
@Update("UPDATE inventory_item SET sellable_quantity = #{sellableQuantity},withholding_quantity = #{withholdingQuantity}, occupy_quantity = #{occupyQuantity} ,version = #{version} + 1 , update_time = NOW() WHERE id = #{id} AND version = #{version} ")
void updateByVersion(InventoryItemDO inventoryItemDO);
}4.2.2 使用mybatis-plus提供的樂觀鎖插件
1、在DO對象中使用@Version注解對樂觀鎖字段進行標注。
public class InventoryItemDO extends BaseDO {
...
@Version
private Integer version;
}2、在mybatis-plus的配置類中添加樂觀鎖插件
public class DailyMartDsAutoConfiguration {
/**
* 設置mybatis-plus攔截器
* 1. 分頁攔截器
* 2. 樂觀鎖攔截器
*/
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
//分頁
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
// 樂觀鎖
interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
return interceptor;
}這樣，當使用inventoryItemMapper.updateById(inventoryItemDO);方法時會自動實現(xiàn)樂觀鎖。
4.3 基于狀態(tài)機實現(xiàn)
用戶退貨時需要調(diào)用庫存釋放接口，可以基于有限狀態(tài)機來實現(xiàn)冪等。
@Override
@Transactional
public void releaseInventory(Long transactionId) {
...
//如果已經(jīng)是釋放狀態(tài)直接返回結果
if(inventoryRecord.getState() == InventoryRecordStateEnum.RELEASE.code()){
return;
}
...
}單一的狀態(tài)機機制不能很好地保證冪等性，因此需要結合樂觀鎖機制才更有效。
4.3 基于Token實現(xiàn)
用戶在創(chuàng)建訂單時需要調(diào)用后臺接口提交表單，像這種客戶端提交表單的操作就很適合使用token機制。
1、在客戶端進入頁面時調(diào)用冪等組件提供的/token方法，后端自動生成token并存儲到Redis中。
@Override
public String createToken() {
String token = Optional.ofNullable(Strings.emptyToNull(idempotentProperties.getPrefix())).orElse(TOKEN_PREFIX_KEY) + UUID.randomUUID();
log.info("Generated Idempotency Key is: {}", token);
distributedCache.put(token, "", Optional.ofNullable(idempotentProperties.getTimeout()).orElse(TOKEN_EXPIRED_TIME));
return token;
}2、在創(chuàng)建訂單接口加上自定義冪等注解，指定冪等類型為Token機制。
@PostMapping("/api/order/create")
@Idempotent(
type = IdempotentTypeEnum.TOKEN,
message = "訂單正在創(chuàng)建，請勿重復提交"
)
public void create(@RequestBody OrderDTO orderDTO) {
orderService.save(orderDTO);
}Token機制也需要結合唯一索引才能形成完整的冪等方案。
4.3 基于分布式鎖實現(xiàn)
使用分布式鎖冪等方案很簡單，在方法上加上冪等注解即可。有兩種使用方式：
1、指定type為IdempotentTypeEnum.PARAM，此時冪等組件會將整個表單的參數(shù)做MD5摘要后作為分布式鎖的key
@Idempotent(
type = IdempotentTypeEnum.PARAM,
message = "訂單正在創(chuàng)建，請勿重復提交"
)
@PostMapping("/api/order/create")
public void create(@RequestBody OrderDTO orderDTO) {
orderService.create(orderDTO);
}2、指定type為IdempotentTypeEnum.SpEL，此時冪等組件會根據(jù)key的值選取參數(shù)作為分布式鎖的key，冪等key可以使用SpEL表達式選擇參數(shù)中的字段。
@Idempotent(
key = "#lockRequest.transactionId", type = IdempotentTypeEnum.SpEL
)
@PostMapping("/api/order/update")
public void update(@RequestBody OrderDTO orderDTO) {
orderService.update(orderDTO);
}通過以上實現(xiàn)，Dailymart項目成功應用了多種冪等性方案，確保了系統(tǒng)的可靠性和穩(wěn)定性。
5. 小結
本文詳細介紹了在分布式系統(tǒng)中冪等性實現(xiàn)方案，同時著重講解了冪等和并發(fā)之間的區(qū)別。一般而言，并發(fā)都會伴隨冪等，而冪等又并非并發(fā)獨有。文章中提供了多種關于冪等的實現(xiàn)方案，不過需要記住，單一使用某種冪等方案往往很難奏效，需要組合多種方式才能形成完整的解決方案。
