Go Mux开发中如何减少重复代码 统一返回固定响应结构

常见的重复代码消除实践 #

你之前封装效果不好，核心问题是只做了半段逻辑的封装，没有把固定不变的全流程收口，资深Go开发者一般会按从简到繁的梯度做封装，完全消除这类重复：

• 第一层：封装全流程统一响应工具函数
  不要只封装序列化单一步骤，要把「设置响应头、写入状态码、组装通用响应结构、序列化、写入响应体」这几个完全固定的步骤全部放进工具函数内部，外部只需要传入每次变动的核心参数即可。注意要先设置Content-Type响应头再调用WriteHeader，避免net/http自动嗅探返回错误的头信息，序列化直接用json.NewEncoder写入响应流，比先Marshal成字节切片再Write少一次内存拷贝，效率更高。
  示例代码：

  func JSON(rw http.ResponseWriter, status int, msg string, data any) {
      rw.Header().Set("Content-Type", "application/json")
      rw.WriteHeader(status)
      resp := responses.UserResponse{
          Status:  status,
          Message: &msg,
          Data:    data,
      }
      if err := json.NewEncoder(rw).Encode(resp); err != nil {
          log.Printf("response encode failed: %v", err)
      }
  }
  

  封装完成后，你原来的错误分支只需要一行代码就能完成所有逻辑：

  if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
      JSON(rw, http.StatusBadRequest, "error", map[string]any{"error": err.Error()})
      return
  }
  

• 第二层：统一错误处理中间件收口错误逻辑
  如果项目里接口数量多，可以进一步把HTTP处理函数的签名改成返回error的形式，套一层全局错误处理中间件。业务Handler里只需要处理正常逻辑，遇到错误直接return，由中间件统一识别错误类型、匹配对应HTTP状态码、组装返回格式，业务代码里甚至不用手动调用响应工具函数写错误返回。Go 1.18+版本还可以搭配泛型把请求体绑定的逻辑也封装成通用工具，连json.Decode的重复代码都可以完全消掉。
  核心示例：

  // 自定义业务错误类型，携带状态码和错误详情
  type AppError struct {
      Status int
      Detail string
      Err    error
  }
  func (e *AppError) Error() string { return e.Detail }
  
  // 带错误返回的Handler签名
  type AppHandler func(rw http.ResponseWriter, r *http.Request) error
  
  // 全局错误处理包装器
  func WrapHandler(handler AppHandler) http.HandlerFunc {
      return func(rw http.ResponseWriter, r *http.Request) {
          if err := handler(rw, r); err != nil {
              var appErr *AppError
              if errors.As(err, &appErr) {
                  JSON(rw, appErr.Status, "error", map[string]any{"error": appErr.Detail})
                  return
              }
              // 未知错误统一打日志返回500，避免泄露内部敏感信息
              log.Printf("internal error: %v", err)
              JSON(rw, http.StatusInternalServerError, "error", map[string]any{"error": "internal server error"})
          }
      }
  }
  
  // 泛型请求体绑定工具
  func BindJSON[T any](r *http.Request) (T, error) {
      var data T
      if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
          return data, &AppError{Status: http.StatusBadRequest, Detail: "invalid request body", Err: err}
      }
      return data, nil
  }
  

  最终业务层的代码会非常简洁，完全没有重复的响应组装逻辑：

  func CreateUser(rw http.ResponseWriter, r *http.Request) error {
      user, err := BindJSON[User](r)
      if err != nil {
          return err
      }
      // 执行业务逻辑...
      return JSON(rw, http.StatusOK, "success", user)
  }
  

这类代码重复的可接受边界 #

• 项目初期、接口总量很少的时候，直接写重复逻辑是可接受的，不用上来就做过度封装。毕竟封装会引入一层间接调用，调试时需要多跳转一层，初期业务逻辑变动快的时候，硬写反而更直观、改起来更快。
• 一旦同类重复代码在项目里出现超过3处，尤其是后续需要全局调整响应格式（比如给所有响应加链路ID、统一修改错误字段结构）的时候，散落在各处的重复代码会带来极高的修改成本，还很容易出现漏改导致的格式不一致问题，这时候就必须做统一封装。
• 封装时要避免过度设计：不用为了覆盖不存在的场景给工具函数加十几项可选配置，只要把完全固定的公共逻辑收口，可变的状态码、消息、数据通过参数传入即可，过度复杂的封装反而会比重复代码更难维护。

内容的提问来源于stack exchange，提问作者Alireza