# sparta

**Repository Path**: wilver/sparta

## Basic Information

- **Project Name**: sparta
- **Description**: sparta 是一个开源的，基于 springboot + redisson + redis 的一个轻量级依赖型的延迟队列，内置有丰富的API，且性能高。零配置，开箱即用，设计符合普通 MQ 队列的使用。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 4
- **Created**: 2023-03-07
- **Last Updated**: 2023-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sparta

#### 介绍
`Sparta` 是一款开源的轻量级延迟队列，通过 `jar` 的方法依赖进项目内，无需部署单独服务，开箱即用。`Sparta` 作为延迟队列，支持业务服务分布式部署方式，也支持单服务的部署。`Sparta` 主要依赖于 `spring boot` 框架，根据业务可选择中间件依赖 `redis` 或者 `etcd` 或 `dragonfly` (`redis 替代方案`)  ，也可以自行实现。Sparta 能保证消息延迟在 `10ms` 以内，高性能、高可靠。

#### 主要功能特性

- 消息模型：1. 生产一条消息消费一条消息,  2. 生产一条消息消费多条消息, 3. 广播消息
- 低延迟：毫秒级延迟，性能瓶颈在对应依赖的中间件
- `ack` 特性 : 支持消息的 `ack` 与 `deny` ，并支持 `deny` 后数据的持久化
- 失败重试特性：消息失败后支持重试
- 消息续签特性：消息过期后，通过 `api` 让消息重新等待
- 失败兜底特性：失败重试 N 次后，会触发兜底方案的运行
- 轻量级：只需引入依赖, 一个注解 `@EnableSparta` 即可开启 `Sparta` 
- 使用简单：`API` 贴合当下主流 `MQ` 的使用方法 （`kafka`, `RabbitMQ` 等）, 且支持 `spring boot starter` 

#### 软件架构



#### 外部依赖

- `jdk8 +`
- `Maven 3.5 +`
- 可选项：`Redis 3.x +` / `etcd` / `dragonfly 0.8.0 +`



#### 安装教程

- 下载 `Sparta` 源码

```shell
git clone https://gitee.com/open-source-one/sparta.git
```

- 安装到本地

```shell
mvn install 
```

- 导入依赖

```xml
<dependency>
    <groupId>com.sparta</groupId>
    <artifactId>sparta-spring-boot-starter</artifactId>
    <version>${latest-sparta.version}</version>
</dependency>
```

#### 使用说明

- 配置启动类，加上启动注解 `@EnableSparta`

```java
@EnableSparta
@SpringBootApplication
public class SpartaExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpartaExampleApplication.class, args);
    }
}
```

- 配置 `application.yml`

```yml
spring:
  sparta:
    system-name: sparta-example
    # 可选：redis/etcd/dragonfly
    type: redis
    threads:
      core-size: 8
    # 选择 redis 的时候，必选此项
    redisson:
      # redis 单机服务配置
      singleServerConfig:
        # redis 链接地址
        address: redis://localhost:6379
        # redis 数据库
        database: 6
    # 等待业务执行超时时间, 秒
    consume-wait-time: 3S
    # 错误重试次数, 业务错误重试，最大次数 0-20之间
    retry: 3
    # 续签次数，续签最大次数 0-20之间
    renew: 3
    # 是否启用关机数据回滚的逻辑
    enable-close-rollback: true
    # 是否需要开启未 ack 的持久化
    enable-deny-persistence: false
    # 开启自动 ack
    enable-auto-ack: true
```

- 使用

  - 定义 `TOPIC` 常量池

  ```java
  public interface TopicConstant {
      String NORMAL_TOPIC = "NORMAL_TOPIC";
  }
  ```

  

  - 定义消息体

  ```java
  @Setter
  @Getter
  public class NormalEntity {
      // 用户 ID
      private String userId;
      // 用户名
      private String username;
      // 密码
      private String password;
      // 年龄
      private Integer age;
      // 生日
      private LocalDateTime birthday;
  }
  ```

  - 生产者

  ```java
  @RestController
  @RequestMapping("/normal")
  public class NormalExampleController {
      
      private final SpartaTemplate<Object> spartaTemplate;
      
      public NormalExampleController (SpartaTemplate<Object> spartaTemplate) {
          this.spartaTemplate = spartaTemplate;
      }
      
      
      @GetMapping("/put")
      public void put (String userId, String username,
                               String password, Integer age) {
          int i = new Random().nextInt(10000);
          NormalEntity normal = new NormalEntity();
          normal.setUserId(userId + i);
          normal.setUsername(username);
          normal.setPassword(password);
          normal.setAge(age);
          normal.setBirthday(LocalDateTime.now());
          this.spartaTemplate.write(userId, TopicConstant.NORMAL_TOPIC, normal, i);
      }
  }
  
  ```

  - 定义消费者

  ```java
  @Component
  public class NormalExampleListener {
      
      @SpartaListener(topics = {TopicConstant.NORMAL_TOPIC})
      public void handler (NormalEntity normalEntity, SpartaChannel channel) {
          // TODO do nothing ......
      }
      
      @FinalRetry(topics = {TopicConstant.NORMAL_TOPIC})
      public void finalRetryHandler (String topic, NormalEntity entity) {
          System.out.println("兜底方案被调用 ........");
          // TODO do nothing .......
      }
  }
  ```