Go Project Guidelines

Overview

Go application following idiomatic patterns and best practices.

Tech Stack

• Language: Go 1.21+
• Testing: Go testing package
• Linting: golangci-lint
• Build: Go modules

Development Commands

# Run the application
go run .

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run linter
golangci-lint run

# Build binary
go build -o bin/app .

# Format code
go fmt ./...

# Tidy dependencies
go mod tidy

Project Structure

cmd/
├── api/           # API server entrypoint
└── worker/        # Background worker entrypoint
internal/
├── config/        # Configuration
├── handler/       # HTTP handlers
├── middleware/    # HTTP middleware
├── model/         # Data models
├── repository/    # Data access
├── service/       # Business logic
└── util/          # Utilities
pkg/               # Public packages

Code Style

• Follow Effective Go guidelines
• Use gofmt for formatting
• Keep functions short and focused
• Use meaningful names (not single letters for non-trivial scopes)
• Document exported functions and types

Error Handling

// Good: wrap errors with context
if err != nil {
    return fmt.Errorf("failed to create user: %w", err)
}

// Good: use errors.Is for error comparison
if errors.Is(err, ErrNotFound) {
    return nil, nil
}

Patterns

• Use interfaces for dependencies
• Keep interfaces small (1-3 methods)
• Accept interfaces, return structs
• Use context for cancellation and timeouts
• Use struct embedding judiciously

Testing

• Write table-driven tests
• Use testify for assertions if needed
• Mock dependencies with interfaces
• Test both success and error cases

func TestCreateUser(t *testing.T) {
    tests := []struct {
        name    string
        input   CreateUserInput
        wantErr bool
    }{
        // test cases
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // test implementation
        })
    }
}

Concurrency

• Use goroutines with caution
• Always handle goroutine lifecycle
• Use channels for communication
• Use sync package for synchronization
• Avoid shared mutable state

Security

• Validate all inputs
• Use prepared statements for SQL
• Don't log sensitive data
• Use crypto/rand for random values