Go Best Practices Type-First Development
Types define the contract before implementation. Follow this workflow:
Define data structures - structs and interfaces first Define function signatures - parameters, return types, and error conditions Implement to satisfy types - let the compiler guide completeness Validate at boundaries - check inputs where data enters the system Make Illegal States Unrepresentable
Use Go's type system to prevent invalid states at compile time.
Structs for domain models:
// Define the data model first type User struct { ID UserID Email string Name string CreatedAt time.Time }
type CreateUserRequest struct { Email string Name string }
// Functions follow from the types func CreateUser(req CreateUserRequest) (*User, error) { // implementation }
Custom types for domain primitives:
// Distinct types prevent mixing up IDs type UserID string type OrderID string
func GetUser(id UserID) (*User, error) { // Compiler prevents passing OrderID here }
func NewUserID(raw string) UserID { return UserID(raw) }
// Methods attach behavior to the type func (id UserID) String() string { return string(id) }
Interfaces for behavior contracts:
// Define what you need, not what you have type Reader interface { Read(p []byte) (n int, err error) }
type UserRepository interface { GetByID(ctx context.Context, id UserID) (User, error) Save(ctx context.Context, user User) error }
// Accept interfaces, return structs func ProcessInput(r Reader) ([]byte, error) { return io.ReadAll(r) }
Enums with iota:
type Status int
const ( StatusActive Status = iota + 1 StatusInactive StatusPending )
func (s Status) String() string { switch s { case StatusActive: return "active" case StatusInactive: return "inactive" case StatusPending: return "pending" default: return fmt.Sprintf("Status(%d)", s) } }
// Exhaustive handling in switch func ProcessStatus(s Status) (string, error) { switch s { case StatusActive: return "processing", nil case StatusInactive: return "skipped", nil case StatusPending: return "waiting", nil default: return "", fmt.Errorf("unhandled status: %v", s) } }
Functional options for flexible construction:
type ServerOption func(*Server)
func WithPort(port int) ServerOption { return func(s *Server) { s.port = port } }
func WithTimeout(d time.Duration) ServerOption { return func(s *Server) { s.timeout = d } }
func NewServer(opts ...ServerOption) *Server { s := &Server{ port: 8080, // sensible defaults timeout: 30 * time.Second, } for _, opt := range opts { opt(s) } return s }
// Usage: NewServer(WithPort(3000), WithTimeout(time.Minute))
Embed for composition:
type Timestamps struct { CreatedAt time.Time UpdatedAt time.Time }
type User struct { Timestamps // embedded - User has CreatedAt, UpdatedAt ID UserID Email string }
Module Structure
Prefer smaller files within packages: one type or concern per file. Split when a file handles multiple unrelated types or exceeds ~300 lines. Keep tests in _test.go files alongside implementation. Package boundaries define the API; internal organization is flexible.
Functional Patterns Use value receivers when methods don't mutate state; reserve pointer receivers for mutation. Avoid package-level mutable variables; pass dependencies explicitly via function parameters. Return new structs/slices rather than mutating inputs; makes data flow explicit. Use closures and higher-order functions where they simplify code (e.g., sort.Slice, iterators). Instructions Return errors with context using fmt.Errorf and %w for wrapping. This preserves the error chain for debugging. Every function returns a value or an error; unimplemented paths return descriptive errors. Explicit failures are debuggable. Handle all branches in switch statements; include a default case that returns an error. Exhaustive handling prevents silent bugs. Pass context.Context to external calls with explicit timeouts. Runaway requests cause cascading failures. Reserve panic for truly unrecoverable situations; prefer returning errors. Panics crash the program. Add or update table-driven tests for new logic; cover edge cases (empty input, nil, boundaries). Examples
Explicit failure for unimplemented logic:
func buildWidget(widgetType string) (*Widget, error) { return nil, fmt.Errorf("buildWidget not implemented for type: %s", widgetType) }
Wrap errors with context to preserve the chain:
out, err := client.Do(ctx, req) if err != nil { return nil, fmt.Errorf("fetch widget failed: %w", err) } return out, nil
Exhaustive switch with default error:
func processStatus(status string) (string, error) { switch status { case "active": return "processing", nil case "inactive": return "skipped", nil default: return "", fmt.Errorf("unhandled status: %s", status) } }
Structured logging with slog:
import "log/slog"
var log = slog.With("component", "widgets")
func createWidget(name string) (*Widget, error) { log.Debug("creating widget", "name", name) widget := &Widget{Name: name} log.Debug("created widget", "id", widget.ID) return widget, nil }
Configuration Load config from environment variables at startup; validate required values before use. Missing config should cause immediate exit. Define a Config struct as single source of truth; avoid os.Getenv scattered throughout code. Use sensible defaults for development; require explicit values for production secrets. Examples
Typed config struct:
type Config struct { Port int DatabaseURL string APIKey string Env string }
func LoadConfig() (*Config, error) { dbURL := os.Getenv("DATABASE_URL") if dbURL == "" { return nil, fmt.Errorf("DATABASE_URL is required") } apiKey := os.Getenv("API_KEY") if apiKey == "" { return nil, fmt.Errorf("API_KEY is required") } port := 3000 if p := os.Getenv("PORT"); p != "" { var err error port, err = strconv.Atoi(p) if err != nil { return nil, fmt.Errorf("invalid PORT: %w", err) } } return &Config{ Port: port, DatabaseURL: dbURL, APIKey: apiKey, Env: getEnvOrDefault("ENV", "development"), }, nil }