2. Go Web基础回顾：使用net/http和Gin框架快速搭建一个简单的RESTful API服务

在深入接口版本控制之前，有必要先巩固Go语言构建Web服务的基础能力。本章将带领你使用标准库 net/http 和流行的轻量级框架 Gin，分别搭建一个简单的RESTful API服务。通过对比两种实现方式，你将更清晰地理解框架的设计哲学及其在版本控制场景中的适用性。

2.1 使用标准库 net/http 构建基础API

Go标准库中的 net/http 包提供了构建HTTP服务器所需的核心原语，无需任何第三方依赖。对于简单的API或微服务，它已经足够胜任。

2.1.1 核心组件与路由注册

标准库使用 http.HandleFunc 或 http.Handle 注册路由。路由匹配基于最长前缀匹配规则，不支持路径参数（如 /users/:id），需要手动解析URL。

2.1.2 代码示例：用户资源CRUD

以下示例展示了如何使用 net/http 实现一个简单的用户列表查询和创建接口。注意手动处理路径和请求方法的过程。

package main

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

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

var users = []User{{ID: 1, Name: "Alice"}}

func usersHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    switch r.Method {
    case http.MethodGet:
        json.NewEncoder(w).Encode(users)
    case http.MethodPost:
        var newUser User
        if err := json.NewDecoder(r.Body).Decode(&newUser); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        newUser.ID = len(users) + 1
        users = append(users, newUser)
        w.WriteHeader(http.StatusCreated)
        json.NewEncoder(w).Encode(newUser)
    default:
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
    }
}

func main() {
    http.HandleFunc("/users", usersHandler)
    // 手动处理 /users/ 前缀，用于获取单个用户
    http.HandleFunc("/users/", func(w http.ResponseWriter, r *http.Request) {
        idStr := strings.TrimPrefix(r.URL.Path, "/users/")
        fmt.Fprintf(w, "User ID: %s", idStr)
    })

    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

2.2 使用Gin框架构建RESTful API

Gin是目前Go社区最受欢迎的Web框架之一，它提供了高性能的路由引擎、中间件链、请求参数绑定和验证等功能，显著提升了开发效率。

2.2.1 Gin的核心特性

• 高性能路由：基于Radix树实现，支持路径参数（:param）和通配符（*param）。
• 中间件链：支持全局、分组和路由级别的中间件注入。
• 请求绑定与验证：自动将JSON、表单、查询参数绑定到结构体，并支持自定义验证器。
• 分组路由：天然支持路由分组，非常适合按API版本组织接口。

2.2.2 代码示例：使用Gin重构用户API

使用Gin后，路由定义更加简洁，参数提取和响应处理也更加直观。

package main

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

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

var users = []User{{ID: 1, Name: "Alice"}}

func main() {
    r := gin.Default()

    // 路由组：v1 版本
    v1 := r.Group("/api/v1")
    {
        v1.GET("/users", func(c *gin.Context) {
            c.JSON(http.StatusOK, users)
        })

        v1.POST("/users", func(c *gin.Context) {
            var newUser User
            if err := c.ShouldBindJSON(&newUser); err != nil {
                c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
                return
            }
            newUser.ID = len(users) + 1
            users = append(users, newUser)
            c.JSON(http.StatusCreated, newUser)
        })

        v1.GET("/users/:id", func(c *gin.Context) {
            id := c.Param("id")
            c.JSON(http.StatusOK, gin.H{"user_id": id})
        })
    }

    r.Run(":8080")
}

2.3 两种实现方式的对比分析

下表从多个维度对比了 net/http 和 Gin 在构建RESTful API时的差异，帮助你根据项目需求做出选择。

2.4 RESTful API 请求处理流程

下面的SVG图展示了Gin框架处理一个HTTP请求的完整生命周期，从接收到响应返回，重点突出了中间件链和路由匹配的位置。

2.5 选择建议与版本控制切入点

对于本课程后续的接口版本控制实践，我们推荐使用 Gin框架 作为基础。原因如下：

• 路由分组天然支持版本隔离：你可以轻松创建 /api/v1、/api/v2 等分组，每个分组拥有独立的中间件和处理逻辑。
• 中间件机制便于实现版本协商：可以通过自定义中间件解析请求头（如 Accept-Version）或URL前缀，动态路由到不同版本的处理函数。
• 社区生态丰富：大量现成的中间件（如认证、限流、日志）可以直接集成到版本控制体系中。