4. HTTP 服务基础：Go 标准库 net/http 构建 RESTful API

在契约压测与校验体系中，HTTP 服务是承载所有请求与响应的核心载体。Go 标准库 net/http 提供了构建高性能 RESTful API 所需的基础设施，无需依赖第三方框架即可完成路由注册、请求处理与中间件编排。本章将深入剖析其核心机制，为后续的契约测试与压测场景打下坚实基础。

4.1 net/http 核心组件与请求生命周期

Go 的 HTTP 服务基于 http.Handler 接口构建，该接口定义了 ServeHTTP(ResponseWriter, *Request) 方法。整个请求处理流程可抽象为以下步骤：

1. 监听端口：http.ListenAndServe 启动 TCP 监听。
2. 连接接受：为每个连接创建 goroutine 处理。
3. 请求解析：将字节流解析为 http.Request 结构体。
4. 路由匹配：http.ServeMux 根据请求路径查找对应 Handler。
5. 中间件链：按注册顺序依次执行中间件逻辑。
6. 业务处理：最终 Handler 写入响应状态码、Header 与 Body。

4.2 路由处理：ServeMux 与模式匹配

http.ServeMux 是 Go 标准库内置的路由器，支持基于路径前缀的匹配规则。在 Go 1.22 版本中，ServeMux 获得了增强的模式匹配能力，支持 HTTP 方法限定与路径变量。

4.2.1 基础路由注册示例

package main

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

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    mux := http.NewServeMux()

    // 精确路径匹配（Go 1.0+）
    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    })

    // 方法 + 路径变量匹配（Go 1.22+）
    mux.HandleFunc("GET /api/users/{id}", func(w http.ResponseWriter, r *http.Request) {
        id := r.PathValue("id")
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(User{ID: 1, Name: "Alice"})
        log.Printf("查询用户 ID: %s", id)
    })

    // 前缀匹配，用于静态文件或分组路由
    mux.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.Dir("./public"))))

    log.Println("服务启动于 :8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

4.3 中间件概念与链式编排

中间件是 HTTP 处理管道中的可插拔组件，用于在请求到达业务 Handler 之前或之后执行横切关注点（如日志、鉴权、限流、请求 ID 注入）。Go 中中间件的本质是一个接收 http.Handler 并返回 http.Handler 的函数。

4.3.1 中间件函数签名

// 标准中间件签名
type Middleware func(next http.Handler) http.Handler

// 使用示例：日志中间件
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        log.Printf("[%s] %s %s", r.Method, r.URL.Path, r.RemoteAddr)
        next.ServeHTTP(w, r) // 调用下一个 Handler
    })
}

4.3.2 中间件链的执行顺序

中间件按注册顺序形成嵌套结构。假设注册顺序为 A → B → C → Handler，则执行顺序为：

1. A 的前置逻辑（请求到达时）
2. B 的前置逻辑
3. C 的前置逻辑
4. Handler 的业务逻辑
5. C 的后置逻辑（响应返回时）
6. B 的后置逻辑
7. A 的后置逻辑

4.3.3 常见中间件实现模式

4.3.4 中间件链式组合

// 中间件组合工具
func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

// 使用示例
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /api/users/{id}", getUserHandler)

    // 组合中间件：日志 → 鉴权 → 限流 → 业务
    wrappedHandler := Chain(mux,
        LoggingMiddleware,
        AuthMiddleware,
        RateLimitMiddleware,
    )

    http.ListenAndServe(":8080", wrappedHandler)
}

// 鉴权中间件示例
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            w.Header().Set("Content-Type", "application/json")
            w.WriteHeader(http.StatusUnauthorized)
            json.NewEncoder(w).Encode(map[string]string{"error": "missing token"})
            return
        }
        // 验证 token 逻辑...
        next.ServeHTTP(w, r)
    })
}

4.4 RESTful API 设计规范与 net/http 实现

RESTful API 的核心是资源导向设计。使用 net/http 实现时，需遵循以下规范：

• 资源路径：使用名词复数形式，如 /api/users、/api/orders
• HTTP 方法：GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
• 状态码：200 OK、201 Created、204 No Content、400 Bad Request、404 Not Found、500 Internal Server Error
• 内容协商：通过 Content-Type 和 Accept Header 支持 JSON/XML

4.5 本章小结