spring-starter-redis-id-generator/README.md

Redis ID 生成器

工程介绍

Redis ID 生成器是一个基于 Spring Boot Starter 的组件，用于生成基于 Redis 的自增 ID。它的核心功能是：

• 提供 generateId(String key) 方法，用于生成自增 ID
• 支持为不同的业务场景设置不同的 ID 计数器
• 支持配置 ID 初始值
• 基于 Redis 的 INCR 命令实现，保证 ID 的唯一性和单调性

技术栈

• Kotlin 1.9.25
• Spring Boot 3.5.9
• Jedis 5.1.0
• Redis 6.0+

构建方法

前提条件

• JDK 17+
• Gradle 8.5+
• Redis 6.0+（运行时需要）

构建步骤

1. 克隆或下载本工程到本地

2. 进入工程目录：

   cd redis-id-generator
   

3. 执行构建命令：

   ./gradlew build --no-daemon
   

4. 构建成功后，会在 build/libs/ 目录下生成 redis-id-generator-1.0.0.jar 文件

引用方法

方法一：本地 JAR 包引用

1. 将构建生成的 redis-id-generator-1.0.0.jar 文件复制到目标工程的 lib/ 目录（如果没有该目录，需要创建）

2. 在目标工程的 build.gradle.kts 文件中添加依赖：

   dependencies {
       // 其他依赖...
       implementation(files("lib/redis-id-generator-1.0.0.jar"))
   }
   

方法二：Maven 仓库引用（未来支持）

未来可以将 JAR 包发布到 Maven 仓库，然后通过坐标引用：

dependencies {
    // 其他依赖...
    implementation("com.sycn:redis-id-generator:1.0.0")
}

配置说明

在目标工程的配置文件（如 application-dev.properties 或 application-prod.properties）中添加以下配置：

# Redis ID生成器配置
# Redis 服务器地址
redis-id-generator.redis.host=localhost
# Redis 服务器端口
redis-id-generator.redis.port=6379
# Redis 密码（如果没有密码，留空）
redis-id-generator.redis.password=
# Redis 数据库索引
redis-id-generator.redis.database=0
# Redis 连接超时时间（毫秒）
redis-id-generator.redis.timeout=3000
# 通用ID计数器的初始值
redis-id-generator.id.initial-value=10000001
# 各ID键的初始值映射（可选）
# redis-id-generator.id.initial-values.user=20000001
# redis-id-generator.id.initial-values.order=30000001

使用示例

1. 在 Spring Boot 配置类中启用 Redis ID 生成器

package com.example.config

import com.sycn.redisidgenerator.RedisIdGeneratorProperties
import com.sycn.redisidgenerator.RedisIdGeneratorService
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
@EnableConfigurationProperties(RedisIdGeneratorProperties::class)
class RedisIdGeneratorConfig {

    @Bean
    fun redisIdGeneratorService(properties: RedisIdGeneratorProperties): RedisIdGeneratorService {
        val service = RedisIdGeneratorService(properties)
        service.init()
        return service
    }
}

2. 在业务代码中使用

package com.example.controller

import com.sycn.redisidgenerator.RedisIdGeneratorService
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api")
class IdController(
    private val redisIdGeneratorService: RedisIdGeneratorService
) {

    // 生成通用ID
    @GetMapping("/id/generate")
    fun generateId(): Long {
        return redisIdGeneratorService.generateId()
    }

    // 生成指定业务的ID
    @GetMapping("/id/generate/user")
    fun generateUserId(): Long {
        return redisIdGeneratorService.generateId("user")
    }

    // 生成订单ID
    @GetMapping("/id/generate/order")
    fun generateOrderId(): Long {
        return redisIdGeneratorService.generateId("order")
    }
}

核心实现原理

1. 连接管理：使用 Jedis 连接池管理 Redis 连接，确保连接的高效利用

2. ID 生成：基于 Redis 的 INCR 命令实现自增，保证 ID 的唯一性和单调性

3. 初始值设置：使用 Redis 的 SETNX 命令设置初始值，确保初始值只设置一次

4. 多业务支持：为不同的业务场景使用不同的 Redis 键，实现业务隔离

5. 配置管理：通过 Spring Boot 的配置属性机制，支持灵活的配置

注意事项

1. Redis 依赖：本组件运行时依赖 Redis 服务，必须确保 Redis 服务可用

2. 性能考虑：

   • ID 生成操作依赖网络 IO，性能会受到网络延迟的影响
   • 建议在生产环境中部署 Redis 集群，提高可用性和性能

3. ID 冲突：

   • 基于 Redis 的 INCR 命令实现，天然保证 ID 的唯一性
   • 不同的业务场景使用不同的键，避免 ID 冲突

4. 初始值设置：

   • 初始值一旦设置，后续重启应用不会重置，因为 Redis 会持久化存储
   • 如果需要重置初始值，需要手动删除 Redis 中的对应键

故障处理

1. Redis 连接失败：

   • 组件在初始化时会尝试连接 Redis，如果连接失败会抛出异常，应用启动失败
   • 确保 Redis 服务正常运行，网络连接畅通

2. ID 生成失败：

   • 检查 Redis 服务是否正常
   • 检查网络连接是否畅通
   • 检查 Redis 权限是否正确

版本历史

1.0.0

• 初始版本
• 实现基本的 ID 生成功能
• 支持配置初始值
• 支持多业务场景

联系我们

• 作者：chenqiang
• 邮箱：chenqiang@h024.cn
• 项目地址：https://github.com/example/redis-id-generator