当前位置：首页 > news >正文

日志系统的设计：从 console.log 到结构化日志

news 2026/7/18 22:25:06

日志系统的设计：从 console.log 到结构化日志

一、console.log 在什么时候不够用

开发阶段,console.log是最直接的调试工具。打印请求参数、输出中间结果,在本地跑一下就知道发生了什么。这个习惯在部署到生产环境后,往往延续下来——生产代码里依然充斥着console.log('用户登录:', userId)。

console.log在生产环境中不够用的原因:

日志没有上下文。你不知道这条日志是哪个请求产生的、来自哪个用户、发生在哪个页面上。在多用户并发的服务器上,日志是交错输出的,无法区分哪些日志属于同一个请求。
日志无法搜索和聚合。当你的日志每天产生几万行,console.log的输出只是一串原始文本,无法按「错误类型」「端点名称」「用户 ID」来做聚合统计。
日志无序,无法还原请求链路。一个请求可能经过多个中间件、调用了多次 AI API,console.log无法把这些分散的日志串联起来。

graph TD A[应用代码] --> B[日志输出] B --> C{输出方式} C -->|console.log| D[原始文本<br/>无结构化<br/>无搜索能力<br/>无法聚合] C -->|结构化日志| E[JSON 格式<br/>按字段搜索<br/>按维度聚合<br/>请求链路追踪] D --> F[排查问题:<br/>grep 手动查找<br/>效率低] E --> G[排查问题:<br/>query+过滤器<br/>快速定位] style D fill:#ffcdd2 style E fill:#c8e6c9

二、结构化日志的核心要素

结构化日志的本质:将每一条日志从「一段文本」变成「一个包含多个字段的 JSON 对象」。每条日志至少包含以下字段:

timestamp:日志产生的时间(ISO 8601 格式)。
level:日志级别(info/warn/error/debug)。
message:日志的简要描述(人类可读的摘要)。
requestId:请求的唯一标识(用于关联同一请求的所有日志)。
userId:当前用户 ID(如果已登录)。
endpoint:当前请求的端点或功能名称。
duration:操作耗时(如 API 调用耗时)。

graph TD A[请求进入] --> B[生成 requestId] B --> C[中间件: 日志记录<br/>info: 请求开始<br/>method/URL/IP] C --> D[业务逻辑] D --> E[数据库查询<br/>info: 查询耗时/duration] D --> F[AI API 调用<br/>info: Token/延迟/模型] D --> G[文件操作<br/>debug: 文件路径/大小] E --> H[中间件: 日志记录<br/>info: 请求完成<br/>statusCode/duration] F --> H G --> H H --> I[所有日志<br/>共享 requestId] style B fill:#e3f2fd style I fill:#c8e6c9

三、日志级别的使用规范

结构化日志中,日志级别不是随意的,需要有明确的规范:

error:发生了需要立即关注的问题。如 API 调用失败、数据库连接丢失、支付处理异常。error 级别的日志应该触发告警(如邮件、Slack 通知)。
warn:发生了潜在的问题,但不影响当前功能。如调用重试成功(第一次失败了但重试后成功)、用户输入不合法(被校验拒绝)、缓存即将过期。warn 级日志在定期审查时需要关注。
info:正常业务流程的关键节点。如用户登录、订单创建、API 调用成功、部署完成。info 级日志用于构建业务流程的可追溯性。
debug:开发和调试信息(生产环境通常关闭)。如函数的参数和返回值、中间计算结果、缓存命中状态。

console.log最大的问题是所有输出都「同等级别」——无法区分「需要立即处理的错误」和「只是记录一下的正常信息」。使用结构化日志的级别,能在日志量大时快速聚焦到重要信息。