编码生成器（生产级别）

序列号生成器 SDK 使用说明

代码仓库地址

https://github.com/zhangzihang3/code-generate

一、项目简介

本项目是一个基于 Spring Boot 3 + MyBatis-Plus 的序列号生成器 SDK，支持按业务编码（businessCode）生成可自定义模板的序列号，适用于订单号、SKU 编码、发票号等场景。

二、快速开始

1. 环境要求

JDK 17+
Maven 3.8+
MySQL 8.0+

2. 数据库初始化

执行sql：

sql 复制代码

source src/main/resources/sql/init.sql

该脚本会创建 seq_generator 数据库、两张表以及一条测试配置数据。

3. 修改数据库连接

如有需要，修改数据源配置：

yaml 复制代码

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/seq_generator
    username: root
    password: root

4. 运行测试

bash 复制代码

mvn test -Dtest=codeTest#generateCombinationMainSkuCode

测试通过后控制台会输出生成的序列号。

三、使用方式

1. 注入服务

java 复制代码

@Autowired
private SeqNumGeneratorService seqNumGeneratorService;

2. 调用生成方法

java 复制代码

Map<String, String> params = new HashMap<>();
params.put("spuCode", "SPU001");

String seqNum = seqNumGeneratorService.nextSeqNum(
    "999",                        // 租户ID
    "COMBINATION_MAIN_SKU_CODE",  // 业务编码
    params                         // 模板参数
);
// 输出示例: CMSKUSPU001000001

3. 配置数据说明

在 seq_num_info_conf 表中配置序列号规则，核心字段：

字段	说明	示例
`business_code`	业务编码（唯一）	`COMBINATION_MAIN_SKU_CODE`
`scope`	配置范围	`DEFAULT_CONF_SCOPE`（默认）/ `TENANT_SCOPE`（租户）
`seq_key_template`	序列号 Key 模板	`COMBINATION_MAIN_SKU_CODE_${spuCode}`
`seq_num_template`	序列号生成模板	`CMSKU${spuCode}${seqNumValue}`
`seq_length`	序号位数（不足补零）	`6`
`start_value`	起始值	`1`
`max_value`	最大值（可选）	`999999`
`seq_num_key_params`	Key 模板参数（逗号分隔）	`spuCode`
`seq_num_temp_params`	序列号模板参数（逗号分隔）	`spuCode,seqNumValue`

四、核心实现原理

整体流程

复制代码

nextSeqNum(租户ID, 业务编码, 参数)
        │
        ▼
┌─────────────────────────┐
│ 1. 查询配置（带缓存）     │  ← SeqNumGeneratorHolder 本地缓存
│    按 businessCode 查表   │
│    按 scope 筛选配置      │
└──────────┬──────────────┘
           ▼
┌─────────────────────────┐
│ 2. 校验 Key 参数         │  ← seq_num_key_params 定义的字段
│    生成 seqNumKey       │  ← 用模板替换参数
└──────────┬──────────────┘
           ▼
┌─────────────────────────┐
│ 3. 获取序列号项          │  ← 本地缓存 / 新建记录
│    （sequence_num_item） │
└──────────┬──────────────┘
           ▼
┌─────────────────────────┐
│ 4. 递增序列值            │  ← UPDATE seq_value + 1（行锁）
│    校验模板参数          │
└──────────┬──────────────┘
           ▼
┌─────────────────────────┐
│ 5. 格式化并替换模板      │  ← StringSubstitutor
│    返回最终序列号        │
└─────────────────────────┘

关键设计

1. 两级缓存（SeqNumGeneratorHolder）

使用 ConcurrentHashMap 缓存配置和序列号项，避免重复查库：

配置缓存 Key：租户ID_业务编码
序列号项缓存 Key：租户ID_业务编码_seqNumKey

2. 并发安全（SequenceNumItemMapper.xml）

通过 SELECT ... FOR UPDATE 行锁 + UPDATE seq_value = seq_value + N 原子操作保证并发安全：

sql 复制代码

-- 查询时加行锁
SELECT * FROM sequence_num_item ... FOR UPDATE;
-- 原子递增
UPDATE sequence_num_item SET seq_value = seq_value + #{stepNum} ...;

3. 模板替换

使用 org.apache.commons.text.StringSubstitutor 进行 ${param} 格式的参数替换，内置参数：

seqNumValue：格式化后的序号值（按 seqLength 补零）
currentDate：当前时间
seqItemDate：序列号项创建日期

4. 配置范围筛选（SeqConfScopeEnum）

同一 businessCode 可配置多条规则，优先级：

DEFAULT_CONF_SCOPE：默认配置
TENANT_SCOPE：按租户匹配的配置

核心类说明

类	职责
SeqNumGeneratorService	生成器接口
SeqNumGeneratorServiceImpl	核心生成逻辑
SeqNumInfoConfService	配置查询服务
SequenceNumItemService	序列号项操作服务
SeqNumGeneratorHolder	本地缓存持有者