Camunda Commons Logging 源码实战用 BaseLogger 打造格式统一的 BPMN/DMN 日志体系【免费下载链接】camunda-bpm-platformCamunda 7 CE is End of Life (EoL). Please check out Camunda 8 instead (https://github.com/camunda/camunda) or read about Camunda 7 Enterprise End of Life (https://camunda.com/blog/2025/02/camunda-7-enterprise-end-of-life-extension/) – Camunda 7 CE was a flexible framework for workflow and decision automation using BPMN and DMN.项目地址: https://gitcode.com/GitHub_Trending/ca/camunda-bpm-platformCamunda Commons Logging 是 Camunda BPM 平台中用于统一日志与异常消息格式的轻量基础库它为每个逻辑组件logical component提供了一致、可检索、带错误码的日志消息模板。本文将以该模块的 README 为主线结合仓库内 BaseLogger 源码与真实模块如 Engine、Spin的落地用法讲解如何定义自定义 Logger、消息编码规范、级别语义以及底层实现原理读完即可在自己的应用或插件中复刻这套日志规范。一、模块定位为什么要有一层Logger 基类Camunda BPM 平台包含流程引擎Engine、DMN 决策引擎、Spin 数据格式处理、Connect 连接器等众多子系统日志若各写各的排查问题时很难快速定位哪个项目、哪个组件、哪条消息。camunda-commons-logging提供的就是一个最小化基类用于编写产生一致的日志与异常消息的 Logger。它的核心理念是每个逻辑组件定义自己的 Logger 类类中每个方法对应一条日志消息从而保证日志可读、可检索、带唯一消息编码。模块依赖关系见 pom.xml核心仅依赖org.slf4j:slf4j-api测试期使用logback-classic、JUnit、AssertJ 与 Mockito。二、消息模板规范PROJ-20023是怎么来的Camunda 的一条日志消息形如PROJ-20023 The attribute with the name invalidId was not found in the element with id elementId returning an empty string.其模板形式为[PROJECT_CODE]-[COMPONENT_ID][MESSAGE_CODE] [MESSAGE]各部分含义README 原文约定commons/logging/README.mdPROJECT_CODE标识项目名的短标识例如SPINSpin 模块即使用该前缀见 SpinLogger.javaEngine 模块使用ENGINE见 ProcessEngineLogger.java。COMPONENT_ID项目内某个组件的唯一两位数字标识。例如 Engine 中00为引擎本体、01为 BPMN 解析器、02为 BPMN 行为、03为持久化ProcessEngineLogger.java。MESSAGE_CODE该日志消息的唯一三位数字标识。MESSAGE有意义的日志消息适当时用单引号包裹关键信息例如Attribute with name abc not found。拼接规则在源码中得到印证formatMessageTemplate直接按projectCode - componentId id messageTemplate组装BaseLogger.java。三、快速上手为业务模块定义一个 Logger3.1 定义 Logger 类按 README 示例为应用中的逻辑组件定义一个 Logger继承BaseLogger通过静态工厂创建实例public class UserRepositoryLogger extends BaseLogger { public static UserRepositoryLogger LOG createLogger( UserRepositoryLogger.class, MYAPP, com.myapp.user, 01 ); public void userCreated(String userId) { logDebug(001, Created user with id {}, userId); } }createLogger(ClassT, String projectCode, String name, String componentId)的四个参数分别为Logger 类型、项目代码、底层 slf4j Logger 名称通常取包名便于日志框架按命名空间过滤、组件两位数字标识。3.2 在业务类中使用public class UserRepository { private final static UserRepositoryLogger LOG UserRepositoryLogger.LOG; public void createUser(UserEntity user) { // save user... // log message LOG.userCreated(user.getId()); } }3.3 输出结果上述代码会输出如下格式的消息com.myapp.user - MYAPP-01001 Created user with id 992112其中com.myapp.user是 slf4j Logger 名称对应createLogger传入的nameMYAPP-01001即PROJECT_CODE(3)COMPONENT_ID(01)MESSAGE_CODE(001)拼接而成随后是占位符替换后的消息内容。3.4 参数占位与惰性求值日志方法采用 slf4j 的{}占位符风格且每个级别方法都先通过isXxxEnabled()做级别开关预检再执行格式化未开启的级别不会产生字符串拼接开销BaseLogger.java例如protected void logDebug(String id, String messageTemplate, Object... parameters) { if(delegateLogger.isDebugEnabled()) { String msg formatMessageTemplate(id, messageTemplate); delegateLogger.debug(msg, parameters); } }四、日志级别语义与默认值README 给出了四种级别的语义约定与示例commons/logging/README.mdLevelDescriptionERRORSignals an error which is severe but may allow the application to continue.Example:SPIN-10033 Unable to change attribute with name id to value #-testWARNSignals a warning which can interfere with the correct execution of the application.Example:SPIN-20023 The attribute with the name invalidId was not found in the element with id elementId returning an empty string.INFOInforms about the progress of the application.Example:SPIN-30001 File with name existingData.xml successful read and parsedDEBUGInformation to help debugging an application.Example:SPIN-41233 Found 12 child elements of element with id testElement补充源码层面的两点细节级别枚举实际包含 5 个值ERROR、WARN、INFO、DEBUG、TRACELevel.javaREADME 表格之外的TRACE同样受支持。解析失败回退默认值Level.parse(value, defaultLevel)会先trim().toUpperCase()后匹配null 或非法值如FATAL回退到默认级别log(String level, String id, ...)变体的默认级别是DEBUG而log(String level, Level defaultLevel, ...)允许调用方指定回退级别Level.java、BaseLogger.java。测试 BaseLoggerTest.java 验证了log(FATAL, ...)回退到logDebug、log(FATAL, Level.WARN, ...)回退到logWarn的行为。五、异常消息格式化exceptionMessage除了日志输出BaseLogger 还提供exceptionMessage(String id, String messageTemplate, Object... parameters)用于生成与日志同模板的异常消息先拼接projectCode-componentIdid前缀再通过 slf4j 的MessageFormatter.arrayFormat替换占位符无参数时直接返回模板BaseLogger.java。对应测试覆盖了单参数、多参数与无参数三种情况BaseLoggerTest.java例如String formattedMessage logger.exceptionMessage(ID, Some message {}, someParameter); // 期望输出: TEST-0101 Some message someParameter这样抛出的异常与日志共享同一套消息编码日志系统、异常堆栈与监控告警中的消息前缀完全一致便于关联定位。六、MDC 支持MdcAccess为了在日志中注入请求/事务上下文例如流程实例 ID、租户 ID模块提供了对 SLF4J MDC 的轻量门面 MdcAccess.java直接转发put、get、remove三个静态方法到org.slf4j.MDCMdcAccess.put(processInstanceId, 12345); String value MdcAccess.get(processInstanceId); MdcAccess.remove(processInstanceId);其行为与约束在 MdcAccessTest.java 中验证put(null, ...)与get(null)会抛出IllegalArgumentExceptionput(key, null)则允许等价于清除该键。七、真实项目落地Engine 与 Spin 的 Logger 分层该库并非玩具代码Camunda 平台各模块均以它为底座。以 Engine 为例ProcessEngineLogger.java 定义了PROJECT_CODE ENGINE并为解析器、行为、持久化等子组件分配了递增的COMPONENT_ID00、01、02、03……每个子组件一个 Logger 类、一套独立的三位消息码区间。Spin 模块则采用抽象父 Logger 子模块 Logger的分层模式SpinLogger.java 持有PROJECT_CODE SPIN并创建核心 Loggerorg.camunda.spin组件01JSON 数据格式与 XML DOM 数据格式分别注册在org.camunda.spin.json、org.camunda.spin.xml命名空间下见 JacksonJsonLogger.java 与 DomXmlLogger.java从而在 slf4j 层面可按包名精确开关某个子模块的日志级别。这种项目代码 组件标识 消息码的编码约定让SPIN-20023、ENGINE-01001这类日志天然具备可检索性按前缀即可 grep 出某个组件全部消息按三位码即可查到某条具体消息的定义。八、接入与集成要点依赖模块坐标org.camunda.commons:camunda-commons-logging仅需 slf4j-api 即可编译运行时由应用自行提供 slf4j 绑定如 logback-classic测试中即采用 logback-classicpom.xml。Logger 命名createLogger的name参数建议使用组件包名与 Maven 模块、日志框架配置文件中的logger name对齐便于统一运维。编码规划两位组件 ID 三位消息码建议为每个逻辑组件规划独立的编码区间避免跨组件消息码冲突。EoL 提醒按 pom.xml 中模块描述7.24.0 为社区版在 Maven Central 的最后发布版本该库后续不再发布新版本如需长期维护可考虑企业版支持。总结Camunda Commons Logging 以不到 300 行的BaseLogger基类配合Level枚举与MdcAccess门面为整个平台提供了统一的日志/异常消息规范[PROJECT_CODE]-[COMPONENT_ID][MESSAGE_CODE] [MESSAGE]。自定义 Logger 时只需继承基类、用createLogger注册项目代码与组件标识再为每条消息定义专属方法即可。借助 Engine、Spin 等模块的真实分层实践你可以直接把这套规范移植到自己的插件或应用中让日志从随心所欲升级为可检索、可归类、可关联异常的工程化资产。【免费下载链接】camunda-bpm-platformCamunda 7 CE is End of Life (EoL). Please check out Camunda 8 instead (https://github.com/camunda/camunda) or read about Camunda 7 Enterprise End of Life (https://camunda.com/blog/2025/02/camunda-7-enterprise-end-of-life-extension/) – Camunda 7 CE was a flexible framework for workflow and decision automation using BPMN and DMN.项目地址: https://gitcode.com/GitHub_Trending/ca/camunda-bpm-platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考