Back to Details

go-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Go Validator

Go 验证器

Generate validator files for GO modular architecture conventions.
为Go模块化架构规范生成验证器文件。

Two-File Pattern

双文件模式

Every validator requires two files:
  1. Port interface: 
    internal/modules/<module>/ports/<validator_name>_validator.go
  2. Validator implementation: 
    internal/modules/<module>/validator/<validator_name>_validator.go
每个验证器都需要两个文件：
  1. 端口接口：
    internal/modules/<module>/ports/<validator_name>_validator.go
  2. 验证器实现：
    internal/modules/<module>/validator/<validator_name>_validator.go

Port File Structure

端口文件结构

The port file contains only the interface definition with its documentation comment.
Example structure:
go
package ports

// PasswordValidator validates password strength according to security policies.
type PasswordValidator interface {
	Validate(password string) error
}
端口文件仅包含接口定义及其文档注释。
示例结构：
go
package ports

// PasswordValidator validates password strength according to security policies.
type PasswordValidator interface {
	Validate(password string) error
}

Validator File Structure

验证器文件结构

The validator implementation file follows this order:
  1. Package imports
  2. Constants - validation rules, thresholds, limits
  3. Struct definition - the validator implementation struct
  4. Interface assertion - compile-time check with 
    var _ ports.XxxValidator = (*XxxValidator)(nil)
  5. Constructor - 
    NewXxxValidator
    function
  6. Methods - validation methods (e.g., 
    Validate
    )
Example structure:
go
package validator

import (
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/errs"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/ports"
)

// 1. Constants
const (
	minLength = 8
	maxLength = 128
)

// 2. Struct definition
type PasswordValidator struct{}

// 3. Interface assertion
var _ ports.PasswordValidator = (*PasswordValidator)(nil)

// 4. Constructor
func NewPasswordValidator() *PasswordValidator {
	return &PasswordValidator{}
}

// 5. Methods
func (v *PasswordValidator) Validate(password string) error {
	// validation logic
	return nil
}
验证器实现文件遵循以下顺序：
  1. 包导入
  2. 常量 - 验证规则、阈值、限制
  3. 结构体定义 - 验证器实现结构体
  4. 接口断言 - 使用
    var _ ports.XxxValidator = (*XxxValidator)(nil)
    进行编译时检查
  5. 构造函数 - 
    NewXxxValidator
    函数
  6. 方法 - 验证方法（如
    Validate
    ）
示例结构：
go
package validator

import (
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/errs"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/ports"
)

// 1. Constants
const (
	minLength = 8
	maxLength = 128
)

// 2. Struct definition
type PasswordValidator struct{}

// 3. Interface assertion
var _ ports.PasswordValidator = (*PasswordValidator)(nil)

// 4. Constructor
func NewPasswordValidator() *PasswordValidator {
	return &PasswordValidator{}
}

// 5. Methods
func (v *PasswordValidator) Validate(password string) error {
	// validation logic
	return nil
}

Port Interface Structure

端口接口结构

Location: 
internal/modules/<module>/ports/<validator_name>_validator.go
go
package ports

// PasswordValidator validates password strength according to security policies.
type PasswordValidator interface {
	Validate(password string) error
}
位置：
internal/modules/<module>/ports/<validator_name>_validator.go
go
package ports

// PasswordValidator validates password strength according to security policies.
type PasswordValidator interface {
	Validate(password string) error
}

Validator Variants

验证器变体

Stateless validator (no dependencies)

无状态验证器（无依赖）

Most validators are stateless utilities with no external dependencies.
go
type EmailValidator struct{}

func NewEmailValidator() *EmailValidator {
	return &EmailValidator{}
}

func (v *EmailValidator) Validate(email string) error {
	// Validation logic
	return nil
}
大多数验证器是无外部依赖的无状态工具。
go
type EmailValidator struct{}

func NewEmailValidator() *EmailValidator {
	return &EmailValidator{}
}

func (v *EmailValidator) Validate(email string) error {
	// Validation logic
	return nil
}

Stateful validator (with dependencies)

有状态验证器（带依赖）

Use when validation requires external data or configuration.
go
type UsernameValidator struct {
	userRepo ports.UserRepository
	minLen   int
	maxLen   int
}

func NewUsernameValidator(
	userRepo ports.UserRepository,
	minLen int,
	maxLen int,
) *UsernameValidator {
	return &UsernameValidator{
		userRepo: userRepo,
		minLen:   minLen,
		maxLen:   maxLen,
	}
}

func (v *UsernameValidator) Validate(ctx context.Context, username string) error {
	if len(username) < v.minLen {
		return errs.ErrUsernameTooShort
	}

	// Check uniqueness using repository
	exists, err := v.userRepo.ExistsByUsername(ctx, username)
	if err != nil {
		return err
	}
	if exists {
		return errs.ErrUsernameAlreadyExists
	}

	return nil
}
当验证需要外部数据或配置时使用。
go
type UsernameValidator struct {
	userRepo ports.UserRepository
	minLen   int
	maxLen   int
}

func NewUsernameValidator(
	userRepo ports.UserRepository,
	minLen int,
	maxLen int,
) *UsernameValidator {
	return &UsernameValidator{
		userRepo: userRepo,
		minLen:   minLen,
		maxLen:   maxLen,
	}
}

func (v *UsernameValidator) Validate(ctx context.Context, username string) error {
	if len(username) < v.minLen {
		return errs.ErrUsernameTooShort
	}

	// Check uniqueness using repository
	exists, err := v.userRepo.ExistsByUsername(ctx, username)
	if err != nil {
		return err
	}
	if exists {
		return errs.ErrUsernameAlreadyExists
	}

	return nil
}

Multi-field validator

多字段验证器

Use when validation involves multiple related fields.
Port interface:
go
type RegistrationValidator interface {
	ValidateEmail(email string) error
	ValidatePassword(password string) error
	ValidatePasswordMatch(password, confirmPassword string) error
}
Implementation:
go
type RegistrationValidator struct{}

func NewRegistrationValidator() *RegistrationValidator {
	return &RegistrationValidator{}
}

func (v *RegistrationValidator) ValidateEmail(email string) error {
	// Email validation logic
	return nil
}

func (v *RegistrationValidator) ValidatePassword(password string) error {
	// Password validation logic
	return nil
}

func (v *RegistrationValidator) ValidatePasswordMatch(password, confirmPassword string) error {
	if password != confirmPassword {
		return errs.ErrPasswordMismatch
	}
	return nil
}
当验证涉及多个相关字段时使用。
端口接口：
go
type RegistrationValidator interface {
	ValidateEmail(email string) error
	ValidatePassword(password string) error
	ValidatePasswordMatch(password, confirmPassword string) error
}
实现：
go
type RegistrationValidator struct{}

func NewRegistrationValidator() *RegistrationValidator {
	return &RegistrationValidator{}
}

func (v *RegistrationValidator) ValidateEmail(email string) error {
	// Email validation logic
	return nil
}

func (v *RegistrationValidator) ValidatePassword(password string) error {
	// Password validation logic
	return nil
}

func (v *RegistrationValidator) ValidatePasswordMatch(password, confirmPassword string) error {
	if password != confirmPassword {
		return errs.ErrPasswordMismatch
	}
	return nil
}

Validation Constants

验证常量

Define validation rules as constants at the package level for clarity and maintainability.
go
const (
	minPasswordLength = 8
	maxPasswordLength = 128
	minUsernameLength = 3
	maxUsernameLength = 32
)
将验证规则定义为包级常量，以提升清晰度和可维护性。
go
const (
	minPasswordLength = 8
	maxPasswordLength = 128
	minUsernameLength = 3
	maxUsernameLength = 32
)

Error Handling

错误处理

Validators MUST return typed domain errors from the module's 
errs
package. When adding new custom errors, translations are mandatory in locale files.
go
// In internal/modules/<module>/errs/errs.go
var (
	ErrPasswordTooShort         = errors.New("password must be at least 8 characters")
	ErrPasswordMissingUppercase = errors.New("password must contain at least one uppercase letter")
	ErrPasswordMissingLowercase = errors.New("password must contain at least one lowercase letter")
	ErrPasswordMissingDigit     = errors.New("password must contain at least one digit")
	ErrPasswordMissingSpecial   = errors.New("password must contain at least one special character")
)
For every new custom error added to 
internal/modules/<module>/errs/errs.go
:
  • Add the translation key to 
    locales/en.json
  • Add the same translation key to every other existing locale file (e.g., 
    locales/pt_BR.json
    )
验证器必须返回来自模块
errs
包的类型化领域错误。添加新的自定义错误时，必须在语言环境文件中提供翻译。
go
// In internal/modules/<module>/errs/errs.go
var (
	ErrPasswordTooShort         = errors.New("password must be at least 8 characters")
	ErrPasswordMissingUppercase = errors.New("password must contain at least one uppercase letter")
	ErrPasswordMissingLowercase = errors.New("password must contain at least one lowercase letter")
	ErrPasswordMissingDigit     = errors.New("password must contain at least one digit")
	ErrPasswordMissingSpecial   = errors.New("password must contain at least one special character")
)
每当向
internal/modules/<module>/errs/errs.go
添加新的自定义错误时：
  • 在
    locales/en.json
    中添加翻译键
  • 在所有其他现有语言环境文件中添加相同的翻译键（例如
    locales/pt_BR.json
    ）

Context Usage

Context 使用

Validators that perform I/O operations (database lookups, API calls) MUST accept 
context.Context
as the first parameter.
go
// Stateless validator - no context needed
func (v *PasswordValidator) Validate(password string) error

// Stateful validator with I/O - context required
func (v *UsernameValidator) Validate(ctx context.Context, username string) error
执行I/O操作（数据库查询、API调用）的验证器必须接受
context.Context
作为第一个参数。
go
// Stateless validator - no context needed
func (v *PasswordValidator) Validate(password string) error

// Stateful validator with I/O - context required
func (v *UsernameValidator) Validate(ctx context.Context, username string) error

Naming

命名规范

  • Port interface: 
    XxxValidator
    (in 
    ports
    package)
  • Implementation struct: 
    XxxValidator
    (in 
    validator
    package, same name — disambiguated by package)
  • Constructor: 
    NewXxxValidator
    , returns a pointer of the struct implementation
  • Validation method: 
    Validate
    for single-purpose validators, or descriptive names for multi-purpose validators
  • 端口接口：
    XxxValidator
    （位于
    ports
    包中）
  • 实现结构体：
    XxxValidator
    （位于
    validator
    包中，名称相同——通过包名区分）
  • 构造函数：
    NewXxxValidator
    ，返回结构体实现的指针
  • 验证方法：单一用途验证器使用
    Validate
    ，多用途验证器使用描述性名称

Fx Wiring

Fx 配置

Add to 
internal/modules/<module>/fx.go
:
go
fx.Provide(
	fx.Annotate(
		validator.NewPasswordValidator,
		fx.As(new(ports.PasswordValidator)),
	),
),
添加到
internal/modules/<module>/fx.go
：
go
fx.Provide(
	fx.Annotate(
		validator.NewPasswordValidator,
		fx.As(new(ports.PasswordValidator)),
	),
),

Dependencies

依赖关系

Validators depend on interfaces only. Common dependencies:
  • ports.XxxRepository
    — for uniqueness checks or data lookups
  • ports.XxxService
    — for external validation services
  • Configuration values — passed as constructor parameters
验证器仅依赖于接口。常见依赖：
  • ports.XxxRepository
    — 用于唯一性检查或数据查询
  • ports.XxxService
    — 用于外部验证服务
  • 配置值 — 作为构造函数参数传递

Testing

测试

Validators MUST have comprehensive unit tests covering:
  1. Valid input passes validation
  2. Each invalid condition returns the correct error
  3. Edge cases (empty strings, boundary values, special characters)
Test file location: 
internal/modules/<module>/validator/<validator_name>_validator_test.go
go
package validator_test

import (
	"testing"

	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/errs"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/validator"
	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

func TestPasswordValidator_ValidPassword_Passes(t *testing.T) {
	// Arrange
	v := validator.NewPasswordValidator()

	// Act
	err := v.Validate("SecureP@ssw0rd")

	// Assert
	require.NoError(t, err)
}

func TestPasswordValidator_TooShort_ReturnsError(t *testing.T) {
	// Arrange
	v := validator.NewPasswordValidator()

	// Act
	err := v.Validate("Ab1!")

	// Assert
	require.Error(t, err)
	assert.ErrorIs(t, err, errs.ErrPasswordTooShort)
}
验证器必须具备全面的单元测试，覆盖：
  1. 有效输入通过验证
  2. 每个无效条件返回正确的错误
  3. 边缘情况（空字符串、边界值、特殊字符）
测试文件位置：
internal/modules/<module>/validator/<validator_name>_validator_test.go
go
package validator_test

import (
	"testing"

	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/errs"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/validator"
	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

func TestPasswordValidator_ValidPassword_Passes(t *testing.T) {
	// Arrange
	v := validator.NewPasswordValidator()

	// Act
	err := v.Validate("SecureP@ssw0rd")

	// Assert
	require.NoError(t, err)
}

func TestPasswordValidator_TooShort_ReturnsError(t *testing.T) {
	// Arrange
	v := validator.NewPasswordValidator()

	// Act
	err := v.Validate("Ab1!")

	// Assert
	require.Error(t, err)
	assert.ErrorIs(t, err, errs.ErrPasswordTooShort)
}

Critical Rules

关键规则

  1. Two files: Port interface in 
    ports/
    , implementation in 
    validator/
  2. Interface in ports: Interface lives in 
    ports/<name>_validator.go
  3. Interface assertion: Add 
    var _ ports.XxxValidator = (*XxxValidator)(nil)
    below the struct
  4. Constructor: MUST return pointer 
    *XxxValidator
  5. Stateless by default: Only add dependencies when validation requires external data
  6. Context when needed: Accept 
    context.Context
    only for validators performing I/O
  7. Typed errors: Return domain errors from module's 
    errs
    package
  8. Error translations: Every new custom error must have entries in 
    locales/en.json
    and all other existing locale files
  9. Constants: Define validation rules as package-level constants
  10. No comments on implementations: Do not add redundant comments above methods in the implementations
  11. Add detailed comment on interfaces: Provide comprehensive comments on the port interfaces to describe their purpose and validation rules
  12. Comprehensive tests: Test valid cases and all invalid conditions
  1. 双文件：端口接口位于
    ports/
    ，实现位于
    validator/
  2. 接口在ports包：接口存放在
    ports/<name>_validator.go
  3. 接口断言：在结构体下方添加
    var _ ports.XxxValidator = (*XxxValidator)(nil)
  4. 构造函数：必须返回
    *XxxValidator
    指针
  5. 默认无状态：仅当验证需要外部数据时才添加依赖
  6. 按需使用Context：仅执行I/O的验证器才接受
    context.Context
  7. 类型化错误：返回模块
    errs
    包中的领域错误
  8. 错误翻译：每个新自定义错误必须在
    locales/en.json
    及所有其他现有语言环境文件中存在对应条目
  9. 常量定义：将验证规则定义为包级常量
  10. 实现无冗余注释：不要在实现的方法上方添加冗余注释
  11. 接口添加详细注释：为端口接口提供全面注释，说明其用途和验证规则 12.全面测试：测试有效场景和所有无效条件

Workflow

工作流程

  1. Create port interface in 
    ports/<name>_validator.go
  2. Create validator implementation in 
    validator/<name>_validator.go
  3. Define validation constants
  4. Add typed errors to module's 
    errs/errs.go
    if needed
  5. Add translations for each new custom error in 
    locales/en.json
    and all other existing locale files
  6. Create comprehensive unit tests in 
    validator/<name>_validator_test.go
  7. Add Fx wiring to module's 
    fx.go
  8. Run 
    make test
    to verify tests pass
  9. Run 
    make lint
    to verify code quality
  10. Run 
    make nilaway
    for static analysis
  1. 在
    ports/<name>_validator.go
    中创建端口接口
  2. 在
    validator/<name>_validator.go
    中创建验证器实现
  3. 定义验证常量
  4. 如有需要，向模块的
    errs/errs.go
    添加类型化错误
  5. 在
    locales/en.json
    及所有其他现有语言环境文件中为每个新自定义错误添加翻译
  6. 在
    validator/<name>_validator_test.go
    中创建全面的单元测试
  7. 向模块的
    fx.go
    添加Fx配置
  8. 运行
    make test
    验证测试通过
  9. 运行
    make lint
    验证代码质量
  10. 运行
    make nilaway
    进行静态分析