后端【免费下载链接】COLA COLA: Clean Object-oriented Layered Architecture项目地址https://gitcode.com/gh_mirrors/col/COLA点击查看免费下载本文围绕 COLA 开源仓库中的 CatchAndLogcatch-log-starter组件展开讲解如何通过「注解 AOP Spring Boot 自动装配」为 Service 层方法提供统一的请求日志、响应日志与异常处理能力。读完本文你将掌握该组件的底层原理切点定义、环绕通知、异常分类与响应适配、三步接入方法加注解、开 DEBUG、看日志以及如何借助仓库内置的 Starter 组件 Archetype 一键生成自己的 Spring Boot Starter。组件定位面向 Service 层的「日志 异常」一体化 Starter组件原文档开门见山地给出了它的定位通过注解 AOP提供 service 级别的 logging 和 exception 处理。也就是说它解决的是应用中最常见也最容易被忽视的两类横切问题每个 Service 方法都要打印入参/出参/耗时日志以及异常抛到上层前需要一个统一的处理出口记录日志、转成约定的错误响应返回给调用方。这两件事如果散落在每个方法里手写代码会极其冗长且难以维护而用注解 AOP 收敛到切面里业务代码可以保持干净。在 COLA 仓库中该组件对应两个形态实际可用的组件cola-component-catchlog-starter坐标com.alibaba.cola:cola-component-catchlog-starterArchetype 模板本文关联文档正是位于 cola-starter-component-archetype 模板中的 README模板内嵌了一套最小可运行的 starter 示例代码CatchAndLog 注解、CatchLogAspect 切面、CatchLogAutoConfiguration 自动配置、spring.factories 等用于指导开发者照着实现自己的 Starter 组件。一、原理注解 AOP 切面 Spring Boot 自动装配整个组件的原理可以从三个层面拆解1. 一个注解标记目标类CatchAndLog.java 是一个运行时注解可同时标注在类和方法上Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface CatchAndLog { }标注在类上时表示该类下所有匹配的 public 方法都会被拦截这也是文档中在GrouponServiceImpl类级别使用的原因标注在方法上则可做到更细粒度的控制。2. 一个切面做环绕拦截CatchLogAspect.java 定义了切点与环绕通知Pointcut(within(CatchAndLog) execution(public * *(..))) public void pointcut() { } Around(value pointcut()) public Object around(ProceedingJoinPoint joinPoint) { long startTime System.currentTimeMillis(); logRequest(joinPoint); Object response null; try { response joinPoint.proceed(); } catch (Throwable e) { response handleException(joinPoint, e); } finally { logResponse(startTime, response); } return response; }切点表达式within(CatchAndLog) execution(public * *(..))的含义是凡是标注了CatchAndLog的类型within内部的 public 方法都会被拦截。环绕逻辑是标准的 AOP 套路先记录请求方法签名 入参通过 fastjson 序列化执行目标方法proceed()若抛出异常交给handleException统一转换为返回值详见下文「异常处理」无论成功失败在finally中记录响应与耗时。Archetype 模板中的 CatchLogAspect.java 与仓库正式组件的实现思路完全一致模板版本为了演示对异常处理保留了//Dummy implementation占位正式组件则补充了完整的异常分级与响应转换逻辑。3. 自动配置机制自动注入切面 Bean依赖 Spring Boot 的 autoConfig 机制组件无需任何手动配置即可生效。核心在 CatchLogAutoConfiguration.javaConfiguration EnableAspectJAutoProxy public class CatchLogAutoConfiguration { Bean ConditionalOnMissingBean(CatchLogAspect.class) public CatchLogAspect catchLogAspect() { return new CatchLogAspect(); } }关键点有两个EnableAspectJAutoProxy开启 AspectJ 自动代理是切面生效的前提ConditionalOnMissingBean(CatchLogAspect.class)允许使用者自定义自己的CatchLogAspectBean 来覆盖默认切面实现按需定制。自动配置类的注册入口在 Archetype 模板的 spring.factories 中org.springframework.boot.autoconfigure.EnableAutoConfiguration ${package}.CatchLogAutoConfiguration即通过 Spring Boot 的spring.factories机制将自动配置类登记到EnableAutoConfiguration列表中应用启动时由 Spring Boot 自动加载${package}是 Archetype 生成时被替换的占位符。二、快速接入一行依赖即可生效因为采用 autoConfig 机制使用者只需添加依赖连EnableXXX开关注解都不需要dependency groupIdcom.alibaba.lst.tech.shared/groupId artifactIdcatch-log-starter/artifactId /dependency说明上面的坐标是组件原文档中记载的阿里内部共享坐标在 COLA 开源仓库中对应的发布坐标是com.alibaba.cola:cola-component-catchlog-starter见 cola-component-catchlog-starter/pom.xml。从 pom.xml 可以看到组件底层依赖的构成理解它有助于预判类路径冲突依赖作用scopespring-boot-autoconfigure提供ConditionalOnMissingBean等自动装配支持providedspring-boot-starter-aop提供 AOP 运行时AspectJ、代理compilecom.alibaba:fastjson入参/出参的 JSON 序列化providedorg.slf4j:slf4j-api日志门面compilecola-component-dto提供Response等返回值类型compilecola-component-exception提供BizException/SysException异常体系compile三、使用步骤三步完成接入步骤 1在 Service 类上添加 CatchAndLog 注解CatchAndLog public class GrouponServiceImpl implements GrouponService { // 类的所有 public 方法自动获得日志 异常处理能力 }步骤 2为组件开启 DEBUG 级日志输出CatchLogAspect 的日志全部打在DEBUG级别详见下文日志行说明因此默认日志配置下是看不到的。在logback-test.xml或项目自己的 logback 配置中加入!--这个是统一异常处理日志记录组件的日志-- logger namecom.alibaba.cola.catchlog levelDEBUG/Archetype 模板自带的 logback-test.xml 就是标准做法root 保持 INFO仅将组件包名模板中为${package}即生成工程自己的包设为 DEBUG。生产环境建议同样只对需要排查的包开 DEBUG避免全量 DEBUG 刷屏。步骤 3通过控制台日志验证 AOP 拦截已生效文档给出了预期的控制台输出DEBUG c.a.l.t.s.catchlog.CatchLogAspect - Start processing: GrouponServiceImpl.queryGrouponItemDetail(..) DEBUG c.a.l.t.s.catchlog.CatchLogAspect - REQUEST : 257 DEBUG c.a.l.t.s.catchlog.CatchLogAspect - RESPONSE : {errCode:UNKNOWN_ERROR...} DEBUG c.a.l.t.s.catchlog.CatchLogAspect - COST : 1329ms各行的业务含义分别是被拦截的方法签名、序列化后的请求入参、序列化后的响应体、方法执行耗时毫秒。只要看到这四类日志就说明 CatchAndLog 已经在做 AOP 拦截。对照当前仓库源码 CatchLogAspect.java实际输出的日志格式与文档示例略有差异新版本统一为大写前缀并改用 SLF4J 占位符START PROCESSING: GrouponServiceImpl.queryGrouponItemDetail(..) REQUEST: {id:257} RESPONSE: {success:false,errCode:UNKNOWN_ERROR,...} COST: 1329ms另外两点值得注意的实现细节入参序列化使用了SerializerFeature.IgnoreErrorGetter遇到 getter 抛异常的字段不会拖垮整个日志序列化、日志记录本身都包裹在 try-catch 中并「吞掉」异常保证日志逻辑永远不影响业务主流程。四、异常处理的统一出口ResponseHandler 机制文档特别强调组件「兼容普通的 HSF service 和 Mtop service」并给出了ResponseHandler的设计示意public class ResponseHandler { public static Object handle(Class returnType, String errCode, String errMsg){ if (isColaResponse(returnType)){ return handleColaResponse(returnType, errCode, errMsg); } if(isMtopResponse(returnType)){ return handleMtopResponse(returnType, errCode, errMsg); } return null; } ... }其核心思想是异常被捕获后要根据方法的返回类型构造一个「携带错误码与错误信息的响应对象」返回给调用方而不是让异常直接冒泡。这样不同的服务协议COLA Response、Mtop Response 等都能获得与自己约定格式一致的错误结果。当前仓库的实现形态开源仓库将这一设计落地为三个协作类ResponseHandlerI.java处理器的统一接口DefaultResponseHandler.java默认实现当前内置了COLA Response 分支——当方法返回类型是Response或其子类returnType Response.class || returnType.getGenericSuperclass() Response.class时通过反射newInstance()构造响应对象填充successfalse、errCode、errMessage后返回文档中的 Mtop 分支为原 README 展示的扩展方向开源默认实现未内置ResponseHandlerFactory.java工厂类优先从 Spring 容器中取自定义的ResponseHandlerIBean取不到才回退到DefaultResponseHandler。也就是说你完全可以像测试用例 CustomResponseHandler.java 那样实现ResponseHandlerI并注册为 Spring Bean即可替换默认的错误响应构造逻辑——这正是「兼容多种 service 协议」的扩展点所在。异常分级BizException 与 SysException切面中 handleException 对异常做了三档分类对应 COLA 的异常体系cola-component-exception异常类型日志级别语义默认错误码BizExceptionWARNDEBUG 时打印堆栈已知业务异常无需重试BIZ_ERRORSysExceptionERROR含堆栈系统异常重试可能成功SYS_ERROR其他ThrowableERROR含堆栈未知异常UNKNOWN_ERROR三种情况最终都会交给ResponseHandlerFactory.get().handle(returnType, errCode, errMessage)构造带错误码的响应返回。文档日志示例中的{errCode:UNKNOWN_ERROR...}正是「未知异常 响应转换」两条链路共同作用的结果。五、进阶用 Archetype 一键生成自己的 Starter 组件文档所在的 cola-starter-component-archetype 是 COLA 为「快速创建 components 工程」提供的 Maven Archetype 模板dev-util-archetypes 说明模板内嵌了本文前面讲到的全套最小实现注解、切面、自动配置、spring.factories、测试配置与启动类。利用它可以把这个「日志 异常」组件的骨架原样复刻到自己的组件中。archetype-metadata.xml 声明了生成的内容src/main/java下的 Java 源码按包名 packaged 并过滤占位符、src/main/resources下的 spring.factories、src/test下的测试工程。生成时package、artifactId等占位符会被替换为用户指定值。仓库还提供了封装脚本 new-cola-starter-component.sh核心命令逻辑等价于mvn archetype:generate \ -DgroupId组件组名 \ -DartifactIdcola-component-name-starter \ -Dpackagecom.alibaba.cola.name \ -DarchetypeGroupIdarchetype groupId \ -DarchetypeArtifactIdcola-starter-component-archetype \ -DarchetypeVersionarchetype version \ -DinteractiveModefalse \ -DarchetypeCataloglocal执行后即得到一个与cola-component-catchlog-starter同构的新 Starter 工程CatchAndLog注解 CatchLogAspect切面 CatchLogAutoConfiguration自动配置 spring.factories注册入口稍加改造即可变成你自己的横切组件。六、测试验证多场景覆盖组件的正确性由测试用例完整覆盖。CatchLogTest.java 中的用例场景包括普通方法调用testAspect带请求参数调用testCatchAndLog返回Response类型testExecuteWithResponse返回 voidtestExecuteWithVoid抛出BizException且返回ResponsetestExecuteWithBizExceptionAndResponse抛出SysException且返回ResponsetestExecuteWithSysExceptionAndResponse未知RuntimeException与 void/Response 组合。这些场景由 Demo.java 提供一个标注了CatchAndLog的演示 Bean覆盖了「成功、业务异常、系统异常、未知异常」与「void、COLA Response」的交叉组合正好验证了前文讲到的异常分级与按返回类型适配响应的行为。小结CatchAndLog 组件用最少的注解侵入把 Service 层普遍存在的日志记录与异常处理收敛到一处CatchAndLog负责标记、CatchLogAspect负责拦截记录、ResponseHandlerI负责按返回类型转换错误响应、BizException/SysException负责异常分级再配合 Spring Boot autoConfig 做到零配置接入。如果在自己的项目中遇到了「每个 Service 方法都在重复打日志、重复 catch 异常」的痛点参照本文的接入三步与 cola-component-catchlog-starter 源码即可快速落地一套统一的 Service 层横切能力。赞分享后端【免费下载链接】COLA COLA: Clean Object-oriented Layered Architecture项目地址https://gitcode.com/gh_mirrors/col/COLA点击查看免费下载相关推荐COLA 组件实战cola-component-catchlog-starter 注解式 AOP 日志与异常处理详解COLA 组件实战cola component catchlog starter 注解式 AOP 日志与异常处理详解 导读 本文围绕 COLAClean O后端mall4j 系统日志实战基于 SysLog 注解与 AOP 切面的后台操作审计方案mall4j 系统日志实战基于 SysLog 注解与 AOP 切面的后台操作审计方案 本文以 mall4j 电商商城项目的后台管理系统为例深入讲解如何通过电商后端前端移动开发告别重复代码COLA框架CatchAndLog与Extension注解的实战指南告别重复代码COLA框架CatchAndLog与Extension注解的实战指南 在日常开发中你是否还在为每个接口重复编写异常捕获和日志记录代码是否在后端上一篇革命性跨平台Flutter应用LoveIwara重新定义二次元内容消费体验下一篇VGGT模型微调指南迁移学习在新场景中的应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考