85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
# 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`）：
|
||
|
||
```go
|
||
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：
|
||
|
||
```go
|
||
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`）：
|
||
|
||
```go
|
||
// 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）：
|
||
|
||
```json
|
||
{ "code": 102000, "message": "SUCCESS", "data": { ... } }
|
||
```
|
||
|
||
失敗（HTTP 依 category，如 404；Member scope 範例）：
|
||
|
||
```json
|
||
{
|
||
"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`。
|