golang-expert
Universal expert guide for Golang development. Covers code style, concurrency, context, data structures, database access, design patterns, documentation, error handling, naming conventions, performanc
SKILL.mdskills/golang-expert/SKILL.md
GitHubGolang Expert Guide
This skill is the definitive source for idiomatic Golang development, consolidating best practices across all engineering domains.
🛠 Core Principles
- KISS & YAGNI: Avoid premature abstraction. A little copying is better than a little dependency.
- Composition over Inheritance: Use interfaces to define behavior, not hierarchies.
- Explicit over Implicit: No hidden magic. Errors are values, not exceptions.
📏 Code Style & Naming
- Naming: Use
MixedCaps(PascalCase/camelCase), no snake_case. Acronyms stay capitalized (e.g.,HTTPClient). - Structure: Package doc first, then imports, constants, types, constructors, methods.
- Exporting: Unexport aggressively. Only export what is necessary for the public API.
- Formatting: Always use
gofmtorgofumpt.
⚡ Concurrency & Context
- Goroutines: Every goroutine must have a clear exit strategy (context or done channel).
- Channels: Share memory by communicating. Use unbuffered channels by default. Only senders close channels.
- Context: Pass
ctx context.Contextas the first parameter. Propagate it through all layers. Never store context in structs. Usecontext.WithoutCancelfor background work that must outlive the request.
🗃 Data Structures & Performance
- Slices: Preallocate capacity with
make([]T, 0, cap)when the size is known. - Maps: Not thread-safe. Use
sync.Mutexorsync.Mapfor concurrent access. - Performance: Optimize only after profiling. Use
sync.Poolfor hot-path allocations.
🛡 Security & Error Handling
- Errors: Wrap errors with
%wfor context. Useerrors.Isanderrors.As. - Security: Prevent SQL injection using parameterized queries. Use
gosecfor SAST. - PII: Never log raw PII. Use structured logging (
slog).
🧪 Testing & Quality
- Table-Driven Tests: Use anonymous structs for test cases with explicit
namefields. - Mocks: Use interfaces to mock dependencies. Prefer
testify(assert, require, suite) for assertions; avoidgomockunless generated proto mocks. - Race Detection: Always run tests with
-race. CI NON-NEGOTIABLE:-race -count=1(count=1 disables test caching for correctness). - Linting CI: Pipeline NON-NEGOTIABLE block on
golangci-lint runwith a curated config (govet, errcheck, gosimple, unused, staticcheck, misspell, gosec, prealloc, nilerr, asasalint).
🛜 HTTP Routers & Middleware Chains (E04 Gap B03 · CHE_RULES §XI Table 2 row 740)
Pick one router per project. NEVER mix routers in the same binary:
| Router | When to use |
|---|---|
net/http + chi (stdlib-compatible) |
Default for APIs < 100 routes. chi.Router patterns play nicely with http.Handler; enables r.Route("/v1", ...) grouping with sub-middleware scopes. |
| Gin | High-throughput JSON APIs with built-in binding/validation. Batteries included but closed ecosystem — gin.HandlerFunc is NOT http.HandlerFunc without adapter. |
| Echo | Balanced batteries + stdlib compat via echo.WrapHandler. Good for teams wanting middleware conventions without Gin lock-in. |
| Fiber | Lowest allocations (fasthttp under the hood). Use ONLY when raw RPS matters; NOT http.Handler compatible — hardest to swap later. |
Middleware order MATTERS. Outer-first execution:
- 🔝 Recover / Panic handler (always OUTERMOST — catches anything downstream)
- Request ID injection (
X-Request-Idpropagates tocontext+ response) - Tracing (OpenTelemetry
otelhttp/ otelgin / otelecho middleware — BEFORE auth so failures are traced) - Structured access log (slog / zap — writes
status,latency_ms,method,route,trace_id) - CORS
- Body size limit (prevents OOM before deserialization)
- Rate limiter (token bucket, global per-IP or per-user)
- AuthN middleware (JWT / session validates identity — populates
ctxwithuserID) - AuthZ / RBAC middleware (checks role / permission against populated identity)
- 🔚 Route handler
chi pattern — nested routing with scoped middleware (idiomatic):
r := chi.NewRouter()
r.Use(mw.Recoverer, mw.RequestID, otelhttp.NewMiddleware("server"))
r.Route("/v1", func(r chi.Router) {
r.Use(mw.Logger) // applies only to /v1/*
r.Post("/login", handleLogin) // public
r.Route("/admin", func(r chi.Router) {
r.Use(RequireRole("admin")) // applies only to /v1/admin/*
r.Get("/users", handleListUsers)
})
})
🗄 Database Access Patterns (E04 Gap B03 · CHE_RULES §XI Table 2 rows 741-743)
Go has FOUR viable data layers with different trade-offs. Pick ONE per repo.
L1 — database/sql + driver (pure stdlib)
- Use for: micro-services with < 10 hand-written queries.
- Rules:
db.SetMaxOpenConns(Ncpu*4),db.SetMaxIdleConns(Ncpu*2),db.SetConnMaxLifetime(30m). - Always pass
ctxtoQueryContext/ExecContext. Usesql.NullXxxor*Tfor nullable columns.
L2 — sqlx (thin stdlib extension — DEFAULT CHOICE for 60% of projects)
- Use for: CRUD apps wanting struct scanning / named parameters WITHOUT ORM overhead.
- NON-NEGOTIABLE: Use
sqlx.DB.Select/Getfor 1-N struct scans;NamedExecfor:parambind vars that work across drivers. - Transactions: always
tx := sqlxDB.BeginTxx(ctx, nil)thendefer tx.Rollback()before first statement; explicittx.Commit()only AFTER the full happy path.
L3 — GORM (full ORM — use only if prototyping speed matters)
- Use for: admin backends, internal tools, rapid iteration. NOT recommended for performance-critical hot paths.
- Rules:
gorm.Open(postgres.New(...), &gorm.Config{SkipDefaultTransaction: true})disables implicit tx per query (2x faster). Alwaysdb.WithContext(ctx).Where(...). - Associations: Use
Preload("X")orJoins("X")explicitly. NeverPreload(clause.Associations)in production queries — it is a SELECT N+1 footgun.
L4 — sqlc (compile-time SQL codegen — SAFEST & FASTEST for > 30 queries)
- Use for: services with stable, long-lived SQL. Write SQL files, sqlc generates type-safe Go. THIS IS NON-NEGOTIABLE when query count > 30.
- Workflow: write
schema.sql+query.sql→sqlc generate→ use generatedQuerierinterface +pgxpool. Mocks are trivial becauseQuerieris an interface. - Pair with
github.com/jackc/pgx/v5/stdliborpgxpool.Poolas the connection pool for Postgres.
Connection pool rule across ALL tiers: Acquire timeout = context.WithTimeout(ctx, 2s) before pool Acquire to prevent queue storms under load. See E05 K8s startup/readiness probes for pool health signals.
🛰 gRPC (grpc-go) (E04 Gap B03 · CHE_RULES §XI Table 2 row 744)
Interceptor chain (order = outer → inner, same as HTTP):
Unary (client + server):
- 🔝 Recovery (panic →
codes.Internal— NEVER let panics propagate) - OTel tracing (
otelgrpc.UnaryServerInterceptor+otelgrpc.UnaryClientInterceptor) - Structured access log (
status_code,method,peer,latency_ms,trace_id) - Deadline validation / minimum deadline enforcement (prevents infinite calls)
- AuthN: extract
authorizationmetadata → validate JWT/session → inject identity intoctx - AuthZ RBAC check against identity
- 🔚 Handler
Streaming: mirror the chain with StreamServerInterceptor variants.
Deadline & cancellation contract (NON-NEGOTIABLE):
- Client: ALWAYS set per-call deadline with
grpc.WithTimeout(ctx, 250*time.Millisecond)orgrpc.CallOption— never rely on parent ctx alone. - Server: Read deadline from incoming context:
if deadline, ok := ctx.Deadline(); okthen short-circuit heavy work if remaining < threshold. - Metadata propagation: Use
metadata.FromIncomingContext(ctx)for inbound;metadata.NewOutgoingContext+grpc.Peerfor outbound hops. Propagatetraceparent,x-request-id, andauthorizationthrough every hop.
🖥️ CLI Applications (cobra + viper) (E04 Gap B03 · CHE_RULES §XI Table 2 row 745)
Conventions:
- Single binary, multiple subcommands:
mycli serve,mycli migrate,mycli seed,mycli version. - Precedence chain for config values (HIGHEST → LOWEST, NON-NEGOTIABLE):
- Explicit CLI flag (
--port) - Environment variable (
MYCLI_PORT) — auto-mapped via viper withAutomaticEnv()+SetEnvPrefix("MYCLI")+EnvKeyReplacer(./-→_) - Config file (
config.yamlin CWD or$HOME/.mycli/) - Hardcoded default (in
flags.Int("port", 8080, "..."))
- Explicit CLI flag (
Cobra patterns:
var rootCmd = &cobra.Command{
Use: "mycli",
Short: "My service CLI",
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
// Loads viper config once, applies to ALL subcommands.
// Validates env vars here; return error = CLI exits 1 cleanly.
return validateConfig(v)
},
}
- Use
PersistentFlags()for flags that apply to every subcommand (e.g.--log-level,--config). Use regularFlags()for command-specific ones. - NEVER use globals for flag values. Bind to a strongly-typed
Configstruct inPersistentPreRunEand inject down.
📝 Logging + Observability Integration (E04 Gap B03 · CHE_RULES §XI Table 2 row 746 → companion E05 §Observability & engineering-contracts §19)
slog (stdlib Go 1.21+) → DEFAULT for most services
- Bootstrap ONCE in
main()with JSON handler:logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))thenslog.SetDefault(logger). - Inject structured fields via
slog.LogAttrs(ctx, slog.LevelInfo, "request_handled", slog.String("route", r), slog.Int("status", s), slog.Duration("latency_ms", d), slog.String("trace_id", traceIdFromCtx(ctx))). - NEVER call
.Error()without a wrapped error:slog.Error("db query failed", "err", err, "query", q)(structured "err" key, NOT formatted into the message).
zap (Uber) → use when allocations matter < 1µs per log
- Use
zap.NewProduction()in prod,zap.NewDevelopment()for local. Alwaysdefer logger.Sync(). - Prefer
logger.Info("msg", zap.String("trace_id", tid), zap.Int("status", s))overSugaredLoggerin hot paths (zero allocations).
OTel + TraceId correlation (bridge to E05):
- Every log line in scope of a request MUST include the propagated
trace_id(extracted fromotel.TraceIDFromSpanContext(otel.GetTraceSpanContext(ctx))). trace_idformat = same asengineering-contracts §19(16 bytes hex). PII hash rule: same as S07 CHE_RULES §X (raw emails/phones never in logs; hash correlation viaNOTIFICATION_PII_HASH_SECRETor equivalent).
💊 Generics 1.18+ Helpers (E04 Gap B03 · CHE_RULES §XI Table 2 row 747)
A small stdlib-style helpers package eliminates 80% of one-off boilerplate. Put these in a single pkg/util/ file (NOT across the codebase):
// Must panics on error (use ONLY in init() / constants / CLI arg parsing before main loop).
func Must[T any](v T, err error) T {
if err != nil { panic(err) }
return v
}
// Ptr converts a value literal to pointer (avoids `x := v; &x`).
func Ptr[T any](v T) *T { return &v }
func Deref[T any](p *T, fallback T) T {
if p == nil { return fallback }
return *p
}
// Slice transformations (pure, no allocation footguns):
func Map[A, B any](in []A, f func(A) B) []B { /* ... */ }
func Filter[T any](in []T, pred func(T) bool) []T { /* ... */ }
func Reduce[T, Acc any](in []T, acc Acc, f func(Acc, T) Acc) Acc { /* ... */ }
func Max[T cmp.Ordered](a, b T) T { if a > b { return a }; return b }
func Min[T cmp.Ordered](a, b T) T { if a < b { return a }; return b }
Rules: Keep helper count < 15 per project. If adding the 16th, stop — it is probably domain logic and belongs in a domain package.
♻️ Runtime — Graceful Shutdown + Health Probes (E04 Gap B03 · CHE_RULES §XI Table 2 row 748 → companion E05 §K8s Probes)
Graceful shutdown (2-phase, NON-NEGOTIABLE for any network service):
// Phase 1 — stop accepting, drain inflight within deadline
ctx, stop := signal.NotifyContext(context.Background(),
syscall.SIGINT, syscall.SIGTERM)
defer stop()
go srv.Serve(listener) // starts server in goroutine (NOT blocking main)
<-ctx.Done() // blocks until signal
// Phase 2 — shutdown with hard deadline after inflight drain window
graceCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
// Tear down ORDER MATTERS:
// 1. HTTP/gRPC server (stops accepting, waits handlers return) → 2. DB pool → 3. Redis → 4. Workers → 5. Logger flush
if err := srv.Shutdown(graceCtx); err != nil { slog.Warn("graceful shutdown incomplete", "err", err) }
dbPool.Close()
If Shutdown() returns before deadline → clean exit 0. If deadline fires → force-exit 1 (losing some inflight > 25s is preferable to OOMKill hanging pod).
Health endpoints (E05 K8s companion):
GET /healthz→ Liveness probe. Returns 200 when process is alive. Do NOT tie to DB/Redis here (if you do, flapping infra kills all pods at once).GET /readyz→ Readiness probe. Returns 200 ONLY when: listener bound + DB poolPingOK + external dependency checks OK. Returns 503 during startup/shutdown window so K8s stops routing new traffic BEFORE shutdown (avoids 502s during rolling update).- Use
chimount:r.Get("/healthz", func(w http.ResponseWriter,_) { w.WriteHeader(200) }). Keep handlers < 1ms.
🔵 B-P1 Go · Codegen ORM + DI + Mocks (E04 §XI P1 coverage 55% → ~65%)
ent ORM (DEFAULT when domain > 15 entities, pure codegen 0 raw SQL leak)
ent = schema-first typed codegen ORM. If you hand-write 40+ SELECTs and the domain is rich (bounded contexts with 15+ types), use ent. Skip ent for projects < 5 tables (sqlc/sqlx simpler).
- Schema directory, 1 file per entity:
ent/schema/event.go → ent/schema/ticket.go → ent/schema/order.go - Codegen step NON-NEGOTIABLE checked into CI:
go generate ./ent/→ emitsent/client.go+ 40 typed methods. CI MUST rungo generateandgit diff --exit-codeto ensure generated code matches schema. If not → FAIL build. - Hooks / Privacy policies: ent.Privacy = row-level RBAC in the generated layer, no manual WHERE. Example privacy rule that returns
ent.DenyIfNoViewer()for ALL mutations if there's no authenticated user → impossible to forget in a handler. - Ent edge traversals:
client.QueryUser().QueryOrders().Where(order.StatusEQ(...)).All(ctx)— typed joins, zero string queries.
Google Wire Compile-Time DI vs Uber Fx Runtime DI (DECISION):
| Situation | Pick | Rule |
|---|---|---|
| Clean startup time, NO reflection, compile-time errors | Wire (wire.NewSet + wire.Build) |
100% codegen. DI graph errors → compile fails. DEFAULT 90% Go services. |
| Dynamic plugins loaded at runtime, conditional modules | Uber Fx | fx.Provide + fx.Invoke. Runtime panics if graph wrong (compile cannot catch). Use ONLY for plugin architectures. |
| Wire workflow minimal: |
// wire.go
//go:build wireinject
var ProviderSet = wire.NewSet(NewDB, NewOrderRepo, NewOrderService, NewHandler)
func InitializeApp() (*App, func(), error) { wire.Build(ProviderSet); return nil, nil, nil }
Run go generate → wire_gen.go → 100% typed graph, no service.NewService(db.NewDB(conf)) constructors 10 deep = maint cost -80%.
Testify Mocks + Suite (DEFAULT testing framework companion)
suite.Suitewith SetupTest/TearDownTest replaces duplicatedt.Cleanupboilerplate in every test function.gomock/testify/mockfor interfaces: NEVER mock concrete structs. Mock ONLY interfaces. Hand-written mocks for 1-2 methods;mockgencodegen for interfaces > 3 methods.- Verify mock calls:
mockRepo.AssertExpectations(t)at end of EVERY test using a mock — if you forgot to expect a call that was made, test FAIL (catches regressions you wouldn't otherwise). - Table-driven pattern PRESERVED + suite:
func (s *OrderServiceSuite) TestCreateOrder() { cases := []struct{ name string; in CreateIn; wantErr bool }{ {"ok", CreateIn{UserID: 1, ItemIDs: []int64{5}}, false}, {"empty items", CreateIn{UserID: 1, ItemIDs: nil}, true}, } for _, tc := range cases { s.Run(tc.name, func() { ... }) } }