Golang Mastery (Senior → Principal)

Operate

• Start by confirming: goal, scope, constraints (Go version, platform, deps), non-functional requirements (latency/throughput/SLO), and “done”.
• Prefer small, end-to-end changes with tests; keep diffs easy to review (unless the user asks otherwise).
• Stdlib-first and “boring” solutions by default; add dependencies only when constraints justify them.
• Explain tradeoffs briefly; keep output actionable (commands, file paths, checklists).

The goal is not “it works locally”, but “it survives production”: clear boundaries, observable behavior, secure defaults, and low ops cost.

Default Go Standards

• Keep packages cohesive; avoid “util” grab-bags; name packages by responsibility, not type.
• Export only what must be used externally; keep APIs minimal and stable.
• Use context.Context for cancellation/timeouts at boundaries; pass ctx as first arg.
• Return errors, do not log-and-return the same error; wrap with %w for context.
• Avoid global state; prefer dependency injection via constructors and interfaces.
• Avoid premature interfaces; introduce interfaces at the consumer boundary.
• Concurrency: avoid shared mutable state; prefer channels for coordination, mutexes for invariants; always handle cancellation and shutdown.

“Bad vs Good” (common production pitfalls)

// ❌ BAD: log-and-return (double logging), no useful context
if err != nil {
    slog.Error("create user failed", "err", err)
    return err
}

// ✅ GOOD: log once at the boundary; wrap error with context
if err != nil {
    return fmt.Errorf("create user: %w", err)
}

Workflow (Feature / Refactor / Bug)

1. Reproduce or specify behavior (tests first if feasible).
2. Sketch design: public API, package boundaries, data shapes, failure modes, concurrency model.
3. Implement smallest slice end-to-end.
4. Add/adjust tests and benchmarks (when performance-sensitive).
5. Validate: formatting, vet, tests, race (when relevant).
6. Review for production readiness: config, logging, metrics, timeouts, retries, shutdown.

Validation Commands

• Run gofmt -w (go list -f '{{.Dir}}' ./...) (PowerShell: gofmt -w @(go list -f '{{.Dir}}' ./...)) and ensure no diffs remain.
• Run go test ./....
• Run go test -race ./... for concurrent code or servers (where supported).
• Run go test -run TestName -count=1 ./path to avoid cached results when debugging.
• Run go test -bench . -benchmem ./... for hotspots.
• If available, run golangci-lint run (or golangci-lint run --fast-only during local iteration).
• If available, run govulncheck ./... (or govulncheck -test ./...) before release.

If you want PowerShell entrypoints:

• sanity: scripts/go_sanity.ps1
• security/vuln: scripts/go_security.ps1

Project Structure & Dependencies

See references/project-structure.md for pragmatic layouts by project size, dependency direction guidance, and package naming heuristics.

Tooling (Up-to-date defaults)

See references/tooling.md for a safe baseline linter set, handling false positives, and configuration patterns.

Advanced Topics (Production)

Use these when the project demands “senior+” rigor (many sections include ❌/✅ patterns):

• Arsitektur & boundaries: references/architecture.md
• Principal playbook (casebook + decision tree): references/principal-playbook.md
• Coding standards (review-required): references/coding-standards.md
• Anti-patterns & bug traps: references/anti-patterns.md
• Concurrency (race/leak/backpressure): references/concurrency.md
• Errors & taxonomy: references/errors.md
• HTTP API & status codes: references/http-api.md
• gRPC (contracts, deadlines, streaming, retries): references/grpc.md
• Frameworks (Gin/Fiber/Beego): references/frameworks.md
• Database & queries: references/database.md
• Migrations and rollbacks (deploy-safe schema change): references/migrations-and-rollbacks.md
• Query engineering (Postgres/SQLC): references/query-engineering.md
• Auth (sessions/JWT/OAuth2): references/auth.md
• Multi-tenant systems (isolation, quotas, blast radius): references/multi-tenant-systems.md
• Outbound HTTP & SSRF hardening: references/outbound-http.md
• Idempotency & outbox: references/idempotency-outbox.md
• Security: references/security.md
• Reliability (timeouts, retries, backpressure): references/reliability.md
• Observability (OTel, correlation): references/observability.md
• Incident runbooks (triage, rollback, blast-radius control): references/incident-runbooks.md
• Log/trace correlation: references/log-correlation.md
• OTel bootstrap: references/otel-bootstrap.md
• Performance (pprof/trace/allocs): references/performance.md
• Testing advanced: references/testing-advanced.md
• Distributed systems: references/distributed-systems.md
• Examples (real-world skeleton): references/examples.md
• Patterns (DI/options/circuit-breaker): references/patterns.md
• Snippets (copy/paste-safe): references/snippets.md

Service/HTTP Defaults

• Set timeouts: server ReadHeaderTimeout, client Timeout/transport timeouts; avoid unbounded requests.
• Always implement graceful shutdown: close listeners, stop accepting, drain, cancel contexts, waitgroups.
• Prefer structured logs; include request IDs; avoid logging secrets/PII.
• Add health endpoints (/healthz, /readyz) and basic metrics hooks.

Docker & Release Defaults

See references/docker.md for secure, reproducible Docker patterns (multi-stage builds, non-root, no latest, health checks).

Data & Persistence Defaults

• Validate inputs at the boundary; normalize early.
• Make error taxonomy explicit (not found, conflict, invalid, unavailable).
• Prefer migrations and explicit schemas; keep transactional boundaries clear.
• Keep domain logic independent of transport (HTTP/GRPC/CLI) where feasible.

Debugging & Performance

• Use pprof and benchmarks for performance claims; measure before/after.
• Watch allocations; prefer strings.Builder, bytes.Buffer, preallocation when proven necessary.
• Avoid reflection-heavy paths in hot loops unless unavoidable.

Security Checklist (Minimum)

• Validate and bound untrusted input (size, depth, time).
• Use crypto/rand for security tokens; never roll your own crypto.
• Store secrets in env/secret managers; never log secrets.
• Prefer least privilege and explicit allowlists for network/file operations.

Library Selection (Practical)

See references/libraries.md for a conservative shortlist (stdlib-first) plus config/env decoding examples.

Code Review Checklist

See references/checklists.md and references/code-review.md for PR checklists (API, concurrency, testing, ops).

Snippets

See references/snippets.md for copy/paste-safe patterns (graceful shutdown, context plumbing, worker pools).

Scripts

• scripts/go_sanity.ps1 - runs gofmt, go test, go vet, optional -race, and golangci-lint if installed.
• scripts/go_security.ps1 - runs govulncheck + quick hardening checks (and optional gosec/staticcheck if installed).
• scripts/init_project.py - bootstraps a clean Go project skeleton (optional).