116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# 3.8 参数校验与错误上抛
|
||
|
||
:::tip 概述
|
||
校验在契约层用标签声明，错误在业务层用哨兵错误上抛——两头都不写手工 if。本页说明绑定优先级、校验标签用法与错误传播路径。
|
||
:::
|
||
|
||
## 绑定优先级
|
||
|
||
请求参数按固定顺序写入，**后写覆盖**：
|
||
|
||
```text
|
||
query（GET 参数） → body（JSON 体） → path（路径参数）
|
||
```
|
||
|
||
最终优先级表现为 **path > body > query**：同名字段以路径参数为准。每个字段同时带 `json`（body）与 `form`（query）标签即可参与两种来源绑定。
|
||
|
||
绑定引擎的入口在 `router.Bind` 包装函数内，handler 拿到的 req 已完成解析与校验。
|
||
|
||
## binding / msg 标签
|
||
|
||
校验读标准 `binding` 标签，错误消息取 `msg` 标签：
|
||
|
||
```go
|
||
// internal/model/dto/example.go
|
||
type ExampleDetailReq struct {
|
||
Id int64 `json:"id" binding:"required" msg:"缺少ID" dc:"记录ID"`
|
||
}
|
||
|
||
type ExampleBatchDeleteReq struct {
|
||
Ids []int64 `json:"ids" binding:"min=1" msg:"请选择要删除的记录" dc:"ID列表"`
|
||
}
|
||
|
||
// internal/model/dto/user.go（多规则 + 多消息示例）
|
||
type UserAddReq struct {
|
||
Username string `json:"username" binding:"required,min=2,max=30" msg:"请输入用户名;用户名长度需在2~30位"`
|
||
Password string `json:"password" binding:"required,min=6,max=32" msg:"请输入密码;密码长度需在6~32位"`
|
||
Mobile string `json:"mobile" binding:"omitempty,phone" msg:"手机号格式不正确"`
|
||
Email string `json:"email" binding:"omitempty,email" msg:"邮箱格式不正确"`
|
||
}
|
||
```
|
||
|
||
常用规则：
|
||
|
||
| 标签 | 含义 | 示例 |
|
||
|---|---|---|
|
||
| required | 必填（零值也算缺失） | `binding:"required"` |
|
||
| min / max | 数值/长度边界 | `binding:"min=1" msg:"请选择记录"` |
|
||
| oneof | 枚举取值 | `binding:"oneof=1 2"` |
|
||
| gte / lte | 大于等于 / 小于等于 | `binding:"gte=1,lte=500"` |
|
||
| omitempty | 空值放行（配合格式规则） | `binding:"omitempty,email"` |
|
||
| phone / email | 内置格式规则（本项目 validator 扩展） | `binding:"omitempty,phone"` |
|
||
|
||
**多消息映射**（utility/validator）：`msg` 以 `;` 分段与 `binding` 多规则**一一对应**（如 `required,min=2,max=30` ↔ `请输入用户名;用户名长度需在2~30位`）；只写一段时适用于全部规则；分段缺失按规则默认提示兜底。校验**快速失败**：返回第一条错误，消息含字段提示语。内嵌结构体（PageReq）由引擎递归校验。
|
||
|
||
校验失败时框架直接以统一信封返回，msg 即上述文案——**不需要 handler 做任何判断**。
|
||
|
||
## UnmarshalBody 逃生舱
|
||
|
||
文件上传等非 JSON 载荷，结构体实现 `UnmarshalBody(c *gin.Context) error` 即可接管解析：
|
||
|
||
```go
|
||
// internal/model/dto/example.go
|
||
func (r *ExampleImportReq) UnmarshalBody(c *gin.Context) error {
|
||
f, err := c.FormFile("file")
|
||
if err != nil {
|
||
return errors.New("请选择文件")
|
||
}
|
||
r.File = f
|
||
return nil
|
||
}
|
||
```
|
||
|
||
返回 error 即校验失败，同样走统一错误信封。
|
||
|
||
## 业务错误上抛
|
||
|
||
service / 钩子内业务失败一律返回 apperr 错误或哨兵错误，**原样上抛，不做包装**：
|
||
|
||
```go
|
||
// internal/service/auth.go（实际代码）
|
||
return nil, consts.CodeCaptchaError
|
||
return nil, consts.CodeUserDisabled
|
||
|
||
// internal/service/category.go（实际代码，格式化消息）
|
||
return apperr.Newf(consts.CodeParamError.Code(), "上级不能选择自己")
|
||
```
|
||
|
||
response 中间件捕获 error 后：
|
||
|
||
```text
|
||
apperr 错误 → 按其 code/msg 直接输出
|
||
普通 error → 映射为通用失败码，msg 取错误文本
|
||
panic → recovery 捕获，输出 500 信封并打错误栈日志
|
||
```
|
||
|
||
## 错误处理禁则
|
||
|
||
| 禁则 | 原因 |
|
||
|---|---|
|
||
| 在 handler 转发 HTTP 状态码 | 统一信封由 response 中间件负责 |
|
||
| 吞掉错误只记日志 | 上层与前端失去失败感知 |
|
||
| 包装后重复加前缀 | 钩子与 service 禁止 wrap，错误原样上抛 |
|
||
| 用 error 做流程控制 | 分支结果用返回值表达，error 只表示失败 |
|
||
|
||
## 编写检查清单
|
||
|
||
- [ ] 必填字段有 required + msg
|
||
- [ ] 零值合法的字段不加 required（等值过滤靠 EqFields 零值跳过）
|
||
- [ ] 文件字段实现 UnmarshalBody
|
||
- [ ] 业务失败返回哨兵/apperr，不 fmt.Errorf 包装
|
||
- [ ] 不在 handler 手写参数判断
|
||
|
||
## 下一步
|
||
|
||
→ [3.9 权限节点配置](/zh/guide/permission.html)
|