go-service-idioms

Go Service Idioms

Provide idiomatic, production-grade Go patterns for backend services: error handling, context propagation, concurrency, package layout, and testing. Apply these defaults whenever writing or reviewing Go code in this catalog's domain, unless the surrounding project's existing conventions say otherwise — match existing patterns first, fall back to this skill's defaults for new code.

Error handling

Wrap errors with %w and enough context to debug without a stack trace, never discard an error silently, and never use panic for expected failure paths (bad input, network failure, not-found). Reserve panic for programmer errors (nil deref, invariant violation) that should crash fast in development.

cfg, err := loadConfig(path)
if err != nil {
    return nil, fmt.Errorf("load config from %s: %w", path, err)
}

Define sentinel errors (var ErrNotFound = errors.New("not found")) or typed errors when callers need to branch on failure kind, and check them with errors.Is / errors.As — never string-match an error message.

Do not wrap an error and then also log it at every layer it passes through; wrap once, log once at the boundary that handles it (an HTTP handler, a CLI entrypoint, a queue consumer).

Context propagation

Thread context.Context as the first parameter of any function that does I/O (network call, DB query, file read over a slow mount) so callers can cancel or bound it with a deadline. Never store a context.Context in a struct field — pass it explicitly through the call chain.

func fetchReservation(ctx context.Context, db *sql.DB, id string) (*Reservation, error) {
    row := db.QueryRowContext(ctx, "SELECT ... WHERE id = $1", id)
    ...
}

Check ctx.Err() (or select on ctx.Done()) inside loops that could run long, and return promptly with ctx.Err() wrapped, rather than polling with time.Sleep.

Concurrency

Prefer golang.org/x/sync/errgroup over hand-rolled sync.WaitGroup + manual error channel when fanning out concurrent work that can fail: