作为后端开发者，业务日志是线上问题排查、操作追溯和审计留痕的核心抓手。手写业务日志不仅重复代码量大，还容易出现记录不规范、关键信息漏记错记的问题，排查线上问题时往往效率极低。

最近我在SpringBoot3项目中接入了mzt-biz-log这款轻量业务日志框架，彻底摆脱了手写日志的繁琐，注解式配置就能精准记录操作人、业务内容、变更前后数据和业务主键等核心信息，全程无侵入、易扩展。本篇全是实打实的落地步骤，不扯多余理论，跟着一步步做就能直接跑通。

一、环境准备

技术集成优先保证版本适配，本次采用稳定对齐的固定环境，直接照搬就能规避所有兼容问题，具体配置如下：

• JDK 17+
• SpringBoot 3.2.5
• Maven 3.8.6+
• mzt-biz-log 3.0.6

二、引入Maven核心依赖

在项目pom.xml中添加框架核心依赖，这款框架本身轻量无冗余依赖，不会增加项目包体积，搭配日常通用工具包即可正常使用。

<!-- 定义bizlog-sdk版本号，推荐在pom.xml properties节点统一管理 -->    3.0.6<!-- mzt-biz-log 正确核心依赖，适配SpringBoot 3.2.5 -->    io.github.mouzt    bizlog-sdk    ${bizlog-sdk.version}

依赖引入后刷新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;@Componentpublic 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@Componentpublic 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 List queryLog(String bizNo, String type) {        return List.of();    }    @Override    public List 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;@Datapublic 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 {    /**     * 更新用户信息     * 
     * 根据传入的用户信息对象，更新对应用户的数据，包括用户名、手机号、年龄等信息     * 
     *     * @param user 包含更新信息的用户对象，必须包含有效的 userId     * @return 更新成功返回 true，失败返回 false     */    boolean updateUser(UserInfo user);    /**     * 删除用户     * 
     * 根据用户 ID 删除对应的用户信息     * 
     *     * @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@Slf4jpublic 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直接生成接口文档，后面我会再单独发一篇关于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 轻量无侵入，稳定性强，注解式开发彻底告别手写日志代码，实现业务逻辑与日志记录完全解耦，日志记录规范统一，大幅提升线上问题排查和操作审计效率。单体应用和微服务项目均可快速接入，尤其适合管理后台、电商等需要完善操作追溯的业务系统。可以先在测试项目调试落地，确认无误后直接迁移至正式项目，整体接入成本极低。使用过程中有什么问题欢迎在评论区留言讨论。