Golang请求错误处理与日志记录技巧

在Go中处理网络请求错误并记录日志，需结合error接口、自定义错误类型、结构化日志和上下文传递。首先，每次调用如client.Do()或resp.Body.Close()后应立即检查err != nil，区分网络错误（如超时、连接拒绝）、HTTP状态码错误（4xx/5xx）及解析错误。使用fmt.Errorf("%w", err)包装错误以保留原始错误链，便于后续通过errors.Is或errors.As判断错误类型。定义自定义错误类型（如NetworkError）可携带StatusCode、IsTimeout等字段，提升错误的可编程性。结合zap等结构化日志库，在日志中记录request_id、url、method、status_code、error message等关键信息，增强可观测性。通过context.Context传递唯一请求ID，实现跨服务调用的日志追踪。对于重试与熔断，可在检测到临时性错误（如5xx、超时）时启用指数退避重试机制，并集成如go-resilience等库实现熔断，防止雪崩效应。最终构建高韧性、易调试的网络请求系统。

在Golang中处理网络请求错误并记录日志，核心在于利用Go语言的error接口进行错误传递和判断，同时结合结构化日志库来捕获和呈现关键信息。这不仅仅是代码层面的逻辑，更是一种系统健壮性和可观测性的设计哲学。

处理Golang网络请求错误并记录日志，本质上是围绕Go的error接口和选择合适的日志库展开。我们需要清晰地捕获错误类型、来源，并以易于分析的方式记录下来，确保系统在面对外部依赖不稳定时依然能够提供有价值的反馈。这不仅仅是“捕获异常”那么简单，它关乎整个系统的韧性和可调试性。

解决方案

在Go语言中，网络请求的错误处理通常围绕着net/http包的客户端操作展开。当调用client.Do()或resp.Body.Close()等方法时，可能会返回一个非nil的error。我们的策略是：

1. 立即检查错误：每次可能产生错误的操作后，都应该紧跟if err != nil进行判断。这是Go的惯用法。
2. 区分错误类型：
   • 网络连接错误：如超时、DNS解析失败、连接被拒绝等，通常是net.Error类型。可以通过errors.As或errors.Is来检查。
   • HTTP协议错误：响应状态码（如4xx, 5xx）本身不是error，但我们需要将其视为业务错误或服务器端错误进行处理。
   • 响应体读取/解析错误：在读取resp.Body或解析JSON/XML时可能发生。
3. 错误包装与传递：使用fmt.Errorf("...: %w", err)来包装原始错误，添加上下文信息，并向上层传递。这保留了原始错误链，方便后续调试。
4. 结构化日志记录：使用如zap或logrus这类结构化日志库，而非Go标准库的log。在记录错误时，附带尽可能多的上下文信息，例如：
   • 请求的URL、方法、头部（敏感信息需脱敏）。
   • 请求体（如果合适且不包含敏感数据）。
   • 响应状态码、响应体（部分）。
   • 错误类型、错误消息、堆栈信息。
   • 一个唯一的请求ID（trace ID），用于关联请求的整个生命周期。
5. 日志级别：根据错误类型和严重程度，使用不同的日志级别。例如，网络连接中断可能记录为ERROR，而一个404响应可能只是WARN或INFO（取决于业务逻辑）。

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"

    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

// CustomError 示例自定义错误类型
type CustomError struct {
    Code    int
    Message string
    Op      string // 操作名
    Err     error  // 包装的原始错误
}

func (e *CustomError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("operation %s failed with code %d: %s, original error: %v", e.Op, e.Code, e.Message, e.Err)
    }
    return fmt.Sprintf("operation %s failed with code %d: %s", e.Op, e.Code, e.Message)
}

func (e *CustomError) Unwrap() error {
    return e.Err
}

var logger *zap.Logger

func init() {
    config := zap.NewProductionConfig()
    config.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
    config.EncoderConfig.TimeKey = "timestamp"
    var err error
    logger, err = config.Build()
    if err != nil {
        panic(fmt.Sprintf("failed to initialize logger: %v", err))
    }
}

func makeRequest(ctx context.Context, url string, method string, body []byte) ([]byte, error) {
    reqID := ctx.Value("request_id").(string) // 从context中获取request ID

    req, err := http.NewRequestWithContext(ctx, method, url, bytes.NewBuffer(body))
    if err != nil {
        logger.Error("Failed to create HTTP request",
            zap.String("request_id", reqID),
            zap.String("url", url),
            zap.String("method", method),
            zap.Error(err),
        )
        return nil, &CustomError{Code: 500, Message: "request creation failed", Op: "makeRequest", Err: err}
    }
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Request-ID", reqID)

    client := &http.Client{
        Timeout: 5 * time.Second, // 设置请求超时
    }

    resp, err := client.Do(req)
    if err != nil {
        // 检查是否是网络超时错误
        if netErr, ok := err.(interface{ Timeout() bool }); ok && netErr.Timeout() {
            logger.Error("Network request timed out",
                zap.String("request_id", reqID),
                zap.String("url", url),
                zap.String("method", method),
                zap.Error(err),
            )
            return nil, &CustomError{Code: 504, Message: "network timeout", Op: "makeRequest", Err: err}
        }
        logger.Error("Failed to perform HTTP request",
            zap.String("request_id", reqID),
            zap.String("url", url),
            zap.String("method", method),
            zap.Error(err),
        )
        return nil, &CustomError{Code: 500, Message: "http request failed", Op: "makeRequest", Err: err}
    }
    defer func() {
        if closeErr := resp.Body.Close(); closeErr != nil {
            logger.Warn("Failed to close response body",
                zap.String("request_id", reqID),
                zap.String("url", url),
                zap.Error(closeErr),
            )
        }
    }()

    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        respBody, _ := io.ReadAll(resp.Body) // 尝试读取响应体，可能包含错误详情
        logger.Warn("Received non-2xx status code",
            zap.String("request_id", reqID),
            zap.String("url", url),
            zap.Int("status_code", resp.StatusCode),
            zap.String("response_body_snippet", string(respBody)),
        )
        return nil, &CustomError{Code: resp.StatusCode, Message: fmt.Sprintf("server responded with status %d", resp.StatusCode), Op: "makeRequest"}
    }

    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        logger.Error("Failed to read response body",
            zap.String("request_id", reqID),
            zap.String("url", url),
            zap.Int("status_code", resp.StatusCode),
            zap.Error(err),
        )
        return nil, &CustomError{Code: 500, Message: "failed to read response body", Op: "makeRequest", Err: err}
    }

    logger.Info("HTTP request successful",
        zap.String("request_id", reqID),
        zap.String("url", url),
        zap.String("method", method),
        zap.Int("status_code", resp.StatusCode),
    )
    return respBody, nil
}

func main() {
    defer logger.Sync() // 确保所有日志都已写入

    // 模拟一个请求ID
    ctx := context.WithValue(context.Background(), "request_id", "req-12345")

    // 模拟成功请求
    fmt.Println("\n--- Simulating Successful Request ---")
    _, err := makeRequest(ctx, "https://jsonplaceholder.typicode.com/todos/1", "GET", nil)
    if err != nil {
        logger.Error("Application error during successful simulation", zap.Error(err))
    }

    // 模拟一个不存在的URL，会得到404
    fmt.Println("\n--- Simulating 404 Not Found ---")
    _, err = makeRequest(ctx, "https://jsonplaceholder.typicode.com/nonexistent", "GET", nil)
    if err != nil {
        var customErr *CustomError
        if errors.As(err, &customErr) {
            logger.Warn("Caught custom error for 404",
                zap.String("request_id", ctx.Value("request_id").(string)),
                zap.Int("error_code", customErr.Code),
                zap.String("error_message", customErr.Message),
            )
        } else {
            logger.Error("Application error during 404 simulation", zap.Error(err))
        }
    }

    // 模拟一个无法连接的地址，会得到网络错误
    fmt.Println("\n--- Simulating Network Error (e.g., connection refused or timeout) ---")
    // 注意：这个URL可能需要根据你的网络环境进行调整，确保它确实无法连接或会超时
    // 例如，一个不存在的私有IP地址，或者一个端口未开放的地址
    ctxTimeout, cancel := context.WithTimeout(ctx, 1*time.Second) // 更短的超时模拟
    defer cancel()
    _, err = makeRequest(ctxTimeout, "http://192.0.2.1:8080/test", "GET", nil) // 这是一个测试保留IP，通常无法连接
    if err != nil {
        var customErr *CustomError
        if errors.As(err, &customErr) {
            logger.Error("Caught custom error for network failure",
                zap.String("request_id", ctx.Value("request_id").(string)),
                zap.Int("error_code", customErr.Code),
                zap.String("error_message", customErr.Message),
                zap.Error(customErr.Unwrap()), // 打印原始错误
            )
        } else {
            logger.Error("Application error during network error simulation", zap.Error(err))
        }
    }

    // 模拟一个POST请求，带JSON body
    fmt.Println("\n--- Simulating POST Request ---")
    postBody := map[string]string{"title": "foo", "body": "bar", "userId": "1"}
    jsonBody, _ := json.Marshal(postBody)
    _, err = makeRequest(ctx, "https://jsonplaceholder.typicode.com/posts", "POST", jsonBody)
    if err != nil {
        logger.Error("Application error during POST simulation", zap.Error(err))
    }
}

如何在Go语言中优雅地定义和使用自定义错误类型？

在Go中，自定义错误类型是提升错误处理可读性和可编程性的关键。它允许我们不仅仅知道“出错了”，还能知道“出了什么类型的错”。我个人觉得，这比仅仅返回一个字符串错误要强大得多，因为它赋予了错误行为和属性。

首先，一个自定义错误类型需要实现error接口，即拥有一个Error() string方法。但更进一步，为了支持Go 1.13+引入的错误包装机制（errors.Is和errors.As），我们应该考虑让自定义错误类型包装底层错误。

定义方式：

package mypackage

import (
    "fmt"
    "net/http"
)

// NetworkError 表示网络请求相关的错误
type NetworkError struct {
    StatusCode int    // HTTP状态码，如果是网络连接错误，可能为0或特定值
    Message    string // 错误描述
    IsTimeout  bool   // 是否是超时错误
    IsTemporary bool   // 是否是临时性错误，可重试
    Op         string // 发生错误的操作名 (e.g., "fetchUser")
    Err        error  // 包装的原始错误
}

// Error 实现 error 接口
func (e *NetworkError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("%s failed: %s (status: %d, timeout: %t, temporary: %t) -> %v",
            e.Op, e.Message, e.StatusCode, e.IsTimeout, e.IsTemporary, e.Err)
    }
    return fmt.Sprintf("%s failed: %s (status: %d, timeout: %t, temporary: %t)",
        e.Op, e.Message, e.StatusCode, e.IsTimeout, e.IsTemporary)
}

// Unwrap 返回被包装的原始错误，支持 errors.Unwrap
func (e *NetworkError) Unwrap() error {
    return e.Err
}

// NewNetworkError 辅助函数，用于创建 NetworkError
func NewNetworkError(op string, statusCode int, msg string, err error) *NetworkError {
    ne := &NetworkError{
        Op:         op,
        StatusCode: statusCode,
        Message:    msg,
        Err:        err,
    }

    // 尝试判断原始错误是否为超时或临时错误
    if netErr, ok := err.(interface{ Timeout() bool }); ok && netErr.Timeout() {
        ne.IsTimeout = true
        ne.IsTemporary = true // 超时通常是临时性的
    } else if netErr, ok := err.(interface{ Temporary() bool }); ok && netErr.Temporary() {
        ne.IsTemporary = true
    }

    // 根据HTTP状态码判断是否是临时性错误
    if statusCode >= http.StatusInternalServerError { // 5xx 错误通常是临时性的
        ne.IsTemporary = true
    }
    return ne
}

使用方式：

在调用方，我们可以使用errors.Is和errors.As来检查错误的类型或其链中是否包含特定错误。

package main

import (
    "errors"
    "fmt"
    "mypackage" // 假设 NetworkError 定义在 mypackage 中
)

func main() {
    // 模拟一个网络超时错误
    originalErr := errors.New("connection reset by peer")
    netErr := mypackage.NewNetworkError("fetchData", 0, "network connection failed", originalErr)
    netErr.IsTimeout = true // 手动标记为超时，如果原始错误无法自动判断

    // 模拟一个HTTP 500错误
    serverErr := mypackage.NewNetworkError("updateData", 500, "internal server error", nil)

    // 检查错误
    if errors.Is(netErr, originalErr) {
        fmt.Println("netErr 包装了 originalErr")
    }

    var specificNetErr *mypackage.NetworkError
    if errors.As(netErr, &specificNetErr) {
        fmt.Printf("这是一个 NetworkError，操作：%s，是否超时：%t\n", specificNetErr.Op, specificNetErr.IsTimeout)
    }

    if errors.As(serverErr, &specificNetErr) {
        fmt.Printf("这是一个 NetworkError，操作：%s，HTTP状态码：%d，是否临时：%t\n", specificNetErr.Op, specificNetErr.StatusCode, specificNetErr.IsTemporary)
    }
}

通过这种方式，我们不仅能通过Error()方法得到可读的错误信息，还能通过IsTimeout、IsTemporary等字段进行程序化的判断，从而实现重试、熔断等高级错误处理逻辑。这让错误不再是“黑盒”，而是带有明确属性的“对象”。

如何在Golang中为网络请求实现上下文感知的结构化日志？

上下文感知和结构化日志是现代微服务架构中不可或缺的组件，尤其是在处理网络请求这种跨服务边界的操作时。我个人认为，没有上下文的日志就像没有GPS的地图，你可能知道大致位置，但很难精确找到问题所在。

上下文感知：意味着日志信息能够携带与当前请求或操作相关的唯一标识符和状态。最常见的是请求ID（Request ID 或 Trace ID）。当一个请求从网关进来，经过多个微服务处理时，这个ID会贯穿始终，所有相关的日志都带上这个ID，这样在排查问题时，可以通过一个ID筛选出所有相关日志，描绘出请求的完整生命周期。Go语言的context.Context是实现这一点的核心机制。

结构化日志：指日志不再是简单的字符串，而是包含键值对（JSON、Logfmt等）的数据结构。这使得日志易于机器解析和聚合，方便日志分析工具（如ELK Stack, Grafana Loki）进行查询、过滤和统计。

实现步骤：

1. 选择结构化日志库：Go标准库的log功能有限，推荐使用zap (Uber) 或 logrus (Sirupsen)。zap以其高性能和零内存分配特性在生产环境中广受欢迎。

2. 初始化日志器：配置日志输出格式（JSON）、日志级别、以及其他编码器选项。

   package main
   
   import (
       "go.uber.org/zap"
       "go.uber.org/zap/zapcore"
   )
   
   var logger *zap.Logger
   
   func init() {
       // 生产环境配置
       config := zap.NewProductionConfig()
       // 定制时间格式
       config.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
       config.EncoderConfig.TimeKey = "timestamp"
       // 也可以添加其他字段，比如服务名
       config.InitialFields = map[string]interface{}{
           "service": "my-network-service",
       }
       var err error
       logger, err = config.Build()
       if err != nil {
           panic("failed to initialize logger: " + err.Error())
       }
   }

3. 使用context.Context传递请求ID：在请求入口处（例如HTTP中间件），生成一个唯一的请求ID，并将其存入context.Context。

   package main
   
   import (
       "context"
       "net/http"
       "github.com/google/uuid" // 假设使用 uuid 生成请求ID
   )
   
   type contextKey string
   const requestIDKey contextKey = "request_id"
   
   // RequestIDMiddleware 是一个HTTP中间件，用于生成和传递请求ID
   func RequestIDMiddleware(next http.Handler) http.Handler {
       return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
           requestID := r.Header.Get("X-Request-ID")
           if requestID == "" {
               requestID = uuid.New().String()
           }
           ctx := context.WithValue(r.Context(), requestIDKey, requestID)
           next.ServeHTTP(w, r.WithContext(ctx))
       })
   }
   
   // GetRequestID 从context中获取请求ID
   func GetRequestID(ctx context.Context) string {
       if val := ctx.Value(requestIDKey); val != nil {
           if id, ok := val.(string); ok {
               return id
           }
       }
       return "unknown" // 或者生成一个新的，取决于你的策略
   }

4. 在日志中嵌入上下文信息：在进行网络请求时，从context中取出请求ID，并作为结构化字段添加到日志中。

   // 假设在 makeRequest 函数中
   func makeRequest(ctx context.Context, url string, method string, body []byte) ([]byte, error) {
       reqID := GetRequestID(ctx) // 从context中获取请求ID
   
       // ... 其他请求逻辑 ...
   
       if err != nil {
           logger.Error("Failed to perform HTTP request",
               zap.String("request_id", reqID), // 关键：将请求ID作为字段
               zap.String("url", url),
               zap.String("method", method),
               zap.Error(err),
               zap.Stack("stacktrace"), // 记录堆栈信息
           )
           return nil, err
       }
   
       logger.Info("HTTP request successful",
           zap.String("request_id", reqID),
           zap.String("url", url),
           zap.String("method", method),
           zap.Int("status_code", resp.StatusCode),
           zap.Duration("latency", time.Since(start)), // 记录请求耗时
       )
       // ...
   }

通过这些实践，我们就能获得高度可观测的日志，当问题出现时，可以迅速定位到具体的请求，并追踪其在系统中的完整路径，极大地提升了故障排查的效率。

Golang网络请求失败后，如何优雅地实现重试与熔断机制？

网络请求失败是常态，尤其是当我们的服务依赖于外部API或微服务时。