幂等验证拦截器 🔄

功能介绍 💡

WARNING

幂等验证拦截器（又称重复请求过滤器）用于防止表单重复提交，确保接口的幂等性，即多次调用与一次调用的结果相同。

应用场景

• ✓ 表单重复提交防护
• ✓ 支付请求幂等控制
• ✓ 订单创建去重
• ✓ 关键操作防重复

配置说明 ⚙️

基础配置参数

参数名	类型	必填	默认值	说明
enabled	boolean	否	false	是否启用拦截器
items	array	是	-	幂等规则列表

幂等规则配置 (items)

参数名	类型	必填	默认值	说明
urls	array	是	-	需要拦截的地址列表
field-name	string	是	-	幂等参数字段名称
parameter-type	string	是	-	参数类型：HEADER/QUERY
expire	string	否	PT10M	过期时间，时间格式说明
business-key	string	否	-	业务标识，用于区分不同业务

TIP

URL匹配规则详见 URL匹配规则说明

配置示例 📝

基础配置

wueasy:
  gateway:
    filter:
      idempotent:
        enabled: true #是否启用，默认false
        items: #规则列表
        - urls: #需要拦截的地址
          - /**
          field-name: uuid #参数字段名称
          parameter-type: HEADER #参数类型
          expire: PT10M #过期时间

多规则配置

wueasy:
  gateway:
    filter:
      idempotent:
        enabled: true
        items:
        - urls:
          - /api/order/**
          field-name: orderToken
          parameter-type: HEADER
          expire: PT30M
          business-key: order
        - urls:
          - /api/payment/**
          field-name: payToken
          parameter-type: QUERY
          expire: PT5M
          business-key: payment

使用说明 📌

1. 客户端调用

POST /api/order/create HTTP/1.1
Host: example.com
uuid: 550e8400-e29b-41d4-a716-446655440000

2. 请求参数说明

• HEADER类型：在请求头中添加幂等标识
• QUERY类型：在URL参数中添加幂等标识

最佳实践 💡

1. 幂等标识生成

   • 使用UUID生成唯一标识
   • 确保标识的唯一性
   • 合理设置过期时间

2. 业务隔离

   • 使用business-key区分业务
   • 不同接口使用不同的field-name
   • 关键操作设置较短的expire时间

注意事项 ⚠️

1. 幂等标识必须唯一
2. 合理设置过期时间
3. 选择合适的parameter-type
4. 注意URL匹配规则的准确性

常见问题 ❓

重复请求未被拦截

• 检查幂等标识是否正确传递
• 验证过期时间是否合理
• 确认URL匹配规则是否正确

正常请求被拦截

• 检查幂等标识是否重复
• 确认过期时间是否过短
• 验证business-key是否配置正确