# elegent-IU

**Repository Path**: itliutong/elegent-iu

## Basic Information

- **Project Name**: elegent-IU
- **Description**: 这是一个基于springboot的优雅的接口幂等性框架。使用这个组件可以让你更轻松、更优雅地在项目中实现接口幂等性处理。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-03-18
- **Last Updated**: 2024-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![](doc/images/logob.png)

# ElegentIU【接口幂等性框架】

#### 介绍

这是一个基于springboot的优雅的接口幂等性框架。使用这个组件可以让你更轻松、更优雅地在项目中实现接口幂等性处理，让你更专注业务代码的开发。它目前支持token、lock两种检查策略。

##### lock检查策略

通过lock机制实现接口的幂等性，示意图如下：

![](doc/images/iu_lock.png)

具体流程步骤：

1. 客户端先请求服务端，会拿到一个能代表这次请求业务的唯一字段
2. 将该字段以 SETNX 的方式存入 redis 中，并根据业务设置相应的超时时间
3. 如果设置成功，证明这是第一次请求，则执行后续的业务逻辑
4. 如果设置失败，则代表已经执行过当前请求，直接返回

##### token检查策略

通过token 机制实现接口的幂等性，示意图如下：

![](doc/images/iu_token.png)

具体流程步骤：

1.客户端会先发送一个请求去获取 token，服务端会生成一个全局唯一的 ID 作为 token 保存在 redis 中，同时把这个 ID 返回给客户端

2.客户端第二次调用业务请求的时候必须携带这个 token

3.服务端会校验这个 token，如果校验成功，则执行业务，并删除 redis 中的 token

4.如果校验失败，说明 redis 中已经没有对应的 token，则表示重复操作，直接返回指定的结果给客户端



#### 使用说明

##### 准备工作

1.在项目中引入依赖

```xml
<dependency>
    <groupId>cn.elegent</groupId>
    <artifactId>elegent-IU</artifactId>
    <version>1.0.0</version>
</dependency>
```
2.在项目配置文件添加配置。

token策略示例如下：

```yaml
elegent:
  iu:
    type: token
    request_name: RequestID
  data:
    type: redis
    redis:
      nodes: 192.168.200.128:6379
```

lock策略示例如下：

```yaml
elegent:
  iu:
    type: lock
    request_name: RequestID
    lock:
      valid_times: 30
  data:
    type: redis
    redis:
      nodes: 192.168.200.128:6379
```

 配置说明：

  （1）type: 接口幂等性策略类型，可选值：lock、token，默认值是lock。

  （2）request_name: 指定head头信息中的名称，缺省值是RequestID

  （3）lock.valid_times :  分布式锁的失效时间（秒），在此时间内，接口不能重复提交。缺省值30。

  （4）data.type ：指定数据中心的类型。默认值为redis。

  （5）data.redis.nodes: redis节点，格式为{ip}:{port},{ip}:{port},{ip}:{port}  ，默认值127.0.0.1:6379

##### 接口幂等性实现

接口幂等性实现，只需要在方法上加上@ElegentIU即可。

##### 用户扩展

###### 用户自定义检查策略

接口幂等性框架目前提供了token、lock两种检查策略，用户也可以自行扩展，步骤如下：

（1）编写检查器类，实现Checker接口，参考以下代码：

```java
/**
 * 用户自定义检查器（分布式锁类型）
 */
@Component
@ConditionalOnProperty(prefix = "elegent.iu", value = "type",havingValue = "xxxx",matchIfMissing = true)
public class XXXXChecker implements Checker {

    @Override
    public boolean check(String uniqueID) {
        //todo: 编写幂等检查逻辑，返回true表示可以访问，返回false表示不可以访问
    }

    @Override
    public void afterSuccess(String uniqueID) {
		//todo: 接口成功执行后，后续的逻辑处理
    }

    @Override
    public void onError(String uniqueID) {
		//todo: 接口执行过程中出错的逻辑处理。
    }

}
```

havingValue指定的就是你想扩展的检查策略名称，名字自定义。

（2）如果应用这个检查策略，在配置文件中指定即可

```yaml
elegent:
  iu:
    type: xxxx
```



#### 参与贡献

1.  从 `master` 分支 `checkout` 一个新分支（**注**：*请务必保证 master 代码是最新的*）
2.  新分支命名格式：`docs/username_description`，例如：`docs/tom_新增分布式锁配置项`
3.  在新分支上编辑文档、代码，并提交代码
4.  最后 `PR` 合并到 `develop` 分支，等待作者合并即可