# code-generator

**Repository Path**: yanxxcloud/code-generator

## Basic Information

- **Project Name**: code-generator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编码生成器 Spring Boot Starter

一个功能完善的业务编码生成器Spring Boot Starter，专为企业级应用设计。支持连续编码生成、智能回收机制、多种持久化方式和灵活的重置策略，可以轻松集成到任何Spring Boot项目中。

## ✨ 核心特性

### 🔢 智能编码生成
- **连续编码保证**：确保生成的编码连续无间断
- **三状态管理**：待确认(PENDING) → 已确认(CONFIRMED) → 已回收(RECYCLED)
- **智能回收机制**：未使用的编码可回收重用，避免编码浪费
- **线程安全**：支持高并发环境下的安全编码生成

### 🎨 灵活格式化
- **简单格式**：`CODE000001`、`ORDER202410290001`
- **日期前缀**：`20241029001`、`INV20241029001`
- **自定义格式**：支持自定义格式化器扩展

### 🔄 定期重置策略
- **按天重置**：每天重新从1开始计数
- **按周重置**：每周重新从1开始计数
- **按月重置**：每月重新从1开始计数
- **自定义策略**：支持自定义重置逻辑

### 💾 多种持久化方式
- **内存存储**：高性能，适合开发测试
- **文件存储**：JSON格式，适合单机部署
- **Redis存储**：分布式缓存，适合集群部署
- **数据库存储**：关系型数据库，适合企业级应用

### 🌐 完整API支持
- **RESTful接口**：提供完整的HTTP API
- **Spring Boot集成**：开箱即用的自动配置
- **SDK工具类**：便捷的编程接口

## 🛠️ 技术栈

- **Java 8+**：兼容Java 8及以上版本
- **Spring Boot 2.7.8**：企业级框架
- **Redis (Jedis)**：分布式缓存支持
- **MySQL**：关系型数据库支持
- **Jackson**：JSON序列化
- **SLF4J**：统一日志接口

## 🚀 快速开始

### 📋 环境要求

- **JDK 8+**：支持Java 8及以上版本
- **Maven 3.6+**：项目构建工具
- **Spring Boot 2.7.x+**：Spring Boot框架
- **Redis**（可选）：使用Redis存储时需要
- **MySQL**（可选）：使用数据库存储时需要

### 📦 添加依赖

在您的项目的`pom.xml`文件中添加以下依赖：

```xml
<dependency>
    <groupId>com.yanxx</groupId>
    <artifactId>code-generator-spring-boot-starter</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

### ⚙️ 基础配置

在`application.properties`或`application.yml`文件中添加配置：

```properties
# 基础配置
code.generator.prefix=ORDER
code.generator.length=8
code.generator.start-value=1

# 存储方式选择: memory, file, redis, database
code.generator.storage-type=memory
```

### 💻 代码使用

#### 方式一：使用Service（推荐）

```java
@Service
public class OrderService {
    
    private final CodeGeneratorService codeGeneratorService;
    
    public OrderService(CodeGeneratorService codeGeneratorService) {
        this.codeGeneratorService = codeGeneratorService;
    }
    
    public String createOrder() {
        // 生成订单号
        String orderCode = codeGeneratorService.generateCode();
        
        try {
            // 业务逻辑处理
            saveOrder(orderCode);
            
            // 确认编码已使用
            codeGeneratorService.confirmCode(orderCode);
            return orderCode;
        } catch (Exception e) {
            // 业务失败，回收编码
            codeGeneratorService.recycleCode(orderCode);
            throw e;
        }
    }
}
```

#### 方式二：直接使用CodeGenerator

```java
@Service
public class InvoiceService {
    
    private final CodeGenerator codeGenerator;
    
    public InvoiceService(CodeGenerator codeGenerator) {
        this.codeGenerator = codeGenerator;
    }
    
    public String generateInvoiceNumber() {
        return codeGenerator.generate();
    }
}
```

#### 方式三：使用SDK工具类

```java
@Configuration
public class CodeGeneratorConfiguration {
    
    @Bean
    public CodeGenerator orderCodeGenerator() {
        return CodeGeneratorSDK.builder()
                .prefix("ORDER")
                .codeLength(8)
                .startValue(1)
                .persistentFile("./order_codes.json")
                .resetDaily()  // 每天重置
                .build();
    }
    
    @Bean
    public CodeGenerator invoiceCodeGenerator() {
        return CodeGeneratorSDK.createDatePrefixGenerator(
                "INV", "yyyyMMdd", 4, 1);  // INV202410290001
    }
}
```

## 📡 REST API 文档

### 🌐 在线API文档

启动应用后，可以选择多种美观的API文档界面：

#### 📋 文档首页（推荐）
- **文档选择页面**：`http://localhost:8080/code-generator/docs`

#### 🎨 多种UI风格
- **Knife4j增强版**：`http://localhost:8080/code-generator/doc.html` - 功能最强大
- **RapiDoc现代版**：`http://localhost:8080/code-generator/docs/rapidoc` - 界面最美观  
- **ReDoc经典版**：`http://localhost:8080/code-generator/docs/redoc` - 阅读体验最佳
- **Swagger UI标准版**：`http://localhost:8080/code-generator/swagger-ui.html` - 最经典

#### 📄 原始数据
- **OpenAPI JSON**：`http://localhost:8080/code-generator/v3/api-docs`

### 📋 API接口概览

#### 生成新编码

```http
GET /api/codes/generate
```

**响应示例：**
```json
{
  "code": "ORDER00000001"
}
```

#### 确认编码使用

```http
POST /api/codes/confirm/{code}
```

**响应示例：**
```json
{
  "success": true,
  "message": "编码确认成功"
}
```

#### 回收未使用编码

```http
POST /api/codes/recycle/{code}
```

**响应示例：**
```json
{
  "success": true,
  "message": "编码回收成功"
}
```

#### 获取系统状态

```http
GET /api/codes/status
```

**响应示例：**
```json
{
  "availableCount": 5,
  "pendingCount": 3,
  "confirmedCount": 100,
  "recycledCount": 5
}
```

#### 获取各状态编码列表

```http
GET /api/codes/pending     # 获取待确认编码
GET /api/codes/confirmed   # 获取已确认编码
GET /api/codes/recycled    # 获取已回收编码
```

**响应示例：**
```json
["ORDER00000002", "ORDER00000003", "ORDER00000005"]
```

### 🧪 API测试

多种界面都支持在线测试功能：

1. **启动应用**
2. **选择界面**：访问 `http://localhost:8080/code-generator/docs` 选择喜欢的界面
3. **测试接口**：
   - **Knife4j**：点击"调试"按钮，支持参数记忆和批量测试
   - **RapiDoc**：点击"TRY"按钮，现代化的测试体验
   - **ReDoc**：右侧面板查看示例，左侧查看详细文档
   - **Swagger UI**：点击"Try it out"按钮，经典的测试方式

#### 🎯 推荐使用场景
- **开发调试**：推荐使用 **Knife4j**，功能最全面
- **演示展示**：推荐使用 **RapiDoc**，界面最美观
- **文档阅读**：推荐使用 **ReDoc**，排版最清晰
- **快速测试**：推荐使用 **Swagger UI**，加载最快速

## 🔧 详细配置

### 💾 存储方式配置

#### 内存存储（默认）
```properties
# 高性能，重启后数据丢失
code.generator.storage-type=memory
```

#### 文件存储
```properties
# JSON格式持久化到本地文件
code.generator.storage-type=file
code.generator.file.path=./data/code_generator.json
```

#### Redis存储
```properties
# 分布式缓存，支持集群部署
code.generator.storage-type=redis
code.generator.redis.key-prefix=app_code_generator

# Redis连接配置
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.password=your_password
spring.redis.database=0
```

#### 数据库存储
```properties
# 关系型数据库，企业级持久化
code.generator.storage-type=database
code.generator.db.generator-id=order_generator

# 数据源配置
spring.datasource.url=jdbc:mysql://localhost:3306/your_database?useSSL=false&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
```

### 🎨 格式化配置

#### 基础格式配置
```properties
# 编码前缀
code.generator.prefix=ORDER
# 数字部分长度（不包括前缀）
code.generator.length=8
# 起始值
code.generator.start-value=1
```

#### 使用SDK进行高级配置
```java
// 日期前缀格式：ORDER20241029001
CodeGenerator generator = CodeGeneratorSDK.createDatePrefixGenerator(
    "ORDER", "yyyyMMdd", 3, 1);

// 按天重置的编码生成器
CodeGenerator dailyGenerator = CodeGeneratorSDK.createDailyResetGenerator(
    "DAILY", 6, 1);

// 使用构建器模式
CodeGenerator customGenerator = CodeGeneratorSDK.builder()
    .prefix("CUSTOM")
    .codeLength(10)
    .startValue(1000)
    .dateFormat("yyyyMMdd")
    .resetMonthly()
    .persistentFile("./custom_codes.json")
    .build();
```

## 🗄️ 数据库表结构

使用数据库存储时，系统会自动创建以下表结构：

```sql
-- 生成器状态表
CREATE TABLE code_generator_state (
    generator_id VARCHAR(100) PRIMARY KEY,
    current_max_value BIGINT NOT NULL
);

-- 编码状态表
CREATE TABLE code_generator_codes (
    generator_id VARCHAR(100) NOT NULL,
    code VARCHAR(100) NOT NULL,
    code_type VARCHAR(20) NOT NULL,  -- 'confirmed', 'pending', 'recycled'
    PRIMARY KEY (generator_id, code)
);
```

## 🎯 应用场景

### 典型使用场景
- **订单系统**：生成连续订单号 `ORDER20241029001`
- **发票系统**：生成发票编号 `INV202410290001`
- **会员系统**：生成会员卡号 `VIP000001`
- **单据系统**：生成各类业务单据编号
- **流水记录**：生成业务流水号

### 业务流程示例
```java
@Service
public class OrderService {
    
    public String processOrder(OrderRequest request) {
        // 1. 生成订单号
        String orderCode = codeGeneratorService.generateCode();
        
        try {
            // 2. 创建订单
            Order order = new Order(orderCode, request);
            
            // 3. 保存到数据库
            orderRepository.save(order);
            
            // 4. 确认编码已使用
            codeGeneratorService.confirmCode(orderCode);
            
            return orderCode;
        } catch (Exception e) {
            // 5. 异常时回收编码
            codeGeneratorService.recycleCode(orderCode);
            throw new OrderProcessException("订单处理失败", e);
        }
    }
}
```

## 🏗️ 架构设计

### 核心组件
- **CodeGenerator**：核心接口，定义编码生成标准
- **SequentialCodeGenerator**：基础实现，保证编码连续性
- **PersistentCodeGenerator**：持久化扩展，支持数据恢复
- **ResettableCodeGenerator**：重置扩展，支持定期重置
- **CodeGeneratorStorage**：存储抽象，支持多种持久化方式

### 设计模式
- **策略模式**：格式化器、重置策略、存储策略
- **工厂模式**：SDK工厂方法
- **建造者模式**：灵活配置构建
- **装饰器模式**：功能层次扩展

## 🤝 贡献指南

欢迎提交Issue和Pull Request来改进这个项目！

### 开发环境搭建
```bash
git clone https://github.com/your-repo/code-generator-spring-boot-starter.git
cd code-generator-spring-boot-starter
mvn clean install
```

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。