Go Microservice

Go Microservice

Overview

A Go service is six things: config, an HTTP/RPC surface, state (DB + cache), async work, outbound calls, and operability. Get those right and the rest is business logic. Go's defaults are safe for CLIs and unsafe for servers — most of this skill is about the settings nobody sets until an incident forces them to.

Verified against Go 1.26 (current, Feb 2026) as of 2026-08. Library versions throughout come from proxy.golang.org, not from blog posts — check go list -m -u <module> for anything newer.

When to Use

• Starting a new Go service, or adding an endpoint/consumer to an existing one
• Choosing a router, database layer, cache client, or queue library
• Reviewing Go service code for production-readiness
• Diagnosing: goroutine leaks, OOMKills, CPU throttling, dropped requests on deploy, connection-pool exhaustion, "slow under load but fine locally"
• Containerising a Go service, or tuning it for Kubernetes

Not for: CLI tools (much of this is irrelevant), library design, or non-service Go.

Step 0: Choose the HTTP layer

Since Go 1.22 the stdlib does method + wildcard routing. Start there and add a router only when you feel the absence. Full comparison, and fiber's net/http incompatibility, in references/frameworks.md.

Quick Reference

Bootstrap a new service

myservice/
  cmd/myservice/main.go      # entry point: parse config, wire, run. Keep it thin.
  internal/
    config/                  # typed config, validated at boot
    http/                    # handlers, middleware, router
    service/                 # business logic — no HTTP or SQL types here
    store/                   # DB access (sqlc output or repositories)
    client/                  # outbound HTTP/gRPC clients
  migrations/
  Dockerfile
  Makefile

1. go mod init <module> — set the go directive to 1.25+ so you get container-aware GOMAXPROCS.
2. Config struct + LoadConfig() that fails fast on missing/invalid values.
3. run() error called from main() — not logic in main, because os.Exit skips deferred cleanup.
4. http.Server with all timeouts set (ReadHeaderTimeout at minimum).
5. /healthz (liveness, process-local) and /readyz (readiness, checks dependencies).
6. Middleware: request ID → structured logging → metrics → panic recovery.
7. Graceful shutdown with the correct drain order — copy it from references/packaging-deploy.md, don't improvise.
8. GOMEMLIMIT ≈ 90% of the container memory limit.

The non-negotiables

These cause incidents when skipped. Everything else is preference.

1. Every http.Server timeout set. &http.Server{Handler: mux} with no timeouts is vulnerable to slowloris by default. ReadHeaderTimeout is the bare minimum.
2. Every outbound call has a timeout. http.DefaultClient has none. A hung dependency with no timeout is how one service's slowness becomes your outage.
3. context.Context first parameter on anything that blocks, propagated, never stored in a struct. Every WithTimeout gets defer cancel().
4. Graceful shutdown, in order: fail readiness → wait for LB propagation → stop accepting → drain in-flight → stop consumers → close resources.
5. GOMEMLIMIT set on every containerised service. GOGC is ratio-based and knows nothing about your cgroup limit — this is the cheapest OOMKill prevention available.
6. Structured logs to stdout as JSON, with a request ID. Never a formatted sentence; never secrets.
7. recover() in every long-lived goroutine. An unrecovered panic in any goroutine kills the whole process.
8. Bounded fan-out. errgroup.SetLimit, or a semaphore. Unbounded concurrency against a dependency is a self-inflicted DoS.
9. Consumers are idempotent. At-least-once delivery is the only kind you get.
10. go test -race in CI. A detected race is a bug, not a flake.

Reference Map

Common Mistakes