Java审计日志核心是明确审计点、统一结构、解耦业务、保障不可篡改与可追溯；应通过切面+注解或专用服务实现，定义含操作时间、用户、IP、路径、类型、结果等字段的事件模型，结合Spring Security获取可靠身份，落盘需独立配置、长期归档并确保字段一致可检索。
在 Java 项目中记录用户关键操作的审计日志，核心是明确审计点、统一日志结构、隔离业务逻辑、确保日志不可篡改且可追溯。不建议直接在业务方法里写 log.info()，而应通过切面、注解或专用审计服务实现解耦和标准化。
定义关键操作与审计事件模型
先梳理哪些操作需审计（如登录、密码修改、权限变更、敏感数据导出、资金转账等），再设计统一的审计事件对象：
- 包含固定字段：操作时间、操作人（用户ID/用户名）、客户端IP、请求路径、操作类型（枚举）、操作结果（成功/失败）、失败原因（如有）
- 支持扩展字段：业务主键（如订单ID）、操作前/后状态快照（JSON序列化）、关联资源标识
- 推荐使用 Lombok + Builder 模式简化构造，避免日志对象污染业务实体
用 @AuditLog 注解 + AOP 自动采集
在关键方法上添加自定义注解，由切面自动提取上下文并记录日志：
- 定义
@AuditLog(action = "修改用户角色")，支持指定 action 描述和是否记录参数 - AOP 切面获取 SecurityContext 中的当前用户、HttpServletRequest 中的 IP 和 URI
- 捕获方法执行结果（包括异常），填充到审计事件中，异步写入日志文件或发往 ELK / Kafka
- 注意：避免记录明文密码、身份证号等敏感字段，需对参数做脱敏处理（如用
StringUtils.mask()）
结合 Spring Security 增强身份上下文可靠性
仅依赖 ThreadLocal 用户信息易被绕过，应以 Spring Security 的 Authentication 为准：
立即学习“Java免费学习笔记（深入）”；
- 在审计日志中优先取
SecurityContextHolder.getContext().getAuthentication().getPrincipal() - 若 Principal 是自定义 UserDetail 实现，确保其包含 userId、username、orgId 等审计必需字段
- 对未认证请求（如开放接口），显式标记为
ANONYMOUS，避免日志缺失主体信息
落盘与合规性要点
审计日志不是普通应用日志，需满足可查、防删、防伪要求：
- 单独配置日志 appender（如 Logback 的
RollingFileAppender），路径独立（如/var/log/app/audit.log） - 启用日志归档与压缩，保留周期不少于180天（依据等保或行业规范）
- 生产环境禁用 console 输出；日志内容不输出堆栈（除非失败且需排查），避免泄露内部结构
- 如需法律效力，可对接硬件时间戳服务或区块链存证组件（进阶场景）
不复杂但容易忽略的是日志字段的一致性和可检索性——所有系统模块用同一套审计事件类，ES 中按 action 和 userId 建索引，才能真正支撑事后溯源与风控分析。
