Go 如何写一个优雅的Handler?

昨天同事问我："为什么你的 handler 函数比业务逻辑还长？"我沉默了三秒，默默删掉了 40 行样板代码。

你是不是也见过这种场景：一个接口，先解码、再校验、转类型、调服务、最后编码返回。五个步骤，行云流水。然后下一个接口，再来一遍，只是变量名从 user 变成了 order。再然后…你的 handlers/ 目录像极了俄罗斯套娃，拆开一层，里面还是那套熟悉的"管道代码"。

今天聊个简单粗暴的方案：用泛型把重复的"管道工"打包，让 handler 只干一件事——调用业务。

先看痛点：这代码怎么越写越像复印机？

// HTTP handler 示例（简化版）
func handleGreet(w http.ResponseWriter, r *http.Request) {
    // ① 解码：字节 → 结构体
    var req ReqGreet
    json.NewDecoder(r.Body).Decode(&req)  // 每个 handler 都要写
    
    // ② 校验：业务规则
    if req.UserID == 0 {  // 每个 handler 都要写
        http.Error(w, "bad request", 400)
        return
    }
    
    // ③ 转类型：传输层 → 领域层
    in := GreetIn{UserID: req.UserID}  // 每个 handler 都要写
    
    // ④ 调用业务（终于！这才是我想写的）
    out, _ := svc.Greet(r.Context(), in)  // ✨ 核心业务只有这一行
    
    // ⑤ 编码返回
    json.NewEncoder(w).Encode(out)  // 每个 handler 都要写
}

发现问题没？5 步里 4 步是"搬运工"的活，只有第④步是真正的业务。更扎心的是：这些搬运代码，每个接口、每个协议（HTTP/gRPC）都要重写一遍。

这就像开奶茶店：每家店都要重新教员工"怎么封口、怎么贴标签"，而不是把封口机做成标准设备。

解决方案：给"管道工"发统一工装

核心思路超简单：既然每个接口的管道逻辑都一样，那就写一个通用适配器 Wrap，把重复劳动一键打包。

第一步：业务函数保持纯净

// 领域层：不依赖 HTTP/gRPC，纯纯的业务逻辑
func (s *Service) Greet(ctx context.Context, in GreetIn) (GreetOut, error) {
    user, _ := s.users.Get(in.UserID)  // 查用户
    msg := "hey " + user.Name + "!"    // 拼问候语
    return GreetOut{Message: msg}, nil  // 返回结果
}

看，没有 http.ResponseWriter，没有 json，没有 protobuf。想怎么测就怎么测，想怎么复用就怎么复用。

第二步：写一个"万能包装器"（泛型登场✨）

// 简化版 Wrap：把管道逻辑打包成函数
func Wrap[In, Out any](
    decode func(*http.Request) (In, error),      // ① 怎么解码
    business func(context.Context, In) (Out, error), // ② 业务函数（核心！）
    encode func(http.ResponseWriter, Out) error, // ③ 怎么编码
) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        in, _ := decode(r)           // 自动解码
        out, _ := business(r.Context(), in)  // 调用你的业务
        encode(w, out)               // 自动编码返回
    })
}

第三步：注册路由时，一行搞定

// 原来：写 30 行样板代码
// 现在：3 行搞定
mux.Handle("POST /greet", Wrap(
    decodeGreet,   // 告诉 Wrap 怎么解码
    svc.Greet,     // 你的核心业务（复用！）
    encodeGreet,   // 告诉 Wrap 怎么编码
))

真实收益：我重构后的"真香"时刻

三年前我写过一个用户服务，20+ 个接口，支持 HTTP + gRPC。当时觉得"每个 handler 写一遍验证也没啥"，直到：

🔸 改一个校验规则：要改 40 个文件（20 接口 × 2 协议）
🔸 新人入职：第一周不是在写业务，是在背"我们的 decode 规范"
🔸 写测试：每个 handler 都要测 decode 失败、validate 失败、encode 失败…

用 Wrap 模式重构后：

• ✅ 新增接口：从"写 50 行样板 +20 行业务"变成"写 10 行 decode/encode +20 行业务"
• ✅ 改校验逻辑：改一处，所有接口自动生效
• ✅ 测试分层：业务逻辑用单元测试（无 transport），管道逻辑每个 transport 只测一次 Wrap

最爽的是类型安全：Go 泛型保证 decode 返回的类型一定能传给业务函数，业务函数返回的类型一定能被 encode 处理。编译期检查，比运行时 panic 友好一万倍。

避坑指南：抽象不是"为了优雅而优雅"

分享几个我踩过的坑，帮你少走弯路：

🔹 Validate 要"可选"：不是所有请求都需要校验。用类型断言 any(in).(validator) 很聪明——有 Validate() 方法才执行，没有就跳过。别搞成"所有结构体必须实现 Validate"。

🔹 错误处理要统一：把"领域错误"（如 UserNotFound）映射到 HTTP 状态码/gRPC code 的逻辑，集中管理。避免每个 handler 自己"猜"该返回 404 还是 400。

🔹 别把 Wrap 写成"瑞士军刀"：有人喜欢把路由匹配、限流、熔断都塞进 Wrap，结果 Wrap 比业务逻辑还复杂。记住：好的抽象是"单一职责"，不是"一个函数解决所有问题"。

写到这里，突然想起《禅与摩托车维修艺术》里的一句话：“当你组装一台摩托车时，重要的不是拧紧多少颗螺丝，而是理解每颗螺丝为什么在那里。”

我们的 Wrap 模式，本质上是把"怎么做"（how）和"做什么"（what）分开：

• decode/encode 解决"怎么把字节变成领域对象"（how）
• svc.Greet 解决"用户打招呼这个业务要做什么"（what）

这种分离带来的不仅是代码复用，更是认知减负。当新人看 svc.Greet 时，他不需要关心这是 HTTP 还是 gRPC 请求，不需要知道 JSON 字段叫 user_id 还是 userId。他只需要理解：输入一个用户 ID，输出一个问候语。

这中设计也符合了那句老话：Handler Thin，Service Fat（Handler 越薄越好，业务全部放 Service）