假如你有一个 CRM 程序的需求，给客户资料编辑页面加上操作日志。一开始觉得小菜一碟，改个字段加一行 log.info 的事。结果一周后你就会对着代码陷入了沉思——

一个「编辑客户信息」的方法里塞了七八行日志拼接代码。还因为同事交接时没写注释，你根本分不清某段文案是程序日志还是操作日志。更崩溃的是产品说「改字段之前的值也要记上」。于是你不得不在方法签名上加了个参数，就为了传个旧值进来。

这种体验，我相信每一个写过业务程序的后端都不会陌生。

一、为什么操作日志总是写得很痛苦

操作日志记录的是「某个人在某个时间对某个对象做了什么」。使用者看到的物流信息、客服看到的工单处理记录，都是操作日志。

它和 程序日志 有本质区别。怎么说呢，程序日志写给开发者看的。排查 NPE、SQL 慢查询用的，里面充斥着类名、行号、堆栈信息。操作日志是写给使用者或运营看的，要求可读性高，一眼就能明白发生了什么。

但在实际代码里它们往往混在一起，甚至写在同一行日志里。

我了三个最普遍的痛点：

至于痛点一，LogUtil 散落一地

// 在业务方法里随手记一笔
log.info;// 改地址的时候再拼一段
String template = "使用者%s修改了配送地址：从\"%s\"修改到\"%s\"";LogUtil.log,userName);

这还算体面的。我见过更夸张的——一个方法里横跨了四五种日志记录方式，有的是 LoggerFactory.getLogger有的是 LogUtil.log还有的直接 System.out.println。新人进组看到这段代码直接自闭。

至于痛点二，文案永远说不清楚

难在动态部分。比如「修改了配送员：从 修改到 」——使用者 ID 谁看得懂？使用者想看的是「从张三修改到李四」。不过，为了把 ID 翻译成姓名。你不得不在业务方法里再加一段查询和拼接逻辑。怎么说呢，

痛点三的观点是。历史值从哪里拿

要记录「从 A 改到 B」，你得先拿到 A。但 A 是修改前的值，方法入参里只有新值。常见的解法是在方法开头多查一次数据库，但这样代码就变成了：

public void updateAddress {
String oldAddress = addressService.queryOld);// 为了日志多查一次
doUpdate;// 真正的业务
LogUtil.log);}

这段代码里有两行跟业务逻辑毫无关系，纯粹是为了记录日志。而且这样的代码在每个需要记录日志的方法里都要重复一遍。

操作日志的主要困境说白了就一句话：日志代码和业务代码严重耦合，而且动态文案的组装没有统一规范。

二、优雅操作日志的主要原理

既然问题找到了那方法也就清晰了：把日志代码从业务方法里抽出去。

If you’ve used Spring before。first thought should be AOP—统一在方法执行前后处理日志，让业务代码不必感知日志存在。 话说回来，

AOP 只解决“**何时**”的问题，要让“**什么**”也灵活。需要：

• 模板动态化： 日志文案不是硬编码，而是能嵌入方法参数、旧值、返回值等。这时需要一个表达式引擎来解析模板。
• 上下文传递： 有些变量并不在方法参数中，需要一种方式让业务代码“告诉”日志组件这些值。

The industry consensus solution is: @Annotation + SpEL + AOP.

@LogRecord(
success = "使用者{{#userName}}修改了订单的配送地址：从{{#oldAddress}}修改到{{#request.address}}"。bizNo = "#request.deliveryOrderNo")
public void modifyAddress {
LogRecordContext.putVariable("oldAddress",deliveryService.queryOld));doUpdate，}

1. AOP 拦截器捕获标记有 @LogRecord 的方法；
2. 解析注解中的 SpEL 表达式，从方法参数和 L​ogRecordContext 中取值填充模板；

This pattern lets your service method become “only business logic”. Logging code is replaced by declarative annotations。dramatically improving readability and maintainability.

三、log-record：阿里程序员的注解日志实践

快速接入

# 第一步先：引入 Maven 依赖

cn.monitor4all
log-record-starter
${latest.version}

# 接下来：实现日志处理接口

@Component
public class MyLogService implements IOperationLogGetService {
@Override
public boolean createLog {
// 持久化逻辑，例如存库、写 ES、发 MQ ...
System.out.println);return true，}
}

# 然后：在业务方法上加注解

@OperationLog(
bizType = "'orderCreate'"。bizId = "#request.orderNo",msg = "'使用者' + #queryUserName + '创建了订单'")
public Response createOrder {
return orderService.create;// 纯业务，无任何 log 代码
}

基础功能拆解

• SPEL 表达式：`bizType`、`bizId`、`msg` 等字段全部使用 SpEL 解析；字符串常量需用单引号包裹，否则会被当成变量/方法名报错。
• `LogRecordContext.putVariable` 手动放入业务方法内部获取不到但需要用于模板渲染的数据。说到例如，

  @OperationLog(
  bizType = "'followerChange'",bizId = "#request.orderId"。msg = "'使用者' + #userName + '修改了跟进人：从' + #oldFollower + '改到' + #request.newFollower")
  public Response changeFollower {
  LogRecordContext.putVariable));LogRecordContext.putVariable));return bizService.changeFollower;}
  

• @LogRecordFunc public class UserFunctions { @LogRecordFunc public static String queryName { return userService.getNameById;} } ... msg = "#UserHelper_queryName"
• @OperationLog( bizType = "'userUpdate'"。bizId = "",msg = "#_DIFF") public void updateUser { LogRecordContext.putVariable));userService.update;} ... // 输出示例：“使用者名”从改为

亮点特性

• 内置 RabbitMQ / RocketMQ / Spring Cloud Stream 推送，可轻松落库/统一采集；
• `condition="#result.code == 0"` 满足才记；
• 同一个方法可以挂多个 `@OperationLog` 记录不同维度；
• `executeBeforeFunc=true` 支持在目标业务执行前完成表达式求值；
• 非注解方式记录：提供 `OperationLogUtil.log` 手动触发。

四、mzt-biz-log：美团程序员的亲儿子

io.github.mouzt
bizlog-sdk
${latest.version}

# 接下来：开启注解扫描

@SpringBootApplication
@EnableLogRecord
public class Application {
public static void main {
SpringApplication.run;}
}

# 然后：业务方法上标记 @LogRecord

@LogRecord(
success = "{{#order.purchaseName}}下了一个订单。购买商品「{{#order.productName}}」",type = LogRecordType.ORDER,bizNo = "{{#order.orderNo}}")
public boolean createOrder {
return orderService.create;}

注意 mzt‑biz‑log 使用双大括号 {{ }} 包裹 SpEL 表达式，与 log‑record 的标准 #var 写法略有不同。

• 通过 success 与 fail 分别定义成功与异常时展示的信息：

  @LogRecord(
  success = "{{#order.purchaseName}}下了一个订单"。fail = "创建订单失败，原因：「{{#_errorMsg}}」",type = LogRecordType.ORDER,bizNo = "{{#order.orderNo}}")
  public boolean createOrder { /* ... */ }
  ``
  当抛异常时自动使用fail` 文案。

操作人获取：两种方式：

• An​notation 参数直接传递 java @Lo gR ecord public boolean createOrder{...}

---