使用与配置

完成快速开始后，可以按接口控制记录内容，并通过配置限制日志大小和异步保存资源。

控制记录内容

设置模块和操作

注解属性	作用	默认行为
AopSystemLogModule.value	Controller 所属模块	未声明时使用 Controller 简单类名
AopSystemLogRecord.name	操作名称	必填；传空白时回退到方法名
AopSystemLogRecord.code	稳定操作编码	未设置时使用方法签名
AopSystemLogRecord.module	当前方法的模块名称	未设置时沿用类级模块
AopSystemLogRecord.responseData	允许记录响应 data	true，同时受全局开关限制

关闭某个操作的响应正文采集：

@AopSystemLogRecord(name = "重置凭证", responseData = false)

这仍会记录操作及可提取的响应码、消息等信息。未标注方法注解的接口不采集；同一次同步 MVC 请求只提交一条日志。

采集请求参数

own:
  system-log:
    capture:
      request-params: true
      response-data: true

request-params 只读取 Servlet 已解析的 query/form 参数，不主动读取请求流，也不自动记录 @RequestBody。文件和二进制响应会省略正文。

记录内容

快照默认不按字段名脱敏，password、Token、Authorization 等可用字段也可能被保留。需要限制内容时，关闭相应采集或自定义响应提取器。快照仍尊重 @JsonIgnore，并对类型、大小和深度进行限制。

补充业务信息

在已采集的 Web 请求中，使用 SystemLogContext 补充信息。下面代码放在业务方法内：

SystemLogContext.current().ifPresent(context ->
        context.extra(Map.of("targetId", "1001")));

其中 SystemLogContext 位于 com.own.component.log.core，Map 为 java.util.Map。采集关闭或接口未标注时，current() 返回空 Optional。

登录成功后，可通过 context.authenticated("1001") 补充确认的用户 ID。它保存在 operation.authenticatedUserId 中，不覆盖操作开始时的匿名发起人。

直接写 HttpServletResponse 时，应在写出前调用 context.response(body) 补充响应。非 Web 场景可调用 SystemLogRecorder.record(SystemLog)；必须提供发起人、操作开始时间和响应完成时间。默认记录器会重新应用本地采集配置及服务名。

配置参考

以下配置项均位于 own.system-log 下。

配置项	默认值	说明
enabled	false	本机采集和默认记录器开关
service-name	取 spring.application.name	启用采集时必须可解析
capture.request-params	false	采集 query/form 参数
capture.response-data	true	采集响应 data
capture.max-response-bytes	16384	64–16384 字节
capture.max-field-bytes	2048	16–2048 字节
capture.max-depth	5	1–10 层
capture.max-collection-size	50	1–100 项
async.workers	2	工作线程数，至少 1
async.queue-capacity	256	排队容量，至少 1
async.shutdown-timeout	10s	关闭时等待保存完成，0–60 秒

完整记录编码超过 32 KiB 时丢弃，该上限不可通过上述配置调整。后端连接和读写超时由各保存器单独设置。

理解日志结果

原始模型为 com.own.component.log.model.SystemLog：

字段	内容
id	原始事件 ID
operator	操作开始时的身份类型、ID、名称、客户端、IP
operation	模块、操作、请求信息、开始时间、登录后确认的用户 ID
response	HTTP 状态、业务 code/message、data、成功标识、完成时间
traceId / serviceName	链路与来源服务
durationMillis / extra	耗时与额外快照

默认响应提取器支持 ResultModel 和统一异常响应 ExceptionMessageModel。无法确认业务结果时 success 为 null，HTTP 错误状态会标记失败。

公共响应协议见 Base 响应与异常。当前 Base 校验失败响应使用 00003 且保留 success=true，该码又是默认提取器认可的操作成功码，因此这一分支可能被记为业务成功；需要应用统一校验错误码或适配响应提取规则。

请求、响应和扩展数据使用 JsonSnapshot，其中 json 为已编码的 JSON 文本，status 表示采集结果：

状态	含义
CAPTURED	已采集
OMITTED	因配置或类型策略省略
TRUNCATED	达到大小、深度或集合上限
UNAVAILABLE	未获取、提取失败或生命周期不支持，具体原因见 reason

自定义扩展

将实现注册为 Spring Bean：

接口	用途
SystemLogOperatorResolver	从请求解析可信发起人
SystemLogResponseExtractor	适配自定义响应结构，返回的数据仍经过快照处理
SystemLogPersistence	保存完整日志，需支持并发调用
SystemLogRecorder	接管记录和分发策略

前三个接口位于 com.own.component.log.spi，Recorder 位于 com.own.component.log.core。

默认发起人解析使用当前会话、可用的客户端参数管理器和 remoteAddr，不直接信任 X-Forwarded-For。若身份在方法切面中才产生，需要将身份解析前移或自行适配 Resolver。

会话 Provider 与请求 TraceId 的基础行为见 Base 上下文。日志记录器使用自己的工作线程和队列，不受 Base customAsyncExecutor 容量配置控制。

默认记录器收集所有保存器，按 Ordered / @Order 顺序调用，@Primary 不会排除其他实现。单个后端异常后仍尝试其余后端；慢后端会占用当前工作线程。

异步保存的边界

record() 返回 true 只代表入队成功。内存队列不自动重试、不提供跨后端事务，进程异常退出可能丢失未完成日志。队列满时直接拒绝，不在业务线程执行保存。

AsyncSystemLogRecorder 提供实例内存计数：acceptedCount() 统计接收任务，droppedCount() 统计提交失败及关闭超时移除的排队任务，failedCount() 按后端异常次数统计。计数重启归零，且存在交叉，不能直接相加作为总提交数。

当前采集面向同步 Spring MVC。异步派发标记 ASYNC_UNSUPPORTED，流式响应、ERROR 二次派发及进入 MVC 前的 Filter 拒绝需要额外适配。日志反映服务端准备返回的内容，不保证客户端已经收到。