Go HTTP 服务器：http.Server 与路由

Go 语言的标准库 net/http 提供了构建 Web 服务器所需的一切核心功能。理解如何正确配置 http.Server 以及掌握内置路由器 http.ServeMux 的工作原理，是开发高性能、稳定 Web 服务的基础。

1. 构建最基础的 HTTP 服务器

首先，我们需要创建一个能够响应 HTTP 请求的程序。Go 的标准库将这一过程简化为了几行代码。

1. 创建一个名为 main.go 的文件。
2. 编写以下代码来启动一个监听 8080 端口的服务器：

package main

import (
    "fmt"
    "net/http"
)

// 定义一个处理函数，必须符合 http.HandlerFunc 签名
func homeHandler(w http.ResponseWriter, r *http.Request) {
    // 写入响应内容
    fmt.Fprint(w, "欢迎来到 Go Web 服务器！")
}

func main() {
    // 使用 http.HandleFunc 注册路由
    // 当访问根路径 "/" 时，调用 homeHandler
    http.HandleFunc("/", homeHandler)

    // 启动 HTTP 服务并监听 8080 端口
    fmt.Println("服务器正在启动，监听端口 :8080")
    err := http.ListenAndServe(":8080", nil)
    if err != nil {
        panic(err)
    }
}

3. 运行该程序：
   在终端中执行 go run main.go。
4. 测试服务器：
   打开浏览器或使用 curl 访问 http://localhost:8080。你将看到返回的文本“欢迎来到 Go Web 服务器！”。

在这一步中，http.ListenAndServe 使用了一个默认的 http.Server 实例和默认的路由器（即 DefaultServeMux）。

2. 使用 http.Server 结构体进行精细控制

在实际生产环境中，我们需要对服务器的行为进行更多控制，例如设置超时时间、配置读写头大小等。这需要我们显式地创建 http.Server 结构体。

1. 修改 main 函数，替换掉简单的 http.ListenAndServe，改为自定义 http.Server 实例：

func main() {
    // 创建一个新的 ServeMux 路由器
    mux := http.NewServeMux()
    mux.HandleFunc("/", homeHandler)

    // 配置 http.Server 结构体
    server := &http.Server{
        Addr:         ":8080",            // 监听地址
        Handler:      mux,               // 调用的路由处理器
        ReadTimeout:  5 * time.Second,    // 读取超时时间
        WriteTimeout: 10 * time.Second,   // 写入超时时间
        IdleTimeout:  120 * time.Second,  // 空闲保持超时时间
    }

    fmt.Println("服务器配置完成，准备启动 :8080")
    // 使用 server.ListenAndServe 启动
    err := server.ListenAndServe()
    if err != nil {
        panic(err)
    }
}

2. 引入 time 包：
   在文件头部添加 "time" 导入，否则代码将无法编译。

3. 观察超时设置的作用：
   这里的 ReadTimeout 定义了从读取完请求头到读取完请求体的最大时间。设置合理的超时可以有效防止慢速攻击（Slowloris attack）并回收资源。

3. 深入理解路由：ServeMux 的匹配规则

Go 内置的 ServeMux 是一个简单的 HTTP 请求多路复用器。理解它的匹配逻辑对于避免路由冲突至关重要。

ServeMux 使用两种匹配模式：

注意：尾部斜杠 / 是决定模式类型的关键。

3.1 验证路由优先级

当多个模式可能匹配同一个请求时，ServeMux 会按照“优先匹配最长、最具体的路径”的原则。

1. 创建如下测试代码来观察匹配顺序：

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

    // 注册子树模式
    mux.HandleFunc("/images/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "这是图片画廊页（子树匹配）")
    })

    // 注册具体资源模式（更长、更具体）
    mux.HandleFunc("/images/thumbnail.png", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "这是具体的缩略图（具体匹配优先）")
    })

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

2. 测试访问：
   • 访问 http://localhost:8080/images/thumbnail.png：你将看到“这是具体的缩略图”。因为 /images/thumbnail.png 比 /images/ 更长，优先级更高。
   • 访问 http://localhost:8080/images/logo.jpg：你将看到“这是图片画廊页”。

3.2 处理未匹配的路由

如果请求的路径没有被任何模式匹配，ServeMux 会自动返回 404 Not Found。

1. 添加一个兜底处理逻辑（如果你想自定义 404 页面）：
   在所有具体路由注册之后，注册一个 / 路径。

    // ... 其他路由注册 ...

    // "/" 匹配所有未被其他更具体路由匹配的请求
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusNotFound)
        fmt.Fprint(w, "404 - 页面未找到")
    })

4. 请求处理流程可视化

为了更直观地理解请求是如何从网络连接流转到具体的处理函数的，我们可以参考以下流程：

5. 实战：处理 POST 请求与 JSON 数据

现代 Web 服务通常通过 JSON 格式进行数据交互。我们需要编写一个能够读取并解析 JSON 请求体的路由。

1. 定义一个用于接收数据的结构体：

type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

2. 编写处理 POST 请求的函数：

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    // 限制只处理 POST 方法
    if r.Method != http.MethodPost {
        http.Error(w, "只允许 POST 请求", http.StatusMethodNotAllowed)
        return
    }

    // 解析请求体中的 JSON 数据
    var user User
    err := json.NewDecoder(r.Body).Decode(&user)
    if err != nil {
        http.Error(w, "请求数据格式错误", http.StatusBadRequest)
        return
    }

    // 业务逻辑处理（此处省略）
    fmt.Printf("接收到新用户: %s (%s)\n", user.Name, user.Email)

    // 返回创建成功的状态码和数据
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

3. 注册路由并引入 encoding/json：

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", homeHandler)
    mux.HandleFunc("/user", createUserHandler) // 注册用户创建接口

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

4. 测试 POST 接口：
   使用 curl 发送一个 JSON 数据包：

   curl -X POST http://localhost:8080/user \
        -H "Content-Type: application/json" \
        -d '{"name":"张三", "email":"zhangsan@example.com"}'

   你应该能在终端接收到服务器返回的 JSON 对象，并在服务器后台看到打印出的日志。

6. 静态文件服务

除了 API 接口，服务器通常还需要托管静态资源（如 CSS、JS、图片）。http.ServeMux 提供了便捷的方法来处理文件服务。

1. 创建一个名为 static 的文件夹，并在其中放入一个 test.txt 文件。
2. 修改 main 函数，添加静态文件路由：

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

    // 挂载静态文件服务
    // 第一个参数是 URL 路径前缀，第二个参数是文件系统路径
    // 访问 /static/... 会映射到 ./static/... 目录
    mux.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.Dir("static"))))

    mux.HandleFunc("/", homeHandler)

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

3. 访问 http://localhost:8080/static/test.txt，浏览器将显示该文本文件的内容。

这里的 http.StripPrefix 是关键：它会在将请求传递给 FileServer 之前，去掉 URL 中的 /static 前缀。如果不这样做，FileServer 将会在文件系统中寻找 static/static/test.txt，从而导致找不到文件。

7. 优雅关闭服务器

在程序更新或维护时，强制终止进程（如 Ctrl+C）可能会导致正在处理的请求中断。Go 1.8+ 引入了 Shutdown 方法来实现优雅关闭。

1. 引入 os、os/signal 和 context 包。
2. 修改 main 函数，添加信号监听逻辑：

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

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

    // 在一个 goroutine 中启动服务器
    go func() {
        fmt.Println("服务器启动中...")
        if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            fmt.Printf("监听错误: %v\n", err)
        }
    }()

    // 监听中断信号 (Ctrl+C)
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, os.Interrupt)
    <-quit // 阻塞，直到收到信号

    fmt.Println("正在关闭服务器...")

    // 创建一个超时上下文
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    // 调用 Shutdown，这会阻止新请求，并等待现有请求完成或超时
    if err := server.Shutdown(ctx); err != nil {
        fmt.Printf("服务器强制关闭: %v\n", err)
    }

    fmt.Println("服务器已退出")
}

3. 测试优雅关闭：
   运行程序后，在浏览器访问 http://localhost:8080。此时在终端按下 Ctrl + C。你会发现服务器不会立即退出，而是等待当前请求处理完毕（或等待 5 秒超时）后才停止。

通过以上步骤，你已经构建了一个具备路由分发、JSON 处理、静态文件托管和优雅关闭功能的完整 HTTP 服务器。