在不可变视图上实现审计日志与变更追踪，须通过自定义包装器将“变更意图”前置到操作发起侧，而非修改集合本身；包装器持审计上下文、做字段级差异比对，并结构化落库，确保日志可查可控。
在不可变视图（immutable view）上增加审计日志与变更追踪，核心矛盾在于：视图本身不支持修改，但审计需要捕获“谁试图变更、意图是什么、原始上下文为何”。这不能靠拦截 set 或 add 实现，而必须把“变更意图”前置到操作发起侧，并通过自定义 Collections 包装器将业务语义注入数据流转链路。
关键不是让集合变可变，而是让每一次对它的“使用请求”自带可审计元信息。
一、为什么用包装器而不是直接改集合？
不可变集合（如 Java 的 Collections.unmodifiableList、Guava 的 ImmutableList、.NET 的 IReadOnlyList<t></t>）本质是防御性封装——它抛出 UnsupportedOperationException 来拒绝写操作。
强行重写 add() 等方法会破坏不可变契约，引发调用方误判。
正确做法是：用包装器包裹原始可变集合 + 审计上下文，对外暴露不可变视图，所有变更入口统一收口到包装器的业务方法中。
例如：
// ✅ 正确：包装器控制入口，视图只读，变更走 auditUpdate()
public class AuditableProductList {
private final List<product> delegate = new ArrayList();
private final AuditLogger logger;
public AuditableProductList(AuditLogger logger) {
this.logger = logger;
}
// 外部只能拿到不可变视图
public List<product> asView() {
return Collections.unmodifiableList(delegate);
}
// 所有变更必须走这里，自动记录审计日志
public void auditUpdate(Product oldProduct, Product newProduct, String operator, String reason) {
// 1. 验证变更合法性（如ID一致、状态允许）
if (!Objects.equals(oldProduct.getId(), newProduct.getId())) {
throw new IllegalArgumentException("ID mismatch in audit update");
}
// 2. 记录字段级差异
logger.logFieldDiffs(
"Product",
oldProduct.getId(),
operator,
reason,
diffFields(oldProduct, newProduct)
);
// 3. 实际更新委托集合
int idx = delegate.indexOf(oldProduct);
if (idx >= 0) {
delegate.set(idx, newProduct);
}
}
}</product></product>
二、包装器需携带的审计上下文
不可变视图本身无状态，但包装器可以持有：
- 当前操作人（
operatorId/username） - 请求来源（
source: "admin-api","batch-job"） - IP 地址或 trace ID（从 ThreadLocal 或 MDC 注入）
- 操作原因字段（前端传入的
changeReason，非空校验） - 事务标识（绑定当前 DB transaction ID，保证日志与业务一致）
这些信息不应由调用方零散传入，而应由包装器在构造时绑定上下文：
// 构造时注入运行时上下文 var context = AuditContext.current(); // 从Filter/Interceptor自动提取 var auditableList = new AuditableProductList(logger, context);
三、字段级变更识别与结构化落库
审计价值不在“改了”，而在“改了哪几个字段、从什么变成什么”。包装器应在 auditUpdate() 中做轻量比对：
- 排除
id、createdAt等非业务字段 - 对
String、Number、LocalDateTime等基础类型直比.equals() - 对嵌套对象递归比对（可用 Jackson
ObjectMapper.valueToTree()转 JSON Node 后比对） - 输出标准化变更项列表：
[
{"field": "price", "old": "99.00", "new": "89.99"},
{"field": "status", "old": "ON_SALE", "new": "DISCONTINUED"}
]
该结构直接映射到数据库 audit_log.payload JSON 字段，支持后续 SQL 查询（如 MySQL payload->>'$.field' = 'price'）。
四、与主流框架协同的关键点
| 场景 | 建议做法 |
|---|---|
| Spring Boot + JPA | 包装器不替代 Entity，而是作为 Service 层返回值；Controller 返回 AuditableProductList.asView()，避免暴露可变引用 |
| React/Vue 前端表单 | 提交时显式带 changeReason 字段，后端包装器强制校验非空，防止“无理由修改” |
| 批量操作（如 Excel 导入） | 包装器提供 auditBatchUpdate(List<diffentry>)</diffentry>，单事务内聚合日志，避免 N 条 SQL |
| 多线程环境（如定时任务） |
AuditContext 必须 ThreadLocal + 显式 bind() / clear()，避免上下文污染 |
不复杂但容易忽略。
