3. HTTP 基础：Go 标准库 net/http 快速搭建 RESTful API、路由与中间件基础

在构建低延迟因子评分接口时，HTTP 通信层是请求进入系统的第一道关卡。Go 标准库 net/http 提供了原生的 HTTP 服务器、客户端及路由能力，无需引入第三方框架即可快速搭建 RESTful API。本章将围绕 net/http 的核心组件，讲解如何构建路由、处理请求与响应，并实现基础的中间件链。

3.1 net/http 核心组件

net/http 包的核心抽象包括 Handler 接口、ServeMux 路由器以及 Server 结构体。理解这三者的关系是掌握 Go HTTP 编程的基础。

组件	作用	关键方法/字段
Handler	定义 HTTP 处理逻辑的接口	ServeHTTP(ResponseWriter, *Request)
ServeMux	基于路径的路由分发器	Handle(pattern, handler) / HandleFunc(pattern, func)
Server	控制 HTTP 服务器生命周期与配置	Addr / Handler / ListenAndServe()

3.2 快速搭建 RESTful API

以下示例展示如何使用 net/http 实现一个简单的因子评分查询接口，支持 GET /score/{userID} 路径。

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "strings"
)

// ScoreResponse 评分响应结构体
type ScoreResponse struct {
    UserID string  `json:"user_id"`
    Score  float64 `json:"score"`
    Level  string  `json:"level"`
}

func scoreHandler(w http.ResponseWriter, r *http.Request) {
    // 从路径中提取 userID: /score/12345
    parts := strings.Split(r.URL.Path, "/")
    if len(parts) < 3 || parts[1] != "score" {
        http.NotFound(w, r)
        return
    }
    userID := parts[2]

    // 模拟查询评分（实际场景会调用缓存或数据库）
    score := 85.5
    level := "A"

    resp := ScoreResponse{
        UserID: userID,
        Score:  score,
        Level:  level,
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(resp)
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/score/", scoreHandler)

    server := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    log.Println("Server starting on :8080")
    log.Fatal(server.ListenAndServe())
}

3.3 路由匹配规则与优先级

ServeMux 的路由匹配遵循以下规则：

• 精确路径（如 /score）只匹配该路径本身。
• 子树路径（如 /score/）匹配以该前缀开头的所有路径，并重定向到带斜杠的版本。
• 最长匹配优先：同时匹配多个模式时，选择最长的模式。
• 默认 404：无匹配时返回 404 Not Found。

注册模式	匹配示例	说明
/score	/score	仅匹配精确路径
/score/	/score/123, /score/abc	匹配所有以 /score/ 开头的路径
/	所有路径	默认兜底处理器

3.4 中间件基础

中间件是一种包装 http.Handler 的设计模式，用于在请求处理前后执行横切逻辑（如日志、鉴权、超时控制）。Go 中典型的中间件实现方式为函数式链式调用。

// loggingMiddleware 记录请求耗时
func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        log.Printf("[%s] %s %s", r.Method, r.URL.Path, time.Since(start))
    })
}

// recoveryMiddleware 捕获 panic 防止进程崩溃
func recoveryMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                log.Printf("panic recovered: %v", err)
                http.Error(w, "Internal Server Error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

// 使用示例
mux := http.NewServeMux()
mux.HandleFunc("/score/", scoreHandler)

// 链式包装：recovery 在最外层，logging 在中间
handler := recoveryMiddleware(loggingMiddleware(mux))

server := &http.Server{
    Addr:    ":8080",
    Handler: handler,
}

3.5 中间件链与请求生命周期

下图展示了一个包含三个中间件的请求处理流程，清晰呈现了请求进入、中间件处理、业务逻辑执行、响应返回的完整生命周期。

3.6 低延迟场景下的最佳实践

• 复用 Handler：避免在每次请求中创建新的 http.Handler 实例，使用闭包或结构体方法复用处理逻辑。
• 控制 Header 写入时机：ResponseWriter 在第一次 Write() 或 WriteHeader() 后锁定状态码和 Header，提前设置好所有 Header 再写入 Body。
• 禁用 Keep-Alive 的 Connection 日志：默认 Server 会记录每个连接事件，生产环境建议设置 ErrorLog 为 io.Discard 或自定义日志器。
• 使用 sync.Pool 复用对象：对于频繁创建的响应结构体或缓冲区，使用 sync.Pool 减少 GC 压力。

// 使用 sync.Pool 复用 ScoreResponse 对象
var scorePool = sync.Pool{
    New: func() interface{} {
        return &ScoreResponse{}
    },
}

func scoreHandlerWithPool(w http.ResponseWriter, r *http.Request) {
    resp := scorePool.Get().(*ScoreResponse)
    defer scorePool.Put(resp)

    // 重置字段
    resp.UserID = extractUserID(r)
    resp.Score = 85.5
    resp.Level = "A"

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(resp)
}