日志系统（Logback + AOP 操作日志）

---
kind: logging_system
name: 日志系统（Logback + AOP 操作日志）
slug: logging_system
category: logging_system
scope:
    - '**'
---

## 1. 使用的框架与工具
- 日志框架：Logback（通过 `logback-spring.xml` 配置），配合 Lombok 的 `@Slf4j` 注解在各模块中统一输出。
- 链路追踪增强：部分服务（如 factorydata、production）在 INFO 异步 Appender 中使用了 `com.yomahub.tlog.core.enhance.logback.async.AspectLogbackAsyncAppender`，用于增强异步日志的上下文传递。
- 业务操作日志：基于 Spring AOP + 自定义注解 `@LogExecution` 实现方法级执行日志记录，并通过 `SysLog` 实体持久化到数据库。

## 2. 核心文件与位置
- 各微服务模块的 Logback 配置文件：
  - `chr/src/main/resources/logback-spring.xml`
  - `factorydata/src/main/resources/logback-spring.xml`
  - `production/src/main/resources/logback-spring.xml`
- AOP 操作日志切面与持久化：
  - `biz/src/main/java/com/lvcc/biz/aspect/LogAspect.java`（AOP 切面）
  - `biz/src/main/java/com/lvcc/biz/entity/system/SysLog.java`（操作日志实体）
  - `biz/src/main/java/com/lvcc/biz/service/system/LogService.java` 及其实现类
  - `biz/src/main/java/com/lvcc/biz/dao/system/LogMapper.java`（MyBatis-Plus Mapper）
- 根目录日志输出目录：`log/`（包含 error、info、heart 等子目录，按日期滚动生成日志文件）

## 3. 架构与约定
- **日志输出结构**：每个服务的 `logback-spring.xml` 均定义以下 Appender：
  - `console`：控制台彩色输出（开发调试用）
  - `file_info`：INFO 级别文件输出，按天+大小滚动，保留 15 天，单文件最大 100MB
  - `ASYNC_INFO_LOG`：异步 INFO 日志 Appender（部分服务使用 TLog 增强版）
  - `file_error`：ERROR 级别独立文件输出
  - `http_trace`：HTTP 跟踪日志（独立 logger 名称 `httptraceLog`）
- **日志格式**：统一使用 `%d{yyyy-MM-dd HH:mm:ss.SSS} %contextName [%thread] %-5level %logger{36} - %msg%n` 模式，包含时间、上下文名、线程、级别、类名和消息。
- **根日志级别**：root 默认 level 为 `debug`（控制台）和 `info`（文件输出）。
- **上下文命名**：所有服务统一设置 `<contextName>febs</contextName>`，便于多服务日志聚合时区分来源。
- **AOP 操作日志**：
  - 通过 `@LogExecution` 注解标记需要记录执行日志的方法
  - `LogAspect` 切面拦截注解方法，记录方法名、参数、操作人、IP、耗时等信息
  - 支持 TRACE/DEBUG/INFO/WARN/ERROR 五种级别，由注解属性控制
  - 同时通过 `@Log` 注解（未在当前代码中展示但被引用）记录用户操作日志到 `SysLog` 表
- **日志分层存储**：
  - `log/info/`：常规业务日志
  - `log/error/`：错误日志
  - `log/heart/`：心跳日志（已注释，当前未启用）
  - `log/httptrace/`：HTTP 请求跟踪日志

## 4. 约定与约束
- **日志框架统一**：所有服务必须使用 Logback 作为日志实现，禁止直接使用 `System.out.println` 或第三方日志框架。
- **注解式日志**：业务方法日志记录必须通过 `@LogExecution` 注解声明，禁止在业务代码中直接调用 `log.info()` 等方式记录结构化操作日志。
- **异步输出**：INFO 级别日志必须通过异步 Appender 输出，避免阻塞主业务流程。
- **日志轮转策略**：所有文件 Appender 必须使用 `SizeAndTimeBasedRollingPolicy`，按天和大小双维度轮转，保留天数不超过 15 天。
- **敏感信息脱敏**：日志中不得直接输出密码、Token 等敏感信息，需通过工具类进行脱敏处理。
- **链路追踪**：推荐使用 TLog 提供的异步 Appender 以支持跨线程链路追踪。
- **异常日志**：全局异常处理器（`GlobalExceptionHandler`）会将异常信息统一记录到 `SysLog` 表，确保错误可追溯。

## 5. 日志级别策略
- **DEBUG**：仅控制台输出，生产环境不输出到文件
- **INFO**：异步文件输出，记录业务关键流程
- **WARN**：与 INFO 同路径输出，记录警告信息
- **ERROR**：独立文件输出，便于快速定位错误
- **TRACE**：仅在开发环境开启，记录详细执行轨迹

该日志系统通过标准化的 Logback 配置、AOP 切面和统一的实体模型，实现了微服务架构下的集中化、结构化、可追溯的日志管理。