@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-LogInfo/346/263/250/350/247/243.md

@@ -0,0 +1,75 @@
+# @LogInfo 方法日志注解
+
+## 功能说明
+
+`@LogInfo` 是方法级别的日志注解，基于 AOP 实现，支持：
+- 记录方法入参和返回值
+- 统计方法执行时间
+- 慢方法检测与告警
+- 联动 Micrometer 指标监控
+- 异常自动记录
+
+## 基本用法
+
+```java
+import com.iflytek.avatar.boot.anno.LogInfo;
+
+@Service
+public class OrderService {
+
+    // 记录请求参数和响应结果，启用指标监控
+    @LogInfo(request = true, response = true, metrics = true)
+    public OrderInfo createOrder(OrderRequest request) {
+        // 业务逻辑...
+        return orderInfo;
+    }
+
+    // 只记录慢方法（超过 1000ms 才输出日志）
+    @LogInfo(costTime = 1000)
+    public void processHeavyTask() {
+        // 耗时操作...
+    }
+
+    // 只记录异常，不记录正常调用
+    @LogInfo
+    public void riskyOperation() {
+        // 可能抛出异常的操作...
+    }
+}
+```
+
+## 注解参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:--|:--|:--|:--|
+| `request` | boolean | false | 是否记录方法入参 |
+| `response` | boolean | false | 是否记录方法返回值 |
+| `metrics` | boolean | false | 是否上报 Micrometer 指标 |
+| `costTime` | long | 0 | 慢方法阈值（ms），0 表示始终记录 |
+
+## 日志输出示例
+
+正常调用：
+```
+2026-03-05 10:30:15.123 [http-nio-8080-exec-1] [abc123def456] INFO  c.i.a.b.anno.LogInfoAspect - [OrderService.createOrder] Status: SUCCESS, Time: 245ms
+→ Request: {"userId":123,"productId":456,"quantity":2}
+→ Response: {"orderId":"ORD20260305001","status":"CREATED"}
+```
+
+慢方法告警：
+```
+2026-03-05 10:35:20.789 [http-nio-8080-exec-2] [def456ghi789] WARN  c.i.a.b.anno.LogInfoAspect - [OrderService.processHeavyTask] Status: SUCCESS, Time: 5234ms (⚠️ threshold: 3000ms)
+```
+
+异常记录：
+```
+2026-03-05 10:40:00.000 [http-nio-8080-exec-3] [ghi789jkl012] ERROR c.i.a.b.anno.LogInfoAspect - [OrderService.riskyOperation] Status: FAILED, Time: 12ms
+→ Exception: java.lang.IllegalStateException: 状态不合法
+```
+
+## 注意事项
+
+- JSON 序列化自动截断超过 2000 字符的内容，避免日志过大
+- `metrics = true` 需要引入 `spring-boot-starter-actuator` 才生效
+- 注解基于 Spring AOP，**不支持同类内部方法调用**（self-invocation 问题）
+- 建议在 Service 层使用，Controller 层的日志由拦截器统一处理

package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/345/205/250/345/261/200/345/274/202/345/270/270/345/244/204/347/220/206.md

@@ -0,0 +1,90 @@
+# 全局异常处理
+
+## 功能说明
+
+模块内置 `GlobalExceptionHandler`，自动处理以下异常类型并返回统一的 `Result` 格式响应：
+
+| 异常类型 | 触发场景 | 响应码 |
+|:--|:--|:--|
+| `BusinessException` | 业务逻辑异常 | 自定义码 |
+| `BadRequestException` | 请求参数错误 | 400 |
+| `MethodArgumentNotValidException` | `@RequestBody` 校验失败 | 400 |
+| `BindException` | `@ModelAttribute` 校验失败 | 400 |
+| `ConstraintViolationException` | `@RequestParam` 校验失败 | 400 |
+| `Exception` | 未捕获的系统异常 | 500 |
+
+## 统一响应格式
+
+所有接口响应均为 `Result<T>` 结构：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+## 抛出业务异常
+
+```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不能为空");
+        }
+        // 业务逻辑...
+    }
+}
+```
+
+## 抛出请求参数异常
+
+```java
+import com.iflytek.avatar.boot.exception.BadRequestException;
+
+@Service
+public class OrderService {
+
+    public void createOrder(OrderRequest request) {
+        if (request.getAmount() <= 0) {
+            throw new BadRequestException("订单金额必须大于0");
+        }
+    }
+}
+```
+
+## 参数校验异常（自动处理）
+
+使用 `@Valid` 或 `@Validated` 注解，校验失败时自动返回 400 响应：
+
+```java
+@RestController
+public class UserController {
+
+    @PostMapping("/user")
+    public Result<Void> createUser(@RequestBody @Valid CreateUserRequest request) {
+        // 校验失败时自动返回 Result{code:400, message:"字段校验信息"}
+    }
+}
+```
+
+```java
+public class CreateUserRequest {
+    @NotBlank(message = "用户名不能为空")
+    private String username;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+}
+```
+
+## 注意事项
+
+- 全局异常处理器可通过 `avatar.web.exception-handler-enabled: false` 关闭
+- 自定义异常处理器继承 `GlobalExceptionHandler` 即可扩展，参见「自定义扩展指南」

package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/346/214/207/346/240/207/347/233/221/346/216/247.md

@@ -0,0 +1,74 @@
+# 指标监控（Micrometer）
+
+## 功能说明
+
+模块集成 Micrometer，通过 `@LogInfo(metrics = true)` 注解自动记录方法级指标，与 Spring Boot Actuator 无缝集成。
+
+## 启用 Actuator 暴露指标
+
+在 `application.yml` 中配置：
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+## 使用 @LogInfo 记录指标
+
+```java
+@Service
+public class OrderService {
+
+    @LogInfo(metrics = true)
+    public OrderInfo createOrder(OrderRequest request) {
+        // 自动记录调用次数和执行时间
+        return orderInfo;
+    }
+}
+```
+
+## 可用指标
+
+| 指标名 | 类型 | 标签 | 说明 |
+|:--|:--|:--|:--|
+| `method.invocation.count` | Counter | `class`, `method`, `status` | 方法调用次数 |
+| `method.execution.time` | Timer | `class`, `method`, `status` | 方法执行时间 |
+
+`status` 标签值：`success` / `failure`
+
+## 查询指标
+
+```bash
+# 查看所有可用指标
+curl http://localhost:8080/actuator/metrics
+
+# 查看方法调用次数
+curl http://localhost:8080/actuator/metrics/method.invocation.count
+
+# 按标签过滤（查看某个方法的成功调用次数）
+curl "http://localhost:8080/actuator/metrics/method.invocation.count?tag=method:createOrder&tag=status:success"
+
+# 查看方法执行时间
+curl http://localhost:8080/actuator/metrics/method.execution.time
+```
+
+## Prometheus 集成
+
+启用 Prometheus 后，指标通过 `/actuator/prometheus` 端点暴露，可直接接入 Grafana 监控面板：
+
+```bash
+curl http://localhost:8080/actuator/prometheus | grep method_
+```
+
+## 注意事项
+
+- 需要引入 `spring-boot-starter-actuator` 才能启用指标功能（模块已自动引入）
+- 指标使用缓存机制，避免重复注册导致的异常
+- 可通过 `avatar.web.metrics.enabled: false` 全局关闭指标功能

package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/346/227/245/345/277/227/344/275/223/347/263/273.md

@@ -0,0 +1,73 @@
+# 结构化日志体系
+
+## 日志格式
+
+### 控制台 / 文件格式
+
+```
+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
+```
+
+格式说明：`时间 [线程名] [traceId] 级别 类名 - 消息`
+
+### JSON 格式（test/prod 环境）
+
+```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 格式日志 |
+
+## 环境分级配置
+
+| 环境 | 控制台输出 | 文件输出 | JSON 输出 |
+|:--|:--|:--|:--|
+| `dev` / `local` | ✅ | ✅ | ❌ |
+| `test` | ✅ | ✅ | ✅ |
+| `prod` | ❌ | ✅ | ✅ |
+
+通过 `spring.profiles.active` 切换环境配置。
+
+## 慢请求日志
+
+请求耗时超过阈值（默认 3000ms）时，自动以 WARN 级别输出并标记 `[SLOW]`：
+
+```
+2026-03-03 17:04:18.456 [http-nio-8080-exec-1] [abc123def456] WARN  c.i.a.b.interceptor.RequestContextInterceptor - [SLOW] Request completed: GET /user/list - 3245ms - status: 200
+```
+
+## 异步日志
+
+日志使用异步 Appender 输出，不阻塞业务线程，对接口性能影响极小。
+
+## 在代码中使用 TraceId
+
+TraceId 已自动注入 MDC，直接使用 SLF4J 即可在日志中看到 traceId：
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@Service
+public class UserService {
+    private static final Logger log = LoggerFactory.getLogger(UserService.class);
+
+    public void doSomething() {
+        log.info("处理用户请求"); // 日志中自动包含当前请求的 traceId
+    }
+}
+```

package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/350/257/267/346/261/202/344/270/212/344/270/213/346/226/207.md

@@ -0,0 +1,77 @@
+# 请求上下文（AvatarContext）
+
+## 功能说明
+
+每个 HTTP 请求进入时，拦截器自动初始化 `AvatarContext` 并绑定到当前线程，请求结束后自动清理，防止内存泄漏。
+
+## 获取请求上下文
+
+```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();     // 请求追踪 ID
+        String clientIp = context.getClientIp();   // 客户端真实 IP
+        long startTime = context.getStartTime();   // 请求开始时间（毫秒）
+
+        return Result.success(userInfo);
+    }
+}
+```
+
+## TraceId 说明
+
+### 自动生成
+请求头中没有 `X-Trace-Id` 时，系统自动生成 UUID 作为 TraceId。
+
+### 客户端传递
+```bash
+curl -H "X-Trace-Id: my-custom-trace-id" http://localhost:8080/api/user/info
+```
+
+### 响应头回传
+系统自动将 TraceId 写入响应头 `X-Trace-Id`，方便客户端追踪链路。
+
+### 日志自动注入
+TraceId 通过 MDC 自动注入日志，无需手动处理：
+```
+2026-03-05 10:30:15.123 [http-nio-8080-exec-1] [abc123def456] INFO  c.i.a.b.controller.UserController - ...
+```
+
+## 客户端 IP 获取
+
+支持多级代理场景，按以下顺序取值：
+1. `X-Forwarded-For`（取第一个非内网 IP）
+2. `X-Real-IP`
+3. `RemoteAddr`
+
+## 异步线程中传递 TraceId
+
+在异步线程中使用 `MDCTaskDecorator` 传递 TraceId：
+
+```java
+@Configuration
+public class AsyncConfig implements AsyncConfigurer {
+
+    @Override
+    public Executor getAsyncExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setTaskDecorator(new MDCTaskDecorator()); // 传递 MDC 上下文
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+## 注意事项
+
+- `ContextManager.get()` 在拦截器作用范围外（如定时任务）返回空上下文，注意判空
+- 拦截器默认拦截 `/**`，排除 `/error`、`/actuator/**`、`/swagger-ui/**`
+- 可通过配置调整拦截路径，参见「配置参考」

package/templates/.claude/skills/avatar-boot-starter-web/references//345/277/253/351/200/237/346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -0,0 +1,52 @@
+# 快速接入指南
+
+## 1. 添加 Maven 依赖
+
+在你的服务 `pom.xml` 中添加：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-web</artifactId>
+</dependency>
+```
+
+> 版本由 `avatar-boot-dependency` BOM 统一管理，无需指定版本号。
+
+## 2. 无需额外配置
+
+所有功能默认启用，引入依赖后即可使用：
+
+- ✅ 全局异常处理自动生效
+- ✅ 请求上下文（TraceId、客户端 IP）自动注入
+- ✅ 结构化日志自动配置
+- ✅ 指标监控自动注册（需有 Actuator）
+
+## 3. 验证接入是否成功
+
+启动应用后，发起任意 HTTP 请求，检查响应头中是否包含 `X-Trace-Id`：
+
+```bash
+curl -v http://localhost:8080/your-api
+# 响应头应包含：X-Trace-Id: xxxxxxxxxxxxxxxx
+```
+
+检查日志输出格式是否包含 traceId 字段：
+
+```
+2026-03-05 10:30:15.123 [http-nio-8080-exec-1] [abc123def456] INFO  c.i.a.b.controller.YourController - ...
+```
+
+## 4. 模块依赖说明
+
+本模块自动引入以下依赖，无需重复声明：
+
+| 依赖 | 用途 |
+|:--|:--|
+| `avatar-boot-core` | 核心功能（AvatarContext、Result 等） |
+| `spring-boot-starter-web` | Spring MVC |
+| `spring-boot-starter-aop` | AOP 支持（@LogInfo 注解） |
+| `spring-boot-starter-actuator` | 监控端点（含 Micrometer） |
+| `spring-boot-starter-validation` | 参数校验 |
+| `logstash-logback-encoder` | JSON 日志格式化 |
+| `hutool-all` | 工具类库 |

package/templates/.claude/skills/avatar-boot-starter-web/references//346/263/250/346/204/217/344/272/213/351/241/271.md

@@ -0,0 +1,68 @@
+# 注意事项
+
+## ThreadLocal 清理
+
+拦截器在请求结束后自动清理 `AvatarContext`，无需手动处理。但在以下场景需注意：
+
+- **定时任务**：不经过拦截器，`ContextManager.get()` 返回空上下文，使用前需判空
+- **消息队列消费**：同上，建议手动初始化上下文或不依赖 `AvatarContext`
+
+## 异步线程 TraceId 传递
+
+默认情况下，异步线程不会继承父线程的 MDC（TraceId）。需要使用 `MDCTaskDecorator`：
+
+```java
+@Configuration
+public class AsyncConfig implements AsyncConfigurer {
+    @Override
+    public Executor getAsyncExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setTaskDecorator(new MDCTaskDecorator());
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+## @LogInfo 同类调用失效
+
+`@LogInfo` 基于 Spring AOP，**同一个类内部方法互相调用时注解不生效**：
+
+```java
+@Service
+public class OrderService {
+
+    public void createOrder() {
+        processOrder(); // ❌ @LogInfo 不生效，因为是内部调用
+    }
+
+    @LogInfo(request = true)
+    public void processOrder() { ... }
+}
+```
+
+解决方案：将被调用方法抽取到另一个 Bean，或通过 `ApplicationContext` 获取代理对象。
+
+## 日志性能
+
+- 使用异步 Appender，不阻塞业务线程
+- `@LogInfo` 的 JSON 序列化自动截断超过 2000 字符的内容
+- 生产环境建议关闭 `request-enabled` 和 `response-enabled`，避免敏感数据写入日志
+
+## CORS 处理
+
+模块不处理跨域问题，建议在 Nginx 或 API 网关层统一配置 CORS，避免在每个服务中重复配置。
+
+## 指标监控依赖
+
+`@LogInfo(metrics = true)` 需要 `spring-boot-starter-actuator` 在 classpath 中。模块已自动引入，但如果手动排除了 actuator 依赖，指标功能将不可用。
+
+## IP 获取准确性
+
+客户端 IP 通过请求头获取，在多级代理场景下取 `X-Forwarded-For` 的第一个非内网 IP。如果代理未正确转发请求头，IP 可能不准确，需在代理层配置 `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for`。
+
+## 版本兼容性
+
+- 本模块仅支持 Spring Boot 3.x，不兼容 Spring Boot 2.x
+- 使用 `jakarta.*` 命名空间，不支持 `javax.*`
+- 需要 Java 21+

package/templates/.claude/skills/avatar-boot-starter-web/references//350/207/252/345/256/232/344/271/211/346/211/251/345/261/225/346/214/207/345/215/227.md

@@ -0,0 +1,107 @@
+# 自定义扩展指南
+
+## 自定义异常处理器
+
+继承 `GlobalExceptionHandler`，添加新的异常类型处理：
+
+```java
+import com.iflytek.avatar.boot.exception.GlobalExceptionHandler;
+import com.iflytek.avatar.boot.entity.response.Result;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@RestControllerAdvice
+public class CustomExceptionHandler extends GlobalExceptionHandler {
+
+    // 处理自定义业务异常
+    @ExceptionHandler(CustomException.class)
+    public Result<Void> handleCustomException(CustomException e) {
+        log.warn("自定义异常: {}", e.getMessage());
+        return Result.error(e.getCode(), e.getMessage());
+    }
+
+    // 处理第三方 SDK 异常
+    @ExceptionHandler(ThirdPartyException.class)
+    public Result<Void> handleThirdPartyException(ThirdPartyException e) {
+        log.error("第三方服务异常", e);
+        return Result.error(500, "第三方服务暂时不可用，请稍后重试");
+    }
+}
+```
+
+> 注意：继承后父类的所有异常处理仍然生效，子类只需添加新的处理方法。
+
+## 自定义拦截器
+
+实现 `HandlerInterceptor` 并注册：
+
+```java
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+public class AuthInterceptor implements HandlerInterceptor {
+
+    @Override
+    public boolean preHandle(HttpServletRequest request,
+                             HttpServletResponse response,
+                             Object handler) throws Exception {
+        String token = request.getHeader("Authorization");
+        if (token == null || !isValid(token)) {
+            response.setStatus(401);
+            return false;
+        }
+        return true;
+    }
+
+    private boolean isValid(String token) {
+        // 鉴权逻辑...
+        return true;
+    }
+}
+```
+
+```java
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class WebMvcConfig implements WebMvcConfigurer {
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        registry.addInterceptor(new AuthInterceptor())
+                .addPathPatterns("/api/**")
+                .excludePathPatterns("/api/public/**");
+    }
+}
+```
+
+## 自定义响应格式
+
+如需修改 `Result` 的字段结构，可在项目中定义自己的响应类，并在自定义异常处理器中使用：
+
+```java
+// 自定义响应结构
+@Data
+@AllArgsConstructor
+public class ApiResponse<T> {
+    private int status;
+    private String msg;
+    private T result;
+    private long timestamp = System.currentTimeMillis();
+
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(200, "ok", data, System.currentTimeMillis());
+    }
+}
+```
+
+> 建议：优先使用框架提供的 `Result<T>`，保持团队内响应格式统一。
+
+## 注意事项
+
+- 自定义拦截器与框架内置拦截器**并行生效**，注意执行顺序
+- 使用 `jakarta.*` 命名空间，不要使用 `javax.*`
+- 自定义异常处理器的 `@RestControllerAdvice` 优先级高于父类，同类型异常以子类为准