template-monorepo/internal/response

HTTP 統一回應

分工

層	職責
Logic	return data, err（err 為 *errs.Error 或標準 error）
Handler	response.Write(ctx, w, data, err)
.api	只描述 data 的型別（如 PingData），不描述外層 Status

Handler 範例

有 request 的 API，模板會自動生成 參數綁定 + 驗證（httpx.Parse）：

var req types.GetUserReq
if err := httpx.Parse(r, &req); err != nil {
    response.Write(r.Context(), w, nil, response.WrapRequestError(err)) // → 400 InputInvalidFormat
    return
}
data, err := l.GetUser(&req)
response.Write(r.Context(), w, data, err)

無 request 的 API（如 GET /health）不會生成 Parse 區塊，屬正常行為。

在 main 可設定驗證錯誤使用的 scope：

response.RequestErrScope = code.Facade

.api 的 request struct 可加 validate: tag 或實作 Validate() error，由 go-zero httpx.Parse 觸發。

Logic 範例

var errb = errs.For(code.Facade)

func (l *XLogic) GetUser(req *types.GetUserReq) (*types.UserVO, error) {
    if req.Id == "" {
        return nil, errb.InputMissingRequired("id")
    }
    // ...
    return vo, nil
}

回應 JSON

成功（HTTP 200）：

{ "code": 0, "message": "SUCCESS", "data": { ... } }

失敗（HTTP 依 category，如 404）：

{
  "code": 10301000,
  "message": "user not found",
  "error": { "biz_code": "10301000", "scope": 10, "category": 301, "detail": 0 }
}

goctl 模板（可選）

專案模板路徑：generate/goctl/api/handler.tpl（不是 api/gogen/）。

make gen-api 已帶 -home generate/goctl，新建的 handler 會自動使用 response.Write。

注意：已存在的 handler 檔案 goctl 不會覆寫（會顯示 exists, ignored）。新增 API 沒問題；若要重生成舊 handler，需先刪除該檔再 make gen-api。