Spring AOP接口日志统一的解决方案_Java

接口日志看似只是打印请求参数、返回值和耗时，进入生产环境后却会同时遇到敏感字段、超大对象、异常路径、traceid 和日志成本等问题。日志越“完整”，泄露和噪声风险反而可能越高。

关键风险： 如果每个 controller 自己记录，字段和格式无法统一；如果一个 aop 无差别序列化所有对象，文件、密码、token 与大列表又可能直接进入日志。企业级接口日志需要的是稳定事件模型，而不是更多 println。

本文用baseaspectlogger 及相关处理链统一采集入口、结果、耗时和异常，并给脱敏与失败补偿留下扩展位置。下文先定义一条可运营的接口日志应包含什么，再用源码说明这些字段在什么时机产生。

一、先统一“哪些调用需要被观察”

metalite 的 aspecttypeenum 把调用分为八类：

类型	场景	是否为入口
`api_receive`	接收 http 请求	是
`job_run`	执行定时任务	是
`mq_consume`	消费消息	是
`dao_call`	访问数据库或搜索引擎	否
`api_call`	调用内部 http 服务	否
`mq_produce`	发送消息	否
`redis_call`	调用 redis	否
`caffeine_call`	调用本地缓存	否

入口负责建立 traceid，调用层沿用当前上下文。这样一条请求可以在 api、rpc、缓存和 dao 日志中使用同一 traceid 关联，而不是靠开发者在每个方法里手工拼接。

这也是统一日志与普通 handlerinterceptor 的区别：拦截器主要看到 http 入口，无法天然覆盖定时任务、缓存、dao 和服务调用。

二、为什么不是每类切面各写一套 logger

metalite 为 api、rpc、redis、caffeine 和任务等场景保留各自的 logger，例如：

public class apireceivelogger extends baseaspectlogger {
    @override
    public aspecttypeenum aspecttype() {
        return aspecttypeenum.api_receive;
    }
}

子类只声明自己属于哪种切面，真正的日志模板都由 baseaspectlogger 完成。它在调用前记录：

开始时间 | 应用名 | 远端ip | 本机ip | 切面类型 | uri或方法 | 入参 |

调用完成后追加：

返回结果 | 耗时毫秒

因此一条日志可以形成稳定结构：

2026-08-07 10:20:30.123|admin|10.0.0.8|10.0.0.12|api_receive|/api/order/list|{"param":{...}}|{"return":{...}}|36

固定分隔字段比随意自然语言更适合检索和聚合，也让不同调用类型可以共用分析规则。

但这里的输出仍是普通文本日志，并没有自动变成 elasticsearch 索引、micrometer 指标或 opentelemetry span；采集、解析、留存和告警仍需部署侧完成。

三、接口名称为什么不能一律写成类名加方法名

baseaspectlogger.fetchname 对入口和内部调用做了不同处理：

api_receive 使用当前请求 uri；
其他类型使用 类名.方法名。

用户报告 /api/order/list 出错时，直接按 uri 搜索比先猜 controller 方法更快；排查 redis 或 rpc 调用时，类名与方法名又比 http 路径更准确。

远端 ip 也只在 api_receive 中读取。内部方法调用没有伪造一个“远端 ip”，避免字段看似完整、语义却是错误的。

四、如何防止入参和返回值把日志撑爆

metalite 用 printcontrol.printlength 为每种切面控制输出：

private int printlength;

当前语义是：

0   → 不输出该切面日志
-1  → 完整输出
>0  → json 序列化后按字符长度截断

这使 api 与 dao 可以采用不同策略。例如 api 在排障期打印有限长度，dao 默认不打印大结果，缓存调用只保留足够识别 key 和结果的片段。

需要注意，当前实现是在对象完整序列化之后再截取字符串。它能减少最终日志体积，却不能避免大对象序列化本身的 cpu 和内存成本；截断后的 json 也可能不是合法完整 json。因此超大列表、文件内容和二进制对象更应该在序列化前按字段或类型忽略，而不是只依赖长度。

五、忽略字段、忽略类型与脱敏应该分开

printcontrol 提供两类忽略规则：

private string ignorefieldname;
private string ignorefieldclass;

aspectlogproperties 还维护全局 desensitizerule：

private list<desensitizerule> globaldesensitizecontrols;

三者分别解决不同问题：

密码、私钥、token：按字段直接不输出；
文件、请求对象等大类型：按类型忽略；
手机号、身份证等仍有排障价值的数据：保留部分字符并脱敏。

日志安全的原则不是“所有内容都打星号”，而是先做数据最小化，再决定哪些字段需要有限展示。

规则按字段名称或类型匹配，字段改名、同名异义和嵌套对象变化都可能造成漏网。因此配置存在不代表治理完成，仍应通过请求、返回值、集合和异常场景的测试验证。

六、日志序列化失败为什么不能拖垮业务

入参或返回值可能包含 fastjson2 无法正常处理的对象。baseaspectlogger 在 fetchparam 和 fetchresult 中捕获序列化异常：

try {
    return fastjson.obj2json(...);
} catch (exception e) {
    log.error("fetchresult error", e);
    return "{\"return\":\"serialize error\"}";
}

准确的源码行为是：记录序列化失败并用错误摘要占位，避免为了写日志改变主业务的成功或失败结果。

这体现了基础设施的降级原则：可观测性很重要，但日志组件不应成为业务接口的新故障源。

七、鉴权或校验提前失败时，日志会不会消失

切面处理器链通常采用 fail-fast：参数校验、认证或限流失败后，不再执行后续业务处理器。

如果日志处理器排在链尾，最直接的实现会导致“成功请求有日志，拒绝请求没日志”。metalite 的 aspecthandlerchain 在前置处理失败时，会从链尾寻找 baseaspectlogger 并补执行日志前置逻辑，然后返回失败响应。

这样认证失败、限流和参数错误仍能获得基本调用上下文。

需要区分的是，前置日志补偿不代表所有处理器都会继续执行，也不代表错误响应一定走成功日志的完整后置流程。异常路径最终还会进入 errorhandle，业务异常只记录消息，其他异常附带堆栈。

八、dao 的 sql 日志为什么需要单独开关

printcontrol 还有一个仅针对 dao_call 的配置：

private boolean printsql;

sql 或 elasticsearch dsl 对慢查询排查很有价值，但它们也可能包含大量参数、敏感条件和长文本。把 sql 输出与普通方法参数分开控制，可以让生产环境默认克制，在受控诊断期按需打开。

开关本身不解决慢 sql、执行计划和数据库指标问题。dao 日志能告诉我们“调用了什么”，数据库监控才能解释“为什么慢”。

九、统一日志方案仍有哪些边界

结合当前源码，至少要公开以下限制：

日志长度是序列化后按字符截断，截断结果不保证是完整 json；
大对象仍会先序列化，长度限制不是性能隔离；
字段忽略和脱敏依赖配置命中，需要持续测试；
baseaspectlogger 输出的是结构化文本，不是自动建好的日志平台；
耗时是当前切面包围的方法耗时，异步返回 future 时不等于任务最终完成耗时；
traceid 是轻量日志关联，不包含 span、父子关系和调用拓扑；
开启完整入参、结果或 sql 会增加泄露与存储风险。

这些边界不削弱统一日志的价值，反而决定了它应该处在什么位置：负责建立一致、可配置、可降级的观测入口，不伪装成完整 apm。

十、从散落的 log.info 到可治理的调用日志

spring boot 接口日志真正难的不是打印一行 json，而是统一回答：

哪些入口和调用需要观察；
每条日志有哪些稳定字段；
大对象输出到什么程度；
哪些字段必须忽略或脱敏；
失败、短路和序列化异常如何降级；
日志耗时代表同步方法，还是异步任务最终结果。

metalite 用 aspecttypeenum、aspecthandlerchain、baseaspectlogger、printcontrol 和 aspectlogproperties 把这些决策集中到工程基座中。业务代码因此少写日志模板，团队也获得了一套可以统一审计和演进的规则。

以上就是spring aop接口日志统一的解决方案的详细内容，更多关于spring aop接口日志统一的资料请关注代码网其它相关文章！