Go / 系统课时
验证请求字段与业务约束
验证请求字段与业务约束
本篇解决 JSON 已成功解析后“值是否可接受”的问题:把必填、范围、枚举和字段间关系集中验证,返回能定位到具体字段的错误,同时把解析失败、字段验证失败和依赖业务状态的冲突分开处理。
学习目标
- 为必填、数值范围、枚举和字段间关系设计明确验证规则
- 收集结构化字段错误,让客户端能定位并修正输入
- 区分 JSON 解析失败、请求字段验证失败与运行时业务冲突
先划清三类失败边界
请求进入处理器后,可以按“解析 → 字段验证 → 业务状态检查”依次推进。解析只回答“数据能否成为目标结构体”,字段验证回答“这组值本身是否满足接口契约”,而余额不足、资源已冻结等依赖当前系统状态的问题应由业务层判断。

把这些失败混成一个“参数错误”,客户端就无法判断该修 JSON、修字段还是处理当前业务状态。状态码并非只有一种设计,但同一 API 应保持一致语义。
用一个主流程验证三层约束
下面的完整程序把 HTTP 处理器里最容易混在一起的逻辑提取成 process:先解析 JSON,再执行确定性的字段规则,最后模拟依赖当前账户状态的业务检查。字段错误一次收集,业务冲突则单独返回。
package main
import (
"encoding/json"
"fmt"
"strings"
)
type transferRequest struct {
SourceAccount string `json:"sourceAccount"`
TargetAccount string `json:"targetAccount"`
Amount int64 `json:"amount"`
Currency string `json:"currency"`
}
type violation struct {
Field string `json:"field"`
Rule string `json:"rule"`
Detail string `json:"detail"`
}
type apiError struct {
Error string `json:"error"`
Violations []violation `json:"violations,omitempty"`
}
type accepted struct {
Status string `json:"status"`
}
func validateTransfer(in transferRequest) []violation {
source := strings.TrimSpace(in.SourceAccount)
target := strings.TrimSpace(in.TargetAccount)
var problems []violation
// 独立字段规则可以一次收集,减少客户端反复提交。
if source == "" {
problems = append(problems, violation{"sourceAccount", "required", "sourceAccount 不能为空"})
}
if target == "" {
problems = append(problems, violation{"targetAccount", "required", "targetAccount 不能为空"})
}
if in.Amount < 1 || in.Amount > 100000 {
problems = append(problems, violation{"amount", "range", "amount 必须在 1 到 100000 之间"})
}
if in.Currency != "CNY" && in.Currency != "USD" {
problems = append(problems, violation{"currency", "one_of", "currency 只能是 CNY 或 USD"})
}
// 只有基础字段有效时才检查跨字段关系,避免级联报错。
if source != "" && target != "" && source == target {
problems = append(problems, violation{"targetAccount", "different_from", "targetAccount 必须与 sourceAccount 不同"})
}
return problems
}
func checkBusiness(in transferRequest) *apiError {
if strings.TrimSpace(in.SourceAccount) == "A-FROZEN" {
return &apiError{Error: "source_account_frozen"}
}
return nil
}
func process(body string) (int, any) {
var in transferRequest
if err := json.Unmarshal([]byte(body), &in); err != nil {
return 400, apiError{Error: "invalid_request_body"}
}
if problems := validateTransfer(in); len(problems) > 0 {
return 422, apiError{Error: "validation_failed", Violations: problems}
}
if conflict := checkBusiness(in); conflict != nil {
return 409, *conflict
}
return 201, accepted{Status: "accepted"}
}
func runCase(name, body string) {
status, payload := process(body)
encoded, _ := json.Marshal(payload)
fmt.Printf("%s: %d %s\n", name, status, encoded)
}
func main() {
runCase("malformed", `{"sourceAccount":`)
runCase("invalid", `{"sourceAccount":"A-100","targetAccount":"A-100","amount":0,"currency":"EUR"}`)
runCase("conflict", `{"sourceAccount":"A-FROZEN","targetAccount":"B-200","amount":5000,"currency":"CNY"}`)
runCase("valid", `{"sourceAccount":"A-100","targetAccount":"B-200","amount":5000,"currency":"CNY"}`)
}预期输出
malformed: 400 {"error":"invalid_request_body"}
invalid: 422 {"error":"validation_failed","violations":[{"field":"amount","rule":"range","detail":"amount 必须在 1 到 100000 之间"},{"field":"currency","rule":"one_of","detail":"currency 只能是 CNY 或 USD"},{"field":"targetAccount","rule":"different_from","detail":"targetAccount 必须与 sourceAccount 不同"}]}
conflict: 409 {"error":"source_account_frozen"}
valid: 201 {"status":"accepted"}示例中的 400、422、409 和 201 是本接口采用的一套一致约定。接入真实处理器时,只需把 process 的状态码和载荷写回响应;业务状态检查仍应由服务层提供真实结果。
让字段错误既稳定又可定位
字段错误至少应包含稳定的字段名和机器可判断的规则码;detail 主要服务于人类阅读,不应成为客户端业务分支的唯一依据。一次返回多个彼此独立的问题,能减少“修一个再请求一次”的往返。
互相依赖的规则要避免级联报错。例如来源账户为空时,没有必要继续报告“来源与目标账户相同”。先检查参与关系的基础字段,再检查跨字段约束,错误更接近真正需要修复的问题。
不把业务状态塞进字段验证
字段验证应尽量是确定性的:相同输入在相同接口契约下得到相同结果。余额是否足够、账户是否冻结、优惠券是否已使用等依赖数据库或外部状态,应该放在业务层;当请求与当前资源状态冲突时,可按接口语义考虑 409。
这样分层后,处理器只负责串联步骤:解析失败立即返回解析错误;解析成功后运行字段验证并返回结构化问题;字段合法才进入业务状态检查。客户端也能据此决定是修 JSON、修字段,还是提示用户处理当前业务状态。