74 lines
1.9 KiB
Markdown
74 lines
1.9 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`）：
|
|||
|
|
|
|||
|
|
```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
|
|||
|
|
}
|
|||
|
|
data, err := l.GetUser(&req)
|
|||
|
|
response.Write(r.Context(), w, data, err)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
無 request 的 API（如 `GET /health`）不會生成 Parse 區塊，屬正常行為。
|
|||
|
|
|
|||
|
|
在 `main` 可設定驗證錯誤使用的 scope：
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
response.RequestErrScope = code.Facade
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`.api` 的 request struct 可加 `validate:` tag 或實作 `Validate() error`，由 go-zero `httpx.Parse` 觸發。
|
|||
|
|
|
|||
|
|
## Logic 範例
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
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）：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{ "code": 0, "message": "SUCCESS", "data": { ... } }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
失敗（HTTP 依 category，如 404）：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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`。
|