Fun Framework

Appearance

参数验证 ​

概述 ​

Fun框架在处理客户端请求时，会对传入的参数进行严格的验证，以确保数据的完整性和正确性。框架内置了参数验证机制，并且兼容流行的go-playground/validator验证库，让开发者能够轻松定义和执行数据验证规则。

核心验证规则 ​

1. 非指针字段不能为空规则 ​

Fun框架有一个重要的设计原则：结构体中的非指针类型字段在请求中必须提供有效值，不能为空。

这意味着：

  • 如果您定义了一个字符串类型的字段（如User string），客户端在请求中必须提供该字段的值
  • 如果您定义了一个整数类型的字段（如Age int），客户端也必须提供该字段的值
  • 只有指针类型的字段（如Name *string）才允许为空或不提供

2. 指针字段的可选性 ​

对于指针类型的字段：

  • 可以完全不提供该字段
  • 可以显式设置为null
  • 也可以提供具体的值

例如，在以下结构体中：

go
type User struct {
    User   string  // 必须提供，不能为空
    Name   *string // 可选字段
    Config *[]Config // 可选字段
}

go-playground/validator兼容性 ​

Fun框架完全兼容go-playground/validator验证库，支持其丰富的验证标签。您可以使用各种验证标签来定义复杂的验证规则：

常用验证标签 ​

  • required - 字段必须存在且非零值
  • min=N / max=N - 最小/最大值限制
  • len=N - 固定长度
  • email - 验证邮箱格式
  • url - 验证URL格式
  • uuid - 验证UUID格式

实际应用示例 ​

go
type User struct {
    User   string `validate:"required,min=6,max=32"` // 必填，长度6-32个字符
    Email  *string `validate:"omitempty,email"`      // 可选，如果提供则验证邮箱格式
    Age    *int   `validate:"omitempty,min=1,max=120"` // 可选，如果提供则验证年龄范围
    Name   *string                                  // 可选，无额外验证规则
}

在上述示例中：

  • [User]字段必须提供，且长度在6到32个字符之间
  • Email字段是可选的，但如果提供了，则必须符合邮箱格式
  • Age字段是可选的，但如果提供了，则必须在1到120之间
  • [Name]字段是完全可选的，无任何验证限制

验证失败处理 ​

当客户端发送的请求不符合验证规则时：

  1. 框架会立即中断请求处理
  2. 记录详细的错误日志
  3. 向客户端返回相应的错误信息

最佳实践 ​

1. 合理设计数据结构 ​

  • 对于必填字段，使用非指针类型并添加适当的验证标签
  • 对于可选字段，使用指针类型
  • 根据业务需求选择合适的验证标签

2. 明确字段要求 ​

  • 在API文档中清楚说明哪些字段是必需的，哪些是可选的
  • 为字段添加适当的验证标签以提供更详细的验证规则

3. 处理验证错误 ​

  • 在客户端处理可能的验证错误响应
  • 根据错误信息指导用户正确填写数据

4. 日志监控 ​

  • 定期检查框架生成的日志，发现常见的参数验证错误
  • 根据日志优化前端表单验证，提升用户体验

错误信息 ​

当参数验证失败时，框架会返回相应的错误信息，帮助开发者和用户快速定位问题。常见的错误包括：

  • 字段缺失错误："Dto must be a pointer or have a corresponding field in the map"
  • 验证规则错误：如字符串长度不符合要求
  • 类型错误：如期望字符串但提供了数字
  • 格式错误：如邮箱格式不正确

通过遵循这些规则和最佳实践，并充分利用go-playground/validator的强大功能，您可以确保API的健壮性和数据的一致性，同时为用户提供更好的使用体验。