Go Web 编程快速入门 02 - 认识 net/http 与 Handler 接口

在上一篇文章中，我们搭建了Go开发环境并创建了第一个Web应用。你可能注意到，仅仅几行代码就能启动一个HTTP服务器，这背后的功臣就是Go标准库中的net/http包。

今天我们深入了解这个强大的包，以及Go Web开发的核心概念------Handler接口。掌握这些基础知识后，你就能理解Go Web应用的运行机制，为后续的路由、中间件等高级特性打下坚实基础。

1. net/http 包概览

net/http包是Go标准库中处理HTTP协议的核心包。它不仅提供了HTTP客户端功能，更重要的是为我们提供了构建HTTP服务器的完整工具集。

1.1 包的主要组成部分

package main

import (
    "fmt"
    "net/http"
    "log"
)

func main() {
    // 1. 创建一个简单的处理函数
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello, %s!", r.URL.Path[1:])
    })
    
    // 2. 启动服务器
    log.Println("服务器启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这段代码虽然简单，但涉及了net/http包的几个核心概念：

• http.HandleFunc：注册路由处理函数
• http.ResponseWriter：响应写入器接口
• http.Request：HTTP请求结构体
• http.ListenAndServe：启动HTTP服务器

1.2 HTTP服务器的工作流程

当客户端发送请求到我们的Go服务器时，整个处理流程是这样的：

// 模拟HTTP服务器的内部工作流程
func simulateServerFlow() {
    // 1. 监听端口，等待连接
    // 2. 接收HTTP请求
    // 3. 解析请求头和请求体
    // 4. 根据URL路径找到对应的Handler
    // 5. 调用Handler处理请求
    // 6. 将响应写回客户端
    // 7. 关闭连接或保持连接（Keep-Alive）
}

让我们通过一个更详细的例子来观察这个流程：

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"
)

func requestLogger(w http.ResponseWriter, r *http.Request) {
    // 记录请求开始时间
    start := time.Now()
    
    // 打印请求信息
    log.Printf("收到请求: %s %s", r.Method, r.URL.Path)
    log.Printf("请求头 User-Agent: %s", r.Header.Get("User-Agent"))
    log.Printf("客户端IP: %s", r.RemoteAddr)
    
    // 处理请求
    fmt.Fprintf(w, "请求处理完成\n")
    fmt.Fprintf(w, "请求方法: %s\n", r.Method)
    fmt.Fprintf(w, "请求路径: %s\n", r.URL.Path)
    fmt.Fprintf(w, "处理时间: %v\n", time.Since(start))
}

func main() {
    http.HandleFunc("/debug", requestLogger)
    
    log.Println("调试服务器启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

运行这个程序，访问http://localhost:8080/debug，你会在控制台看到详细的请求信息，同时浏览器会显示处理结果。

2. Handler 接口深度解析

Handler接口是Go Web开发的核心概念。理解它的工作原理，就能理解整个Go Web框架的设计哲学。

2.1 Handler接口定义

// Handler接口的定义（来自net/http包源码）
type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

这个接口非常简洁，只有一个方法ServeHTTP。任何实现了这个方法的类型都可以作为HTTP处理器。

让我们创建一个自定义的Handler：

package main

import (
    "fmt"
    "net/http"
    "log"
    "time"
)

// 定义一个自定义的Handler类型
type TimeHandler struct {
    format string
}

// 实现Handler接口的ServeHTTP方法
func (th *TimeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // 设置响应头
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    
    // 获取当前时间并格式化
    currentTime := time.Now().Format(th.format)
    
    // 写入响应
    fmt.Fprintf(w, "当前时间: %s\n", currentTime)
    fmt.Fprintf(w, "请求路径: %s\n", r.URL.Path)
}

func main() {
    // 创建Handler实例
    timeHandler := &TimeHandler{
        format: "2006-01-02 15:04:05", // Go的时间格式化模板
    }
    
    // 注册Handler
    http.Handle("/time", timeHandler)
    
    log.Println("时间服务器启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

2.2 HandlerFunc类型

Go提供了一个便利的类型HandlerFunc，它允许我们将普通函数转换为Handler：

// HandlerFunc的定义（简化版）
type HandlerFunc func(ResponseWriter, *Request)

// HandlerFunc实现了Handler接口
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

这意味着任何符合func(ResponseWriter, *Request)签名的函数都可以通过类型转换成为Handler：

package main

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

// 普通的处理函数
func greetingHandler(w http.ResponseWriter, r *http.Request) {
    name := strings.TrimPrefix(r.URL.Path, "/greeting/")
    if name == "" {
        name = "陌生人"
    }
    fmt.Fprintf(w, "你好, %s! 欢迎访问我们的网站。\n", name)
}

// 另一个处理函数
func aboutHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprint(w, "这是一个Go Web应用示例\n")
    fmt.Fprint(w, "使用net/http包构建\n")
}

func main() {
    // 方式1：使用http.HandleFunc（内部会进行类型转换）
    http.HandleFunc("/greeting/", greetingHandler)
    
    // 方式2：手动类型转换
    http.Handle("/about", http.HandlerFunc(aboutHandler))
    
    log.Println("服务器启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

2.3 多个Handler的组合使用

在实际项目中，我们通常需要多个Handler来处理不同的路由。让我们看一个更完整的例子：

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "strconv"
    "time"
)

// 用户信息结构体
type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
    Age  int    `json:"age"`
}

// 模拟用户数据
var users = []User{
    {ID: 1, Name: "张三", Age: 25},
    {ID: 2, Name: "李四", Age: 30},
    {ID: 3, Name: "王五", Age: 28},
}

// 首页Handler
func homeHandler(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path != "/" {
        http.NotFound(w, r)
        return
    }
    
    fmt.Fprint(w, "欢迎来到用户管理系统\n")
    fmt.Fprint(w, "可用接口:\n")
    fmt.Fprint(w, "GET /users - 获取所有用户\n")
    fmt.Fprint(w, "GET /user/{id} - 获取指定用户\n")
}

// 用户列表Handler
func usersHandler(w http.ResponseWriter, r *http.Request) {
    // 设置JSON响应头
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    
    // 将用户列表编码为JSON
    if err := json.NewEncoder(w).Encode(users); err != nil {
        http.Error(w, "编码JSON失败", http.StatusInternalServerError)
        return
    }
}

// 单个用户Handler
func userHandler(w http.ResponseWriter, r *http.Request) {
    // 从URL路径中提取用户ID
    idStr := r.URL.Path[len("/user/"):]
    id, err := strconv.Atoi(idStr)
    if err != nil {
        http.Error(w, "无效的用户ID", http.StatusBadRequest)
        return
    }
    
    // 查找用户
    for _, user := range users {
        if user.ID == id {
            w.Header().Set("Content-Type", "application/json; charset=utf-8")
            json.NewEncoder(w).Encode(user)
            return
        }
    }
    
    // 用户不存在
    http.Error(w, "用户不存在", http.StatusNotFound)
}

// 日志中间件Handler
type LoggingHandler struct {
    handler http.Handler
}

func (lh *LoggingHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    start := time.Now()
    log.Printf("开始处理请求: %s %s", r.Method, r.URL.Path)
    
    // 调用下一个Handler
    lh.handler.ServeHTTP(w, r)
    
    log.Printf("请求处理完成: %s %s (耗时: %v)", 
        r.Method, r.URL.Path, time.Since(start))
}

// 创建带日志的Handler
func withLogging(handler http.Handler) http.Handler {
    return &LoggingHandler{handler: handler}
}

func main() {
    // 注册路由
    http.HandleFunc("/", homeHandler)
    http.HandleFunc("/users", usersHandler)
    http.HandleFunc("/user/", userHandler)
    
    // 创建带日志的服务器
    server := &http.Server{
        Addr:    ":8080",
        Handler: withLogging(http.DefaultServeMux),
    }
    
    log.Println("用户管理服务器启动在 :8080")
    log.Fatal(server.ListenAndServe())
}

这个例子展示了几个重要概念：

• 不同路由的Handler处理
• JSON响应的生成
• 错误处理和HTTP状态码
• Handler的组合（日志中间件）

3. ServeMux：默认的路由器

ServeMux是Go标准库提供的HTTP请求路由器。当我们使用http.HandleFunc时，实际上是在操作默认的ServeMux实例。

3.1 理解ServeMux的工作原理

package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    // 创建一个新的ServeMux实例
    mux := http.NewServeMux()
    
    // 注册处理函数
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "根路径处理器\n")
        fmt.Fprintf(w, "实际请求路径: %s\n", r.URL.Path)
    })
    
    mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "API路径处理器\n")
        fmt.Fprintf(w, "实际请求路径: %s\n", r.URL.Path)
    })
    
    mux.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "用户API处理器\n")
        fmt.Fprintf(w, "实际请求路径: %s\n", r.URL.Path)
    })
    
    // 使用自定义的ServeMux
    server := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }
    
    log.Println("自定义路由服务器启动在 :8080")
    log.Fatal(server.ListenAndServe())
}

3.2 路由匹配规则

ServeMux的路由匹配遵循最长前缀匹配原则：

package main

import (
    "fmt"
    "log"
    "net/http"
)

func routeDemo() {
    mux := http.NewServeMux()
    
    // 注册多个路由，观察匹配优先级
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "匹配到根路径处理器: %s\n", r.URL.Path)
    })
    
    mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "匹配到API路径处理器: %s\n", r.URL.Path)
    })
    
    mux.HandleFunc("/api/v1/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "匹配到API v1路径处理器: %s\n", r.URL.Path)
    })
    
    mux.HandleFunc("/api/v1/users", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "匹配到用户API处理器: %s\n", r.URL.Path)
    })
    
    // 测试不同路径的匹配结果：
    // /           -> 根路径处理器
    // /api/test   -> API路径处理器
    // /api/v1/    -> API v1路径处理器
    // /api/v1/users -> 用户API处理器
    
    log.Println("路由演示服务器启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

func main() {
    routeDemo()
}

4. 实战：构建一个简单的博客API

让我们运用所学知识，构建一个简单但完整的博客API：

package main

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

// 博客文章结构体
type Article struct {
    ID      int       `json:"id"`
    Title   string    `json:"title"`
    Content string    `json:"content"`
    Author  string    `json:"author"`
    Created time.Time `json:"created"`
}

// 模拟数据存储
var articles = []Article{
    {
        ID:      1,
        Title:   "Go Web开发入门",
        Content: "Go语言在Web开发领域表现出色...",
        Author:  "张三",
        Created: time.Now().Add(-24 * time.Hour),
    },
    {
        ID:      2,
        Title:   "理解HTTP协议",
        Content: "HTTP协议是Web通信的基础...",
        Author:  "李四",
        Created: time.Now().Add(-12 * time.Hour),
    },
}

var nextID = 3

// 博客API处理器
type BlogAPI struct{}

func (api *BlogAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // 设置CORS头（允许跨域）
    w.Header().Set("Access-Control-Allow-Origin", "*")
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    
    // 解析路径
    path := strings.TrimPrefix(r.URL.Path, "/api/articles")
    
    switch r.Method {
    case "GET":
        if path == "" || path == "/" {
            api.listArticles(w, r)
        } else {
            api.getArticle(w, r, path)
        }
    case "POST":
        if path == "" || path == "/" {
            api.createArticle(w, r)
        } else {
            http.Error(w, "不支持的操作", http.StatusMethodNotAllowed)
        }
    default:
        http.Error(w, "不支持的HTTP方法", http.StatusMethodNotAllowed)
    }
}

// 获取文章列表
func (api *BlogAPI) listArticles(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]interface{}{
        "success": true,
        "data":    articles,
        "total":   len(articles),
    })
}

// 获取单篇文章
func (api *BlogAPI) getArticle(w http.ResponseWriter, r *http.Request, path string) {
    idStr := strings.Trim(path, "/")
    id, err := strconv.Atoi(idStr)
    if err != nil {
        http.Error(w, "无效的文章ID", http.StatusBadRequest)
        return
    }
    
    for _, article := range articles {
        if article.ID == id {
            json.NewEncoder(w).Encode(map[string]interface{}{
                "success": true,
                "data":    article,
            })
            return
        }
    }
    
    http.Error(w, "文章不存在", http.StatusNotFound)
}

// 创建新文章
func (api *BlogAPI) createArticle(w http.ResponseWriter, r *http.Request) {
    var newArticle Article
    
    if err := json.NewDecoder(r.Body).Decode(&newArticle); err != nil {
        http.Error(w, "无效的JSON数据", http.StatusBadRequest)
        return
    }
    
    // 设置文章ID和创建时间
    newArticle.ID = nextID
    nextID++
    newArticle.Created = time.Now()
    
    // 添加到文章列表
    articles = append(articles, newArticle)
    
    // 返回创建的文章
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(map[string]interface{}{
        "success": true,
        "data":    newArticle,
        "message": "文章创建成功",
    })
}

// 首页处理器
func homeHandler(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path != "/" {
        http.NotFound(w, r)
        return
    }
    
    fmt.Fprint(w, `
简单博客API服务器

可用接口:
GET  /api/articles     - 获取所有文章
GET  /api/articles/{id} - 获取指定文章
POST /api/articles     - 创建新文章

示例POST数据:
{
    "title": "新文章标题",
    "content": "文章内容...",
    "author": "作者姓名"
}
`)
}

func main() {
    // 创建博客API处理器
    blogAPI := &BlogAPI{}
    
    // 注册路由
    http.HandleFunc("/", homeHandler)
    http.Handle("/api/articles", blogAPI)
    http.Handle("/api/articles/", blogAPI)
    
    log.Println("博客API服务器启动在 :8080")
    log.Println("访问 http://localhost:8080 查看API文档")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这个博客API展示了：

• 自定义Handler的实现
• HTTP方法的处理
• JSON数据的编码和解码
• 路径参数的解析
• 错误处理和状态码设置

你可以使用curl或Postman测试这个API：

# 获取所有文章
curl http://localhost:8080/api/articles

# 获取指定文章
curl http://localhost:8080/api/articles/1

# 创建新文章
curl -X POST http://localhost:8080/api/articles \
  -H "Content-Type: application/json" \
  -d '{"title":"测试文章","content":"这是测试内容","author":"测试作者"}'

5. 总结

通过这篇文章，我们深入了解了Go Web开发的核心概念：

• net/http包提供了构建HTTP服务器的完整工具集
• Handler接口是Go Web开发的核心，任何实现了ServeHTTP方法的类型都可以处理HTTP请求
• HandlerFunc类型让普通函数也能成为Handler
• ServeMux负责路由匹配，遵循最长前缀匹配原则
• 通过组合多个Handler，可以构建复杂的Web应用

掌握这些基础概念后，你已经具备了理解更高级特性的能力。在下一篇文章中，我们将探讨路由和中间件的设计模式，学习如何构建更加灵活和可维护的Web应用架构。

Handler接口的简洁设计体现了Go语言"少即是多"的哲学。正是这种简洁性，让Go在Web开发领域展现出了强大的表现力和灵活性。