用户操作日志模块的设计与实现

在系统开发中，日志框架常被用于调试与追踪运行状态，但这类日志主要面向技术人员。与之不同，用户操作日志面向的是业务人员与审计需求，它需要回答“谁在什么时间对哪个对象做了什么操作，改动了哪些字段”。这类日志在企业管理、协作平台、后台系统中几乎是标配能力。

然而，操作日志模块的开发并不简单。它横跨架构设计、对象建模、反射与切面编程、存储设计等多个方面，是检验开发者综合能力的典型题目。本文将从功能定义出发，逐步推导出一套可落地的实现方案。

一、功能定义：从四类操作说起

在多数系统中，操作可分为增、删、改、查四类。对操作日志而言，这四类的处理难度并不相同：

• 查询操作：通常不改变对象状态，一般无需记录；
• 新增操作：只涉及一个“新状态”；
• 删除操作：只涉及一个“旧状态”；
• 编辑操作：同时涉及“编辑前”和“编辑后”两个状态。

编辑操作是操作日志中最核心、最复杂的场景。 一旦解决了编辑操作，其余三类都可以视为它的特例：

• 新增 = null → 新对象；
• 删除 = 旧对象 → null；
• 查询 = 旧对象 → 旧对象。

因此，本文以编辑操作为主线展开。

假设我们有一个校园卫生大扫除系统，其中包含分配任务、开始任务、验收任务、新增人员等方法。以 startTask 为例：

public String startTask(String taskId, Integer userId, Date startTime, Tool tool) {
    // 业务逻辑
}

该方法涉及任务 ID、责任人、开始时间、使用工具等多个参数。操作日志需要记录：谁（userId）在什么时间，对哪个任务（taskId），把哪些字段从什么值改成了什么值。

二、模型设计：切面的分层策略

要在不侵入业务代码的前提下采集这些信息，切面（AOP）是自然的选择。根据拦截位置的不同，可以分为三种策略：

2.1 上层切面

在业务方法入口处拦截，直接获取方法参数。优点是实现简单、与业务解耦；缺点是只能拿到“入参”，无法直接感知对象在数据库中的旧状态，需要额外查询。

2.2 下层切面

在数据访问层拦截，直接对比数据库更新前后的记录。优点是能拿到完整的旧值与新值；缺点是与持久层耦合较深，且批量操作、逻辑删除等场景处理复杂。

2.3 混合切面

结合上下两层：上层切面负责识别“谁在操作、操作了什么业务语义”，下层切面负责采集“字段级的新旧值变化”。这是推荐方案，兼顾语义清晰与数据完整。

三、对象属性对比：找出真正变化

拿到新旧两个对象后，核心任务是逐字段对比，找出发生变化的属性。常见做法是基于反射遍历字段：

for (Field field : clazz.getDeclaredFields()) {
    field.setAccessible(true);
    Object oldVal = field.get(oldObj);
    Object newVal = field.get(newObj);
    if (!Objects.equals(oldVal, newVal)) {
        // 记录变化
    }
}

但直接使用 equals 并不够，需要处理几个问题：null 值、集合顺序、时间精度、数值类型差异等。因此需要引入统一的比较器策略。

四、对象属性处理：分类应对

不同属性需要不同处理方式，建议分为三类：

4.1 普通属性

如字符串、数字、布尔值、日期等，直接比较即可。日期建议统一格式化到相同精度，避免因毫秒差异产生“假变化”。

4.2 特殊属性

如集合、Map、数组、嵌套对象等。集合需要判断“是否同一批元素”，嵌套对象需要递归比较或序列化后比较。对复杂结构，可先转为 JSON 再对比，但要注意字段顺序问题。

4.3 业务属性

某些字段虽然在技术上变化了，但业务上不关心，例如更新时间、版本号、内部计数器。这类字段应通过注解或配置排除，避免日志噪音。

五、易用性注解：降低接入成本

为了让业务开发者用起来简单，注解是最佳载体。可以设计如下注解：

@OperationLog(module = "任务管理", action = "开始任务")
public String startTask(String taskId, Integer userId, Date startTime, Tool tool) { ... }

再配合字段级注解：

@LogField(name = "任务名称")
private String taskName;
@LogIgnore
private Date updateTime;

通过注解，业务代码只需少量标注，即可自动生成结构化日志。注解还可以支持自定义转换器，把枚举值、ID 转成可读文本。

六、存储设计

操作日志的存储需要考虑三点：

1. 结构化：建议存储为“操作主体 + 操作对象 + 字段变更列表”的形式，便于检索与展示；
2. 可扩展：字段变更列表可用 JSON 存储，避免频繁改表；
3. 可归档：日志量增长快，应按时间分区或冷热分离，历史数据转入低成本存储。

典型表结构可包含：日志 ID、操作人、操作时间、模块、动作、对象类型、对象 ID、变更详情（JSON）、请求来源等字段。

七、方案总结

一套完整的操作日志模块应具备以下特征：

• 以编辑操作为核心，兼容增删查；
• 采用混合切面采集语义与数据；
• 反射对比字段，分类处理属性；
• 注解驱动，低侵入接入；
• 结构化存储，支持归档与检索。

八、系统实现要点

在实际编码中，建议按以下顺序推进：

1. 定义注解与日志实体；
2. 实现字段比较器与属性处理器；
3. 编写切面，串联“采集—对比—组装—落库”流程；
4. 提供异步写入能力，避免阻塞主流程；
5. 增加单元测试，覆盖 null、集合、嵌套对象等边界场景。

操作日志模块看似简单，实则是对架构抽象能力的一次综合考验。把编辑操作做扎实，其余场景自然水到渠成。