@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-web/README.md

@@ -0,0 +1,1007 @@
+---
+name: avatar-boot-starter-web
+description: 当使用 avatar-boot-starter-web 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供全面的 Web 开发基础设施，包括请求上下文管理、结构化日志、全局异常处理、指标集成。
+---
+
+# Avatar Boot Starter Web 技能
+
+## 何时使用此技能
+
+当用户出现以下情况时调用此技能：
+
+- 提到 "avatar-boot-starter-web"、"web starter" 或 "web 模块"
+- 询问请求上下文、TraceId 或请求追踪
+- 想要配置或排查 Avatar Boot 应用中的日志问题
+- 询问全局异常处理或错误响应
+- 需要为 Web 应用配置 CORS
+- 想要检测或监控慢请求
+- 询问客户端 IP 提取或代理处理
+- 提到 `@LogInfo` 注解或方法级日志
+- 想要集成 Micrometer 指标/监控
+- 正在使用 Avatar Boot 创建新的 Web 应用
+- 询问结构化日志或 JSON 日志格式
+- 需要在业务逻辑中访问请求上下文
+- 排查 TraceId 传播问题
+- 询问异步场景下的 TraceID 传播（1.0.0-SNAPSHOT+）
+- 使用 @Async、CompletableFuture 或自定义线程池（1.0.0-SNAPSHOT+）
+- 想要自定义 TraceID 生成策略（1.0.0-SNAPSHOT+）
+- 需要集成 Micrometer Tracing 或分布式追踪系统（1.0.0-SNAPSHOT+）
+
+## 模块概述
+
+`avatar-boot-starter-web` 模块是一个 Spring Boot starter，为 Avatar Boot 应用提供生产就绪的 Web 开发基础设施。它遵循 Spring Boot 自动配置约定，无需任何配置即可开始使用。
+
+**核心能力：**
+- 自动初始化请求上下文并生成 TraceId
+- 结构化日志并自动注入 TraceId
+- 全局异常处理并返回标准化响应
+- 使用 Micrometer 集成指标
+- CORS 支持（默认禁用）
+- 慢请求检测和监控
+- 代理感知的客户端 IP 提取
+
+## 核心功能
+
+### 1. 请求上下文管理
+
+**功能说明：**
+- 为每个 HTTP 请求自动初始化 `AvatarContext`
+- 从 `X-Trace-Id` 请求头生成或传播 TraceId
+- 提取客户端 IP（代理感知，支持 X-Forwarded-For）
+- 追踪请求耗时并检测慢请求
+- 自动清理 ThreadLocal 以防止内存泄漏
+
+**核心组件：**
+- `RequestContextInterceptor` - 拦截所有请求（可配置路径）
+- `AvatarContext` - 保存请求元数据（traceId、uri、method、clientIp、startTime）
+- `ContextManager` - 基于 ThreadLocal 的上下文访问器
+
+**使用示例：**
+引入pom依赖：
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-web</artifactId>
+    <version>${avatar.boot.version}</version>
+</dependency>
+```
+
+```java
+import com.iflytek.avatar.boot.context.AvatarContext;
+import com.iflytek.avatar.boot.context.ContextManager;
+
+@RestController
+public class UserController {
+
+    @GetMapping("/user/info")
+    public Result<UserInfo> getUserInfo() {
+        // 访问当前请求上下文
+        AvatarContext context = ContextManager.get();
+        String traceId = context.getTraceId();
+        String clientIp = context.getClientIp();
+
+        log.info("Processing request for user from IP: {}", clientIp);
+        return Result.success(userInfo);
+    }
+}
+```
+
+### 2. 结构化日志
+
+**功能说明：**
+- 自动将 TraceId 注入所有日志消息
+- 使用 Logstash Logback Encoder 提供 JSON 日志格式
+- 支持多种日志输出（控制台、文件、JSON 文件）
+- 使用异步 appender 实现高性能
+- 自动为慢请求添加 `[SLOW]` 前缀标记
+
+**日志格式：**
+
+控制台/文件格式：
+```
+2026-03-03 17:04:15.123 [http-nio-8080-exec-1] [abc123def456] INFO  c.i.a.b.controller.UserController - Request started: GET /user/info from 192.168.1.100
+```
+
+JSON 格式：
+```json
+{
+  "timestamp": "2026-03-03T17:04:15.123+08:00",
+  "level": "INFO",
+  "thread": "http-nio-8080-exec-1",
+  "logger": "com.iflytek.avatar.boot.controller.UserController",
+  "message": "Request started: GET /user/info from 192.168.1.100",
+  "traceId": "abc123def456",
+  "app": "avatar-app"
+}
+```
+
+**日志文件：**
+- `logs/${spring.application.name}.log` - 所有日志
+- `logs/${spring.application.name}-error.log` - 仅错误日志
+- `logs/${spring.application.name}-json.log` - JSON 格式日志
+
+**环境特定行为：**
+- **dev/local**：控制台 + 文件输出
+- **test**：控制台 + 文件 + JSON 输出
+- **prod**：仅文件 + JSON 输出（无控制台）
+
+### 3. @LogInfo 注解
+
+**功能说明：**
+- 通过 AOP 提供方法级日志
+- 记录请求参数和响应结果
+- 追踪方法执行时间
+- 集成指标记录
+- 自动记录异常及堆栈信息
+
+**注解参数：**
+```java
+@LogInfo(
+    request = true,      // 记录请求参数（默认：false）
+    response = true,     // 记录响应结果（默认：false）
+    metrics = true,      // 记录指标（默认：false）
+    costTime = 3000      // 慢方法阈值（毫秒）（默认：3000）
+)
+```
+
+**使用示例：**
+```java
+@Service
+public class UserService {
+
+    @LogInfo(request = true, response = true, metrics = true, costTime = 2000)
+    public UserInfo getUserById(Long userId) {
+        // 业务逻辑
+        return userInfo;
+    }
+}
+```
+
+**日志输出：**
+```
+[UserService.getUserById] Status: SUCCESS, Time: 156ms
+→ Request: [123]
+→ Response: {"id":123,"name":"John Doe"}
+```
+
+**慢方法警告：**
+```
+[UserService.getUserById] Status: SUCCESS, Time: 2345ms (⚠️ threshold: 2000ms)
+→ Request: [123]
+→ Response: {"id":123,"name":"John Doe"}
+```
+
+### 4. 全局异常处理
+
+**功能说明：**
+- 捕获所有异常并返回标准化的 `Result<?>` 响应
+- 处理业务异常、参数校验错误和系统错误
+- 记录异常及请求上下文（URI、方法）
+- 返回适当的 HTTP 状态码
+
+**支持的异常类型：**
+- `BusinessException` - 业务逻辑错误（HTTP 200 带错误码）
+- `MethodArgumentNotValidException` - @RequestBody 校验（HTTP 400）
+- `BindException` - @ModelAttribute 校验（HTTP 400）
+- `ConstraintViolationException` - @RequestParam 校验（HTTP 400）
+- `RuntimeException` - 运行时错误（HTTP 500）
+- `Exception` - 所有其他异常（HTTP 500）
+
+**使用示例：**
+```java
+import com.iflytek.avatar.boot.exception.BusinessException;
+import com.iflytek.avatar.boot.entity.response.ResultCode;
+
+@Service
+public class UserService {
+
+    public void updateUser(Long userId) {
+        if (userId == null) {
+            throw new BusinessException(ResultCode.PARAM_ERROR, "用户ID不能为空");
+        }
+        // 业务逻辑
+    }
+}
+```
+
+**响应格式：**
+```json
+{
+  "code": 400,
+  "message": "用户ID不能为空",
+  "data": null,
+  "success": false
+}
+```
+
+### 5. 指标集成
+
+**功能说明：**
+- 记录方法调用次数和执行时间
+- 使用 Micrometer 进行指标收集
+- 缓存指标实例以避免重复注册
+- 支持成功/失败状态追踪
+
+**记录的指标：**
+- `method.invocation.count` - 计数器，标签：class、method、status
+- `method.execution.time` - 计时器，标签：class、method、status
+
+**使用方式：**
+使用 `@LogInfo(metrics = true)` 时会自动记录指标。
+
+**手动记录：**
+```java
+@Autowired
+private MetricsRecorder metricsRecorder;
+
+public void someMethod() {
+    long startTime = System.currentTimeMillis();
+    try {
+        // 业务逻辑
+        long costTime = System.currentTimeMillis() - startTime;
+        metricsRecorder.recordMethodMetrics("MyClass", "someMethod", costTime, null);
+    } catch (Exception e) {
+        long costTime = System.currentTimeMillis() - startTime;
+        metricsRecorder.recordMethodMetrics("MyClass", "someMethod", costTime, e);
+        throw e;
+    }
+}
+```
+
+### 6. CORS 支持
+
+**功能说明：**
+- 提供可配置的跨域资源共享
+- 出于安全考虑默认禁用
+- 支持自定义源、方法、请求头和凭证
+
+**配置示例：**
+```yaml
+avatar:
+  web:
+    cors-enabled: true
+    cors:
+      allowed-origins:
+        - "https://example.com"
+        - "https://app.example.com"
+      allowed-methods:
+        - GET
+        - POST
+        - PUT
+        - DELETE
+      allowed-headers:
+        - "*"
+      exposed-headers:
+        - X-Trace-Id
+      allow-credentials: true
+      max-age: 3600
+```
+
+### 7. TraceID 异步支持与 Micrometer 集成
+
+**版本要求：** Avatar Boot 1.0.0-SNAPSHOT+
+
+**功能说明：**
+- 使用 TransmittableThreadLocal 自动传播 TraceID 到异步线程
+- 支持 @Async、CompletableFuture、自定义线程池
+- 可插拔的 TraceID 生成器（UUID、Snowflake、自定义）
+- 可选的 Micrometer Tracing 集成（支持 Zipkin、Jaeger）
+- 向后兼容，无需修改现有代码
+
+**核心改进：**
+
+#### 7.1 异步场景自动支持
+
+**问题：** 之前使用普通 ThreadLocal，无法在异步线程中传播 TraceID
+
+**解决方案：**
+- 使用阿里巴巴的 TransmittableThreadLocal (TTL)
+- 自动配置 TaskDecorator 装饰异步任务
+- 支持 @Async、CompletableFuture、自定义线程池
+
+**使用示例：**
+
+```java
+@Service
+public class UserService {
+
+    @Async
+    public CompletableFuture<User> getUserAsync(String userId) {
+        // TraceID 自动传播到异步线程
+        String traceId = ContextManager.get().getTraceId();
+        log.info("Async thread TraceID: {}", traceId);
+
+        User user = userRepository.findById(userId);
+        return CompletableFuture.completedFuture(user);
+    }
+}
+```
+
+**日志输出：**
+```
+[main] [abc123] Request started: GET /users/1
+[avatar-async-1] [abc123] Async thread TraceID: abc123
+[main] [abc123] Request completed: GET /users/1 - 150ms
+```
+
+#### 7.2 可插拔的 TraceID 生成器
+
+**默认实现：** 使用 UUID（去除连字符）
+
+**自定义实现：**
+
+```java
+@Component
+public class SnowflakeTraceIdGenerator implements TraceIdGenerator {
+
+    private final Snowflake snowflake = IdUtil.getSnowflake(1, 1);
+
+    @Override
+    public String generate() {
+        return String.valueOf(snowflake.nextId());
+    }
+}
+```
+
+#### 7.3 Micrometer Tracing 集成（可选）
+
+**启用方式：**
+
+```yaml
+avatar:
+  web:
+    tracing:
+      micrometer-enabled: true
+
+management:
+  tracing:
+    enabled: true
+    sampling:
+      probability: 1.0
+```
+
+**收益：**
+- 与 Spring Cloud 生态无缝集成
+- 支持 Zipkin、Jaeger 等分布式追踪系统
+- 自动传播 W3C Trace Context 和 B3 格式
+
+**异步配置：**
+
+```yaml
+avatar:
+  web:
+    async:
+      enabled: true              # 是否启用异步支持（默认：true）
+      core-pool-size: 10         # 核心线程数
+      max-pool-size: 50          # 最大线程数
+      queue-capacity: 200        # 队列容量
+      thread-name-prefix: avatar-async-
+```
+
+**追踪配置：**
+
+```yaml
+avatar:
+  web:
+    tracing:
+      micrometer-enabled: false  # 是否启用 Micrometer 集成（默认：false）
+      generator-type: uuid       # TraceID 生成策略（uuid, snowflake, custom）
+```
+
+**性能影响：**
+- 内存开销：每个异步任务额外复制一份上下文（约 1KB）
+- CPU 开销：上下文复制和恢复（< 1ms）
+- 总体影响：< 5%（压测验证）
+
+**依赖版本：**
+- TransmittableThreadLocal: 2.14.5
+- Micrometer Tracing: 1.4.3（可选）
+
+## 配置指南
+
+### 基础配置（最小化）
+
+```yaml
+spring:
+  application:
+    name: my-app
+
+# 所有功能默认启用，无需额外配置
+```
+
+### 高级配置（所有选项）
+
+```yaml
+avatar:
+  web:
+    # 功能开关
+    interceptor-enabled: true           # 启用请求拦截器（默认：true）
+    exception-handler-enabled: true     # 启用全局异常处理器（默认：true）
+    cors-enabled: false                 # 启用 CORS（默认：false）
+
+    # 拦截器配置
+    interceptor:
+      trace-id-header: X-Trace-Id       # TraceId 请求头名称（默认：X-Trace-Id）
+      include-paths:                    # 拦截路径（默认：/**）
+        - /**
+      exclude-paths:                    # 排除路径
+        - /error
+        - /actuator/**
+        - /favicon.ico
+        - /webjars/**
+        - /swagger-ui/**
+        - /v3/api-docs/**
+
+    # 日志配置
+    log:
+      request-enabled: true             # 记录请求开始（默认：true）
+      response-enabled: true            # 记录请求完成（默认：true）
+      slow-request-threshold: 3000      # 慢请求阈值（毫秒）（默认：3000）
+
+    # 异步配置（1.0.0-SNAPSHOT+）
+    async:
+      enabled: true                     # 启用异步支持（默认：true）
+      core-pool-size: 10                # 核心线程数（默认：10）
+      max-pool-size: 50                 # 最大线程数（默认：50）
+      queue-capacity: 200               # 队列容量（默认：200）
+      thread-name-prefix: avatar-async- # 线程名前缀（默认：avatar-async-）
+
+    # 追踪配置（1.0.0-SNAPSHOT+）
+    tracing:
+      micrometer-enabled: false         # 启用 Micrometer 集成（默认：false）
+      generator-type: uuid              # TraceID 生成策略（uuid, snowflake, custom）
+
+    # CORS 配置（仅当 cors-enabled: true 时生效）
+    cors:
+      allowed-origins:
+        - "*"
+      allowed-methods:
+        - GET
+        - POST
+        - PUT
+        - DELETE
+        - OPTIONS
+      allowed-headers:
+        - "*"
+      exposed-headers:
+        - X-Trace-Id
+      allow-credentials: true
+      max-age: 3600
+
+# 日志配置
+logging:
+  level:
+    root: INFO
+    com.iflytek.avatar.boot: DEBUG
+  file:
+    path: logs
+```
+
+### 环境特定配置
+
+**开发环境（dev）：**
+```yaml
+spring:
+  config:
+    activate:
+      on-profile: dev
+
+avatar:
+  web:
+    log:
+      slow-request-threshold: 5000  # 开发环境放宽阈值
+
+logging:
+  level:
+    root: INFO
+    com.iflytek.avatar.boot: DEBUG
+```
+
+**生产环境（prod）：**
+```yaml
+spring:
+  config:
+    activate:
+      on-profile: prod
+
+avatar:
+  web:
+    cors-enabled: false  # 生产环境禁用 CORS
+    log:
+      slow-request-threshold: 2000  # 生产环境更严格的阈值
+
+logging:
+  level:
+    root: INFO
+    com.iflytek.avatar.boot: INFO
+  file:
+    path: /var/log/app
+```
+
+## 常见使用场景
+
+### 场景 1：API 网关集成
+
+在 API 网关（Kong、Nginx）后构建服务时：
+
+```yaml
+avatar:
+  web:
+    interceptor:
+      trace-id-header: X-Request-Id  # 匹配网关的请求头名称
+      exclude-paths:
+        - /health
+        - /metrics
+```
+
+### 场景 2：微服务分布式追踪
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private RestTemplate restTemplate;
+
+    public void createOrder(OrderRequest request) {
+        // TraceId 自动可用
+        AvatarContext context = ContextManager.get();
+        String traceId = context.getTraceId();
+
+        // 将 TraceId 传播到下游服务
+        HttpHeaders headers = new HttpHeaders();
+        headers.set("X-Trace-Id", traceId);
+
+        HttpEntity<OrderRequest> entity = new HttpEntity<>(request, headers);
+        restTemplate.postForObject("http://inventory-service/api/reserve", entity, Void.class);
+    }
+}
+```
+
+### 场景 3：性能监控
+
+```java
+@RestController
+@RequestMapping("/api/reports")
+public class ReportController {
+
+    @LogInfo(request = true, response = false, metrics = true, costTime = 5000)
+    @GetMapping("/sales")
+    public Result<SalesReport> generateSalesReport(@RequestParam String startDate,
+                                                     @RequestParam String endDate) {
+        // 重计算
+        SalesReport report = reportService.generateReport(startDate, endDate);
+        return Result.success(report);
+    }
+}
+```
+
+### 场景 4：自定义异常处理
+
+```java
+@Component
+public class CustomExceptionHandler extends GlobalExceptionHandler {
+
+    @ExceptionHandler(AuthenticationException.class)
+    @ResponseStatus(HttpStatus.UNAUTHORIZED)
+    public Result<?> handleAuthenticationException(AuthenticationException e) {
+        log.error("Authentication failed: {}", e.getMessage());
+        return Result.fail(401, "认证失败，请重新登录");
+    }
+}
+```
+
+### 场景 5：@Async 异步方法（1.0.0-SNAPSHOT+）
+
+**自动支持 TraceID 传播**：
+
+```java
+@Service
+public class NotificationService {
+
+    @Async
+    public void sendNotification(String userId, String message) {
+        // TraceID 自动传播到异步线程
+        String traceId = ContextManager.get().getTraceId();
+        log.info("Sending notification with TraceID: {}", traceId);
+        // ... 发送通知
+    }
+}
+```
+
+### 场景 6：CompletableFuture 并行处理（1.0.0-SNAPSHOT+）
+
+**自动支持 TraceID 传播**：
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private Executor asyncExecutor;
+
+    public Order createOrder(OrderRequest request) {
+        String traceId = ContextManager.get().getTraceId();
+
+        CompletableFuture<Void> inventoryCheck = CompletableFuture.runAsync(() -> {
+            // TraceID 自动传播
+            log.info("Checking inventory with TraceID: {}", traceId);
+            inventoryService.checkStock(request.getProductId());
+        }, asyncExecutor);
+
+        CompletableFuture<Void> paymentProcess = CompletableFuture.runAsync(() -> {
+            // TraceID 自动传播
+            log.info("Processing payment with TraceID: {}", traceId);
+            paymentService.process(request.getPayment());
+        }, asyncExecutor);
+
+        CompletableFuture.allOf(inventoryCheck, paymentProcess).join();
+
+        return orderRepository.save(new Order(request));
+    }
+}
+```
+
+### 场景 7：自定义线程池（1.0.0-SNAPSHOT+）
+
+**需要使用 MdcTaskDecorator**：
+
+```java
+@Configuration
+public class CustomThreadPoolConfig {
+
+    @Autowired
+    private MdcTaskDecorator mdcTaskDecorator;
+
+    @Bean
+    public ThreadPoolTaskExecutor customExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setCorePoolSize(5);
+        executor.setMaxPoolSize(10);
+        executor.setQueueCapacity(100);
+        executor.setThreadNamePrefix("custom-");
+
+        // 应用 MDC 任务装饰器以传播 TraceID
+        executor.setTaskDecorator(mdcTaskDecorator);
+
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+## 故障排查
+
+### 问题 1：日志中未显示 TraceId
+
+**症状：**
+- 日志中没有显示 TraceId（方括号内）
+- JSON 日志中缺少 traceId 字段
+
+**可能原因：**
+1. 请求拦截器被禁用
+2. 请求路径被排除
+3. Logback 配置不正确
+
+**解决方案：**
+```yaml
+# 1. 确保拦截器已启用
+avatar:
+  web:
+    interceptor-enabled: true
+
+# 2. 检查排除路径
+avatar:
+  web:
+    interceptor:
+      exclude-paths:
+        - /actuator/**  # 确保你的路径没有被排除
+
+# 3. 验证 logback-spring.xml 包含 TraceId 模式
+# 模式应包含：[%X{traceId}]
+```
+
+### 问题 2：CORS 错误
+
+**症状：**
+- 浏览器显示 CORS 策略错误
+- 预检 OPTIONS 请求失败
+
+**解决方案：**
+```yaml
+# 显式启用 CORS
+avatar:
+  web:
+    cors-enabled: true
+    cors:
+      allowed-origins:
+        - "https://your-frontend-domain.com"  # 使用凭证时不要用 "*"
+      allow-credentials: true
+```
+
+**重要提示：** 如果 `allow-credentials: true`，则不能使用 `allowed-origins: ["*"]`。必须指定确切的源。
+
+### 问题 3：慢请求误报
+
+**症状：**
+- 许多请求被标记为 [SLOW]，但实际上并不慢
+- 阈值对你的使用场景来说太低
+
+**解决方案：**
+```yaml
+# 根据环境调整阈值
+avatar:
+  web:
+    log:
+      slow-request-threshold: 5000  # 增加到 5 秒
+
+# 或禁用慢请求日志
+avatar:
+  web:
+    log:
+      response-enabled: false
+```
+
+### 问题 4：ThreadLocal 内存泄漏
+
+**症状：**
+- 内存使用随时间增长
+- 生产环境出现 OutOfMemoryError
+
+**诊断：**
+拦截器会在 `afterCompletion()` 中自动清理 ThreadLocal。如果出现内存泄漏：
+
+1. 检查是否手动设置上下文但未清理：
+```java
+// ❌ 错误 - 手动设置但未清理
+ContextManager.set(context);
+// ... 业务逻辑
+// 缺失：ContextManager.clear();
+
+// ✅ 正确 - 让拦截器处理
+AvatarContext context = ContextManager.get();
+```
+
+2. 验证拦截器已注册：
+```yaml
+avatar:
+  web:
+    interceptor-enabled: true  # 必须为 true
+```
+
+### 问题 5：客户端 IP 显示为代理 IP
+
+**症状：**
+- `context.getClientIp()` 返回代理/负载均衡器 IP
+- 未捕获真实客户端 IP
+
+**解决方案：**
+确保你的代理/负载均衡器设置了正确的请求头：
+
+```nginx
+# Nginx 配置
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Real-IP $remote_addr;
+```
+
+拦截器按以下顺序检查请求头：
+1. `X-Forwarded-For`（如果有多个则取第一个 IP）
+2. `X-Real-IP`
+3. `Proxy-Client-IP`
+4. `WL-Proxy-Client-IP`
+5. `request.getRemoteAddr()`
+
+### 问题 6：@LogInfo 不工作
+
+**症状：**
+- 使用 @LogInfo 注解的方法没有日志
+- 指标未记录
+
+**可能原因：**
+1. AOP 未启用
+2. 方法未通过 Spring 代理调用
+3. LogInfoAspect 未注册
+
+**解决方案：**
+```java
+// ❌ 错误 - 直接调用方法会绕过 AOP
+@Service
+public class UserService {
+    @LogInfo
+    public void method1() { }
+
+    public void method2() {
+        this.method1();  // 直接调用，AOP 不会拦截
+    }
+}
+
+// ✅ 正确 - 通过 Spring 代理调用
+@Service
+@RequiredArgsConstructor
+public class UserService {
+    private final UserService self;  // 注入自身
+
+    @LogInfo
+    public void method1() { }
+
+    public void method2() {
+        self.method1();  // 代理调用，AOP 生效
+    }
+}
+```
+
+### 问题 7：异步线程中 TraceID 为 null（1.0.0-SNAPSHOT+）
+
+**症状：**
+- 异步方法中 `ContextManager.get().getTraceId()` 返回 null
+- 异步线程的日志中没有 TraceID
+
+**可能原因：**
+1. 使用了自定义线程池但未应用 MdcTaskDecorator
+2. 异步支持被禁用
+3. 使用了不受管理的线程（如 new Thread()）
+
+**解决方案：**
+
+**方案 1：使用配置的异步执行器**
+```java
+@Service
+public class MyService {
+    @Autowired
+    private Executor asyncExecutor;  // 使用 Avatar Boot 配置的执行器
+
+    public void doWork() {
+        CompletableFuture.runAsync(() -> {
+            // TraceID 自动传播
+            String traceId = ContextManager.get().getTraceId();
+        }, asyncExecutor);
+    }
+}
+```
+
+**方案 2：自定义线程池应用 MdcTaskDecorator**
+```java
+@Configuration
+public class ThreadPoolConfig {
+    @Autowired
+    private MdcTaskDecorator mdcTaskDecorator;
+
+    @Bean
+    public ThreadPoolTaskExecutor customExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setTaskDecorator(mdcTaskDecorator);  // 关键：应用装饰器
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+**方案 3：检查异步支持是否启用**
+```yaml
+avatar:
+  web:
+    async:
+      enabled: true  # 确保为 true
+```
+
+### 问题 8：如何验证异步 TraceID 传播是否生效（1.0.0-SNAPSHOT+）
+
+**验证方法：**
+
+```java
+@RestController
+public class TestController {
+
+    @Autowired
+    private Executor asyncExecutor;
+
+    @GetMapping("/test-async")
+    public String testAsync() {
+        String mainTraceId = ContextManager.get().getTraceId();
+        log.info("Main thread TraceID: {}", mainTraceId);
+
+        CompletableFuture.runAsync(() -> {
+            String asyncTraceId = ContextManager.get().getTraceId();
+            log.info("Async thread TraceID: {}", asyncTraceId);
+        }, asyncExecutor).join();
+
+        return "Check logs";
+    }
+}
+```
+
+**预期日志输出：**
+```
+[http-nio-8080-exec-1] [abc123] Main thread TraceID: abc123
+[avatar-async-1] [abc123] Async thread TraceID: abc123
+```
+
+如果异步线程的 TraceID 为 null 或不一致，说明传播未生效。
+
+## 组件参考
+
+### 核心类
+
+| 类 | 包 | 用途 |
+|-------|---------|---------|
+| `WebAutoConfiguration` | `com.iflytek.avatar.boot.config` | 主自动配置类 |
+| `WebProperties` | `com.iflytek.avatar.boot.config` | 配置属性 |
+| `WebMvcConfiguration` | `com.iflytek.avatar.boot.config` | MVC 配置（拦截器、CORS） |
+| `MetricsConfiguration` | `com.iflytek.avatar.boot.config` | 指标记录器配置 |
+| `RequestContextInterceptor` | `com.iflytek.avatar.boot.interceptor` | 请求上下文初始化 |
+| `GlobalExceptionHandler` | `com.iflytek.avatar.boot.exception` | 全局异常处理 |
+| `LogInfo` | `com.iflytek.avatar.boot.anno` | 方法级日志注解 |
+| `LogInfoAspect` | `com.iflytek.avatar.boot.anno` | @LogInfo 的 AOP 切面 |
+| `MetricsRecorder` | `com.iflytek.avatar.boot.metrics` | 指标记录工具 |
+| `AvatarContext` | `com.iflytek.avatar.boot.context` | 请求上下文持有者（在 core 中） |
+| `ContextManager` | `com.iflytek.avatar.boot.context` | ThreadLocal 上下文管理器（在 core 中） |
+
+### 配置属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|----------|------|---------|-------------|
+| `avatar.web.interceptor-enabled` | boolean | true | 启用请求拦截器 |
+| `avatar.web.exception-handler-enabled` | boolean | true | 启用全局异常处理器 |
+| `avatar.web.cors-enabled` | boolean | false | 启用 CORS |
+| `avatar.web.interceptor.trace-id-header` | String | X-Trace-Id | TraceId 请求头名称 |
+| `avatar.web.interceptor.include-paths` | List<String> | ["/**"] | 拦截路径 |
+| `avatar.web.interceptor.exclude-paths` | List<String> | ["/error", "/actuator/**", ...] | 排除路径 |
+| `avatar.web.log.request-enabled` | boolean | true | 记录请求开始 |
+| `avatar.web.log.response-enabled` | boolean | true | 记录请求完成 |
+| `avatar.web.log.slow-request-threshold` | long | 3000 | 慢请求阈值（毫秒） |
+| `avatar.web.async.enabled` | boolean | true | 启用异步支持（1.0.0-SNAPSHOT+） |
+| `avatar.web.async.core-pool-size` | int | 10 | 异步执行器核心线程数（1.0.0-SNAPSHOT+） |
+| `avatar.web.async.max-pool-size` | int | 50 | 异步执行器最大线程数（1.0.0-SNAPSHOT+） |
+| `avatar.web.async.queue-capacity` | int | 200 | 异步执行器队列容量（1.0.0-SNAPSHOT+） |
+| `avatar.web.async.thread-name-prefix` | String | avatar-async- | 异步线程名前缀（1.0.0-SNAPSHOT+） |
+| `avatar.web.tracing.micrometer-enabled` | boolean | false | 启用 Micrometer 集成（1.0.0-SNAPSHOT+） |
+| `avatar.web.tracing.generator-type` | String | uuid | TraceID 生成策略（1.0.0-SNAPSHOT+） |
+| `avatar.web.cors.allowed-origins` | List<String> | ["*"] | 允许的源 |
+| `avatar.web.cors.allowed-methods` | List<String> | ["GET", "POST", ...] | 允许的 HTTP 方法 |
+| `avatar.web.cors.allowed-headers` | List<String> | ["*"] | 允许的请求头 |
+| `avatar.web.cors.exposed-headers` | List<String> | ["X-Trace-Id"] | 暴露的响应头 |
+| `avatar.web.cors.allow-credentials` | boolean | true | 允许凭证 |
+| `avatar.web.cors.max-age` | long | 3600 | 预检缓存时间（秒） |
+
+## 依赖
+
+此模块依赖于：
+
+- `avatar-boot-core` - 核心功能（AvatarContext、Result 等）
+- `spring-boot-starter-web` - Spring MVC
+- `spring-boot-starter-validation` - 参数校验
+- `spring-boot-starter-aop` - @LogInfo 的 AOP 支持
+- `micrometer-core` - 指标（可选）
+- `logstash-logback-encoder` - JSON 日志格式化
+- `hutool-all` - 工具库（UUID、字符串处理）
+
+## 最佳实践
+
+1. **始终使用 Result<T> 作为 API 响应** - 确保响应格式一致
+2. **生产环境不要禁用拦截器** - TraceId 对故障排查至关重要
+3. **谨慎使用 @LogInfo** - 仅在关键业务方法上使用，避免日志膨胀
+4. **根据环境配置慢请求阈值** - 开发环境可以放宽，生产环境应严格
+5. **生产环境永远不要使用 CORS "*" 配合凭证** - 安全风险
+6. **始终将 TraceId 传播到下游服务** - 启用分布式追踪
+7. **使用环境特定的日志级别** - 开发环境用 DEBUG，生产环境用 INFO
+8. **在生产环境监控指标** - 为高失败率或慢方法设置告警
+9. **不要捕获并吞掉异常** - 让 GlobalExceptionHandler 处理它们
+10. **在 finally 块中清理资源** - 尽管拦截器会处理上下文清理
+
+## 版本要求
+
+- Java 21+
+- Spring Boot 3.5.3+
+- Maven 3.8.6+
+
+## 相关技能
+
+- `avatar-boot-sdk-development` - 用于整体 Avatar Boot 架构和依赖管理
+- `java-spring-boot` - 用于通用 Spring Boot 开发模式
+- `systematic-debugging` - 用于排查此模块的问题
+
+## 其他资源
+
+- 模块 README：`avatar-boot-starter-web/README.md`
+- 配置示例：`avatar-boot-starter-web/src/main/resources/application-example.yml`
+- Logback 配置：`avatar-boot-starter-web/src/main/resources/logback-spring.xml`