validator

✨ Features

• 🚀 Zero third-party dependencies — Only Go standard library, supply-chain secure
• ⚡ Zero-reflection VarString fast path — String variable validation bypasses reflect entirely, 0 heap allocations, 2~3× faster than reflection path
• 🏷️ 126 built-in field rules — required, min/max, email, IP, UUID, datetime, Luhn checksum, semver, ISBN, ISSN, BIC/SWIFT, cron, Data URI, BCP 47, Ethereum/Bitcoin address, PNG/JPEG/GIF/WebP/BMP/TIFF/ICO/AVIF/HEIC/SVG image magic-number validation, etc.
• 🔗 Cross-field rules — range, fieldcontains, fieldlen, requiredWithout, etc.
• 🌍 i18n native support — 9 built-in language translations (en/zh/zh-TW/ja/ko/fr/de/es/ru), switch with one line, extensible to any language
• 🔄 go-playground/validator compatible — Struct tag syntax and API highly compatible, minimal migration cost
• 🧩 JSON Schema validation — Lightweight JSON Schema subset validation, suitable for API gateway scenarios
• 🔒 Concurrency safe — Validator instances are reusable, struct compilation results auto-cached
• 🛠️ Custom rules — RegisterValidation for custom validation functions, context propagation supported
• 📊 Array-style error output — TranslateValidationErrors outputs serializable JSON errors
• 🌐 Gateway utilities — IP allowlist/blocklist (CIDR/wildcard), HTTP status codes, headers, content types, JSON Path validation
• 📎 Format validation — email, IP, UUID, base64, URL, URI (including mailto/tel), protocol, WebSocket, semver, ISBN-10/13, ISSN, BIC/SWIFT, cron, Data URI, BCP 47 language tags, Ethereum/Bitcoin addresses, image formats (PNG/JPEG/GIF/WebP/BMP/TIFF/ICO/AVIF/HEIC/SVG via magic numbers)
• 📦 Generic enum validator — NewEnumValidator[T] type-safe enum value validation
• 🔀 Tag comma escaping — \, preserves commas in parameters, | as alternative separator
• 🛑 Rule execution policy — Short-circuit on single field failure, other fields unaffected

🏗️ Architecture

graph TB
    subgraph "User Layer"
        APP["Application Code"]
    end

    subgraph "Root Package validator"
        V["Validate Instance<br/>Struct / Var / VarString"]
        CACHE["Compilation Cache<br/>structPlan"]
        TAGS["Built-in Rules<br/>87+ builtinRules"]
        STAGS["String Rules<br/>stringRuleMap"]
        TRANS["Error Translation<br/>translations.go → i18n.Lookup"]
        OPTS["Configuration<br/>Option / SetLocale"]
        ERRORS["Error Model<br/>ValidationErrors"]
    end

    subgraph "rule Package"
        RPARSE["Tag Parsing<br/>ParseTag"]
        RFIELD["Field Path<br/>FieldByPath"]
        RTIME["Time Rules<br/>TimeValue / ResolveTimeExpr"]
    end

    subgraph "validate Package"
        COMPARE["Comparison<br/>CompareNumbers / Strings"]
        FORMAT["Format Validation<br/>Email / IP / URL / UUID / Base64"]
        ENUM["Enum Validation<br/>EnumValidator"]
        JSON["JSON Validation<br/>ValidateJSON / JSONPath"]
        NETWORK["Network Validation<br/>IPSet / CIDR / Wildcard"]
        CONSTANTS["Message Constants<br/>constants.go"]
    end

    subgraph "i18n Package (Unified Translation Store)"
        I18N["i18n Core<br/>SetLocale / Msg / Lookup / Register"]
        I18N_EN["en.go"]
        I18N_ZH["zh.go / zh_tw.go"]
        I18N_JA["ja.go / ko.go"]
        I18N_OTHER["fr.go / de.go / es.go / ru.go"]
    end

    subgraph "schema Package"
        SCHEMA["JSON Schema<br/>ValidateJSONSchema"]
    end

    APP --> V
    V --> CACHE
    V --> TAGS
    V --> STAGS
    V --> TRANS
    V --> OPTS
    V --> ERRORS
    V --> RPARSE
    V --> RFIELD
    V --> RTIME

    TAGS --> FORMAT
    TAGS --> COMPARE
    TAGS --> ENUM
    STAGS --> FORMAT

    APP --> COMPARE
    APP --> FORMAT
    APP --> NETWORK
    APP --> SCHEMA

    SCHEMA --> I18N
    COMPARE --> I18N
    FORMAT --> I18N
    ENUM --> I18N
    JSON --> I18N
    NETWORK --> I18N

    OPTS --> I18N
    TRANS --> I18N

    style APP fill:#e1f5fe
    style V fill:#fff3e0
    style STAGS fill:#ffe0b2
    style I18N fill:#e8f5e9
    style SCHEMA fill:#fce4ec

📦 Installation

go get github.com/HitGameAI/apex-toolbox/pkg/argus

Requires Go 1.21+

🚀 Quick Start

package main

import (
    "fmt"
    "github.com/HitGameAI/apex-toolbox/pkg/argus"
)

type User struct {
    Name  string `json:"name" validate:"required,min=2,max=50"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=0,lte=150"`
}

func main() {
    v := validator.New()
    err := v.Struct(User{Name: "A", Email: "bad", Age: -1})

    // Switch language with one line
    validator.SetLocale("en")
    messages := validator.TranslateValidationErrors(err, "en")
    for _, msg := range messages {
        fmt.Printf("%s: %s\n", msg.Field, msg.Message)
    }
    // Register new language (9 built-in: en/zh/zh-TW/ja/ko/fr/de/es/ru)
    validator.RegisterI18nMessages("pt", map[string]string{
        "required": "{field} é obrigatório",
    })
    // name: name must be at least 2 characters
    // email: email must be a valid email address
    // age: age must be greater than or equal to 0
}

🔌 Framework Integration

Argus seamlessly replaces the default validator of mainstream web frameworks. Existing binding flows like ShouldBindJSON and httpx.Parse trigger validation automatically, zero intrusion into business code:

Complete integration examples (runnable example code, curl demos, and unified error responses): docs/frameworks.md

⚡ VarString Zero-Reflection Fast Path

For string variable validation, VarString provides a zero-allocation fast path that completely bypasses reflect:

v := validator.New()

// Traditional Var path — interface{} boxing + reflect
err := v.Var("user@example.com", "email")

// VarString zero-reflection path — direct string parameter, 0 heap allocations
err = v.VarString("user@example.com", "email")

How it works:

• VarString looks up stringRuleMap (zero-reflection implementations of all string-compatible rules) and calls rule functions directly with string parameters
• Unsupported rules (e.g., cross-field rules like eqfield, required_if) automatically fall back to the reflect path, maintaining full compatibility
• Errors return lightweight stringFieldError, which also implements the FieldError interface

Supported zero-reflection rules:

required · min · max · len · eq · ne · gt · gte · lt · lte · alpha · alphanum · email · url · uri · ip · ipv4 · ipv6 · uuid · uuid3/4/5 · semver · isbn10/13 · issn · bic · cron · base64 · json · hostname · fqdn · mac · cidr · e164 · lowercase · uppercase · boolean · number · datetime · latitude · longitude · eth_addr · btc_addr · bcp47 · datauri · oneof · oneofci · contains · startswith · endswith and 70+ more rules

📚 Documentation

🔄 Migrating from go-playground/validator

Argus's struct tag syntax and core API are highly compatible with go-playground/validator:

// go-playground/validator
import "github.com/go-playground/validator/v10"
v := validator.New()

// Argus — just change the import path
import "github.com/HitGameAI/apex-toolbox/pkg/argus"
v := validator.New()

Key differences:

🚀 Performance Benchmarks

Full performance comparison between Argus and go-playground/validator/v10 is available at go-argus-benchmark.

VarString Zero-Reflection Path vs Var Reflection Path

Argus vs go-playground/validator/v10

Key optimizations: zero-reflection VarString fast path, hand-written email parser replacing net/mail, pre-compiled rule dispatch table, sync.Pool error object reuse, zero-allocation isEmptyValue, zero-allocation lowercase/uppercase byte checks, json.NewDecoder replacing json.Valid, lightweight URL/URI parsing replacing net/url, etc. See go-argus-benchmark for details.

🔗 Ecosystem

go-rpc-gateway Integration

go-rpc-gateway integrates Argus out of the box, providing struct tag-based gRPC interceptors. Combined with protoc-go-inject-tag to inject validate:"..." tags on generated pb code, no manual parameter validation needed:

import "github.com/HitGameAI/apex-rpc-gateway/middleware"

// gRPC Unary interceptor — auto-validates validate tags on req
unary := middleware.StructTagValidatorUnaryInterceptor()

// gRPC Stream interceptor — auto-validates each stream message
stream := middleware.StructTagValidatorStreamInterceptor()

Validation failures automatically return codes.InvalidArgument. Fields without injected tags are skipped, no false positives.

📄 License

MIT License