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 → svcCtx.Validator.ValidateAll）：

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

在 .api 的 request 欄位加 validate:"required,email" 等 tag，make gen-api 後會寫入 internal/types，無需在 Logic 再手動驗證。

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

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

response.RequestErrScope = code.Facade

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

進階驗證可使用 svcCtx.Validator.ValidateAll(&req)（gateway/internal/library/validate）。回傳的 validate.ValidationErrors 經 response.WrapRequestError 會映射為 400 InputInvalidFormat。

Logic 範例

各模組 logic / usecase 綁定對應 scope（不要一律用 code.Facade）：

// internal/logic/member/errors.go
var errb = errs.For(code.Member)

func (l *XLogic) GetUser(req *types.GetUserReq) (*types.UserVO, error) {
    out, err := l.svcCtx.MemberProfile.Get(...)
    if err != nil {
        return nil, err // Member scope 錯誤原樣傳遞
    }
    return vo, nil
}

回應 JSON

成功（HTTP 200）：

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

失敗（HTTP 依 category，如 404；Member scope 範例）：

{
  "code": 29301000,
  "message": "member not found",
  "error": { "biz_code": "29301000", "scope": 29, "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。