golang

Go HTTP Handler 测试入门：不用启动端口也能测接口

Handler 不一定要启动服务才能测试很多人测试 HTTP 接口时，会先启动服务，再用 curl 或浏览器访问。这种手动测试有用，但不适合长期保护代码。每次改 handler 都手动点一遍，很快会漏。Go 标准库提供了，可以在测试里构造请求、记录响应，不需要真的监听端口。

Leeting Yan 2020-04-08 7 分钟阅读 3159 字

Handler 不一定要启动服务才能测试

很多人测试 HTTP 接口时，会先 go run . 启动服务，再用 curl 或浏览器访问。这种手动测试有用，但不适合长期保护代码。每次改 handler 都手动点一遍，很快会漏。Go 标准库提供了 net/http/httptest，可以在测试里构造请求、记录响应，不需要真的监听端口。

HTTP handler 在 Go 里本质是一个函数：

func(w http.ResponseWriter, r *http.Request)

既然是函数，就可以直接调用。httptest.NewRequest 帮你创建请求，httptest.NewRecorder 帮你记录响应。这样你可以在单元测试里检查状态码、响应头和 JSON 内容。

这篇文章用一个文章创建接口做例子，讲清楚 handler 测试的基本套路。

最小 handler 测试

先写一个健康检查：

func healthHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}
	w.WriteHeader(http.StatusOK)
	fmt.Fprintln(w, "ok")
}

测试：

func TestHealthHandler(t *testing.T) {
	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
	rec := httptest.NewRecorder()

	healthHandler(rec, req)

	resp := rec.Result()
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		t.Fatalf("status = %d, want %d", resp.StatusCode, http.StatusOK)
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		t.Fatalf("read body: %v", err)
	}
	if strings.TrimSpace(string(body)) != "ok" {
		t.Fatalf("body = %q, want ok", string(body))
	}
}

没有端口，没有真实网络，测试速度很快。rec.Result() 会把 recorder 转成 *http.Response，方便读取状态和 body。

测试方法不允许

继续测错误路径：

func TestHealthHandlerMethodNotAllowed(t *testing.T) {
	req := httptest.NewRequest(http.MethodPost, "/healthz", nil)
	rec := httptest.NewRecorder()

	healthHandler(rec, req)

	if rec.Code != http.StatusMethodNotAllowed {
		t.Fatalf("status = %d, want %d", rec.Code, http.StatusMethodNotAllowed)
	}
}

这里直接用 rec.Code 也可以。测试 handler 时，不要只测成功路径。HTTP 接口最容易出问题的地方往往是方法、参数、JSON 格式和依赖失败。

测试 JSON 响应

假设有响应函数：

type Article struct {
	ID    int64  `json:"id"`
	Title string `json:"title"`
}

func writeJSON(w http.ResponseWriter, status int, value interface{}) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(value)
}

Handler：

func articleHandler(w http.ResponseWriter, r *http.Request) {
	article := Article{ID: 1, Title: "Go 测试入门"}
	writeJSON(w, http.StatusOK, article)
}

测试：

func TestArticleHandler(t *testing.T) {
	req := httptest.NewRequest(http.MethodGet, "/article", nil)
	rec := httptest.NewRecorder()

	articleHandler(rec, req)

	resp := rec.Result()
	defer resp.Body.Close()

	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "application/json") {
		t.Fatalf("content-type = %q", got)
	}

	var article Article
	if err := json.NewDecoder(resp.Body).Decode(&article); err != nil {
		t.Fatalf("decode response: %v", err)
	}

	if article.ID != 1 || article.Title != "Go 测试入门" {
		t.Fatalf("article = %+v", article)
	}
}

不要用字符串直接比较整段 JSON，除非顺序和格式完全固定。解码成结构体再断言字段，测试更稳。

用依赖替身测试 handler

真实 handler 往往依赖 service：

type ArticleService interface {
	Create(ctx context.Context, title string) (Article, error)
}

type Handler struct {
	service ArticleService
}

创建接口：

type createArticleRequest struct {
	Title string `json:"title"`
}

func (h *Handler) createArticle(w http.ResponseWriter, r *http.Request) {
	var req createArticleRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid json", http.StatusBadRequest)
		return
	}

	article, err := h.service.Create(r.Context(), req.Title)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	writeJSON(w, http.StatusCreated, article)
}

测试替身：

type fakeArticleService struct {
	title string
	err   error
}

func (s *fakeArticleService) Create(ctx context.Context, title string) (Article, error) {
	s.title = title
	if s.err != nil {
		return Article{}, s.err
	}
	return Article{ID: 10, Title: title}, nil
}

测试：

func TestCreateArticle(t *testing.T) {
	service := &fakeArticleService{}
	h := &Handler{service: service}

	body := strings.NewReader(`{"title":"Go Handler 测试"}`)
	req := httptest.NewRequest(http.MethodPost, "/articles", body)
	rec := httptest.NewRecorder()

	h.createArticle(rec, req)

	if rec.Code != http.StatusCreated {
		t.Fatalf("status = %d, want %d", rec.Code, http.StatusCreated)
	}
	if service.title != "Go Handler 测试" {
		t.Fatalf("service title = %q", service.title)
	}
}

这个测试没有数据库，也没有真实 service。它只验证 handler 是否正确解析请求，并调用依赖。

小结

httptest 让 Go HTTP handler 测试变得很轻。你可以用 httptest.NewRequest 构造请求，用 httptest.NewRecorder 捕获响应，检查状态码、响应头和 JSON 内容。测试不需要启动端口，也不需要真实网络。

Handler 测试最适合覆盖 HTTP 边界：方法不允许、请求体非法、参数缺失、依赖返回错误、成功响应格式。业务规则本身应该更多放在 service 测试里，handler 测试不要变成大型端到端测试。

当接口有自动化测试保护后，你改路由、响应格式和错误处理时会更有底。Go 把 handler 设计成普通函数，这让测试天然简单，要把这个优势用起来。

常见问题与解答

handler 测试要不要启动真实端口？

不需要。httptest.NewRecorder 足够测试 handler 的逻辑。真实端口测试留给集成测试。

怎么测试 handler 里的 context？

httptest.NewRequest 创建的请求带默认 context。可以用 .WithContext() 传入自定义 context：

ctx := context.WithValue(context.Background(), userIDKey{}, int64(42))
req := httptest.NewRequest(http.MethodGet, "/profile", nil).WithContext(ctx)

怎么测试 multipart 上传？

用 mime/multipart 包构造请求 body，再用 httptest.NewRequest 传入：

var b bytes.Buffer
writer := multipart.NewWriter(&b)
part, _ := writer.CreateFormFile("file", "test.txt")
part.Write([]byte("hello"))
writer.Close()
req := httptest.NewRequest(http.MethodPost, "/upload", &b)
req.Header.Set("Content-Type", writer.FormDataContentType())

handler 测试最佳实践

每个 handler 一个测试函数：不要在一个测试里测很多 handler。每个测试只关心一个 handler 的一种行为。

用子测试覆盖多个场景：

func TestCreateArticle(t *testing.T) {
    cases := []struct {
        name       string
        body       string
        wantStatus int
    }{
        {"valid", `{"title":"hello"}`, http.StatusCreated},
        {"empty title", `{"title":""}`, http.StatusBadRequest},
        {"bad json", `{title}`, http.StatusBadRequest},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodPost, "/articles", strings.NewReader(c.body))
            rec := httptest.NewRecorder()
            handler(rec, req)
            if rec.Code != c.wantStatus {
                t.Fatalf("status = %d", rec.Code)
            }
        })
    }
}

测试中间件：中间件测试和 handler 测试一样。传入一个假的 next handler，验证中间件是否正确包装：

func TestLoggingMiddleware(t *testing.T) {
    var called bool
    next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        called = true
        w.WriteHeader(http.StatusOK)
    })

    req := httptest.NewRequest(http.MethodGet, "/", nil)
    rec := httptest.NewRecorder()
    logging(next).ServeHTTP(rec, req)

    if !called {
        t.Fatal("next not called")
    }
}

实践练习

完成以下练习以巩固所学知识：

阅读 Go 官方文档相关章节
编写一个完整的示例程序
为示例程序编写单元测试
使用 go test 和 go benchmark 验证实现
尝试优化内存分配和运行时间

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

函数是否处理了所有 error 返回值
并发代码是否有明确的退出路径和 WaitGroup
用户输入是否经过校验和清洗
敏感配置是否通过环境变量或加密存储注入
测试是否覆盖了正常路径和至少一个错误路径
日志是否包含足够的上下文信息但不泄露敏感数据
接口设计是否符合最小接口原则

CI/CD 集成建议

每次提交前运行 go fmt ./...
CI 中运行 go vet ./... 和 golangci-lint run
单元测试使用 go test -race ./... 检测数据竞争
关键路径的 benchmark 加入回归测试
使用 go mod verify 确保依赖完整性

性能调优检查点

使用 pprof 分析 CPU 和内存使用
关注 benchmark 的 allocs/op，减少高频路径的堆分配
检查数据库查询是否使用索引
确认外部 HTTP 调用有合理的超时设置
缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

goroutine 和线程的区别
channel 的缓冲和非缓冲用法
defer 的执行顺序和与返回值的关系
map 的并发不安全性和解决方案
interface 的隐式实现和类型断言
slice 的底层数组和 append 机制
GC 的基本原理和调优参数
context 的使用场景和超时控制
error 的包装和 errors.Is/errors.As
sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

把文中所有示例代码在自己的机器上跑一遍
给示例代码补充错误分支的测试用例
尝试基于本文内容构建一个小型完整项目
在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

Go 官方网站：https://go.dev/
Go 标准库文档：https://pkg.go.dev/std
Go by Example：https://gobyexample.com/
Effective Go：https://go.dev/doc/effective_go
Go 常见问题：https://go.dev/doc/faq
Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页