SpringBoot3实战集成mzt-biz-log，一行代码搞定业务日志记录

作为后端开发者业务日志是线上问题排查、操作追溯和审计留痕的核心抓手。手写业务日志不仅重复代码量大还容易出现记录不规范、关键信息漏记错记的问题排查线上问题时往往效率极低。最近我在SpringBoot3项目中接入了mzt-biz-log这款轻量业务日志框架彻底摆脱了手写日志的繁琐注解式配置就能精准记录操作人、业务内容、变更前后数据和业务主键等核心信息全程无侵入、易扩展。本篇全是实打实的落地步骤不扯多余理论跟着一步步做就能直接跑通。一、环境准备技术集成优先保证版本适配本次采用稳定对齐的固定环境直接照搬就能规避所有兼容问题具体配置如下JDK 17SpringBoot 3.2.5Maven 3.8.6mzt-biz-log 3.0.6二、引入Maven核心依赖在项目pom.xml中添加框架核心依赖这款框架本身轻量无冗余依赖不会增加项目包体积搭配日常通用工具包即可正常使用。!-- 定义bizlog-sdk版本号推荐在pom.xml properties节点统一管理 -- properties bizlog-sdk.version3.0.6/bizlog-sdk.version /properties !-- mzt-biz-log 正确核心依赖适配SpringBoot 3.2.5 -- dependency groupIdio.github.mouzt/groupId artifactIdbizlog-sdk/artifactId version${bizlog-sdk.version}/version /dependency依赖引入后刷新Maven确保所有依赖下载完成如果中央仓库下载缓慢直接切换阿里云镜像就能加速。三、核心配置实现mzt-biz-log核心配置分为操作人获取和日志持久化两部分框架不限制日志存储介质支持数据库、ES、MongoDB等多种落地方式日常开发优先存入业务日志表。3.1 自定义操作人获取类框架无法自动获取登录用户信息需要自定义实现操作人获取接口从项目登录上下文、Token解析或者ThreadLocal中获取当前操作人这段代码可以直接适配项目登录体系复用。import com.mzt.logapi.beans.Operator; import com.mzt.logapi.service.IOperatorGetService; import org.springframework.stereotype.Component; Component public class CustomOperatorGetService implements IOperatorGetService { Override public Operator getUser() { // 替换为项目真实获取登录用户逻辑 // 示例return UserContext.getCurrentUser().getUsername(); // 测试阶段可暂用固定值上线后对接登录体系 return new Operator(admin); } }3.2 自定义日志持久化处理器实现框架日志记录接口重写核心保存方法调试阶段可以先打印控制台日志方便查看效果正式环境直接对接数据库Mapper将日志存入业务日志表全程不侵入任何业务代码。import com.mzt.logapi.beans.LogRecord; import com.mzt.logapi.service.ILogRecordService; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Component; import java.util.List; Slf4j Component public class CustomLogRecordService implements ILogRecordService { /** * 日志核心保存方法 */ Override public void record(LogRecord logRecord) { // 调试阶段控制台打印日志 log.info(业务日志); log.info(操作人{}, logRecord.getOperator()); log.info(业务类型{}, logRecord.getType()); log.info(业务ID{}, logRecord.getBizNo()); log.info(操作内容{}, logRecord.getAction()); log.info(操作时间{}, logRecord.getCreateTime()); log.info(); // 生产环境对接数据库实现日志入库 // BizLogEntity logEntity buildLogEntity(logRecord); // bizLogMapper.insert(logEntity); } Override public ListLogRecord queryLog(String bizNo, String type) { return List.of(); } Override public ListLogRecord queryLogByBizNo(String bizNo, String type, String subType) { return List.of(); } }3.3 开启日志注解功能在SpringBoot启动类上添加开启注解激活框架的日志记录功能这一步绝对不能省略否则注解会完全不生效。import com.mzt.logapi.starter.annotation.EnableLogRecord; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication EnableLogRecord(tenant ) public class Springboot3BizLogApplication { public static void main(String[] args) { SpringApplication.run(Springboot3BizLogApplication.class, args); } }至此核心配置全部完成没有繁琐的YAML配置整体结构清晰后续扩展和修改都很方便也不会对原有业务代码造成任何影响。四、业务代码接入实战配置完成后直接通过注解就能实现日志自动记录框架支持SpEL表达式可动态获取方法入参、业务数据灵活记录各类操作详情。接下来以用户管理模块为例演示编辑、删除场景的日志接入方式覆盖日常开发核心业务场景。4.1 准备业务实体类先创建基础的用户实体类模拟业务数据对象用于后续日志记录测试。import lombok.Data; Data public class UserInfo { private Long userId; private String username; private String phone; private Integer age; }4.2 注解实现业务日志记录在业务实现类的方法上添加日志注解框架会在方法执行成功后自动记录日志异常场景不记录完全符合日常业务日志的记录逻辑。针对数据修改场景可以通过框架上下文存入旧数据实现变更前后的对比记录。import com.example.bizlogdemo.entity.UserInfo; /** * 用户服务接口 * 提供用户信息的更新和删除操作 */ public interface UserService { /** * 更新用户信息 * p * 根据传入的用户信息对象更新对应用户的数据包括用户名、手机号、年龄等信息 * /p * * param user 包含更新信息的用户对象必须包含有效的 userId * return 更新成功返回 true失败返回 false */ boolean updateUser(UserInfo user); /** * 删除用户 * p * 根据用户 ID 删除对应的用户信息 * /p * * param userId 要删除的用户 ID * return 删除成功返回 true失败返回 false */ boolean deleteUser(Long userId); }import com.example.bizlogdemo.entity.UserInfo; import com.mzt.logapi.context.LogRecordContext; import com.mzt.logapi.starter.annotation.LogRecord; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; Service Slf4j public class UserServiceImpl implements UserService { /** * 编辑用户信息记录变更前后数据 */ Override LogRecord( bizNo {{#user.userId}}, success 编辑用户信息用户ID{{#user.userId}}修改前用户名{{#oldUser.username}}修改后用户名{{#user.username}}修改前手机号{{#oldUser.phone}}修改后手机号{{#user.phone}}, type user ) public boolean updateUser(UserInfo user) { // 查询数据库旧数据 UserInfo oldUser getUserById(user.getUserId()); log.info(执行用户更新操作用户ID{}, user.getUserId()); // 旧数据存入上下文供日志注解读取 LogRecordContext.putVariable(oldUser, oldUser); return true; } /** * 删除用户记录删除操作 */ Override LogRecord( bizNo {{#userId}}, success 删除用户用户ID{{#userId}}, type user ) public boolean deleteUser(Long userId) { log.info(执行用户删除操作用户ID{}, userId); return true; } /** * 模拟根据ID查询用户旧数据 */ private UserInfo getUserById(Long userId) { UserInfo oldUser new UserInfo(); oldUser.setUserId(userId); oldUser.setUsername(测试用户); oldUser.setPhone(13800138000); oldUser.setAge(20); return oldUser; } }实战小贴士数据修改场景通过LogRecordContext.putVariable()存入旧数据即可在注解中通过SpEL表达式调用实现变更对比记录新增场景直接记录业务内容bizNo使用生成后的主键即可。五、接口测试与日志验证编写控制层接口调用业务层方法测试日志是否正常记录确认整体集成效果。为了方便测试控制层接口我集成了knife4J直接生成接口文档。import com.example.shardingspheredemo.entity.UserInfo; import com.example.shardingspheredemo.service.UserService; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import jakarta.annotation.Resource; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/user) Tag(name 用户管理接口, description 用户增删改查接口) public class UserController { Resource private UserService userService; PostMapping(/update) Operation(summary 更新用户, description 传入用户信息返回用户ID) ApiResponse(responseCode 200, description 新增成功, content Content(schema Schema(implementation String.class))) public String updateUser(RequestBody UserInfo user) { boolean result userService.updateUser(user); return result ? 修改成功 : 修改失败; } GetMapping(/delete/{userId}) Operation(summary 根据ID删除用户, description 传入用户ID删除用户数据) public String deleteUser(PathVariable Long userId) { boolean result userService.deleteUser(userId); return result ? 删除成功 : 删除失败; } }5.1 接口实测1. 用户编辑接口测试测试请求地址及参数如下测试结果日志打印如下2. 用户删除接口测试测试请求地址及参数如下测试结果日志打印如下六、实战扩展思路敏感数据脱敏针对手机号、身份证号等敏感信息自定义脱敏规则在日志记录前完成处理异步日志记录使用Async实现异步保存日志避免日志记录影响业务接口性能异常日志记录结合全局异常处理器记录操作失败日志完善全流程操作追溯批量业务日志框架支持批量操作场景循环遍历业务逻辑注解依旧正常生效七、总结mzt-biz-log 轻量无侵入稳定性强注解式开发彻底告别手写日志代码实现业务逻辑与日志记录完全解耦日志记录规范统一大幅提升线上问题排查和操作审计效率。单体应用和微服务项目均可快速接入尤其适合管理后台、电商等需要完善操作追溯的业务系统。可以先在测试项目调试落地确认无误后直接迁移至正式项目整体接入成本极低。使用过程中有什么问题欢迎在评论区留言讨论。