# xxdun-logging-starter **Repository Path**: pjlwlcxy/xxdun-logging-starter ## Basic Information - **Project Name**: xxdun-logging-starter - **Description**: `xxdun-logging-starter` 是一个企业级通用日志组件，专门为解决多团队协作开发中的日志告警不清晰问题而设计。通过标准化的日志格式和智能的注解继承机制，实现了业务模块、负责人、供应商等关键信息的自动关联，让日志告警能够第一时间定位到具体负责人。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-11 - **Last Updated**: 2025-11-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # xxdun-logging-starter ## 📋 项目概述 `xxdun-logging-starter` 是一个企业级通用日志组件，专门为解决多团队协作开发中的日志告警不清晰问题而设计。通过标准化的日志格式和智能的注解继承机制，实现了业务模块、负责人、供应商等关键信息的自动关联，让日志告警能够第一时间定位到具体负责人。 ## 🎯 核心价值 ### 解决的核心问题 - **告警归属不明确**：传统日志无法直观看出告警属于哪个业务模块 - **负责人定位困难**：出现问题时无法快速找到对应负责人 - **多供应商环境混乱**：多团队协作时日志信息混杂，难以区分 - **调用链路不清晰**：复杂的业务调用链路难以追踪 ### 核心优势 - **业务模块化**：通过注解自动关联业务模块信息 - **负责人追踪**：每个日志都包含明确的负责人信息 - **智能继承**：支持调用链路中的注解信息继承 - **多环境适配**：支持开发、测试、生产环境的差异化配置 - **开箱即用**：Spring Boot Starter设计，零配置集成 ## 🏗️ 架构设计 ### 核心设计理念 #### 1. 分层注解体系 - **@ModuleInfo**（类级别）：定义大业务模块信息 - **@MethodTrace**（方法级别）：定义方法级别的业务信息 - **注解继承机制**：支持调用链路中的注解信息智能继承 #### 2. 智能调用链路追踪 - 自动分析调用堆栈，跳过框架类 - 支持注解信息的层层递进查找 - 优先使用当前方法注解，缺失时向上查找调用链路 #### 3. MDC上下文管理 - 统一的MDC上下文设置和清理 - 支持跟踪ID、业务模块、重要性等多维度信息 - 线程安全的上下文管理 ### 技术架构 ``` xxdun-logging-starter ├── annotation/ # 注解定义 │ ├── ModuleInfo # 业务模块注解 │ ├── MethodTrace # 方法追踪注解 │ ├── BusinessImportance # 业务重要性枚举 │ └── LogLevel # 日志级别枚举 ├── aspect/ # AOP切面 │ ├── LoggingAspect # Controller层切面 │ └── ServiceLoggingAspect # Service层切面 ├── config/ # 配置类 │ ├── LoggingAutoConfiguration # 自动配置 │ ├── LoggingProperties # 配置属性 │ └── LogPatternConfig # 日志格式配置 └── util/ # 工具类 ├── LogHelper # 增强日志工具 └── MDCContextUtil # MDC上下文工具 ``` ## 🚀 快速开始 ### 1. 添加依赖 ```xml com.xxdun xxdun-logging-starter 1.0.0 ``` ### 2. 基础配置 在 `application.yml` 中配置： ```yaml xxdun: logging: starter: enabled: true format: type: standard include-trace-id: true include-module-info: true aspect: controller-enabled: true service-enabled: true log-params: true ``` ### 3. 使用示例 #### Controller层使用 ```java @RestController @ModuleInfo( moduleName = "用户管理模块", supplierName = "基础平台团队", owner = "张三", businessDomain = "用户中心" ) public class UserController { @GetMapping("/users/{id}") @MethodTrace( methodName = "查询用户信息", importance = BusinessImportance.HIGH ) public User getUser(@PathVariable Long id) { return userService.getUserById(id); } } ``` #### Service层使用 ```java @Service public class UserService { @MethodTrace( methodName = "根据ID查询用户", supplierName = "用户服务团队", owner = "李四" ) public User getUserById(Long id) { // 业务逻辑 LogHelper.info("查询用户ID: {}", id); return userRepository.findById(id); } } ``` #### 直接使用LogHelper ```java // 自动从调用链路获取注解信息 LogHelper.info("用户登录成功，用户名: {}", username); // 手动指定供应商和负责人 LogHelper.error("用户登录失败", "认证服务团队", "王五", exception); ``` ## 📊 日志输出效果 ### 标准格式输出 ``` 2024-01-15 10:30:25.123 [http-nio-8080-exec-1] INFO [TRACE_ID:abc123def456] [MODULE:USER_MGMT:用户管理模块] [SUPPLIER:BASE_TEAM:基础平台团队] [SUB_MODULE:] [METHOD:QUERY_USER:查询用户信息] [IMPORTANCE:HIGH] [DOMAIN:用户中心] [PRIORITY:5] [LAYER:CONTROLLER] - [用户管理模块] [查询用户信息] [基础平台团队] [张三] 查询用户ID: 123 ``` ### 简化格式（开发环境） ``` 10:30:25.123 [http-nio-8080-exec-1] INFO [USER_MGMT::QUERY_USER] [HIGH] - [用户管理模块] [查询用户信息] [基础平台团队] [张三] 查询用户ID: 123 ``` ## ⚙️ 详细配置 ### 完整配置示例 ```yaml xxdun: logging: starter: enabled: true # 日志格式配置 format: type: standard # standard, simple, json, http, error include-trace-id: true include-module-info: true include-sub-module-info: true include-importance: true include-http-info: true # AOP切面配置 aspect: controller-enabled: true service-enabled: true log-params: true log-result: false log-execution-time: true validate-annotation-association: true execution-time-threshold: 5000 # 业务模块配置 module: default-supplier-code: "DEFAULT" default-supplier-name: "默认供应商" default-business-domain: "通用业务" default-priority: 5 default-importance: "NORMAL" ``` ### 环境差异化配置 #### 开发环境 ```yaml xxdun: logging: format: type: simple aspect: log-params: true # 开发环境记录参数 log-result: true # 开发环境记录返回值 ``` #### 生产环境 ```yaml xxdun: logging: format: type: json # 生产环境使用JSON格式 aspect: log-params: false # 生产环境不记录敏感参数 log-result: false # 生产环境不记录返回值 execution-time-threshold: 3000 # 生产环境阈值更严格 ``` ## 🔧 高级特性 ### 1. 注解继承机制 组件支持智能的注解继承： - Service层方法可以继承Controller层的@ModuleInfo注解 - 支持调用链路中注解信息的层层递进查找 - 优先使用当前方法注解，缺失时向上查找 ### 2. 业务重要性分级 ```java public enum BusinessImportance { CRITICAL, // 关键业务 HIGH, // 重要业务 NORMAL, // 一般业务 LOW // 次要业务 } ``` ### 3. 执行时间监控 自动记录方法执行时间，超过阈值时记录警告日志： ``` 2024-01-15 10:30:25.123 [http-nio-8080-exec-1] WARN - [订单管理模块] [创建订单] [订单团队] [赵六] 方法执行超时 | 耗时: 5200ms ``` ### 4. HTTP请求信息集成 自动捕获并记录HTTP请求信息： - 请求URI和Method - 客户端IP地址 - User-Agent信息 ## 🎨 注解详解 ### @ModuleInfo - 业务模块注解 | 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | moduleName | String | 是 | 业务模块名称 | | supplierName | String | 是 | 供应商/团队名称 | | owner | String | 是 | 模块负责人 | | contact | String | 否 | 联系方式 | | description | String | 否 | 模块描述 | | businessDomain | String | 否 | 业务领域 | | priority | int | 否 | 优先级(1-10) | ### @MethodTrace - 方法追踪注解 | 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | methodName | String | 是 | 方法名称 | | description | String | 否 | 方法描述 | | supplierName | String | 否 | 供应商名称 | | owner | String | 否 | 负责人 | | level | LogLevel | 否 | 日志级别 | | logParams | boolean | 否 | 是否记录参数 | | logResult | boolean | 否 | 是否记录返回值 | | logExecutionTime | boolean | 否 | 是否记录执行时间 | | importance | BusinessImportance | 否 | 业务重要性 | ## 🔍 故障排查 ### 常见问题 1. **注解不生效** - 检查是否添加了`@EnableAspectJAutoProxy` - 确认配置文件中`enabled: true` 2. **调用链路信息缺失** - 检查方法是否被AOP代理 - 确认调用链路中存在业务方法 3. **性能问题** - 生产环境关闭参数记录`log-params: false` - 调整执行时间阈值 ### 调试模式 开启调试日志查看注解继承过程： ```yaml logging: level: com.xxdun.logging: DEBUG ``` ## 📈 监控集成 ### 与监控系统对接 组件输出的结构化日志可以直接被监控系统解析： ```json { "timestamp": "2024-01-15T10:30:25.123+08:00", "level": "INFO", "traceId": "abc123def456", "moduleCode": "USER_MGMT", "moduleName": "用户管理模块", "supplierCode": "BASE_TEAM", "supplierName": "基础平台团队", "methodCode": "QUERY_USER", "methodName": "查询用户信息", "importance": "HIGH", "businessDomain": "用户中心", "priority": 5, "layer": "CONTROLLER", "message": "查询用户ID: 123" } ``` ### 告警规则配置 基于业务重要性配置差异化告警： - **CRITICAL**: 立即通知，电话告警 - **HIGH**: 企业微信/钉钉通知 - **NORMAL**: 邮件通知 - **LOW**: 记录日志，不主动通知 ## 🤝 贡献指南 ### 开发环境搭建 1. 克隆项目 ```bash git clone https://github.com/xxdun/xxdun-logging-starter.git ``` 2. 导入IDE 3. 运行测试验证 ### 代码规范 - 遵循阿里巴巴Java开发规范 - 使用Checkstyle进行代码检查 - 提交前运行所有测试 ### 提交规范 - feat: 新功能 - fix: 修复bug - docs: 文档更新 - style: 代码格式调整 - refactor: 代码重构 ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 ## 👥 团队信息 - **项目负责人**: 智学蔚来架构团队 - **技术支持**: http://www.zxwlit.cn - **文档维护**: 技术文档团队 **xxdun-logging-starter** - 让每一次告警都能第一时间找到负责人！