# lzh-1.8-log-spring-boot-starter

**Repository Path**: coding_13/lzh-1.8-log-spring-boot-starter

## Basic Information

- **Project Name**: lzh-1.8-log-spring-boot-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-10
- **Last Updated**: 2025-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lzh-1.8-log-spring-boot-starter

这是一个 Spring Boot Starter 模块，用于在项目中自动集成日志记录功能，支持日志切面、MDC 上下文管理、分布式追踪等功能，适用于微服务架构下的日志追踪场景。

## 功能特性

- **日志切面（LogAdvice）**：通过 AOP 实现方法级别的日志记录，支持通过 `@Log` 注解控制日志输出。
- **分布式追踪支持（MDCTraceUtil）**：支持生成和传递 `traceId` 和 `spanId`，用于请求链路追踪。
- **MDC 上下文适配器（TtlMDCAdapter）**：使用 `TransmittableThreadLocal` 实现 MDC 上下文在线程池中的传递，适用于异步场景。
- **Web 请求过滤器（WebTraceFilter）**：在 Web 请求开始时自动注入追踪信息。
- **自动配置（LogAutoConfigure）**：自动注册相关组件，开箱即用。

## 使用方式

1. 将该模块作为依赖引入 Spring Boot 项目：

```xml
<dependency>
    <groupId>com.lzh</groupId>
    <artifactId>lzh-1.8-log-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

2. 在 Spring Boot 启动类上无需额外配置，自动生效。

3. 在需要记录日志的方法或类上添加 `@Log` 注解：

```java
@RestController
public class ExampleController {

    @Log
    @GetMapping("/example")
    public String example() {
        return "Hello, World!";
    }
}
```

4. 日志中将自动包含 `traceId` 和 `spanId`，便于链路追踪。

## 配置说明

- 日志格式可在 `logback-spring.xml` 中自定义，建议包含 `%X{traceId}` 和 `%X{spanId}`。
- 可通过 `application.properties` 或 `application.yml` 配置日志级别、过滤规则等。

## 模块结构

- `LogAutoConfigure`：自动配置类，负责注册组件。
- `LogAdvice`：AOP 切面，实现方法级别的日志记录。
- `Log`：注解，用于标记需要记录日志的方法或类。
- `MDCTraceUtil`：追踪工具类，用于生成和管理 `traceId` 和 `spanId`。
- `TtlMDCAdapter`：线程安全的 MDC 实现，支持异步场景。
- `TtlMDCAdapterInitializer`：MDC 适配器初始化器。
- `WebTraceFilter`：Web 请求过滤器，注入追踪信息。

## 许可证

本项目采用 MIT 许可证，请参见 [LICENSE](LICENSE) 文件。