## 1. 使用的框架与工具 - **门面**:SLF4J(`org.slf4j.Logger`,通过 `LoggerFactory.getLogger(...)` 获取实例)。 - **实现**:Logback(Spring Boot 默认),由 `ai-server/src/main/resources/logback-spring.xml` 配置。 - **集成方式**:Spring Boot 自动装配。`logback-spring.xml` 仅 include Spring Boot 自带的 `defaults.xml` 和 `console-appender.xml`,未自定义 appender / layout / file sink。 ## 2. 关键文件 - `ai-server/src/main/resources/logback-spring.xml`:唯一的 logback 配置,定义 root level = `debug`,输出到 `CONSOLE`。 - `ai-server/src/main/java/com/zsjz/ai/App.java`:应用入口,使用 `log.info(...)` 打印启动与工作空间检查日志。 - `ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java`、`LoginRequestFilter.java`、`LoginResponseFilter.java`、`GatewayRegistry.java`、`AdminAuthWebFilter.java`:网关侧全部使用 SLF4J 日志。 仓库中不存在其他 `logback*.xml` 或 `logging.properties` 类配置文件;唯一匹配 `logback-spring.xml|logback.xml` 的文件是 `docs/design/stability-usability-report.md`(文档引用)。 ## 3. 架构与约定 ### 3.1 Logger 实例化模式 所有 Java 类统一采用 SLF4J 静态字段模式: ```java private static final Logger log = LoggerFactory.getLogger(ClassName.class); ``` 在 ai-server 模块中观察到约 913 处 `log.debug/info/warn/error` 调用,覆盖 228 个源文件;在 ai-gateway 模块中有约 28 处调用,集中在路由、认证、注册等核心路径。 ### 3.2 日志级别策略 - **全局根级别**:``(`logback-spring.xml`),即 debug 及以上全部输出到控制台。 - **业务代码实际使用**:主要使用 `info` 和 `error`;`warn` 用于非致命异常场景(如网关白名单拒绝、上游不可用、登录响应过大跳过解析等);极少使用 `debug`。 - 未发现按包名或模块设置不同级别的规则——全仓统一 debug 输出。 ### 3.3 结构化字段与消息格式 - 不使用任何 JSON 结构化日志框架(无 Jackson、GELF、Logstash Encoder 等)。所有日志为纯文本,参数通过 SLF4J 占位符 `{}` 拼接。 - 业务日志普遍使用中文前缀标记模块边界,例如: - `【数据治理】开始执行数据治理任务, caseId={}, userId={}` - `[阶段一] 清理/去重任务执行失败或超时` - 网关侧错误日志以 `requestId` 作为上下文标识:`"[{}] gateway internal error", requestId, error`。 ### 3.4 输出目标(Sink) - 仅输出到 **控制台**(`CONSOLE` appender,来自 Spring Boot 内置 `console-appender.xml`)。 - 没有文件 appender、rolling file、异步 appender、外部日志收集器(如 Filebeat、Fluentd、ELK)集成。 - 因此生产部署需依赖容器 stdout/stderr 或进程管理器进行日志采集。 ### 3.5 前端日志 - 前端(`ai-electron/frontend`)未发现统一的 logger 封装;API 层通过 axios 拦截器等处理请求/响应,但没有集中化的前端日志子系统。 ## 4. 约定与约束 - **约定(观察到的行为)**: - 所有 Java 类通过 `LoggerFactory.getLogger(ClassName.class)` 获取 SLF4J logger,并以私有静态字段持有。 - 业务日志消息使用中文描述并带 `caseId`、`userId`、`requestId` 等业务键。 - 异常一律以 `log.error("...", e)` 形式记录堆栈。 - **约束(被实现强制的规则)**: - 根日志级别固定为 `debug`(由 `logback-spring.xml` 声明)。 - 日志输出目标仅为控制台(``)。 - 仓库内不存在其他 logback 配置文件,任何新增 sink 或格式化规则必须修改该文件。 - 未引入任何第三方日志编码/收集依赖(pom.xml 中无相关 artifact),因此不能假定存在 JSON 输出或远端投递能力。