Structfieldsenforcer: Preventing Critical Field Initialization Bugs

Ever deployed to production only to discover your database connection failed because someone forgot to initialize a critical configuration field? Or spent hours debugging a mysterious failure that turned out to be a missing API key? If you've worked with Go structs for configuration or critical data structures, you've probably experienced the pain of missing mandatory fields. That's why I built structfieldsenforcer.

The Problem with Optional-By-Default Fields

Go's zero-value initialization is generally a feature, but it becomes a liability when dealing with configuration and critical data structures:

type Config struct {
    DatabaseURL string
    APIKey      string
    Port        int
    Debug       bool
}

// This compiles and runs, but will fail at runtime
config := Config{
    Debug: true,
    // Missing critical fields: DatabaseURL, APIKey, Port
}

The code above compiles without warnings, but will cause runtime failures when you try to connect to a database with an empty URL or make API calls with a missing key.

Real-World Impact

Configuration Management Nightmare

In production systems, missing configuration often leads to:

• Silent failures during startup
• Runtime panics when accessing external services
• Hard-to-debug issues where the absence of a value causes unexpected behavior
• Security vulnerabilities when authentication fields are left empty

Team Collaboration Issues

When multiple developers work on the same codebase:

• New team members might not know which fields are critical
• Code reviews can't easily catch missing initializations
• Refactoring existing structs becomes risky without clear mandatory field markers

The Solution: Explicit Mandatory Fields

Structfieldsenforcer uses struct tags to mark fields as mandatory:

type Config struct {
    DatabaseURL string `mandatory:""`
    APIKey      string `mandatory:""`
    Port        int    `mandatory:""`
    Debug       bool   // Optional - no tag
}

Now the tool can detect violations:

// This will be flagged by the analyzer
config := Config{
    DatabaseURL: "postgres://localhost/mydb",
    Debug:       true,
    // Missing: APIKey and Port
}

How Structfieldsenforcer Works

The tool operates in several modes to help you fix violations:

Detection Mode (Default)

# Check for violations
structfieldsenforcer ./...

This scans your codebase and reports any struct literals missing mandatory fields.

Auto-Fix Mode

# Fix violations by adding TODO comments
structfieldsenforcer -fix ./...

Before fixing:

config := Config{
    DatabaseURL: "postgres://localhost/mydb",
    Debug:       true,
}

After fixing:

config := Config{
    DatabaseURL: "postgres://localhost/mydb",
    Debug:       true,
    APIKey:      // TODO: provide value for APIKey,
    Port:        // TODO: provide value for Port,
}

The tool intentionally creates compilation errors with TODO comments to ensure you don't miss mandatory fields that need values.

Constructor Generation

# Generate missing constructors
structfieldsenforcer -fix -constructors=gen ./...

This creates constructor functions that include all mandatory fields:

func NewConfig(apikey string, databaseURL string, port int) *Config {
    return &Config{APIKey: apikey, DatabaseURL: databaseURL, Port: port}
}

Constructor Updates

# Update existing constructors
structfieldsenforcer -fix -constructors=update ./...

If you have existing constructors missing mandatory fields, the tool will update them:

Before:

func NewConfig(databaseURL string) *Config {
    return &Config{DatabaseURL: databaseURL}
}

After:

func NewConfig(apikey string, databaseURL string, port int) *Config {
    return &Config{APIKey: apikey, DatabaseURL: databaseURL, Port: port}
}

Advanced Usage

Custom Tag Names

# Use 'required' instead of 'mandatory'
structfieldsenforcer -tag=required ./...

Custom Constructor Patterns

# Look for Build* and Make* functions too
structfieldsenforcer -constructor-patterns="New*,Build*,Make*" ./...

CI/CD Integration

The tool returns appropriate exit codes for automation:

• 0 - Success, no violations
• 1 - Violations found
• 2 - Syntax errors
• 3 - File system errors

Installation and Quick Start

# Install the tool
go install github.com/flaticols/structfieldsenforcer@latest

# Check your codebase
structfieldsenforcer ./...

# Fix violations with TODO comments
structfieldsenforcer -fix ./...

# Fix violations and generate constructors
structfieldsenforcer -fix -constructors=gen ./...

When to Use Structfieldsenforcer

This tool is particularly valuable for:

• Configuration structs where missing fields cause runtime failures
• API request/response structures where certain fields are required
• Database models where mandatory fields should never be empty
• Large codebases where manual field verification is impractical
• Team environments where explicit contracts improve code clarity

Try It Out

The tool is designed to integrate seamlessly into your existing Go workflow. Start with detection mode to see what violations exist in your codebase, then use the auto-fix features to resolve them systematically.

Check out the project on GitHub and let me know how it works for your codebase!