Go http.Server ErrorLog 怎样接入结构化日志

想把 Go HTTP 服务的标准错误接入统一日志系统时，直接给 http.Server.ErrorLog 一个自定义 *log.Logger 即可。关键是：ErrorLog 接收的是连接接收错误、Handler 异常和底层文件系统错误等服务端错误，不是每个请求的访问日志；因此应通过一个并发安全的 io.Writer 适配器，把标准库格式化消息包装成 JSON 行。

官方文档：https://pkg.go.dev/net/http#Server

下面的示例只说明接口关系和接入边界，不把未执行的代码输出描述为本机运行结果。

先确定 ErrorLog 的职责边界

官方定义中，Server.ErrorLog 的类型是 *log.Logger。它用于记录接受连接失败、Handler 的意外行为以及底层 FileSystem 错误；如果设为 nil，则回退到 log 包的标准 logger。这个范围决定了它适合接入“服务端错误”通道，而不适合代替访问日志中间件。

ConnState 是另一个独立回调，关注连接状态变化；请求路径、状态码、耗时等访问字段仍应在 Handler 或中间件层采集。先分开这两个职责，后续的 JSON 字段才不会混成一条含义不清的日志。

用 Writer 适配器输出 JSON 行

log.Logger 会把格式化后的文本写入一个 io.Writer。因此，适配现有结构化日志时不需要改动 net/http，只需实现 Writer：接收一条完整文本、去掉末尾换行、放进固定字段，再由 json.Encoder 输出一行 JSON。

package main

import (
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
    "strings"
    "sync"
)

// jsonLineWriter 把 log.Logger 的文本消息转换为一行 JSON。
type jsonLineWriter struct {
    mu sync.Mutex // 多个服务端 goroutine 可能同时写入，必须保护一条 JSON 行的完整性。
    dst io.Writer // 真实项目中可以替换成文件、管道或日志代理的输入流。
}

func (w *jsonLineWriter) Write(p []byte) (int, error) {
    // log.Logger 通常会附带换行；去掉它，避免 message 字段包含无意义的尾部空白。
    message := strings.TrimRight(string(p), "\r\n")
    record := struct {
        Level   string `json:"level"`
        Source  string `json:"source"`
        Message string `json:"message"`
    }{
        Level: "error", Source: "net/http", Message: message,
    }

    w.mu.Lock()
    defer w.mu.Unlock() // 无论编码是否成功，都要释放互斥锁。
    if err := json.NewEncoder(w.dst).Encode(record); err != nil {
        // 返回写入错误，让 log.Logger 按其约定处理，而不是静默丢日志。
        return 0, err
    }
    return len(p), nil
}

func main() {
    writer := &jsonLineWriter{dst: os.Stderr}
    serverLogger := log.New(writer, "", 0) // 前缀和时间交给 JSON 字段，避免重复文本。
    server := &http.Server{
        Addr:     ":8080",
        ErrorLog: serverLogger,
    }
    _ = server // 这里只展示配置关系；生产代码继续设置 Handler 并启动服务。
}

这段代码的重点不是“把所有日志都变成 JSON”，而是给 ErrorLog 一个满足 *log.Logger 要求的出口。若已有日志库提供安全的 Writer 或字段编码器，优先复用它；不要在 Write 中按空格拆分消息，以免错误文本中的空格、引号和换行破坏字段含义。

并发写入和字段设计要先定下来

HTTP 服务会并发处理连接，多个错误可能同时到达同一个 Writer。若 Writer 直接交替写入共享缓冲区，JSON 行可能互相穿插；示例中的互斥锁只保护“编码并写出”这一小段，不应把网络请求处理或慢速远端发送放进锁里。

字段建议保持稳定：level 表示错误级别，source 表示来源包，message 保存标准库原始消息。若要增加服务名、环境或实例标识，可以在外层日志管道补充；不要从错误文本中猜测请求 ID。原始消息可能很长或含换行，生产实现应增加长度上限和脱敏策略，但不能通过截断破坏 JSON 编码。

兼容策略：ErrorLog 不是访问日志钩子

接入后仍要保留三条边界：

• 服务端错误：交给 Server.ErrorLog，统一输出错误级别和来源。
• 请求访问记录：在 Handler 或中间件采集方法、路径、状态码和耗时，不要等待 ErrorLog 回调。
• 连接生命周期：需要观察连接状态时使用 Server.ConnState，不要把连接状态变化伪装成错误。

最后按四项检查接入结果：Writer 是否始终返回正确的字节数或真实错误；并发写入是否保持一条 JSON 一行；ErrorLog 是否只负责服务端错误；以及日志出口失败时是否有明确的降级策略。这样既保留了 net/http 的默认错误语义，也能让日志平台稳定解析。

把 ErrorLog 设成 nil 会怎样？

服务器会使用 log 包的标准 logger。需要统一格式或统一出口时，才创建自定义 *log.Logger 注入。

ErrorLog 能记录每个请求的状态码吗？

不能把它当作访问日志钩子。状态码、耗时和请求路径应在 Handler 或中间件层显式记录。

为什么不直接让 ErrorLog 接收 JSON 字符串？

因为字段类型固定为 *log.Logger。使用 Writer 适配器可以保留标准库的 logger 约定，并在单一出口完成 JSON 编码和并发控制。