结构化日志Mock测试与依赖隔离数据传输优化方案 - 第2节

2.1 什么是结构化日志

结构化日志（Structured Logging）是指将日志记录为具有预定义字段和类型的键值对集合，而非传统的纯文本字符串。每条日志都是一个独立的数据对象，可以被程序化地解析、查询和分析。

一个典型的结构化日志条目通常包含以下字段：

常见的序列化格式包括 JSON、Logfmt 和 Avro。在微服务和云原生架构中，JSON 是最广泛使用的格式。

// 结构化日志示例（JSON 格式）
{
  "timestamp": "2025-03-21T14:32:10.123Z",
  "level": "WARN",
  "logger": "com.payment.gateway",
  "message": "第三方支付接口响应超时，触发重试",
  "paymentId": "PAY-20250321-9921",
  "retryCount": 2,
  "timeoutMs": 5000,
  "traceId": "ab3f8c91e2d4"
}

2.2 结构化日志 vs 普通日志

普通日志（非结构化日志）通常使用字符串拼接或格式化输出，日志内容混杂在一起，难以被自动化工具解析。

2.3 日志级别最佳实践

日志级别定义了日志的严重程度和关注优先级。标准级别从低到高依次为：DEBUG → INFO → WARN → ERROR。

2.3.1 级别定义与使用场景

2.3.2 级别使用原则

• DEBUG 不进入生产： 生产环境默认关闭 DEBUG 级别，避免海量日志冲击磁盘和监控系统。仅在线上排查问题时临时开启，且需设置采样率。
• INFO 记录边界： 每个请求/事务只记录开始和结束，不记录中间每一步。避免在循环中打印 INFO。
• WARN 可恢复： 系统能自动恢复或降级处理的情况使用 WARN，不应触发告警电话，但需纳入日报分析。
• ERROR 必须处理： 每条 ERROR 日志都代表一次功能受损或数据风险，必须关联明确的错误码和上下文，并触发告警。

2.4 结构化日志的典型架构

下图展示了一个微服务中结构化日志从产生到消费的完整链路：

2.5 代码示例：Java 中使用 SLF4J + Logback 输出结构化日志

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import net.logstash.logback.argument.StructuredArguments;

public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    public void createOrder(String userId, String orderId, BigDecimal amount) {
        log.info("订单创建成功",
            StructuredArguments.keyValue("userId", userId),
            StructuredArguments.keyValue("orderId", orderId),
            StructuredArguments.keyValue("amount", amount),
            StructuredArguments.keyValue("status", "CREATED")
        );
    }

    public void handlePaymentTimeout(String paymentId, int retryCount) {
        log.warn("支付接口超时，触发重试",
            StructuredArguments.keyValue("paymentId", paymentId),
            StructuredArguments.keyValue("retryCount", retryCount),
            StructuredArguments.keyValue("timeoutMs", 5000)
        );
    }

    public void processError(String orderId, Exception e) {
        log.error("订单处理异常",
            StructuredArguments.keyValue("orderId", orderId),
            StructuredArguments.keyValue("errorType", e.getClass().getSimpleName()),
            e  // 异常对象自动展开为 stack_trace 字段
        );
    }
}