Go / 系统课时

验证请求字段与业务约束

验证请求字段与业务约束

本篇解决 JSON 已成功解析后“值是否可接受”的问题:把必填、范围、枚举和字段间关系集中验证,返回能定位到具体字段的错误,同时把解析失败、字段验证失败和依赖业务状态的冲突分开处理。

学习目标

  • 为必填、数值范围、枚举和字段间关系设计明确验证规则
  • 收集结构化字段错误,让客户端能定位并修正输入
  • 区分 JSON 解析失败、请求字段验证失败与运行时业务冲突

先划清三类失败边界

请求进入处理器后,可以按“解析 → 字段验证 → 业务状态检查”依次推进。解析只回答“数据能否成为目标结构体”,字段验证回答“这组值本身是否满足接口契约”,而余额不足、资源已冻结等依赖当前系统状态的问题应由业务层判断。

请求失败边界流程

把这些失败混成一个“参数错误”,客户端就无法判断该修 JSON、修字段还是处理当前业务状态。状态码并非只有一种设计,但同一 API 应保持一致语义。

用一个主流程验证三层约束

下面的完整程序把 HTTP 处理器里最容易混在一起的逻辑提取成 process:先解析 JSON,再执行确定性的字段规则,最后模拟依赖当前账户状态的业务检查。字段错误一次收集,业务冲突则单独返回。

go
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"}`)
}

预期输出

text
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、修字段,还是提示用户处理当前业务状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

验证请求字段与业务约束

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通