Go / 系统课时

实现路由与处理器层

实现路由与处理器层

API 契约确定后,处理器应只承担 HTTP 协议适配:识别路由、解析并验证输入、调用业务服务,再把结果编码成响应。本节用 Go 标准库实现一条可运行的创建任务链路,并通过接口注入把业务逻辑与 HTTP 层解耦。

学习目标

  • 使用 Go 1.22+ 的 ServeMux 方法路由将请求分发到处理器
  • 将 JSON 解析、参数验证、业务调用和响应编码拆成清晰边界
  • 通过接口注入业务服务,让处理器可以独立验证和测试

划分处理链路

这条链路可以拆成四个连续边界:路由只判断“哪个方法和路径交给谁”,处理器负责 HTTP 输入输出,校验函数负责请求约束,TaskService 承担创建任务的业务动作。业务层不认识 http.ResponseWriter,HTTP 层也不直接访问数据库。

路由、处理器与业务服务的数据流

这种分层的关键不是增加文件数量,而是限制依赖方向。处理器可以决定状态码、响应头和 JSON 形状,但“任务能否创建、如何持久化、是否需要事务”应由服务层决定。

实现可替换的处理器

下面的完整程序不启动监听端口,而是用 httptest 构造请求和响应记录器,直接把请求交给路由。这样既能验证 ServeMux 的方法与路径匹配,也能演示处理器如何通过 TaskService 接口调用业务逻辑。

go
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())
}

预期输出

text
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 层边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现路由与处理器层

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通