Go / 系统课时
实现路由与处理器层
实现路由与处理器层
API 契约确定后,处理器应只承担 HTTP 协议适配:识别路由、解析并验证输入、调用业务服务,再把结果编码成响应。本节用 Go 标准库实现一条可运行的创建任务链路,并通过接口注入把业务逻辑与 HTTP 层解耦。
学习目标
- 使用 Go 1.22+ 的
ServeMux方法路由将请求分发到处理器 - 将 JSON 解析、参数验证、业务调用和响应编码拆成清晰边界
- 通过接口注入业务服务,让处理器可以独立验证和测试
划分处理链路
这条链路可以拆成四个连续边界:路由只判断“哪个方法和路径交给谁”,处理器负责 HTTP 输入输出,校验函数负责请求约束,TaskService 承担创建任务的业务动作。业务层不认识 http.ResponseWriter,HTTP 层也不直接访问数据库。

这种分层的关键不是增加文件数量,而是限制依赖方向。处理器可以决定状态码、响应头和 JSON 形状,但“任务能否创建、如何持久化、是否需要事务”应由服务层决定。
实现可替换的处理器
下面的完整程序不启动监听端口,而是用 httptest 构造请求和响应记录器,直接把请求交给路由。这样既能验证 ServeMux 的方法与路径匹配,也能演示处理器如何通过 TaskService 接口调用业务逻辑。
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"net/http/httptest"
"strings"
)
type CreateTaskInput struct {
Title string `json:"title"`
Priority string `json:"priority"`
}
type Task struct {
ID string `json:"id"`
Title string `json:"title"`
Priority string `json:"priority"`
Status string `json:"status"`
}
type TaskService interface {
Create(context.Context, CreateTaskInput) (Task, error)
}
type memoryTaskService struct{}
func (memoryTaskService) Create(_ context.Context, in CreateTaskInput) (Task, error) {
return Task{ID: "t-001", Title: in.Title, Priority: in.Priority, Status: "pending"}, nil
}
type app struct {
tasks TaskService
}
func (a app) routes() http.Handler {
router := http.NewServeMux()
router.HandleFunc("POST /v1/tasks", a.handleCreateTask)
return router
}
func (a app) handleCreateTask(w http.ResponseWriter, r *http.Request) {
in, err := decodeCreateTask(r)
if err != nil {
writeError(w, http.StatusBadRequest, "INVALID_ARGUMENT", err.Error())
return
}
if err = validateCreateTask(&in); err != nil {
writeError(w, http.StatusBadRequest, "INVALID_ARGUMENT", err.Error())
return
}
task, err := a.tasks.Create(r.Context(), in)
if err != nil {
writeError(w, http.StatusInternalServerError, "INTERNAL", "internal server error")
return
}
w.Header().Set("Location", "/v1/tasks/"+task.ID)
writeJSON(w, http.StatusCreated, task)
}
func decodeCreateTask(r *http.Request) (CreateTaskInput, error) {
defer r.Body.Close()
var in CreateTaskInput
decoder := json.NewDecoder(r.Body)
decoder.DisallowUnknownFields()
if err := decoder.Decode(&in); err != nil {
return in, fmt.Errorf("invalid JSON: %w", err)
}
// 第二次解码只允许遇到 EOF,借此拒绝多个顶层 JSON 值。
if err := decoder.Decode(new(struct{})); err != io.EOF {
return in, fmt.Errorf("request body must contain one JSON object")
}
return in, nil
}
func validateCreateTask(in *CreateTaskInput) error {
in.Title = strings.TrimSpace(in.Title)
if len(in.Title) == 0 || len(in.Title) > 120 {
return fmt.Errorf("title must contain 1 to 120 characters")
}
switch in.Priority {
case "low", "normal", "high":
return nil
default:
return fmt.Errorf("priority must be low, normal, or high")
}
}
func writeError(w http.ResponseWriter, status int, code, message string) {
writeJSON(w, status, map[string]any{
"error": map[string]string{"code": code, "message": message},
})
}
func writeJSON(w http.ResponseWriter, statusCode int, value any) {
h := w.Header()
h.Set("Content-Type", "application/json")
w.WriteHeader(statusCode)
_ = json.NewEncoder(w).Encode(value)
}
func main() {
handler := app{tasks: memoryTaskService{}}.routes()
request := httptest.NewRequest(
"POST",
"/v1/tasks",
strings.NewReader(`{"title":"ship report","priority":"high"}`),
)
response := httptest.NewRecorder()
handler.ServeHTTP(response, request)
fmt.Printf("status=%d\n", response.Code)
fmt.Printf("location=%s\n", response.Header().Get("Location"))
fmt.Printf("body=%s", response.Body.String())
}预期输出
status=201
location=/v1/tasks/t-001
body={"id":"t-001","title":"ship report","priority":"high","status":"pending"}固定 ID 只用于让示例输出稳定可复现;接入真实服务后,ID 应由业务层或存储层生成。httptest.NewRecorder 只负责记录本次处理器写出的状态码、响应头和响应体,适合这里的最小验证。
收紧解析与验证边界
JSON 解码器启用未知字段拒绝后,客户端把 priority 拼错成其他字段名时会立即得到 400。第一次解码读取任务对象,第二次解码只用于确认请求体已经结束,从而拒绝连续提交两个顶层 JSON 值。
输入验证也应在调用 TaskService 之前完成。这样非法标题或非法优先级不会进入业务层;而服务内部错误统一映射为稳定的 500 响应,避免把数据库错误、内部路径或实现细节直接暴露给客户端。
验收路由边界
主示例已经覆盖成功路径:POST /v1/tasks 命中处理器,返回 201、Location 和任务 JSON。继续补自动化测试时,应重点覆盖非法 JSON、未知字段和非法 priority 返回 400 且服务不被调用,以及服务失败返回 500。
当路由只负责分发、处理器只负责 HTTP 适配、业务能力通过接口注入时,后续加入持久化、幂等控制或集成测试都不需要推翻现有 HTTP 层边界。