# trace-spring-boot-starter

**Repository Path**: sunlightwang/trace-spring-boot-starter

## Basic Information

- **Project Name**: trace-spring-boot-starter
- **Description**: trace-spring-boot-starter 是一个轻量级的分布式链路追踪组件，基于 Spring Boot 自动配置机制开发。该组件可以为每个请求生成唯一的 Trace ID（追踪 ID），并在 HTTP、Feign、Dubbo 等多种调用链路中自动传递，帮助开发者快速定位跨服务调用问题。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# trace-spring-boot-starter

## 介绍

`trace-spring-boot-starter` 是一个轻量级的分布式链路追踪组件，基于 Spring Boot 自动配置机制开发。该组件可以为每个请求生成唯一的 Trace ID（追踪 ID），并在 HTTP、Feign、Dubbo 等多种调用链路中自动传递，帮助开发者快速定位跨服务调用问题。

## 软件架构

```
trace-spring-boot-starter
├── core                           # 核心模块
│   ├── annotation                 # 注解定义
│   │   └── EnableTrace            # 启用 Trace 功能注解
│   ├── config                     # 自动配置
│   │   ├── TraceAutoConfiguration # 主自动配置类
│   │   └── TraceWebAutoConfiguration
│   ├── filter                     # 过滤器
│   │   ├── TraceFilter            # HTTP 请求过滤器
│   │   └── DubboTraceFilter       # Dubbo RPC 过滤器
│   ├── generator                  # Trace ID 生成器
│   │   ├── TraceIdGenerator       # 生成器接口
│   │   ├── UuidTraceIdGenerator   # UUID 生成策略
│   │   ├── SnowflakeTraceIdGenerator # 雪花算法生成策略
│   │   └── RedisTraceIdGenerator # Redis 生成策略（预留）
│   ├── interceptor                # 拦截器
│   │   └── FeignTraceInterceptor  # Feign 客户端拦截器
│   ├── properties                 # 配置属性
│   │   └── TraceProperties        # Trace 配置属性类
│   ├── util                       # 工具类
│   │   └── TraceUtils             # Trace 工具类
│   ├── TraceApplication           # 应用入口
│   └── TraceContext               # Trace 上下文管理
```

## 功能特性

- **自动 Trace ID 生成**：支持 UUID、雪花算法等多种生成策略
- **HTTP 请求追踪**：自动在请求头中传递 Trace ID
- **Feign 客户端追踪**：支持 Spring Cloud OpenFeign 调用链追踪
- **Dubbo RPC 追踪**：支持 Dubbo 微服务调用链追踪
- **线程池传递**：支持在异步线程中保持 Trace ID 上下文
- **MDC 集成**：与 SLF4J MDC 无缝集成，方便日志追踪
- **Spring Boot 自动配置**：开箱即用，支持条件化配置

## 技术栈

- Java 8+
- Spring Boot 2.7.x
- Spring Cloud OpenFeign
- Apache Dubbo 2.7.x
- SLF4J

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.common.trace.core</groupId>
    <artifactId>trace-spring-boot-starter</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

### 2. 启用 Trace 功能

在 Spring Boot 启动类上添加 `@EnableTrace` 注解：

```java
import com.common.trace.core.annotation.EnableTrace;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

### 3. 配置参数（可选）

在 `application.yml` 或 `application.properties` 中配置：

```yaml
trace:
  # 是否启用追踪，默认 true
  enabled: true
  # Trace ID 生成策略：UUID, SNOWFLAKE（预留：REDIS）
  generator: UUID
  # HTTP 请求头名称
  header-name: X-Trace-Id
  # Feign 调用追踪，默认 true
  feign:
    enabled: true
  # Dubbo 调用追踪，默认 true
  dubbo:
    enabled: true
```

雪花算法配置（当 `generator: SNOWFLAKE` 时）：

```yaml
trace:
  generator: SNOWFLAKE
  snowflake-worker-id: 1
  snowflake-datacenter-id: 1
```

## 使用说明

### 获取当前 Trace ID

在业务代码中可以通过 `TraceContext` 获取当前请求的 Trace ID：

```java
import com.common.trace.core.TraceContext;

// 获取当前请求的 Trace ID
String traceId = TraceContext.getTraceId();
```

### 在日志中输出 Trace ID

由于集成了 MDC，可以直接在日志配置中使用 `%X{traceId}` 占位符：

```xml
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>
```

### 异步线程支持

`TraceContext` 提供了 `wrap` 方法来支持在线程池中传递 Trace ID：

```java
import com.common.trace.core.TraceContext;

// 包装 Runnable
Runnable wrappedTask = TraceContext.wrap(() -> {
    // 在新线程中自动获取父线程的 Trace ID
    String traceId = TraceContext.getTraceId();
    // 业务逻辑
});
executor.execute(wrappedTask);

// 包装 Callable
Callable<String> wrappedCallable = TraceContext.wrap(() -> {
    return TraceContext.getTraceId();
});
```

## 工作原理

### HTTP 请求流程

1. 请求进入 `TraceFilter`
2. 检查请求头中是否存在 `X-Trace-Id`
3. 存在则使用原有 ID，不存在则生成新的 Trace ID
4. 将 Trace ID 存入 `TraceContext` 和 MDC
5. 将 Trace ID 添加到响应头返回
6. 请求完成后清除上下文

### Feign 调用流程

1. `FeignTraceInterceptor` 在请求发送前拦截
2. 从 `TraceContext` 获取当前 Trace ID
3. 将 Trace ID 添加到 Feign 请求头
4. 调用下游服务

### Dubbo 调用流程

1. 消费者端：将 Trace ID 放入 RPC 上下文附件
2. 服务提供者端：从 RPC 上下文附件获取 Trace ID
3. 设置到 `TraceContext` 供业务使用

## 贡献指南

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

## 许可证

MIT License