Java学习随笔：一次请求的日志该留下哪些线索（2026-10-20）

学习 Java 服务开发时，我很容易把注意力放在接口能否返回正确结果上。可是只要把场景换成多个请求同时执行，再加上一次偶发超时，单看返回值就很难还原过程。今天整理的这个小问题是：一次请求结束以后，日志究竟应该留下哪些线索，才能让后来的排查有依据。

可以先想象一个订单查询接口。请求进来了，服务检查参数，读取本地数据，再向另一个服务查询补充信息，最后拼出结果。如果日志只有“开始查询”和“查询失败”，即使每条日志都有时间，也不知道失败发生在哪个订单、哪个环节，以及调用方最终收到了什么结果。记录了动作名称，却没有记录动作所在的业务现场，这样的日志很容易变成没有上下文的碎片。

我认为首先要区分请求标识和业务标识。请求标识用来串起一次调用，业务标识用来说明这次调用处理的对象。同一个订单可能先后被查询很多次，也可能因为调用方重试而在很短时间内收到两次请求。如果只有订单号，就容易把不同调用的过程混在一起；如果只有请求标识，又要额外查找它对应的业务对象。把两种标识的职责分清楚，比单纯增加日志数量更有帮助。

接下来需要记录有意义的状态变化。参数校验通过、外部调用返回、结果组装完成，这些阶段可能对应不同的故障原因，但不代表每一个方法入口都应该打印一行。对于一个普通查询，可以在入口留下必要的关联信息，在重要分支留下决策依据，在出口留下结果类型与耗时。这样阅读日志时，就能知道请求从哪里进入、走了哪条路径、最后停在哪里。日志的位置应该由排查问题的需要决定，而不是机械地跟着方法数量增长。

失败信息也需要说清楚边界。假设向下游查询时发生超时，日志可以表达“补充信息查询超时”，并保留异常堆栈和关联标识。如果上层每经过一个方法都把同一个异常再打印一次，就会出现很多看似独立、实际上来自同一次故障的错误记录。更清楚的做法是约定由哪个边界负责记录完整异常，其他层只补充确实有价值的信息。业务上允许的无结果，也应该和系统无法完成查询的失败区分开，避免让正常分支淹没真正需要关注的错误。

耗时同样需要一个明确的口径。接口总耗时和外部调用耗时回答的是两个问题：前者说明调用方等待了多久，后者帮助缩小慢在哪里。记录耗时之前，应该先确定计时从哪里开始，到哪里结束，是否包含排队和重试。比较两段日志的时间戳只能提供线索，不能自动证明某个方法就是瓶颈。只有让字段含义稳定，后续的比较和统计才有意义。

Java 服务里还经常会遇到异步任务。请求线程把工作交给线程池以后，不能想当然地认为原来的日志上下文会自动跟过去。需要明确哪些关联信息要随任务传递，以及任务结束后如何清理。如果借助与线程关联的上下文机制，更要考虑线程会被复用：上一个任务残留的信息可能让下一个任务的日志带上错误标识。即使还没有引入复杂的链路工具，也可以先把传递和清理的责任设计清楚。

记录现场时，也不能把整个请求对象原样输出当成省事办法。密码、令牌和不必要的个人信息不应进入日志；体积很大的字段会增加存储和检索负担，也可能遮住真正有用的内容。对来自外部的文本，还应限制长度并处理换行等字符，避免一条输入被展示成多条日志。保留能够定位问题的最少信息，通常比事无巨细地复制数据更可靠。

最后可以用一个小练习检查设计：准备一次成功查询、一次参数错误和一次下游超时，只阅读它们留下的日志，尝试回答每次请求处理了什么、经历了哪些关键步骤、结果是什么，以及下一步应查哪里。如果这些问题仍然答不出来，就继续调整字段和记录位置。今天的体会是，日志也是接口设计的一部分，它面向的是事后理解系统的人。把业务上下文讲清楚，代码在运行之后才仍然有机会被读懂。