# version-upgrade

**Repository Path**: alex200816/version-upgrade

## Basic Information

- **Project Name**: version-upgrade
- **Description**: 简单易用的版本升级工具，支持SQL脚本执行和Java代码执行，提供自动回滚功能，可集成到任何Java项目
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2024-08-25
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 版本升级工具

一个简单易用的版本升级工具，支持SQL脚本执行和Java代码执行，提供自动回滚功能，可集成到任何Java项目。

## 特性

- ✅ **零配置版本号**：无需配置版本号，程序自动读取和管理
- ✅ **自动版本检测**：自动读取本地当前版本
- ✅ **智能版本计算**：自动计算需要升级的版本，支持跨版本升级
- ✅ **多步骤执行**：支持SQL和Java混合执行，按顺序执行
- ✅ **自动回滚**：升级失败时自动执行回滚步骤
- ✅ **参数传递**：支持向Java代码传递参数
- ✅ **Spring Boot支持**：可在Spring Boot启动前自动执行
- ✅ **缓存优化**：SQL脚本自动缓存，避免重复读取

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>cn.002alex</groupId>
    <artifactId>version-upgrade</artifactId>
    <version>2.0.0</version>
</dependency>
```

### 2. 创建文件结构

```
src/main/resources/
└── version/
    ├── version.xml          # 版本配置文件
    └── sql/                 # SQL脚本目录
        ├── 1.0.1.sql
        └── 1.0.2.sql
```

### 3. 配置 version.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<versions>
    <!-- 版本 1.0.0 - 初始版本 -->
    <version>
        <version>1.0.0</version>
        <releaseTime>2024-01-01 00:00:00</releaseTime>
        <description>初始版本发布</description>
        <steps></steps>
    </version>

    <!-- 版本 1.0.1 - 执行SQL -->
    <version>
        <version>1.0.1</version>
        <releaseTime>2024-02-01 00:00:00</releaseTime>
        <description>新增用户表</description>
        <steps>
            <step type="SQL">1.0.1.sql</step>
        </steps>
    </version>

    <!-- 版本 1.0.2 - 执行Java代码 -->
    <version>
        <version>1.0.2</version>
        <releaseTime>2024-03-01 00:00:00</releaseTime>
        <description>数据迁移</description>
        <steps>
            <step type="JAVA">com.example.upgrade.DataMigration</step>
        </steps>
    </version>

    <!-- 版本 1.0.3 - 多个步骤 -->
    <version>
        <version>1.0.3</version>
        <releaseTime>2024-04-01 00:00:00</releaseTime>
        <description>订单模块重构</description>
        <steps>
            <step type="JAVA">com.example.upgrade.BackupOrders</step>
            <step type="SQL">1.0.3_create_table.sql</step>
            <step type="SQL">1.0.3_init_data.sql</step>
            <step type="JAVA">com.example.upgrade.InitOrders</step>
        </steps>
        <rollbackSteps>
            <step type="SQL">rollback_1.0.3.sql</step>
            <step type="JAVA">com.example.upgrade.RestoreOrders</step>
        </rollbackSteps>
    </version>
</versions>
```

### 4. 一行代码搞定

#### 普通Java项目

```java
public class Application {
    public static void main(String[] args) {
        // 一行代码搞定！不需要配置版本号
        VersionUpgradeEngine.builder()
                .dataSource(dataSource)     // 如果需要执行SQL
                .upgrade();                  // 自动读取本地版本，自动升级到最新版
    }
}
```

#### Spring Boot项目

在启动类上添加 `@EnableVersionUpgrade` 注解：

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


## 生命周期

### 完整流程图

![流程图](./images/lifecycle.png)

### 两种启动模式

| 模式                | 使用方式                                  |
| ----------------- | ------------------------------------- |
| **Spring Boot**   | 引入依赖后自动通过 ApplicationRunner 触发，无需手动调用 |
| **非 Spring Boot** | 手动创建 Engine 实例并调用 `upgrade()` 方法      |

### 监听器与处理器触发时机

#### 升级监听器 (VersionUpgradeListener)

| 方法                           | 触发时机      |
| ---------------------------- | --------- |
| `onUpgradeStart()`           | 开始升级前     |
| `onVersionUpgradeStart()`    | 每个版本开始升级前 |
| `onStepUpgradeStart()`       | 每个步骤开始执行前 |
| `onStepUpgradeComplete()`    | 步骤执行成功    |
| `onVersionUpgradeComplete()` | 版本升级成功    |
| `onUpgradeComplete()`        | 全部升级完成    |

#### 异常监听器 (VersionExceptionListener)

| 方法                         | 触发时机        |
| -------------------------- | ----------- |
| `onStepUpgradeException()` | 步骤执行失败      |
| `onUpgradeException()`     | 版本升级过程中发生异常 |

#### 回滚监听器 (VersionRollbackListener)

| 方法                            | 触发时机     |
| ----------------------------- | -------- |
| `onRollbackStart()`           | 回滚开始     |
| `onVersionRollbackStart()`    | 版本回滚开始   |
| `onStepRollbackStart()`       | 每个回滚步骤开始 |
| `onStepRollbackComplete()`    | 回滚步骤成功   |
| `onVersionRollbackComplete()` | 版本回滚完成   |
| `onRollbackComplete()`        | 全部回滚完成   |
| `onRollbackException()`       | 回滚步骤失败   |

#### 处理器 (VersionUpgradeHandler)

| 方法                 | 触发时机          |
| ------------------ | ------------- |
| `handle()`         | JAVA 类型步骤执行   |
| `beforeRollback()` | 回滚开始前         |
| `afterRollback()`  | 回滚完成后         |
| `rollback()`       | JAVA 类型回滚步骤执行 |

## 详细配置

### XML配置说明

| 标签                | 说明     | 必填 |
| ----------------- | ------ | -- |
| `<version>`       | 版本号    | 是  |
| `<releaseTime>`   | 发布时间   | 否  |
| `<description>`   | 更新说明   | 否  |
| `<steps>`         | 执行步骤集合 | 否  |
| `<step>`          | 单个执行步骤 | 否  |
| `<rollbackSteps>` | 回滚步骤集合 | 否  |

### step标签属性

| 属性             | 说明                      | 可选值                      |
| -------------- | ----------------------- | ------------------------ |
| `type`         | 执行类型                    | `SQL` / `JAVA`           |
| `invokeParams` | 传递给Java的参数（仅type=JAVA时） | key1=value1\&key2=value2 |

### step标签值

- type=SQL时：SQL脚本文件名（放在version/sql/目录下）
- type=JAVA时：Java类全限定名

### 自定义Java处理器

实现 `VersionUpgradeHandler` 接口：

```java
@Slf4j
public class DataMigration implements VersionUpgradeHandler {
    
    @Override
    public void handle(VersionXml.Step step, VersionXml versionXml) {
        log.info("开始数据迁移...");
        log.info("当前版本: {}", versionXml.getVersion());

        // 解析参数
        if (step != null && step.getInvokeParams() != null) {
            String params = step.getInvokeParams();
            log.info("接收参数: {}", params);
        }

        // 执行迁移逻辑
        // ...

        log.info("数据迁移完成");
    }
    
    @Override
    public void rollback(VersionXml.Step step, VersionXml versionXml) {
        log.info("开始回滚版本: {}", versionXml.getVersion());
        // 执行回滚逻辑
    }
}
```

Spring Boot项目中，直接使用 `@Component` 注解即可自动注册。

## 高级配置

### 传递参数给Java代码

```xml
<version>
    <version>1.0.7</version>
    <releaseTime>2024-07-01 00:00:00</releaseTime>
    <description>批量数据处理</description>
    <steps>
        <step type="JAVA" invokeParams="batchSize=1000&mode=strict">com.example.BatchProcess</step>
    </steps>
</version>
```

**Java 代码接收参数**：

```java
@Slf4j
public class BatchProcess implements VersionUpgradeHandler {
    @Override
    public void handle(VersionXml.Step step, VersionXml versionXml) {
        if (step != null && step.getInvokeParams() != null) {
            String params = step.getInvokeParams();
            Map<String, String> paramMap = parseParams(params);

            String batchSize = paramMap.get("batchSize");
            String mode = paramMap.get("mode");

            log.info("批次大小: {}, 模式: {}", batchSize, mode);
        }
    }
}
```

### 条件执行

```xml
<version>
    <version>1.0.9</version>
    <releaseTime>2024-09-01 00:00:00</releaseTime>
    <description>根据环境决定是否升级</description>
    <condition>
        <type>ENV</type>
        <key>ENABLE_NEW_FEATURE</key>
        <value>true</value>
        <operator>eq</operator>
    </condition>
    <steps>
        <step type="SQL">1.0.9.sql</step>
    </steps>
</version>
```

## 回滚机制

当某个版本升级失败时：

1. 立即停止后续版本的升级
2. 自动执行该版本的 `<rollbackSteps>`（如果配置了）
3. 本地版本号保持为上次成功升级的版本

## 完整配置示例

```xml
<?xml version="1.0" encoding="UTF-8"?>
<versions>
    <!-- 版本 1.0.0 - 初始版本 -->
    <version>
        <version>1.0.0</version>
        <releaseTime>2024-01-01 00:00:00</releaseTime>
        <description>系统初始版本</description>
        <steps></steps>
    </version>

    <!-- 版本 1.0.1 - SQL变更 -->
    <version>
        <version>1.0.1</version>
        <releaseTime>2024-02-01 00:00:00</releaseTime>
        <description>新增用户表索引</description>
        <steps>
            <step type="SQL">1.0.1.sql</step>
        </steps>
    </version>

    <!-- 版本 1.0.2 - 纯Java逻辑 -->
    <version>
        <version>1.0.2</version>
        <releaseTime>2024-03-01 00:00:00</releaseTime>
        <description>执行缓存预热</description>
        <steps>
            <step type="JAVA">com.example.upgrade.CacheWarming</step>
        </steps>
    </version>

    <!-- 版本 1.0.3 - 先SQL后Java -->
    <version>
        <version>1.0.3</version>
        <releaseTime>2024-04-01 00:00:00</releaseTime>
        <description>新增订单表并初始化</description>
        <steps>
            <step type="SQL">1.0.3.sql</step>
            <step type="JAVA">com.example.upgrade.OrderInit</step>
        </steps>
    </version>

    <!-- 版本 1.0.4 - 带回滚 -->
    <version>
        <version>1.0.4</version>
        <releaseTime>2024-05-01 00:00:00</releaseTime>
        <description>危险的数据操作，需要配置回滚</description>
        <steps>
            <step type="SQL">1.0.4.sql</step>
        </steps>
        <rollbackSteps>
            <step type="SQL">rollback_1.0.4.sql</step>
            <step type="JAVA">com.example.upgrade.RestoreData</step>
        </rollbackSteps>
    </version>

    <!-- 最新版本 -->
    <version>
        <version>1.0.5</version>
        <releaseTime>2024-06-01 00:00:00</releaseTime>
        <description>性能优化</description>
        <steps></steps>
    </version>
</versions>
```

## 最佳实践

1. **小步快跑**：每个版本尽量做小的改动，便于问题定位
2. **详细描述**：每个版本的 description 要写清楚改动内容
3. **及时回滚**：涉及数据的操作一定要配置回滚步骤
4. **测试环境验证**：正式环境升级前先在测试环境验证
5. **日志记录**：重要操作要在 description 中记录，便于问题排查

## 常见问题

### Q1: SQL 文件放哪里？

**A**: 放在 `src/main/resources/version/sql/` 目录下

### Q2: 升级失败会自动回滚吗？

**A**: 如果配置了 `rollbackSteps`，会自动执行回滚

### Q3: Java 代码怎么接收参数？

**A**: 通过 `step.getInvokeParams()` 方法获取

### Q4: 可以同时执行多个步骤吗？

**A**: 可以，在 `<steps>` 中配置多个 `<step>` 即可，按顺序执行

### Q5: 如何在Spring Boot中注册自定义处理器？

**A**: 使用 `@Component` 注解，框架会自动扫描注册

### Q6: 支持跨版本升级吗？

**A**: 支持，例如从1.0.2升级到1.0.5会自动执行1.0.3 → 1.0.4 → 1.0.5