3. HTTP 服务基础：从标准库到 Gin 框架

本章是微服务架构的通信基石。HTTP 服务是微服务之间最常用的交互方式，理解 Go 语言原生的 net/http 标准库，再掌握 Gin 框架的进阶能力，是构建生产级微服务的必备技能。我们将从最底层的路由与处理器开始，逐步过渡到中间件、RESTful API 设计，最终形成一套可落地的 HTTP 服务开发范式。

3.1 net/http 标准库：零依赖的 HTTP 服务

Go 语言的标准库 net/http 提供了构建 HTTP 服务所需的核心原语，无需任何第三方依赖即可启动一个 Web 服务。理解其底层机制，有助于你后续更深入地理解 Gin 等框架的设计思想。

3.1.1 核心组件与工作流程

net/http 的核心由三个关键接口和类型组成：

一个典型的请求处理流程如下：

3.1.2 快速启动一个 HTTP 服务

以下代码展示了如何使用标准库创建一个返回 "Hello, World!" 的服务：

package main

import (
    "fmt"
    "net/http"
)

// 定义一个处理器
func helloHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello, World!")
}

func main() {
    // 注册路由
    http.HandleFunc("/hello", helloHandler)

    // 启动服务器，监听 8080 端口
    fmt.Println("Server starting on :8080")
    if err := http.ListenAndServe(":8080", nil); err != nil {
        fmt.Printf("Server failed: %v\n", err)
    }
}

3.1.3 自定义 Server 与超时控制

生产级服务必须配置超时参数，防止资源耗尽。通过自定义 http.Server 结构体可以实现精细控制：

srv := &http.Server{
    Addr:         ":8080",
    Handler:      myHandler,
    ReadTimeout:  10 * time.Second,  // 读取请求体的超时
    WriteTimeout: 15 * time.Second, // 写入响应体的超时
    IdleTimeout:  60 * time.Second, // 长连接空闲超时
}

if err := srv.ListenAndServe(); err != nil {
    log.Fatalf("Server error: %v", err)
}

3.2 Gin 框架快速入门：提升开发效率

标准库虽然强大，但在路由匹配、参数解析、中间件链等方面较为原始。Gin 是目前 Go 社区最流行的 HTTP 框架之一，以高性能和简洁的 API 著称。它封装了 net/http，提供了更丰富的功能。

3.2.1 为什么选择 Gin？

3.2.2 第一个 Gin 服务

安装 Gin：go get -u github.com/gin-gonic/gin

package main

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

func main() {
    // 创建一个默认的路由引擎，默认包含 Logger 和 Recovery 中间件
    r := gin.Default()

    // 定义一个 GET 请求的路由
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "pong",
        })
    })

    // 启动服务，默认监听 0.0.0.0:8080
    r.Run() // 等同于 r.Run(":8080")
}

3.3 路由与中间件：构建可扩展的请求处理链

路由定义了请求的入口，中间件则提供了在请求到达处理器之前或之后执行通用逻辑的能力。两者结合，构成了 Gin 框架的核心处理模型。

3.3.1 Gin 路由详解

Gin 的路由支持多种模式，满足 RESTful 设计需求：

• 精确匹配： r.GET("/user", handler) 仅匹配 /user。
• 参数路由： r.GET("/user/:id", handler) 匹配 /user/123，通过 c.Param("id") 获取参数。
• 通配符路由： r.GET("/files/*filepath", handler) 匹配 /files/ 下的所有路径。
• 路由分组： 使用 Group 方法为同一前缀的路由统一添加中间件或设置路径前缀。

// 路由分组示例
v1 := r.Group("/api/v1")
{
    v1.GET("/users", getUsers)
    v1.POST("/users", createUser)
    v1.GET("/users/:id", getUserByID)
}

// 为分组统一添加中间件
v1.Use(AuthMiddleware())
{
    v1.PUT("/users/:id", updateUser)
    v1.DELETE("/users/:id", deleteUser)
}

3.3.2 中间件机制与实现

中间件是一个函数，接收 *gin.Context 作为参数。通过调用 c.Next() 将控制权传递给下一个中间件或最终的处理器。中间件可以用于日志记录、身份认证、请求限流、链路追踪等。

// 自定义一个简单的日志中间件
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求前
        start := time.Now()
        path := c.Request.URL.Path

        // 调用下一个中间件或处理器
        c.Next()

        // 请求后
        latency := time.Since(start)
        status := c.Writer.Status()
        log.Printf("[%d] %s %v", status, path, latency)
    }
}

// 在路由中使用
r.Use(LoggerMiddleware())
r.GET("/test", func(c *gin.Context) {
    c.String(http.StatusOK, "OK")
})

3.3.3 请求处理链的 SVG 图示

下图展示了 Gin 框架中一个 HTTP 请求经过中间件链和路由匹配，最终到达处理器的完整流程：

3.4 RESTful API 设计：微服务的通信语言

REST（Representational State Transfer）是一种架构风格，而非协议。在微服务架构中，RESTful API 是服务间最常用的通信契约。良好的 API 设计能显著提升系统的可维护性和可理解性。

3.4.1 核心原则与资源命名

• 资源导向： URL 表示资源（名词），而非操作（动词）。例如 /users 表示用户集合，/users/123 表示单个用户。
• 使用 HTTP 方法表达操作：
  • GET：查询资源（幂等、安全）。
  • POST：创建资源（非幂等）。
  • PUT：全量更新资源（幂等）。
  • PATCH：部分更新资源（幂等）。
  • DELETE：删除资源（幂等）。
• 使用复数名词： 推荐 /users 而非 /user，保持一致性。
• 版本控制： 通过 URL 前缀或请求头进行版本管理，例如 /api/v1/users。

3.4.2 状态码与错误处理

正确使用 HTTP 状态码是 API 设计的重要部分：

错误响应体应包含机器可读的错误码和人类可读的消息：

// 统一的错误响应结构
{
    "code": 10001,
    "message": "User not found",
    "details": "No user exists with ID: 999"
}

// Gin 中实现
func getUserByID(c *gin.Context) {
    id := c.Param("id")
    user, err := db.FindUser(id)
    if err != nil {
        c.JSON(http.StatusNotFound, gin.H{
            "code":    10001,
            "message": "User not found",
            "details": err.Error(),
        })
        return
    }
    c.JSON(http.StatusOK, user)
}

3.4.3 RESTful API 设计示例

以下是一个用户管理系统的 RESTful API 设计：

3.4.4 RESTful API 架构的 SVG 图示

下图展示了客户端通过 RESTful API 与微服务进行交互的典型架构：

3.5 本章小结

本章从 net/http 标准库出发，逐步深入到 Gin 框架的路由、中间件和 RESTful API 设计。你应当掌握以下核心能力：

• 使用标准库快速搭建 HTTP 服务，并理解其底层组件。
• 熟练使用 Gin 框架进行路由注册、参数绑定和中间件开发。
• 遵循 RESTful 原则设计清晰、一致的 API 接口。
• 正确使用 HTTP 状态码和统一的错误响应格式。