# trace4j

**Repository Path**: chenhao1003/trace4j

## Basic Information

- **Project Name**: trace4j
- **Description**: 零侵入式 Java 全链路业务追溯组件 Trace4J，基于注解 + Mybatis 拦截器自动采集接口操作、数据库字段级变更；支持正向业务 ID 追溯、后续会添加任意子 ID 反向全链路溯源，智能规整批量插入日志、自动区分多次修改记录；配套执行快照留存，不受数据库清空 / 脏数据影响
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 链路追踪, 监控, 工具类, Java, SpringBoot

## README

# trace4j

#### 介绍

零侵入式 Java 全链路业务追溯组件 Trace4J，基于注解 + MyBatis 拦截器自动采集接口操作、数据库字段级变更；支持正向业务 ID 追溯、后续会添加任意子 ID 反向全链路溯源，智能规整批量插入日志、自动区分多次修改记录；配套执行快照留存，不受数据库清空 / 脏数据影响

#### 软件架构

```
trace4j 核心架构分为四层：

┌─────────────────────────────────────────────────────┐
│                   Controller / Service 层            │
│          业务方法上标注 @BusinessTrace 注解            │
│     通过 SpEL 表达式声明 businessId / node / desc      │
└────────────────────┬────────────────────────────────┘
                     │ AOP 环绕增强
┌────────────────────▼────────────────────────────────┐
│             BusinessTraceAspect（AOP 切面）           │
│  ① 解析 SpEL → 提取 businessId、节点名称、描述         │
│  ② 记录流程节点日志 → 写入 business_trace 表           │
│  ③ 快照 DataChangeContext → 写入 data_change_trace 表 │
│  ④ 自动采集请求 URL + 入参 JSON 作为执行快照留存        │
└────────────────────┬────────────────────────────────┘
                     │ ThreadLocal 传递
┌────────────────────▼────────────────────────────────┐
│        DataChangeInterceptor（MyBatis 拦截器）        │
│  ① 拦截 Executor.update（INSERT / UPDATE / DELETE）   │
│  ② INSERT：直接记录新实体快照                          │
│  ③ UPDATE：先通过主键查旧数据，再与新实体配对           │
│  ④ 变更记录暂存 DataChangeContext（ThreadLocal）       │
│  ⑤ 自动识别 @TableName 表名，兼容 MyBatis-Plus Wrapper │
└────────────────────┬────────────────────────────────┘
                     │ 持久化
┌────────────────────▼────────────────────────────────┐
│                   数据持久层                          │
│  business_trace    — 流程节点轨迹（步骤、时间、接口）    │
│  data_change_trace — 字段级变更（表名、字段、新旧值）    │
│  自动过滤系统字段（id/createTime/updateTime 等）       │
│  按节点 + 时间窗口智能匹配变更归属                      │
└─────────────────────────────────────────────────────┘
```

**核心技术栈：**

| 组件 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.2.5 | 基础框架 |
| Spring AOP | - | 注解切面拦截 |
| MyBatis-Plus | 3.5.6 | ORM + 拦截器扩展 |
| Hutool | 5.8.27 | Bean 对比、工具类 |
| MySQL | 8.x | 追溯数据持久化 |

**核心模块说明：**

| 模块 | 类名 | 职责 |
|------|------|------|
| 注解定义 | `@BusinessTrace` | 标注业务方法，声明 businessId / node / desc（支持 SpEL） |
| AOP 切面 | `BusinessTraceAspect` | 环绕增强，记录流程节点 + 快照数据变更 + 采集请求上下文 |
| MyBatis 拦截器 | `DataChangeInterceptor` | 拦截 INSERT/UPDATE，提取新旧实体写入 ThreadLocal |
| 线程上下文 | `DataChangeContext` | ThreadLocal 暂存变更快照，方法结束由切面统一消费并清理 |
| 拦截器注册 | `MybatisInterceptorRegistrar` | 在 Bean 初始化完成后自动将拦截器注入 SqlSessionFactory |
| 追溯报告 | `TraceTextService` | 按 businessId 聚合节点 + 变更，生成结构化纯文本报告 |
| 查询接口 | `TraceController` | 提供 /trace/report、/trace/nodes、/trace/changes、/trace/detail 查询 API |

#### 安装教程

1.  确保环境已安装 **JDK 17+**、**Maven 3.8+**、**MySQL 8.x**
2.  克隆本仓库并进入项目目录：
    ```bash
    git clone https://gitee.com/your-username/trace4j.git
    cd trace4j
    ```
3.  修改 `src/main/resources/application.yml` 中的数据库连接配置：
    ```yaml
    spring:
      datasource:
        url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
        username: your_username
        password: your_password
    ```
4.  编译并启动：
    ```bash
    mvn clean package -DskipTests
    java -jar target/business-trace-demo-1.0.0.jar
    ```
    启动成功后默认监听 `http://localhost:8088`

#### 使用说明

##### 1. 在业务方法上添加 `@BusinessTrace` 注解

```java
@PostMapping("/product/shelf")
@BusinessTrace(businessId = "#id", node = "'商品上架'", desc = "'商品正式上架，开放购买'")
public Map<String, Object> shelfProduct(@RequestParam Long id) {
    ProductEntity product = productMapper.selectById(id);
    product.setStatus(1);
    product.setShelfTime(LocalDateTime.now());
    productMapper.updateById(product);
    return Map.of("id", id, "status", 1);
}
```

**注解参数说明：**

| 参数 | 说明 | SpEL 示例 |
|------|------|-----------|
| `businessId` | 业务唯一标识（必填） | `"#id"` / `"#result"` / `"#dto.orderId"` |
| `node` | 流程节点名称（必填） | `"'商品上架'"` / `"#dto.nodeName"` |
| `desc` | 操作描述（选填） | `"'设置商品价格'"` / `"#dto.desc"` |

##### 2. 追溯报告查询 API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/trace/report?businessId=1` | GET | 获取完整追溯报告（纯文本，适合日志/告警场景） |
| `/trace/nodes?businessId=1` | GET | 获取流程节点列表（JSON 结构化数据） |
| `/trace/changes?businessId=1` | GET | 获取字段级数据变更列表（JSON 结构化数据） |
| `/trace/detail?businessId=1` | GET | 综合查询（report + nodes + changes 一次性返回） |

##### 3. 追溯报告输出示例

```
========== 业务轨迹追溯报告 ==========
业务ID：1
======================================

第1步：商品创建草稿
时间：2025-06-02 10:00:01
操作内容：创建商品草稿，等待后续完善信息
调用接口：/demo/product/draft
--------------------------------------
数据变更：
  表：product（5个字段）
    新增 → name：（新增） → 华为Mate 70 Pro 5G旗舰手机
    新增 → brand：（新增） → 华为
    新增 → category：（新增） → 手机数码
    新增 → stock：（新增） → 500
    新增 → status：（新增） → 0

第2步：商品定价
时间：2025-06-02 10:00:02
操作内容：设置商品原价与销售价
调用接口：/demo/product/price
--------------------------------------
数据变更：
  表：product（2个字段）
    修改 → originalPrice：null → 7999.00
    修改 → price：null → 6999.00

第3步：商品上架
时间：2025-06-02 10:00:03
操作内容：商品正式上架，开放购买
调用接口：/demo/product/shelf
--------------------------------------
数据变更：
  表：product（2个字段）
    修改 → status：0 → 1
    新增 → shelfTime：（新增） → 2025-06-02T10:00:03

...

======================================
流程结束，共 10 个操作步骤
======================================
```

##### 4. 内置演示场景

| 接口 | 说明 |
|------|------|
| `POST /demo/fullFlow` | 完整正向流程：商品草稿 → 定价 → 上架 → 预售 → 促销 → 补货 → 下单 → 支付 → 发货 → 收货 |
| `POST /demo/refundFlow` | 退款异常流程：商品上架 → 下单 → 支付 → 全额退款 |
| `POST /demo/cancelFlow` | 取消异常流程：商品上架 → 下单 → 取消订单 |

##### 5. 数据库表结构

项目启动时自动执行 `schema.sql` 初始化以下表：

| 表名 | 说明 |
|------|------|
| `business_trace` | 业务流程轨迹表（节点名称、操作描述、请求接口、请求参数） |
| `data_change_trace` | 字段数据变更追溯表（表名、字段名、修改前值、修改后值） |
| `product` | 演示用商品表 |
| `order_info` | 演示用订单表 |

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request

#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)