go-conventions

Go Development Conventions

Stack Defaults

Layer	Technology
Language	Go (latest stable)
Formatting	gofmt / goimports
Linting	golangci-lint
Testing	testing (stdlib), testify (optional)
Integration Testing	testcontainers-go
HTTP	net/http (stdlib), chi, gin, or echo
Logging	slog (stdlib) or zerolog
Config	envconfig or environment variables

Project Structure

project/
├── cmd/
│   └── server/
│       └── main.go            # Entry point
├── internal/                   # Private application code
│   ├── handler/               # HTTP handlers
│   ├── service/               # Business logic
│   ├── repository/            # Data access
│   ├── model/                 # Domain types
│   └── middleware/            # HTTP middleware
├── pkg/                       # Public reusable packages (optional)
├── go.mod
├── go.sum
├── Makefile
└── README.md

• internal/ is enforced by Go compiler — cannot be imported externally
• cmd/ for application entry points; each subdirectory is a binary
• pkg/ only for truly reusable packages intended for external import

Error Handling

Go's (T, error) return pattern is the natural Result pattern:

func GetUser(id string) (*User, error) {
    user, err := repo.FindByID(id)
    if err != nil {
        return nil, fmt.Errorf("get user %s: %w", id, err)
    }
    return user, nil
}

Rules

• Always check returned errors — never ignore with _
• Wrap errors with context: fmt.Errorf("operation context: %w", err)
• Use errors.Is(err, target) for sentinel errors
• Use errors.As(err, &target) for typed errors
• Define domain errors as sentinel values or custom types
• Never panic in library code — panic only for truly unrecoverable programmer errors
• At API boundary: map domain errors to HTTP status codes, return JSON error response

Custom Error Types

type NotFoundError struct {
    Resource string
    ID       string
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %s not found", e.Resource, e.ID)
}

Testing

Use the testing package with table-driven tests:

func TestAdd(t *testing.T) {
    tests := []struct {
        name     string
        a, b     int
        expected int
    }{
        {"positive", 1, 2, 3},
        {"negative", -1, -2, -3},
        {"zero", 0, 0, 0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := Add(tt.a, tt.b)
            if result != tt.expected {
                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, result, tt.expected)
            }
        })
    }
}

Conventions

• Test files: *_test.go in same package
• Test naming: TestFuncName_Condition or TestFuncName with subtests
• Use t.Run() for subtests
• testify/assert or testify/require if present in project (don't add without reason)
• testcontainers-go for integration tests with real databases
• Use t.Helper() in test helper functions
• Use t.Parallel() for independent tests

Naming

• Exported: PascalCase (GetUser, UserService)
• Unexported: camelCase (getUserByID, parseConfig)
• Acronyms: All caps (HTTPClient, UserID, JSONAPI — not HttpClient, UserId)
• Interfaces: Name by behavior, not I-prefix (Reader, Writer, Storer — not IReader)
• Single-method interfaces: Name after the method (type Closer interface { Close() error })
• Packages: Short, lowercase, singular (user, http, config — not users, utils)
• Receivers: Short, 1-2 letters, consistent (func (s *Server) Start())

Interfaces

• Accept interfaces, return structs — functions take interface params but return concrete types
• Define interfaces at the consumer side, not where the implementation lives
• Keep interfaces small — prefer single-method interfaces (Go idiom)
• Use interfaces for testing boundaries (mock external deps)

// Defined by the consumer, not the implementor
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*model.User, error)
}

type UserService struct {
    repo UserRepository  // Accepts interface
}

Concurrency

• Use context.Context as first parameter for cancellation and timeout propagation
• errgroup.Group for parallel work with error collection
• Goroutines: always handle errors, don't leak (use context.WithCancel)
• Channels: prefer unidirectional (chan<-, <-chan) in function signatures
• sync.Mutex for shared state; keep critical sections small
• Never start goroutines in init()

Code Quality

• Run gofmt / goimports — non-negotiable
• golangci-lint with project config (.golangci.yml)
• No unused variables or imports (compiler enforces)
• Errors are values — handle them, don't ignore
• Prefer returning errors over logging and continuing
• Use context.Context for request-scoped values and cancellation

Anti-Patterns

• Naked returns (confusing in functions longer than a few lines)
• init() overuse (hard to test, implicit ordering)
• panic in library code (return errors instead)
• Global mutable state (inject dependencies)
• Ignoring errors with _
• God packages named utils or helpers
• Interfaces with many methods (keep them small)
• Not using context.Context for cancellation

Additional Resources

For detailed patterns, consult:

• references/patterns.md — HTTP handlers, middleware, database, logging, config, graceful shutdown