golang

Go JSON 请求校验入门：不用框架也能写清楚规则

写 JSON API 时，校验是绕不开的。字段缺失、字符串太长、枚举值不合法、嵌套数组为空，这些都应该在进入业务逻辑前拦住。很多项目会使用校验库，这没问题；但初学者最好先理解不用框架时规则应该放在哪里、错误怎么组织。

PlumePHP 2025-06-19 9 分钟阅读 4379 字

本文用“创建项目”接口做例子，写一套轻量校验方式。目标不是造校验框架，而是让代码清楚、错误可读、测试容易。

请求结构

type CreateProjectRequest struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Visibility  string   `json:"visibility"`
	Tags        []string `json:"tags"`
}

规则：

name 必填，长度 3 到 60
description 最多 500
visibility 只能是 private 或 public
tags 最多 10 个，每个不超过 30

字段错误结构

type FieldError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

type ValidationErrors []FieldError

func (e ValidationErrors) Error() string {
	return "validation failed"
}

校验函数返回一个错误列表：

func (r CreateProjectRequest) Validate() error {
	var errs ValidationErrors

	name := strings.TrimSpace(r.Name)
	if name == "" {
		errs = append(errs, FieldError{Field: "name", Message: "名称不能为空"})
	} else if len([]rune(name)) < 3 || len([]rune(name)) > 60 {
		errs = append(errs, FieldError{Field: "name", Message: "名称长度必须在 3 到 60 之间"})
	}

	if len([]rune(r.Description)) > 500 {
		errs = append(errs, FieldError{Field: "description", Message: "描述不能超过 500 字"})
	}

	if r.Visibility != "private" && r.Visibility != "public" {
		errs = append(errs, FieldError{Field: "visibility", Message: "可见性只能是 private 或 public"})
	}

	if len(r.Tags) > 10 {
		errs = append(errs, FieldError{Field: "tags", Message: "标签最多 10 个"})
	}
	for i, tag := range r.Tags {
		if strings.TrimSpace(tag) == "" {
			errs = append(errs, FieldError{Field: fmt.Sprintf("tags[%d]", i), Message: "标签不能为空"})
		}
		if len([]rune(tag)) > 30 {
			errs = append(errs, FieldError{Field: fmt.Sprintf("tags[%d]", i), Message: "标签不能超过 30 字"})
		}
	}

	if len(errs) > 0 {
		return errs
	}
	return nil
}

这里使用 []rune 计算中文长度，避免 len(string) 按字节计算导致中文长度不符合直觉。

Handler 中使用

func (h *ProjectHandler) Create(w http.ResponseWriter, r *http.Request) {
	var req CreateProjectRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		writeError(w, http.StatusBadRequest, "invalid_json", "JSON 格式不正确")
		return
	}
	if err := req.Validate(); err != nil {
		var validation ValidationErrors
		if errors.As(err, &validation) {
			writeJSON(w, http.StatusBadRequest, map[string]any{
				"error": map[string]any{
					"code":   "validation_failed",
					"fields": validation,
				},
			})
			return
		}
		writeError(w, http.StatusBadRequest, "invalid_request", err.Error())
		return
	}
	// 调用 service
}

前端拿到字段错误后，可以把错误显示在对应表单项旁边。这比只返回“参数错误”有用得多。

规范化和校验分开

有些字段需要 trim 或去重。可以先规范化：

func (r *CreateProjectRequest) Normalize() {
	r.Name = strings.TrimSpace(r.Name)
	r.Visibility = strings.TrimSpace(strings.ToLower(r.Visibility))
	for i := range r.Tags {
		r.Tags[i] = strings.TrimSpace(r.Tags[i])
	}
}

Handler：

req.Normalize()
if err := req.Validate(); err != nil {
	// ...
}

规范化会改变输入值，校验只判断是否合法。两者分开，代码更容易理解。

测试校验规则

func TestCreateProjectRequestValidate(t *testing.T) {
	tests := []struct {
		name    string
		req     CreateProjectRequest
		wantErr bool
	}{
		{name: "valid", req: CreateProjectRequest{Name: "Go 工具", Visibility: "private"}},
		{name: "missing name", req: CreateProjectRequest{Visibility: "private"}, wantErr: true},
		{name: "bad visibility", req: CreateProjectRequest{Name: "Go 工具", Visibility: "team"}, wantErr: true},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			err := tt.req.Validate()
			if tt.wantErr && err == nil {
				t.Fatal("expected error")
			}
			if !tt.wantErr && err != nil {
				t.Fatalf("unexpected error: %v", err)
			}
		})
	}
}

校验函数不依赖 HTTP，很容易测试。复杂校验也应该尽量放在这种普通函数里，而不是藏在 handler 深处。

小结

Go JSON 请求校验可以从简单函数开始。请求结构负责表达输入，Normalize 做清理，Validate 返回字段错误列表，handler 把它映射成统一 JSON 响应。必填、长度、枚举、数组元素都可以清楚写出来。

校验库能减少样板代码，但不能替你决定业务规则。先把规则写清楚，再考虑是否引入库。入门阶段理解这个边界，比记住某个框架标签更重要。

嵌套结构的校验扩展

实际 API 往往有嵌套对象和数组：

type CreateTeamRequest struct {
	Name    string   `json:"name"`
	Leader  UserRef  `json:"leader"`
	Members []UserRef `json:"members"`
}

type UserRef struct {
	Email string `json:"email"`
	Role  string `json:"role"`
}

func (r CreateTeamRequest) Validate() error {
	var errs ValidationErrors
	if strings.TrimSpace(r.Name) == "" {
		errs = append(errs, FieldError{Field: "name", Message: "团队名称不能为空"})
	}
	if err := r.Leader.Validate(); err != nil {
		if ve, ok := err.(ValidationErrors); ok {
			for _, e := range ve {
				e.Field = "leader." + e.Field
				errs = append(errs, e)
			}
		}
	}
	if len(r.Members) == 0 {
		errs = append(errs, FieldError{Field: "members", Message: "至少需要一名成员"})
	}
	for i, m := range r.Members {
		if err := m.Validate(); err != nil {
			if ve, ok := err.(ValidationErrors); ok {
				for _, e := range ve {
					e.Field = fmt.Sprintf("members[%d].%s", i, e.Field)
					errs = append(errs, e)
				}
			}
		}
	}
	if len(errs) > 0 {
		return errs
	}
	return nil
}

嵌套校验的关键是用路径前缀定位错误。leader.email 比只说 “email 格式错误” 更清楚。

校验库与手写校验的对比

Go 社区常见的校验库有：

go-playground/validator：标签驱动，功能丰富
ozzo-validation：函数式 API，类型安全
hand-written：就是本文的方式，零依赖

手写校验的好处是完全可控，错误信息可以本地化，规则可以动态组合。校验库的好处是减少样板代码。建议：先用本文方式理解校验的本质，再决定是否引入库。

// go-playground/validator 示例（对比）
type User struct {
	Name  string `validate:"required,min=3,max=60"`
	Email string `validate:"required,email"`
	Age   int    `validate:"gte=0,lte=120"`
}

统一响应格式

错误响应应该有统一结构：

type APIResponse struct {
	Success bool        `json:"success"`
	Data    any         `json:"data,omitempty"`
	Error   *APIError   `json:"error,omitempty"`
}

type APIError struct {
	Code    string      `json:"code"`
	Message string      `json:"message"`
	Fields  []FieldError `json:"fields,omitempty"`
}

func WriteValidationError(w http.ResponseWriter, errs ValidationErrors) {
	resp := APIResponse{
		Success: false,
		Error: &APIError{
			Code:    "validation_failed",
			Message: "请求参数校验失败",
			Fields:  errs,
		},
	}
	w.WriteHeader(http.StatusBadRequest)
	json.NewEncoder(w).Encode(resp)
}

前端拿到这个结构后，可以按 field 把错误显示在对应输入框下方。

常见校验规则清单

必填：字符串非空、指针非 nil、切片非空
长度：最小长度、最大长度（注意 []rune 和 len 的区别）
范围：数字的最小值和最大值
枚举：值必须在指定列表中
格式：邮箱、URL、手机号、UUID 等正则校验
唯一性：数组中元素是否重复
关联：两个字段的依赖关系（如密码和确认密码一致）
业务规则：用户年龄不能大于当前年份减去某个值

校验参数的性能影响

简单校验（字符串长度、数字范围）几乎没有性能开销。复杂校验（正则、数据库查询）要控制执行次数。不要在循环里做 N+1 查询，可以先把需要查数据库的规则放到 service 层。

规则组合与校验管道

复杂校验往往由多个独立规则组合而成。可以设计一个规则管道：

type Rule func(x any) (FieldError, bool)

func Required() Rule {
    return func(x any) (FieldError, bool) {
        if x == nil {
            return FieldError{Message: "必填"}, false
        }
        if s, ok := x.(string); ok && strings.TrimSpace(s) == "" {
            return FieldError{Message: "不能为空"}, false
        }
        return FieldError{}, true
    }
}

func MinLen(n int) Rule {
    return func(x any) (FieldError, bool) {
        s, ok := x.(string)
        if !ok {
            return FieldError{Message: "不是字符串"}, false
        }
        if len([]rune(s)) < n {
            return FieldError{Message: fmt.Sprintf("最少 %d 个字符", n)}, false
        }
        return FieldError{}, true
    }
}

func ValidateField(field string, value any, rules ...Rule) []FieldError {
    var errs []FieldError
    for _, rule := range rules {
        if ferr, ok := rule(value); !ok {
            ferr.Field = field
            errs = append(errs, ferr)
        }
    }
    return errs
}

使用：

func (r CreateProjectRequest) ValidatePipe() error {
    var errs ValidationErrors
    errs = append(errs, ValidateField("name", r.Name, Required(), MinLen(3))...)
    errs = append(errs, ValidateField("visibility", r.Visibility, Required())...)
    if len(errs) > 0 {
        return errs
    }
    return nil
}

原子规则的好处是规则之间没有顺序依赖，每个规则只检查一件事。在大型项目中，规则可以做成可配置化，不改动业务代码就能调整校验策略。

校验与国际化（i18n）

错误信息最终要展示给用户，中文项目和英文项目的措辞差异很大。可以抽离消息模板：

type Messages struct {
    Required       string
    TooShort       string
    TooLong        string
    InvalidFormat  string
    AllowedValues  string
}

func DefaultMessages() Messages {
    return Messages{
        Required:      "不能为空",
        TooShort:      "长度不能少于 %d",
        TooLong:       "长度不能多于 %d",
        InvalidFormat: "格式不正确",
        AllowedValues: "只能是 %s",
    }
}

校验函数接收消息模板，同一套逻辑可以输出多语言错误：

func (r CreateProjectRequest) ValidateWithLang(msgs Messages) error {
    var errs ValidationErrors
    if strings.TrimSpace(r.Name) == "" {
        errs = append(errs, FieldError{
            Field:   "name",
            Message: msgs.Required,
        })
    }
    // ...
    return errs
}

国际化推荐用 nicksnyder/go-i18n 或自建消息映射表。不要在校验逻辑里直接拼接中文字符串，把语言层和校验层分开。

校验的性能考虑

func BenchmarkValidation(b *testing.B) {
    req := CreateProjectRequest{
        Name:       "benchmark project name",
        Visibility: "public",
        Tags:       []string{"tag1", "tag2", "tag3"},
    }
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        req.Validate()
    }
}

轻量校验（字符串长度检查、枚举判断）单次耗时通常在微秒级。即使 QPS 上万，校验也不会成为瓶颈。但如果校验里嵌入了正则表达式、远程 API 调用或数据库查询，就要非常谨慎。

不要在校验层做数据库查询。校验应该只处理输入本身的约束，业务级别的唯一性检查（如邮箱是否已被注册）应该在 service 层完成。这样校验函数保持无状态，测试也更简单。

常见反模式

在校验里直接修改输入：校验应该是只读操作。清理（Normalize）和校验应该分开。
返回布尔值代替错误信息：if !valid(req) 让调用方不知道哪里错了，调试困难。
panic 代替 error：校验失败不是不可恢复的程序错误，不要用 panic。
校验和业务逻辑混在一起：CreateUser 函数里既校验又写入数据库，测试困难，职责不清。
忽略 []rune 和 len 的区别：中文环境下，len("你好") = 6，而 len([]rune("你好")) = 2。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

函数是否处理了所有 error 返回值
并发代码是否有明确的退出路径和 WaitGroup
用户输入是否经过校验和清洗
敏感配置是否通过环境变量或加密存储注入
测试是否覆盖了正常路径和至少一个错误路径
日志是否包含足够的上下文信息但不泄露敏感数据
接口设计是否符合最小接口原则

CI/CD 集成建议

每次提交前运行 go fmt ./...
CI 中运行 go vet ./... 和 golangci-lint run
单元测试使用 go test -race ./... 检测数据竞争
关键路径的 benchmark 加入回归测试
使用 go mod verify 确保依赖完整性

性能调优检查点

使用 pprof 分析 CPU 和内存使用
关注 benchmark 的 allocs/op，减少高频路径的堆分配
检查数据库查询是否使用索引
确认外部 HTTP 调用有合理的超时设置
缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

goroutine 和线程的区别
channel 的缓冲和非缓冲用法
defer 的执行顺序和与返回值的关系
map 的并发不安全性和解决方案
interface 的隐式实现和类型断言
slice 的底层数组和 append 机制
GC 的基本原理和调优参数
context 的使用场景和超时控制
error 的包装和 errors.Is/errors.As
sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

把文中所有示例代码在自己的机器上跑一遍
给示例代码补充错误分支的测试用例
尝试基于本文内容构建一个小型完整项目
在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

Go 官方网站：https://go.dev/
Go 标准库文档：https://pkg.go.dev/std
Go by Example：https://gobyexample.com/
Effective Go：https://go.dev/doc/effective_go
Go 常见问题：https://go.dev/doc/faq
Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页