请求参数验证

核心框架通过 server_api/pkg/validate 统一处理 JSON、Query 和 URI 参数。管理端、用户端及插件 Controller 均使用相同入口，参数错误返回业务码 400 和字段级中文提示。

标签约定

type MemberSetStatusReq struct {
    ID     uint `json:"id" binding:"required" validate:"用户ID" comment:"用户ID"`
    Status int  `json:"status" binding:"required,oneof=1 2" validate:"目标状态" comment:"目标状态：1启用，2禁用"`
}

标签	说明
json / form / uri	请求字段名称
binding	required、oneof、min、max、email、url 等验证规则
validate	面向用户的字段语义，例如“用户ID”“目标状态”
comment	完整字段说明，可包含枚举值和补充规则

validate 从 comment 提取简洁的核心名称，不应写成完整错误句子。所有请求字段都需要该标签，即使字段当前没有 binding 规则。

Controller 使用

JSON 请求体和 GET 查询参数统一使用 Bind：

if err := requestvalidate.Bind(c, &req); err != nil {
    response.Fail(c, response.CodeErrParams, err.Error())
    return
}

URI 参数使用 BindURI。已经完成赋值的结构体可以使用 validate.Struct(&req) 再次校验。Controller 不应直接调用 Gin ShouldBind*，也不应使用“参数错误”覆盖验证器生成的语义化提示。

错误信息

规则	返回示例
required	登录账号不能为空
oneof=1 2	目标状态取值不正确
len=6	短信验证码长度必须为6
字符串 min=6	新密码长度不能少于6个字符
字符串 max=32	昵称长度不能超过32个字符
数组 min/max	日志ID列表至少包含1项 / 最多包含500项
email / url	邮箱格式不正确 / 插件主页地址必须是有效的URL地址

JSON 语法错误返回“请求参数格式错误”；JSON 类型不匹配时尽量返回对应字段“格式不正确”。为保持响应简洁，系统只返回第一条验证错误。

自定义规则

RegisterValidation 注册字段级规则，RegisterStructValidation 注册跨字段规则。注册必须发生在服务启动阶段、开始并发处理请求之前。规则仍写在 binding 中，字段文案仍由 validate 决定。

唯一性、数据库状态、登录用户权限等依赖外部状态的判断属于业务校验，应继续放在 Logic 层，不能塞进字段验证器。