existential-birds/beagle / plugins/beagle-go/skills/go-web-expert
go-web-expert
VerifiedComprehensive Go web development persona enforcing zero global state, explicit error handling, input validation, testability, and documentation conventions. Use when building Go web applications to ensure production-quality code from the start.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.3 KB |
| references/testing-handlers.md | markdown | 22.8 KB |
| references/validation.md | markdown | 12.4 KB |
references/validation.md
View on GitHub# Input Validation with go-playground/validator
## Common Validation Tags
The `go-playground/validator` package uses struct tags to declare constraints. Here are the most frequently used tags for web APIs.
### String Constraints
```go
type CreatePostRequest struct {
Title string `json:"title" validate:"required,min=1,max=200"`
Slug string `json:"slug" validate:"required,alphanum"`
Body string `json:"body" validate:"required,min=10,max=50000"`
Status string `json:"status" validate:"required,oneof=draft published archived"`
Website string `json:"website" validate:"omitempty,url"`
}
```
| Tag | Description |
|-----|-------------|
| `required` | Field must be present and non-zero |
| `omitempty` | Skip validation if field is zero value |
| `min=N` | Minimum length (string) or value (number) |
| `max=N` | Maximum length (string) or value (number) |
| `len=N` | Exact length |
| `oneof=a b c` | Value must be one of the listed options (space-separated) |
| `alpha` | Letters only |
| `alphanum` | Letters and numbers only |
| `ascii` | ASCII characters only |
### Format Validators
```go
type ContactRequest struct {
Email string `json:"email" validate:"required,email"`
Phone string `json:"phone" validate:"omitempty,e164"`
Website string `json:"website" validate:"omitempty,url"`
IP string `json:"ip" validate:"omitempty,ip"`
}
```
| Tag | Description |
|-----|-------------|
| `email` | Valid email address |
| `url` | Valid URL |
| `uri` | Valid URI |
| `uuid` | Valid UUID (any version) |
| `uuid4` | Valid UUID v4 |
| `ip` | Valid IPv4 or IPv6 address |
| `ipv4` | Valid IPv4 address |
| `e164` | Valid E.164 phone number |
| `json` | Valid JSON string |
### Numeric Constraints
```go
type PaginationRequest struct {
Page int `json:"page" validate:"required,gte=1"`
PageSize int `json:"page_size" validate:"required,gte=1,lte=100"`
}
type ProductRequest struct {
Price float64 `json:"price" validate:"required,gt=0"`
Quantity int `json:"quantity" validate:"required,gte=0,lte=10000"`
Weight float64 `json:"weight" validate:"omitempty,gte=0"`
}
```
| Tag | Description |
|-----|-------------|
| `gt=N` | Greater than N |
| `gte=N` | Greater than or equal to N |
| `lt=N` | Less than N |
| `lte=N` | Less than or equal to N |
| `ne=N` | Not equal to N |
---
## Custom Validators
Register custom validation functions for domain-specific rules.
### Simple Custom Validator
```go
func setupValidator() *validator.Validate {
v := validator.New()
// Register a custom "slug" validator
v.RegisterValidation("slug", func(fl validator.FieldLevel) bool {
val := fl.Field().String()
matched, _ := regexp.MatchString(`^[a-z0-9]+(-[a-z0-9]+)*$`, val)
return matched
})
// Register a custom "strong_password" validator
v.RegisterValidation("strong_password", func(fl validator.FieldLevel) bool {
val := fl.Field().String()
if len(val) < 8 {
return false
}
hasUpper := regexp.MustCompile(`[A-Z]`).MatchString(val)
hasLower := regexp.MustCompile(`[a-z]`).MatchString(val)
hasDigit := regexp.MustCompile(`[0-9]`).MatchString(val)
return hasUpper && hasLower && hasDigit
})
return v
}
```
Usage:
```go
type CreatePostRequest struct {
Slug string `json:"slug" validate:"required,slug"`
}
type RegisterRequest struct {
Password string `json:"password" validate:"required,strong_password"`
}
```
### Custom Validator with Parameters
```go
// Usage: validate:"not_reserved=admin root system"
v.RegisterValidation("not_reserved", func(fl validator.FieldLevel) bool {
val := fl.Field().String()
param := fl.Param() // "admin root system"
reserved := strings.Fields(param)
for _, r := range reserved {
if strings.EqualFold(val, r) {
return false
}
}
return true
})
```
### Using JSON Tag Names in Error Messages
By default, validator uses Go struct field names in errors. Register the JSON tag name function to get API-friendly field names:
```go
v := validator.New()
v.RegisterTagNameFunc(func(fld reflect.StructField) string {
name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
if name == "-" {
return ""
}
return name
})
```
Now `e.Field()` returns `"email"` instead of `"Email"` in validation errors.
---
## Nested Struct Validation
Validator automatically descends into nested structs when `validate:"required"` or `validate:"dive"` is used.
### Required Nested Struct
```go
type CreateOrderRequest struct {
Items []OrderItem `json:"items" validate:"required,min=1,dive"`
Address ShippingAddress `json:"address" validate:"required"`
}
type OrderItem struct {
ProductID string `json:"product_id" validate:"required,uuid"`
Quantity int `json:"quantity" validate:"required,gte=1,lte=100"`
}
type ShippingAddress struct {
Street string `json:"street" validate:"required,min=1,max=200"`
City string `json:"city" validate:"required,min=1,max=100"`
State string `json:"state" validate:"required,len=2"`
ZipCode string `json:"zip" validate:"required,numeric,len=5"`
Country string `json:"country" validate:"required,iso3166_1_alpha2"`
}
```
Key points:
- `dive` tells the validator to validate each element inside a slice
- Without `dive`, only the slice itself is checked (length, required)
- Nested structs with `validate:"required"` are validated recursively
### Optional Nested Struct
Use a pointer for optional nested structs:
```go
type UpdateProfileRequest struct {
Name string `json:"name" validate:"omitempty,min=1,max=100"`
Address *ShippingAddress `json:"address" validate:"omitempty"`
}
```
When `Address` is `nil`, validation is skipped. When present, all its field rules apply.
---
## Slice and Map Validation
### Slice Validation
```go
type BulkCreateRequest struct {
// Validate the slice itself (1-50 items) AND each element
Users []CreateUserRequest `json:"users" validate:"required,min=1,max=50,dive"`
}
```
The `dive` tag means: after validating the slice-level constraints (`min=1,max=50`), validate each element according to its own struct tags.
### Slice of Primitives
```go
type TagRequest struct {
Tags []string `json:"tags" validate:"required,min=1,max=10,dive,required,min=1,max=50"`
}
```
Reading left to right:
1. `required` -- slice must be present
2. `min=1,max=10` -- slice must have 1-10 elements
3. `dive` -- now validate each element
4. `required,min=1,max=50` -- each string must be non-empty and max 50 chars
### Map Validation
```go
type MetadataRequest struct {
// Validate keys and values separately
Metadata map[string]string `json:"metadata" validate:"required,max=20,dive,keys,min=1,max=50,endkeys,required,max=500"`
}
```
Reading left to right:
1. `required,max=20` -- map is required, max 20 entries
2. `dive` -- enter the map
3. `keys,min=1,max=50,endkeys` -- each key must be 1-50 chars
4. `required,max=500` -- each value must be non-empty and max 500 chars
---
## Cross-Field Validation
Validate fields relative to each other using `eqfield`, `nefield`, `gtfield`, etc.
### Password Confirmation
```go
type RegisterRequest struct {
Email string `json:"email" validate:"required,email"`
Password string `json:"password" validate:"required,min=8,max=72"`
ConfirmPassword string `json:"confirm_password" validate:"required,eqfield=Password"`
}
```
### Date Range Validation
```go
type DateRangeRequest struct {
StartDate time.Time `json:"start_date" validate:"required"`
EndDate time.Time `json:"end_date" validate:"required,gtfield=StartDate"`
}
```
### Cross-Field Tags
| Tag | Description |
|-----|-------------|
| `eqfield=Other` | Must equal the value of `Other` |
| `nefield=Other` | Must not equal the value of `Other` |
| `gtfield=Other` | Must be greater than `Other` |
| `gtefield=Other` | Must be greater than or equal to `Other` |
| `ltfield=Other` | Must be less than `Other` |
| `ltefield=Other` | Must be less than or equal to `Other` |
### Struct-Level Validation
For complex cross-field rules that cannot be expressed with tags, use struct-level validation:
```go
v.RegisterStructValidation(func(sl validator.StructLevel) {
req := sl.Current().Interface().(CreateEventRequest)
if req.EndDate.Before(req.StartDate) {
sl.ReportError(req.EndDate, "end_date", "EndDate", "after_start", "")
}
if req.MaxAttendees > 0 && req.MinAttendees > req.MaxAttendees {
sl.ReportError(req.MinAttendees, "min_attendees", "MinAttendees", "lte_max", "")
}
}, CreateEventRequest{})
```
---
## Error Message Formatting for API Responses
### Basic Formatting
```go
func formatValidationErrors(err error) string {
var msgs []string
for _, e := range err.(validator.ValidationErrors) {
msgs = append(msgs, fmt.Sprintf("field '%s' failed on '%s'", e.Field(), e.Tag()))
}
return strings.Join(msgs, "; ")
}
```
### Structured JSON Error Response
For richer API responses, return field-level errors as a map:
```go
type ValidationError struct {
Field string `json:"field"`
Message string `json:"message"`
}
func formatValidationErrorsJSON(err error) []ValidationError {
var errs []ValidationError
for _, e := range err.(validator.ValidationErrors) {
errs = append(errs, ValidationError{
Field: e.Field(),
Message: msgForTag(e),
})
}
return errs
}
func msgForTag(e validator.FieldError) string {
switch e.Tag() {
case "required":
return "this field is required"
case "email":
return "must be a valid email address"
case "min":
return fmt.Sprintf("must be at least %s characters", e.Param())
case "max":
return fmt.Sprintf("must be at most %s characters", e.Param())
case "oneof":
return fmt.Sprintf("must be one of: %s", e.Param())
case "uuid":
return "must be a valid UUID"
case "gte":
return fmt.Sprintf("must be at least %s", e.Param())
case "lte":
return fmt.Sprintf("must be at most %s", e.Param())
case "eqfield":
return fmt.Sprintf("must match %s", e.Param())
default:
return fmt.Sprintf("failed validation: %s", e.Tag())
}
}
```
### Usage in Handler
```go
func (s *Server) handleCreateUser(w http.ResponseWriter, r *http.Request) error {
var req CreateUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
return &AppError{Code: 400, Message: "invalid JSON"}
}
if err := validate.Struct(req); err != nil {
errs := formatValidationErrorsJSON(err)
writeJSON(w, 422, map[string]any{
"error": "validation failed",
"fields": errs,
})
return nil
}
// proceed with validated request...
return nil
}
```
Example API response:
```json
{
"error": "validation failed",
"fields": [
{"field": "email", "message": "must be a valid email address"},
{"field": "name", "message": "this field is required"}
]
}
```
---
## Validation Anti-Patterns
### Validating in the service layer
```go
// BAD: validation scattered across layers
func (s *UserService) Create(ctx context.Context, name, email string) (*User, error) {
if name == "" {
return nil, errors.New("name required") // should be caught at handler
}
}
```
Validate once at the boundary. Services receive trusted data.
### Using validate tags without dive on slices
```go
// BAD: only checks slice length, not element contents
Items []OrderItem `json:"items" validate:"required,min=1"`
// GOOD: dive validates each element
Items []OrderItem `json:"items" validate:"required,min=1,dive"`
```
### Ignoring the difference between required and omitempty
```go
// Required: field must be present and non-zero
Name string `validate:"required"` // "" is invalid
// Omitempty: skip validation if zero, validate if present
Bio string `validate:"omitempty,min=10,max=1000"` // "" is valid, "short" is invalid
```
### Not limiting request body size
```go
// BAD: attacker can send gigabytes
json.NewDecoder(r.Body).Decode(&req)
// GOOD: limit body size
r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1MB limit
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
// MaxBytesError is returned if the limit is exceeded
return &AppError{Code: 413, Message: "request body too large"}
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |