HTTP请求/响应日志记录最佳实践：字段设计、脱敏采样与可观测性

做后端这些年，我最大的感受就是：真正难搞的从来不是功能开发，而是线上出了问题时，手里只有一句“请求失败了”，没有请求报文、没有参数快照、没有响应详情，全靠用户截图和客服转述去还原现场，那个过程特别煎熬。后来我养成了一个习惯，把 HTTP 请求/响应数据当作系统的一等公民来对待，从“临时打印几行日志”正式升级成一套有设计、有节制的记录方案。

这篇文章不是某个日志库的说明书，而是我在多个技术栈、多种方案里沉淀下来的完整思路：在什么位置记录、记录哪些字段、怎么脱敏、怎么限流采样、怎么把日志变成可观测性数据。适合正在搭建 API 服务和维护平台的开发者，也适合被联调问题折磨得想亲手给服务“装上黑匣子”的团队新人。

1. 先想清楚：记录 HTTP 请求/响应到底是为了什么

1.1 我们记录的数据，每一类都有明确用途

很多项目一开始就是“为了记录而记录”，不分青红皂白全部打日志，最后日志又乱又大，真正要查的时候反而没法用。所以要先把目标定下来：这套日志是给谁看的，解决什么问题？

以我自己的经验，核心用途就三类。第一类是故障重建，接口报错时，我要能知道是哪个用户、带的什么参数、经过哪条链路、返回了什么错误，这需要完整的请求快照。第二类是安全审计，比如涉及支付、改密、登录的接口，谁在什么时间干了什么，不能等出事之后才抓瞎。第三类是性能分析，状态码分布、耗时变化、哪个上游节点慢，都要能从记录里统计出来。

带着这些目标去选字段，思路会清晰很多。我最终固定下来一套字段模板：

这中间最关键的一点：不要把什么都存。健康检查、静态资源、探活请求，记录了纯粹是浪费磁盘；反而是登录、下单、支付这类核心链路，哪怕压力再大也要保证。记录策略必须能按路径、按接口分组灵活调整，这是后面所有设计的前提。

1.2 “优雅”的标准，不是功能多，而是可控

我自己衡量一套 HTTP 记录方案是不是优雅，就看三个词：低侵入、可配置、可检索。

低侵入的意思是，业务代码里不应该到处埋点。我见过有人每个 Controller 方法里都复制一段日志代码，最后接口改了日志忘了删，输出格式五花八门，这绝对不是优雅。记录逻辑应该收敛在统一的中间件、过滤器或网关层，业务开发不需要关心。可配置是说要能按环境调级别：本地开发只看摘要，压测环境全量采样，生产环境按接口设置比例，这些都应该在配置里完成，而不是改代码重启。可检索则是说日志不能只是给人眼看的，还要能被日志平台快速查出来，所以结构化字段比大段文本重要得多。

一句话总结：真正的优雅，是当你半夜被叫起来排查故障时，这套系统能三分钟内把你需要的信息完整、准确、安全地交到你手里。

2. 记录放在哪一层：三种主流方案怎么选

2.1 应用层方案：中间件与过滤器拦截

应用层拦截是最直接的做法，也是大多数后端项目的第一选择。它的优势在于能拿到业务上下文：登录态、用户 ID、业务单号、具体异常堆栈，这些信息网关层根本不知道。

以 Java Spring Boot 为例，最常用的是 OncePerRequestFilter，配合 ContentCachingRequestWrapper 和 ContentCachingResponseWrapper 缓存请求和响应内容：

java复制@Component
public class LoggingFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        long start = System.nanoTime();
        String reqId = request.getHeader("X-Request-Id");
        if (reqId == null || reqId.isBlank()) {
            reqId = UUID.randomUUID().toString().replace("-", "");
        }

        ContentCachingRequestWrapper requestWrapper =
                new ContentCachingRequestWrapper(request, 1024 * 1024);
        ContentCachingResponseWrapper responseWrapper =
                new ContentCachingResponseWrapper(response);

        try {
            chain.doFilter(requestWrapper, responseWrapper);
        } finally {
            long costMs = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);
            byte[] requestBody = requestWrapper.getContentAsByteArray();
            byte[] responseBody = responseWrapper.getContentAsByteArray();
            // 在这里统一输出结构化日志，后续会讲脱敏、截断
            logRequest(responseWrapper, requestBody, responseBody, costMs, reqId);
            responseWrapper.copyBodyToResponse();
        }
    }
}

这段代码里有个极其重要的细节：读取请求体必须在 chain.doFilter 之后，因为 ContentCachingRequestWrapper 是在 Controller 真正读取输入流时才把内容缓存下来的。很多新手在 doFilter 前面直接调用 getContentAsByteArray()，拿到的一直是空数组，这就是典型的读取时机错误，后面第 5 章我会专门讲。

Node.js 生态里，Express 的中间件模型做这件事几乎是零成本，只需要注意注册顺序必须放在业务路由之前，并且要在 body-parser 之后，否则拿不到 req.body：

javascript复制app.use((req, res, next) => {
  const start = Date.now();
  const reqId = req.headers['x-request-id'] ?? randomUUID();
  res.setHeader('X-Request-Id', reqId);

  res.on('finish', () => {
    const entry = {
      reqId,
      method: req.method,
      url: req.originalUrl,
      status: res.statusCode,
      costMs: Date.now() - start,
      query: sanitize(req.query),
      body: sanitize(req.body),   // 前提：已经挂了 bodyParser
    };
    logger.info(entry);
  });

  next();
});

这里我刻意没有记录响应体。原因后面会细说，但先给结论：在 Node 里要拿到响应体必须包装 res.end，这会引入额外的内存拷贝和复杂度，而绝大多数排查场景中，响应状态码加耗时已经能定位 90% 的问题。

Python FastAPI 同样可以在中间件里统一处理。需要注意的是 Starlette 的 Request.body() 自带缓存，调用一次之后后续路由依然能正常读取，所以可以在中间件里放心读取：

python复制@app.middleware("http")
async def logging_middleware(request: Request, call_next):
    start = time.perf_counter()
    body_bytes = await request.body()
    response = await call_next(request)
    cost_ms = (time.perf_counter() - start) * 1000

    logger.info({
        "req_id": request.headers.get("x-request-id") or uuid4().hex,
        "method": request.method,
        "path": request.url.path,
        "query": sanitize_obj(request.query_params),
        "request_body_preview": body_bytes[:1024].decode("utf-8", errors="replace"),
        "status": response.status_code,
        "cost_ms": round(cost_ms, 3),
    })
    return response

这三段代码虽然语言不同，思路完全一致：用一个全局中间件统一收口，业务代码保持干净，记录动作和业务逻辑彻底解耦。

2.2 网关层方案：Nginx 访问日志与 API 网关

如果服务已经上了 Nginx 或 API 网关，网关层记录是最省事、最不侵入的方案。Nginx 的 access_log 可以自定义格式，把关键字段打出来：

nginx复制log_format trace '$remote_addr [$time_local] "$request" '
                '$status $body_bytes_sent "$http_user_agent" '
                'req_id=$http_x_request_id '
                'upstream=$upstream_addr '
                'request_time=$request_time '
                'upstream_response_time=$upstream_response_time';

access_log /var/log/nginx/api.access.log trace buffer=32k flush=5s;

request_time 是整个请求从 Nginx 接收到响应结束的总耗时，upstream_response_time 才是后端服务真正处理的时间。这两个字段同时记录，能直接判断时间消耗在网络传输还是后端业务。

更现代的方案是使用 OpenResty 的 Lua 脚本，或者 APISIX、Kong 这类网关的日志插件。它们可以把请求体和响应体都缓存下来，打成 JSON 发送到 Kafka 或 ES，功能比 Nginx 的 access_log 强大得多。我自己在规模较大的系统里，网关层的价值主要是“广覆盖”，所有流量都能记录，不依赖业务团队是否配合。

2.3 应用层和网关层怎么分工

有人会觉得既然网关层能记录，应用层就不用做了。这个想法要分情况看。

网关层做的是“流量视角”，它能看到哪个客户端、什么时间、打到哪个上游，但它看不到业务语义。比如网关只知道用户请求了 /v1/orders，不知道这个用户对应的订单号是什么、是不是被限流的对象。反过来，应用层完全掌握业务上下文，但数据链路长，如果服务实例特别多，日志分散在各个机器上，采集成本就上去了。

我的实践结论是：网关层做基础流量记录，负责状态码、耗时、来源 IP、节点分布；应用层做深入诊断记录，负责请求体、响应体、用户身份和业务异常。两层用同一个 X-Request-Id 关联，既不会日志爆炸，排查时又能从外到内逐层深入。

3. 真正干活时会踩的五个细节坑

3.1 请求体只能读一次，怎么解决

HTTP 请求体本质是一个 InputStream，读到底就没了，就像磁带播到头不能再从开头重放。中间件先读一次，Controller 再读就得到一个空流，这是实现日志功能碰到的第一个拦路虎。

解决办法就是“包装”：把原请求包进一个能缓存内容的包装器里。Java 里用 ContentCachingRequestWrapper，它内部用字节缓冲记录 getInputStream 读过的内容，Controller 读的时候日志系统悄悄“偷看”一份。Python 里 Starlette 的 Request.body() 自带缓存，读一次后存进内存，后续访问直接返回缓存。Node 里则是依赖 body-parser 先解析，之后从 req.body 拿对象，不走流。

这里要注意一个权衡：缓存请求体意味着把整个 body 都放进内存。如果一个接口允许上传几十 MB 的文件，缓存就会带来内存压力。所以我的建议是：大文件上传接口直接不记录 body，只记录文件大小；普通 JSON 接口设置缓存上限，超过阈值就放弃记录。ContentCachingRequestWrapper 的构造函数第二个参数就是缓存上限，上面代码里我写的是 1MB，你可以按业务压测结果调整。

3.2 敏感字段必须脱敏

这是所有方案里最不能省的一环。请求头里的 Authorization、Cookie，请求体里的 password、idCard、mobile，一旦明文落进日志，轻则不合规，重则直接成为安全事故。

脱敏要用递归方式处理嵌套结构，不能只匹配顶层 key。比如 JSON body 里的 {"user": {"mobile": "13800000000"}}，只看第一层是发现不了的。这是我常用的一版 Python 脱敏函数：

python复制SENSITIVE_KEYS = {"password", "token", "authorization",
                  "cookie", "id_card", "mobile", "bank_card"}

def mask(data):
    if isinstance(data, dict):
        return {
            k: ("***" if k.lower() in SENSITIVE_KEYS else mask(v))
            for k, v in data.items()
        }
    if isinstance(data, list):
        return [mask(i) for i in data]
    return data

注意几个细节。第一，字段名大小写不敏感，统一转小写再匹配，否则 Password 和 password 会漏一个。第二，脱敏不能放在业务代码里，要放在日志输出的统一出口，在中间件里做好，后续任何人打印日志都默认安全。第三，URL 查询参数里也可能带敏感信息，比如 ?token=xxx，对 query string 同样要过一遍脱敏。

3.3 全量记录会害死你：截断与采样

全量记录是所有方案的终极大坑，尤其是响应体。一个导出接口返回 10MB JSON，如果原样打进日志，不说内存和磁盘，日志平台先疯了。

我习惯的做法是给记录管道加两道闸门。第一道是截断：请求体超过 1KB 只记录前 1KB，响应体超过 4KB 只在日志里记录大小和前三 KB 的摘要。大多数排查场景中，1KB 的请求体和 4KB 的响应体足够看清问题。第二道是采样：对低频核心接口全量记录，对高频普通接口按 1/10 或 1/100 采样，对日志系统自身的健康检查接口直接不记录。采样不是简单的“省日志”，它实际上是用极小的成本保留了统计意义上的样本，状态码分布、平均耗时照样能算出来。

还有一个容易忽视的点：记录时机的选择。请求进来先记录一条，响应结束后再记录一条，还是只记录一条完整记录？我推荐后者。两条记录中间如果业务处理耗时很长，会产生大量“只见请求不见响应”的中间态日志，不仅增加磁盘量，排查时反而干扰。一条记录里同时放请求和响应的快照，信息最完整。

3.4 日志系统不能拖垮业务：性能控制

记录日志本身是 IO 操作，处理不当会对业务产生不可忽视的延迟。最直观的例子：如果直接用 System.out 或同步写文件，日志量稍大就会拖慢接口响应。

正确姿势是让日志异步化。Java 里可以用 Logback/Log4j2 的 AsyncAppender，把写盘操作塞进独立线程；Python 里可以用 QueueHandler 加一个后台线程消费；Node 里像 pino 这类库本身就支持异步。异步的思路是相通的：业务线程只负责把日志放进内存队列，写盘由专门的线程批量处理。

但异步也不能盲目用，要处理队列积压。一旦日志生产速度快于消费速度，内存队列会无限膨胀，最终把应用 OOM。常规做法是给队列设置容量上限和拒绝策略：队列满了就丢弃日志并记录丢弃次数，宁可少几条日志也不能让业务线程卡死。性能问题的底线很清楚：日志系统是服务的一部分，不是服务的负担。

3.5 异步线程里，别把 traceId 弄丢了

用 ThreadLocal 存 traceId 是 Java 里的常见做法，但它有个致命问题：线程池里新开的线程拿不到主线程的 ThreadLocal 值，导致异步代码里打出来的日志全部没有 traceId。

Java 里推荐用 TransmittableThreadLocal，它能在创建线程或提交任务时把主线程的上下文自动拷贝过去。Node.js 对应的是 AsyncLocalStorage，它专门解决异步上下文传递问题，async/await 随便用，上下文不会丢。Python 里用 contextvars，在中间件里 ContextVar.set()，异步任务中 ContextVar.get() 照样能取到。

判断 traceId 有没有丢，方法很简单：找一个纯异步链路打一条日志，看日志平台里这条日志的 traceId 是否和出口日志一致。不一致就说明上传下传没有打通，排查链路时会被活活害死。

4. 从“打日志”升级到“可观测性”

4.1 结构化日志：别再用字符串拼大文本

我见过最多的反面写法，就是 ${method} ${url} ${status} ${cost} 这种拼接式字符串日志。短时间看没问题，一旦要用日志平台查询就完蛋了，你想按状态码过滤都无处下手，只能苦哈哈地写正则。

结构化日志的核心是让每条日志成为一组 key-value 字段。我常用的输出模板是这样一份 JSON：

json复制{
  "ts": "2025-01-15T14:32:11.782Z",
  "level": "INFO",
  "req_id": "a3f2c1d9e4",
  "method": "POST",
  "path": "/v1/orders",
  "query": {"source": "app"},
  "status": 201,
  "cost_ms": 23.4,
  "client_ip": "10.0.3.12",
  "user_id": "u_10086",
  "request_size": 456,
  "response_size": 312,
  "request_body": "{\"sku\":\"A001\",\"qty\":2}",
  "response_body": "{\"orderId\":\"o_20250115\"}"
}

这份 JSON 的每一层字段都有检索价值。req_id 用来把日志和链路追踪系统关联，status 和 cost_ms 用来聚合统计，path 用来按接口维度分析。在实际落地时，我建议日志库直接支持 JSON 序列化，而不是手拼字符串。手拼会撞上两个坑：字段值里如果带了引号或换行，整个 JSON 就碎掉了；嵌套对象序列化时漏掉一层，查询时又搜不到。

4.2 traceId：把一次请求串成一条线

单条日志再完整，也只是一张照片；traceId 的存在，是把一次链路的所有照片串成一部电影。不管是网关、应用、数据库客户端还是下游服务，只要大家约定好往日志里带同一个 traceId，整个请求就是一条可追溯的线。

实现上分三步。第一步：在入口处获取外部传入的 X-Request-Id，没有就自己生成 32 位随机串；第二步：把这个值塞进当前请求上下文的日志框架里，后续所有日志自动带上；第三步：把同一个值写进响应头，这样前端和用户反馈问题时可以直接提供一串 ID，后端拿 ID 一搜就能定位整条链路。这一步做下来，再把日志采集到 ELK 或 Loki，debug 体验跟开了天眼没区别。

4.3 状态码、耗时与连接复用：这些指标比日志更早报警

日志是“事后查案”，指标是“事中报警”。同一个中间件里，顺手把请求状态和耗时同步上报到 Prometheus，比单纯记录日志多一层价值。核心的指标就是三个维度：按状态码统计的请求量、按路径统计的耗时分布、按上游节点统计的错误率。http 状态码的分类也很直接，2xx 是正常，4xx 是客户端问题，5xx 是服务端问题，看分布就能知道该从哪里下手。

这里有一个非常容易误判的场景：当你发现接口平均耗时突然升高，先别急着怀疑业务代码变慢，检查一下 HTTP 连接复用是不是失效了。如果客户端每次请求都重新建 TCP 连接、重做 TLS 握手，这部分开销不会显示在业务日志的耗时里，但会体现在服务的连接数和整体响应时间上。记录日志时顺手记上 upstream_response_time 和 request_time，就能把网络层和后端耗时分离，快速定位瓶颈在链路哪一段。

5. 线上真实问题：记录日志本身也会翻车

5.1 请求体记录为空的经典场景

这是所有第一次写 Spring 请求日志的人都会遇到的。原因前面提过：ContentCachingRequestWrapper 的缓存是边读边写，在 chain.doFilter 之前 Controller 还没有读取请求体，缓存里自然什么都没有。我当时踩这个坑的时候，排查了两个小时，把代码翻来覆去看了半天，最后才意识到是读取时机的问题。

解法只有一句话：请求体必须在 chain.doFilter 之后读取。响应体同理，也必须等业务写完响应之后再拿。如果响应体是通过 copyBodyToResponse() 交还的，还要注意不要漏了这一步，否则客户端会收到一个空响应。

5.2 压缩响应乱码

记录响应体时，如果服务开了 gzip 压缩，拿到的是压缩后的二进制字节，直接转字符串就是一堆乱码。处理方式是根据响应头的 Content-Encoding 判断：如果是 gzip，先解压再摘要；如果是 br 压缩，用对应的解压算法。压缩后的二进制还有一个特点，没法按字符串长度截断，必须解压之后再截断，否则会把一个字符拦腰截成两半，产生非法字符。

更省事的办法是：只记录 Content-Length 和压缩类型，不记录实际 body。响应体的价值本就不如请求体高，配合状态码和耗时，绝大多数问题已经足够定位。

5.3 日志磁盘被打满

有一次我排查线上问题，发现服务挂了一个多小时没响应，查明原因是日志文件把磁盘写满了。那天的流量是平时的几十倍，全量记录响应体加上同步写日志，直接拖垮了整台机器。从那以后我定了三条规矩：第一，所有 body 记录必须走截断逻辑；第二，全流程日志比例必须在配置里显式控制，不允许默认 100% 记录；第三，日志文件必须配滚动策略，按天切分、按大小压缩、老日志定期清理。磁盘便宜，但服务不可用很贵。

这个惨痛教训的后续是，我要求所有服务的日志配置里必须加磁盘空间告警，日志目录使用率超过 80% 就要通知到人。记录系统本身也是被监控的对象，这句话不是开玩笑的。

5.4 问题速查表

把我在线上踩过的和帮别人排查过的典型问题整理成一张表，方便对照排查：

这套表格背后的排查思路是：先确认记录动作本身没有副作用，再看字段是否完整和正确。日志系统一旦出错，往往比业务问题更隐蔽，因为它不会让服务报警，只会安静地让排查变得更艰难。所以上线 HTTP 请求日志功能之后，我通常会在测试环境特意制造几次异常请求，翻翻生成的日志确认字段、脱敏、截断都符合预期，再放到生产环境。

我个人在实际操作中体会最深的一点是：记录 HTTP 请求/响应数据这件事，平时看起来不产生任何业务价值，但它是所有系统里最值得提前投资的基础设施。等到线上真正出问题的那一刻，它的价值就完全体现出来了：你能对着结构化日志在几分钟内还原现场，而不是卑微地靠用户截图去猜。所谓“优雅”，也从来不是代码写得多么花哨，而是这套记录系统在你最需要它的时候，能够准确、完整、安全地出现在你面前。