EFCv4.1.0-SNAPSHOT

外观

日志采集重点文件与方法 ​

面向应用扩展保存器、补充当前请求日志，以及排查异步接收与实际保存差异。采集开关和字节预算见使用与配置。

本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。

SystemLogContext ​

源码：SystemLogContext。

一次 Servlet 请求的可变采集上下文。正常由拦截器创建并在完成阶段冻结为 SystemLog；业务代码通过 current() 访问，不自行调用 complete() 提前结束采集。

方法 / 重载用途、参数与返回值注意事项
SystemLogContext(OperatorInfo operator, String module, String name, String code, String method, String path, String traceId, String service, boolean responseData, JsonSnapshot requestParams, SafeLogSnapshot snapshots, SystemLogResponseExtractor extractor)构造本次操作元数据、快照工具与响应提取器，同时生成 ID 和起始时间。集成层入口；operator 等必要信息应完整，纳秒时钟用于耗时，Instant 用于绝对时间。
current()返回 Optional<SystemLogContext>；无 Servlet 请求或未采集时为空。不要直接 get() 假设所有接口已开启日志。
authenticated(String userId)在未完成时补充本次认证成功的用户 ID，经文本限长。不替换原 operator；已经 complete 后无操作。
extra(Object value)立即捕获扩展对象快照并覆盖 extra。多次调用不合并；先自行组成 Map，且只放业务可记录字段。
response(Object body)提取 code/message/success/data，并补取 MDC TraceId。不是发送 HTTP 响应；提取失败标 EXTRACT_FAILED，二进制内容省略。
unsupportedAsync()标记当前响应属于不支持的异步采集。最终 data 将标 ASYNC_UNSUPPORTED，不表示业务请求失败。
complete(int status, Exception failure)首次调用冻结并返回 Optional<SystemLog>，后续为空。status>=400 设置 success=false；写出失败/不支持异步会将响应数据标不可用。

以下片段放在受采集的业务请求方法中，import 为 com.own.component.log.core.SystemLogContext、java.util.Map。仅在认证已成功后补充 userId：

java
SystemLogContext.current().ifPresent(context -> {
    context.authenticated(String.valueOf(userId));
    context.extra(Map.of("orderId", orderId, "stage", "validated"));
});

SystemLogPersistence ​

源码：SystemLogPersistence。

同步保存 SPI。应用注册 Bean 或选用 Business 保存器；传入的是安全日志快照，不是 HttpServletRequest。

方法 / 重载用途、参数与返回值注意事项
save(SystemLog log)同步保存一条日志，成功正常返回，失败可抛 Exception。实现不要只入自己的内存队列就宣称持久化完成；多后端之间没有共同事务。

SystemLogRecorder ​

源码：SystemLogRecorder。

采集到保存之间的接收入口。默认由 AsyncSystemLogRecorder 实现，也可以由应用提供明确的接收策略。

方法 / 重载用途、参数与返回值注意事项
record(SystemLog log)返回是否接收此次日志。true 不保证任何后端已经保存；根据实现决定队列/同步语义。

AsyncSystemLogRecorder ​

源码：AsyncSystemLogRecorder。

有界内存异步记录器；工作线程向所有保存器依次分发相同安全快照，一家失败继续下一家。程序退出或异常停机会丢失尚未保存的内存任务，没有持久化队列或自动重试。

方法 / 重载用途、参数与返回值注意事项
AsyncSystemLogRecorder(SystemLogPersistence persistence, SafeLogSnapshot snapshots, SystemLogProperties properties)构造单保存器版本，委托列表构造器。校验配置，创建固定 worker 数及有界队列。
AsyncSystemLogRecorder(List<SystemLogPersistence> persistences, SafeLogSnapshot snapshots, SystemLogProperties properties)复制保存器列表并创建执行器。列表必须非空且元素非 null；构造后不动态发现新的保存器。
record(SystemLog source)启用时做安全快照和整条大小检查，再入队；成功 true。关闭返回 false 且不计 dropped；超限、非法数据、队列满或关闭后拒绝均可能返回 false。
acceptedCount()返回成功交给执行器的记录数。计的是接收，不是落库成功；与失败计数不能直接相减作成功条数。
droppedCount()返回超限/拒绝等丢弃计数及关闭时移除的等待任务数量。中断关闭路径未逐项统计所有未保存数据，不是严格审计总数。
failedCount()返回保存器执行失败次数。同一日志多个后端失败会累计多次，不是失败日志条数。
close()停止接收并等待 shutdownTimeout，超时 shutdownNow。超时可能丢等待任务、打断运行任务；中断时恢复中断标记。

SafeLogSnapshot ​

源码：SafeLogSnapshot。

限长、限深、限集合大小地提取 JSON。它省略部分框架/流/身份对象，但不是通用敏感字段脱敏器；应用仍需控制记录内容。

方法 / 重载用途、参数与返回值注意事项
SafeLogSnapshot(ObjectMapper mapper, SystemLogProperties properties)复制 Jackson 2 Mapper、注册时间模块，读取 Capture 限额。不会把应用 Mapper 的对象引用直接作为自身 Mapper。
capture(Object value)返回包含 json/status/reason 的 JsonSnapshot。null 可以正常捕获；超过预算标 TRUNCATED，提取异常标 UNAVAILABLE。会调用可序列化属性访问器。
recapture(JsonSnapshot snapshot)重新解析并按当前限额捕获已有快照。null 标 NOT_PROVIDED；坏 JSON 标 INVALID_JSON；不自动信任远端快照。
text(String value)按 UTF-8 字节预算截断单个字段，null 仍 null。按 Unicode code point 截断，不能把预算当字符数。
fitsRecord(SystemLog log)序列化整条日志，检查是否 <=32768 字节。硬性上限，不由 maxResponseBytes 放大；序列化失败返回 false。

SystemLogResponseExtractor ​

源码：SystemLogResponseExtractor。

自定义响应协议提取 SPI，返回 ExtractedResponse(code,message,data,success)。

方法 / 重载用途、参数与返回值注意事项
extract(Object body)从实际 Controller 返回体提取四个字段。与 HTTP 状态分开；Boolean success 可为 null 表达未知，不强推全部成功。

嵌套 record 的 code()/message()/data()/success() 仅读取提取结果；data 随后再由快照工具捕获。默认实现的成功码识别见理解日志结果。

SystemLogOperatorResolver ​

源码：SystemLogOperatorResolver。

从请求解析发起人，适合已有自定义身份体系的应用覆盖。

方法 / 重载用途、参数与返回值注意事项
resolve(HttpServletRequest request)返回 OperatorInfo，包含类型、ID、名称、客户端和 IP。从可信认证结果取身份，不把客户端任意 Header 当成已认证用户。

扩展与实际保存 ​

应用扩展通常实现保存器或两个提取 SPI 即可，不需要手动创建上下文。简单保存器完整例子见快速开始；数据库、文件、MQ 的保存和失败规则见 Business 系统日志。