| name | go-expert |
| description | Use when writing, debugging, reviewing, or discussing Go code, goroutines, channels, Go modules, gRPC, Go tooling, profiling, or any Go ecosystem concern. Covers concurrency, standard library, testing, performance, security, cryptography, frameworks, project layout, platform-specific builds, cgo, and common pitfalls. Trigger keywords include Go, golang, goroutine, channel, go mod, go build, go test, go vet, gRPC, protobuf, delve, pprof, TinyGo, cgo, net/http, Go module, GOPATH, GOOS, and GOARCH. |
Go Expert
A comprehensive Go reference for writing, reviewing, debugging, and reasoning
about Go code. This skill IS the knowledge — every section carries executable
code that demonstrates correct idioms, common pitfalls, and the library
surface you reach for in practice.
Every code block is runnable Go (unless marked as pseudo-code). Prefer the
pattern shown here over inventing your own — Go's ecosystem has converged on
these conventions through a decade of production use.
1. Go Language Core
1.1 Zero Values
Every type has a zero value — the default when a variable is declared but not
initialized. Go never leaves memory uninitialized, and this property is the
foundation of many patterns (nil channels in select, nil slices as empty,
zero-valued structs as usable defaults).
var i int // 0
var f float64 // 0.0
var b bool // false
var s string // "" (empty string, never nil)
var p *int // nil
var sl []int // nil, len=0, cap=0 — append, range, len() all work
var m map[string]int // nil — READ returns zero value; WRITE panics
var ch chan int // nil — blocks forever on send and receive
var fn func() // nil — calling it panics
var iface io.Reader // nil interface: both type and value are nil
var st MyStruct // all fields zeroed recursively
Nil-slice and nil-map behaviour is a frequent source of bugs:
var m map[string]int
v := m["missing"] // 0 (zero value), no panic
m["key"] = 1 // PANIC: assignment to entry in nil map
var sl []int
sl = append(sl, 1) // OK: append creates backing array
for _, v := range sl {} // OK: zero iterations
n := len(sl) // 0, no panic
Nil channels are deliberate design tools:
var ch chan int
select {
case ch <- 1: // never selected — nil channel blocks forever
default:
fmt.Println("nil channel disables the send case")
}
// Disabling a select case dynamically:
var done chan struct{} // nil, so <-done never fires
select {
case <-done: // disabled
case <-ticker.C:
fmt.Println("tick")
}
1.2 Short Variable Declarations
:= declares and initializes in one statement. Re-declaration is legal in
multi-variable := when at least one variable is new in the same scope.
// Basic
x := 42 // var x int = 42
name := r.FormValue("name")
// Multi-variable — at least one must be new in this scope
f, err := os.Open("f1")
g, err := os.Open("f2") // err is re-declared, g is new; LEGAL
// Shadowing is a common bug — := creates a NEW variable in inner scope
var client *http.Client
if debug {
client, err := newDebugClient() // shadows outer client!
_ = client
}
fmt.Println(client) // nil — the outer client was never assigned
Use var when the zero value is the correct starting state, or when you need
to declare without initializing. Use := for initialization. Never use var x = expr — that is x := expr.
// Prefer var for zero-value initialization
var buf bytes.Buffer // zero value is ready to use
var mu sync.Mutex // zero value is ready to use
var wg sync.WaitGroup // zero value is ready to use
// Prefer := for expression initialization
start := time.Now()
items := fetchItems(ctx)
1.3 Named Return Values
Named return values act as local variables in the function body and are
initialized to their zero values. A bare return returns them as-is.
func split(sum int) (x, y int) {
x = sum * 4 / 9
y = sum - x
return // bare return: returns x, y
}
Named returns interact with defer in subtle but useful ways:
func readFile(path string) (content []byte, err error) {
f, err := os.Open(path)
if err != nil {
return nil, err // explicit return
}
defer func() {
if closeErr := f.Close(); closeErr != nil && err == nil {
err = closeErr // modify named return; caller sees this error
}
}()
return io.ReadAll(f)
}
Pitfalls:
// Shadowing — the inner err hides the named return
func bad() (result int, err error) {
result, err := compute() // CREATES new result and err, shadows named ones
return // bare return uses the NAMED ones — always (0, nil)!
}
// Fixed — don't shadow
func good() (result int, err error) {
var e error
result, e = compute() // e is local; result and err are named returns
if e != nil {
err = e
}
return
}
1.4 Blank Identifier
_ discards values the compiler requires but you don't need.
// Unused import with side effects
import _ "net/http/pprof" // registers handlers via init()
// Unused variable
for _, v := range items { // index discarded
process(v)
}
// Compile-time interface check (preferred over runtime panic)
var _ http.Handler = (*MyHandler)(nil) // MyHandler implements http.Handler
var _ json.Marshaler = (*MyType)(nil)
// Discard return values you genuinely don't need
f, _ := os.Open("file") // only need the file, not the error
// ⚠️ Never discard errors in production code — use for throwaway scripts only
1.5 Iota
iota is a predeclared identifier in const declarations. It increments by 1
on each const spec, resetting to 0 at each const keyword.
// Basic enumeration
type Priority int
const (
PriorityLow Priority = iota // 0
PriorityMedium // 1
PriorityHigh // 2
)
// Bitmask with iota
type Permission uint8
const (
PermRead Permission = 1 << iota // 1 (0001)
PermWrite // 2 (0010)
PermExec // 4 (0100)
PermAdmin // 8 (1000)
)
func (p Permission) Has(flag Permission) bool {
return p&flag != 0
}
// Skip values
const (
_ = iota // skip 0
KB = 1 << (10 * iota) // 1 << 10 = 1024
MB // 1 << 20 = 1048576
GB // 1 << 30
)
// Multiple iota expressions per line
const (
a, b = iota, iota + 1 // 0, 1
c, d // 1, 2
e, f // 2, 3
)
1.6 Defer
defer schedules a function call to execute when the surrounding function
returns. Arguments to the deferred function are evaluated at the defer
statement — NOT when the function executes.
// Argument evaluation time
func example() {
i := 0
defer fmt.Println(i) // i evaluated NOW (0), prints "0" at return
i++
// returns, prints 0
}
// Fix with closure if you need the final value:
func fixed() {
i := 0
defer func() { fmt.Println(i) }() // reads i when function executes
i++
// returns, prints 1
}
Execution order is LIFO (stack).
func lifo() {
defer fmt.Println("1")
defer fmt.Println("2")
defer fmt.Println("3")
// prints: 3, 2, 1
}
Common patterns:
// Resource cleanup
func processFile(path string) error {
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
return process(f)
}
// Mutex unlock
func (c *Cache) Get(key string) (Value, bool) {
c.mu.Lock()
defer c.mu.Unlock()
return c.data[key]
}
// Recovery in goroutines
go func() {
defer func() {
if r := recover(); r != nil {
log.Printf("goroutine panicked: %v", r)
}
}()
doDangerousWork()
}()
// Measuring function duration
func trace(name string) func() {
start := time.Now()
log.Printf("enter %s", name)
return func() { log.Printf("exit %s (%s)", name, time.Since(start)) }
}
func myFunc() {
defer trace("myFunc")() // note the extra () — trace returns a func
// ...
}
1.7 Panic and Recover
recover only works inside a deferred function; it returns the value passed to
panic. It returns nil when no panic is in progress.
func safeCall(fn func()) (err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic: %v", r)
}
}()
fn()
return nil
}
Recover does not propagate across goroutines. A panic in a goroutine kills
the entire program if not recovered inside that goroutine.
// WRONG — the main goroutine's defer cannot catch this panic
defer func() { recover() }()
go func() {
panic("boom") // kills the program
}()
// RIGHT — recover inside the goroutine
go func() {
defer func() { recover() }()
panic("contained")
}()
Sentinel panics — prefer errors for expected failures, reserve panics for
programmer errors (invariant violations, impossible states):
// Panic for invariant violations — things that should never happen
func divide(a, b int) int {
if b == 0 {
panic("divide by zero: invariant violation")
}
return a / b
}
// Error for expected failures — things that can happen in normal operation
func readConfig(path string) (Config, error) {
data, err := os.ReadFile(path)
if err != nil {
return Config{}, fmt.Errorf("readConfig %s: %w", path, err)
}
return parse(data)
}
1.8 Init Functions
Each file can have multiple init() functions. Within a package, they run in
source-file order (lexicographic by filename). Across packages, they run in
dependency order: a package's deps' init() runs first, then its own.
// package a imports package b
// order: b.init(), a.init()
var globalMap map[string]int
func init() {
globalMap = make(map[string]int)
globalMap["initialized"] = 1
}
Avoid init() except for: registering database drivers, registering HTTP
handlers (pprof), initializing package-level state that cannot be expressed as
a var declaration. Prefer explicit New() constructors over init-side-effects.
1.9 Build Tags
Go 1.17+ uses //go:build syntax. The old // +build syntax is still
supported but deprecated.
//go:build linux && amd64
// +build linux,amd64
package mypkg
//go:build !windows
package mypkg
//go:build go1.18
package mypkg
//go:build integration
package mypkg // test file using //go:build integration
//go:build ignore
package main // file excluded from build entirely
Common GOOS values: linux, darwin, windows, freebsd, openbsd,
netbsd, dragonfly, solaris, illumos, plan9, aix, js, wasip1,
android, ios.
Common GOARCH values: amd64, 386, arm, arm64, mips, mips64,
ppc64, ppc64le, riscv64, s390x, wasm.
1.10 Structs
type User struct {
ID int64 `json:"id" db:"user_id"`
Name string `json:"name" db:"name"`
Email string `json:"email,omitempty" db:"email"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
password string // unexported: invisible to encoding/json, encoding/xml, etc.
}
Struct tags are arbitrary string metadata accessed via reflect:
type Config struct {
Host string `env:"HOST" default:"localhost"`
Port int `env:"PORT" default:"8080"`
}
func parseEnv(v any) {
t := reflect.TypeOf(v).Elem()
for i := 0; i < t.NumField(); i++ {
field := t.Field(i)
envKey := field.Tag.Get("env")
def := field.Tag.Get("default")
_ = envKey
_ = def
}
}
Embedding (not inheritance — composition):
type Logger struct{}
func (l Logger) Info(msg string) { fmt.Println("INFO:", msg) }
type Server struct {
Logger // promoted: Server.Info(...) calls Logger.Info
addr string
}
s := Server{addr: ":8080"}
s.Info("starting") // promoted method call
// Embedding an interface in a struct creates a decorator pattern
type ReadWriter struct {
io.Reader
io.Writer
}
// ReadWriter satisfies io.ReadWriter if both fields are set
1.11 Interfaces
Go interfaces are satisfied implicitly. Any type that has the methods satisfies
the interface — no implements keyword.
type Writer interface {
Write([]byte) (int, error)
}
// os.File, bytes.Buffer, net.Conn all implement Writer — no declaration needed
// Interface segregation — small interfaces composed
type Reader interface{ Read([]byte) (int, error) }
type Closer interface{ Close() error }
type ReadCloser interface {
Reader
Closer
}
The nil-interface vs nil-concrete-value distinction — a classic Go bug:
type MyError struct{ msg string }
func (e *MyError) Error() string { return e.msg }
func doWork() error {
var err *MyError // nil concrete value
return err // returns a NON-nil error interface!
// The interface has type=*MyError, value=nil — not equal to nil
}
func main() {
err := doWork()
if err != nil {
fmt.Println("error:", err) // THIS PRINTS — err is not nil!
}
}
// Fix: return nil, not a typed nil pointer
func doWorkFixed() error {
return nil // explicitly nil
}
// Or:
func doWorkFixed2() error {
var err *MyError
if err != nil {
return err
}
return nil
}
Type assertions and type switches:
// Type assertion (panics if wrong type)
w := v.(io.Writer)
// Safe type assertion (ok pattern)
w, ok := v.(io.Writer)
if !ok {
fmt.Println("not a Writer")
}
// Type switch
switch x := v.(type) {
case nil:
fmt.Println("nil")
case int:
fmt.Println("int:", x)
case string:
fmt.Println("string:", x)
case io.Reader:
data, _ := io.ReadAll(x)
fmt.Println("reader:", len(data))
default:
fmt.Printf("unknown type: %T\n", x)
}
// Type switch with fallthrough-like logic
switch x := v.(type) {
case int, int8, int16, int32, int64:
fmt.Println("signed integer:", reflect.TypeOf(x))
case uint, uint8, uint16, uint32, uint64:
fmt.Println("unsigned integer:", reflect.TypeOf(x))
}
1.12 Generics (Go 1.18+)
Type parameters use [T any] syntax. The any constraint is an alias for
interface{}. Constraints can be interface types with type elements.
// Simple generic function
func First[T any](slice []T) (T, bool) {
if len(slice) == 0 {
var zero T
return zero, false
}
return slice[0], true
}
// Generic data structure
type Set[T comparable] struct {
data map[T]struct{}
}
func NewSet[T comparable]() *Set[T] {
return &Set[T]{data: make(map[T]struct{})}
}
func (s *Set[T]) Add(v T) {
s.data[v] = struct{}{}
}
func (s *Set[T]) Contains(v T) bool {
_, ok := s.data[v]
return ok
}
Constraints:
// The ~ operator matches any type whose UNDERLYING type matches
type Unsigned interface {
~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}
type MyUint uint // MyUint satisfies Unsigned because underlying is uint
// Ordered is built-in (golang.org/x/exp/constraints or cmp.Ordered in Go 1.21+)
func Max[T cmp.Ordered](a, b T) T {
if a > b {
return a
}
return b
}
// Custom constraint with method set
type Stringer interface {
~string | ~[]byte
String() string
}
// Type inference works for most calls
m := Max(3, 5) // T inferred as int
s := Max("a", "b") // T inferred as string
// m := Max(3, 5.0) // error: default types int and float64 mismatch
m = Max(float64(3), 5.0) // explicit conversion, T inferred as float64
1.13 Error Handling
Go errors are values. The error interface has one method: Error() string.
// Sentinel errors — fixed values, check with errors.Is
var ErrNotFound = errors.New("not found")
var ErrPermission = errors.New("permission denied")
// Error types — custom structs, check with errors.As
type ValidationError struct {
Field string
Value any
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("validation: %s=%v", e.Field, e.Value)
}
// Wrapping with %w (exactly one %w per format string)
func getUser(id int) (*User, error) {
u, err := db.GetUser(id)
if err != nil {
return nil, fmt.Errorf("getUser %d: %w", id, err)
}
return u, nil
}
errors.Is unwraps the chain checking each error for equality:
if errors.Is(err, ErrNotFound) {
// handles ErrNotFound at any depth in the wrapped chain
}
errors.As unwraps the chain checking for type assignability:
var valErr *ValidationError
if errors.As(err, &valErr) {
fmt.Println("bad field:", valErr.Field)
}
Opaque errors (no sentinel, no type check — just behavioural):
func IsTemporary(err error) bool {
type temporary interface{ Temporary() bool }
var t temporary
return errors.As(err, &t) && t.Temporary()
}
Never inspect err.Error() string to make decisions — it's for humans, not
control flow. Use errors.Is and errors.As instead.
1.14 Context
Context carries deadlines, cancellation signals, and request-scoped values
across API boundaries. The first parameter convention is universal in Go.
// Creation
ctx := context.Background() // root context, never cancelled, no deadline
ctx := context.TODO() // placeholder: use when unsure which context to use
// Cancellation
ctx, cancel := context.WithCancel(parentCtx)
defer cancel() // ALWAYS call cancel to release resources
// Timeouts
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
defer cancel()
// Deadlines
ctx, cancel := context.WithDeadline(parentCtx, time.Now().Add(30*time.Second))
defer cancel()
// Values — use sparingly, only for request-scoped data (trace IDs, not optional args)
type contextKey string
const traceIDKey contextKey = "traceID"
ctx = context.WithValue(ctx, traceIDKey, "abc123")
Never store context in a struct; pass it as the first parameter:
// RIGHT
func (s *Server) Handle(ctx context.Context, req *Request) (*Response, error) { ... }
// WRONG
type Server struct {
ctx context.Context // NEVER do this
}
The ctx.Done() channel is the standard cancellation mechanism:
func process(ctx context.Context, input <-chan Item) error {
for {
select {
case <-ctx.Done():
return ctx.Err() // context.Canceled or context.DeadlineExceeded
case item, ok := <-input:
if !ok {
return nil
}
handle(item)
}
}
}
2. Concurrency Patterns
2.1 Goroutines
Goroutines are lightweight threads managed by the Go runtime with M:N
scheduling. They start with a ~2KB stack that grows and shrinks as needed.
go func() {
fmt.Println("running in a goroutine")
}()
// Common: fire and forget with recovery
go func() {
defer func() {
if r := recover(); r != nil {
log.Printf("goroutine panic: %v\n%s", r, debug.Stack())
}
}()
doWork()
}()
Goroutines have no identity — no thread-local storage, no goroutine ID in the
standard library. Pass data explicitly:
// WRONG
var user string
go func() { fmt.Println(user) }() // reads shared variable
// RIGHT
go func(user string) { fmt.Println(user) }(user)
Goroutine leaks — any goroutine blocked on a channel that never receives or
sends will live forever:
// LEAK: this goroutine blocks sending to ch forever
ch := make(chan int)
go func() { ch <- 42 }()
// ch is never received — goroutine leaks
// Leak detection at program exit:
// import _ "net/http/pprof"
// go tool pprof http://localhost:6060/debug/pprof/goroutine
2.2 Channels
Channels are typed conduits. Unbuffered channels (make(chan T)) require
simultaneous sender and receiver — a synchronous handoff. Buffered channels
(make(chan T, N)) hold up to N elements before blocking sends.
ch := make(chan int) // unbuffered: synchronous
ch := make(chan int, 10) // buffered: capacity 10, async up to capacity
// Send
ch <- 42
// Receive
v := <-ch
v, ok := <-ch // ok is false if channel is closed and drained
// Range — loops until channel is closed (used by receiver)
for v := range ch {
process(v)
}
// Close — sender MUST close; receiver must not
close(ch)
// Send on closed channel → panic
// Receive from closed channel → zero value, ok=false (after drain)
Channel direction types document intent and prevent bugs:
func producer(out chan<- int) { // send-only
for i := 0; i < 10; i++ {
out <- i
}
close(out)
}
func consumer(in <-chan int) { // receive-only
for v := range in {
fmt.Println(v)
}
}
The nil-channel trick: select never selects a nil channel. This enables
dynamic case enable/disable.
var in <-chan int = nil // disabled
for {
select {
case v := <-in:
process(v)
case <-ctx.Done():
return
}
}
2.3 Select
select blocks until one of its cases can proceed, then executes it. If
multiple cases are ready, one is chosen pseudo-randomly (uniform).
select {
case v := <-ch1:
fmt.Println("ch1:", v)
case ch2 <- 42:
fmt.Println("sent to ch2")
case <-time.After(5 * time.Second):
fmt.Println("timeout")
}
The default case makes select non-blocking:
select {
case v := <-ch:
fmt.Println("received:", v)
default:
fmt.Println("no value available")
}
// Polling with default (busy-wait — use sparingly)
for {
select {
case v := <-ch:
process(v)
default:
// do other work
}
}
The random selection is not round-robin. Do not rely on ordering between ready
cases — if you need fairness, implement it explicitly.
2.4 Sync Primitives
sync.Mutex — mutual exclusion for shared state:
type Cache struct {
mu sync.Mutex
items map[string]Item
}
func (c *Cache) Get(key string) (Item, bool) {
c.mu.Lock()
defer c.mu.Unlock()
item, ok := c.items[key]
return item, ok
}
sync.RWMutex — multiple readers, exclusive writer. Readers hold read lock
(RLock/RUnlock), which allows concurrency among readers:
type SafeMap struct {
mu sync.RWMutex
data map[string]string
}
func (m *SafeMap) Get(key string) string {
m.mu.RLock()
defer m.mu.RUnlock()
return m.data[key]
}
func (m *SafeMap) Set(key, value string) {
m.mu.Lock()
defer m.mu.Unlock()
m.data[key] = value
}
// Two-reader rule: RWMutex may prefer writers, starving readers.
// Use sync.Mutex if writes are frequent — the overhead of the
// read-write bookkeeping can exceed the benefit.
sync.WaitGroup — wait for a collection of goroutines:
var wg sync.WaitGroup
for _, url := range urls {
wg.Add(1) // increment BEFORE launching goroutine
go func(url string) {
defer wg.Done() // decrement in defer
fetch(url)
}(url)
}
wg.Wait() // blocks until counter reaches zero
sync.Once — execute exactly once:
var (
once sync.Once
client *http.Client
)
func getClient() *http.Client {
once.Do(func() {
client = &http.Client{Timeout: 10 * time.Second}
})
return client
}
sync/atomic — lock-free operations for simple counters and flags:
var counter int64
func increment() {
atomic.AddInt64(&counter, 1)
}
func get() int64 {
return atomic.LoadInt64(&counter)
}
// Compare-and-swap (CAS) for state transitions
var state int32
const (
stateIdle int32 = 0
stateRunning int32 = 1
)
func startIfIdle() bool {
return atomic.CompareAndSwapInt32(&state, stateIdle, stateRunning)
}
sync.Map — concurrent map with two valid use cases:
// Case 1: entry written once, read many times
var cache sync.Map
cache.Store("key", expensiveValue)
v, ok := cache.Load("key")
// Case 2: disjoint key sets per goroutine
// (each goroutine writes different keys)
// For all other cases, use map + sync.Mutex
// Range over sync.Map
cache.Range(func(key, value any) bool {
fmt.Printf("%v: %v\n", key, value)
return true // continue iteration
})
sync.Cond — goroutine waiting on a condition:
var mu sync.Mutex
cond := sync.NewCond(&mu)
ready := false
// Waiter
go func() {
cond.L.Lock()
for !ready { // ALWAYS check condition in a loop
cond.Wait() // releases lock, waits for Signal/Broadcast, re-acquires
}
// ready is true
cond.L.Unlock()
}()
// Signaler
cond.L.Lock()
ready = true
cond.Broadcast() // wake all waiters
cond.L.Unlock()
2.5 Errgroup
golang.org/x/sync/errgroup runs parallel work with error propagation:
g, ctx := errgroup.WithContext(ctx)
for _, url := range urls {
url := url // capture for closure (or Go 1.22+ does this automatically)
g.Go(func() error {
return fetch(ctx, url)
})
}
if err := g.Wait(); err != nil {
log.Printf("at least one fetch failed: %v", err)
}
// With concurrency limit
g.SetLimit(10) // max 10 concurrent goroutines
2.6 Worker Pool and Semaphore Patterns
Counting semaphore with a buffered channel:
sem := make(chan struct{}, 10) // max 10 concurrent
for _, item := range items {
item := item
sem <- struct{}{} // acquire
go func() {
defer func() { <-sem }() // release
process(item)
}()
}
// Wait for all to finish: fill the semaphore
for i := 0; i < cap(sem); i++ {
sem <- struct{}{}
}
close(sem)
Worker pool with input channel:
jobs := make(chan Job, 100)
var wg sync.WaitGroup
// Start fixed pool of workers
for w := 0; w < runtime.NumCPU(); w++ {
wg.Add(1)
go func() {
defer wg.Done()
for job := range jobs { // range exits when channel closed
job.Process()
}
}()
}
// Send jobs
for _, job := range allJobs {
jobs <- job
}
close(jobs) // signal workers to exit after draining
wg.Wait()
2.7 Pipeline Patterns
Fan-out — distribute work to multiple goroutines:
func fanOut(ctx context.Context, input <-chan Item, workers int) []<-chan Result {
outputs := make([]<-chan Result, workers)
for i := 0; i < workers; i++ {
ch := make(chan Result)
outputs[i] = ch
go func(out chan<- Result) {
defer close(out)
for item := range input {
select {
case out <- process(item):
case <-ctx.Done():
return
}
}
}(ch)
}
return outputs
}
Fan-in — merge multiple channels into one:
func fanIn(ctx context.Context, channels ...<-chan Result) <-chan Result {
var wg sync.WaitGroup
out := make(chan Result)
multiplex := func(ch <-chan Result) {
defer wg.Done()
for v := range ch {
select {
case out <- v:
case <-ctx.Done():
return
}
}
}
wg.Add(len(channels))
for _, ch := range channels {
go multiplex(ch)
}
go func() {
wg.Wait()
close(out)
}()
return out
}
Pipeline — chain stages via channels:
func pipeline() {
naturals := make(chan int)
squares := make(chan int)
// Stage 1: generate
go func() {
for i := 0; i < 100; i++ {
naturals <- i
}
close(naturals)
}()
// Stage 2: square
go func() {
defer close(squares)
for n := range naturals {
squares <- n * n
}
}()
// Stage 3: consume
for s := range squares {
fmt.Println(s)
}
}
2.8 Common Concurrency Bugs
Loop-variable capture — the classic Go race:
// BUG — all goroutines share the same loop variable
for _, item := range items {
go func() {
process(item) // item is the same variable, final value used
}()
}
// FIX (Go < 1.22): copy to a new variable
for _, item := range items {
item := item // shadow; new variable per iteration
go func() {
process(item)
}()
}
// Go 1.22+ — loop variables are per-iteration by default
Unbuffered channel deadlock:
// DEADLOCK: send on unbuffered channel with no receiver ready
ch := make(chan int)
ch <- 1 // blocks forever — no goroutine to receive
fmt.Println("never reached")
Closing from receiver side:
// Receiver must never close — it doesn't own the channel.
// If the receiver needs to signal "stop," use a separate done channel or ctx.Done().
Send on closed channel:
ch := make(chan int)
close(ch)
ch <- 1 // PANIC: send on closed channel
Data races — detect with -race:
go test -race ./...
go build -race -o myapp
go run -race main.go
The race detector has ~10x memory overhead and cannot be used in production.
It is a development-only tool.
Goroutine leak from unclosed channel:
// LEAK: goroutine blocks on send forever
ch := make(chan int)
go func() { ch <- work() }() // blocks when function returns
// ch never received, never closed → goroutine lives forever
// FIX: always provide a way out
go func() {
select {
case ch <- work():
case <-ctx.Done():
}
}()
WaitGroup misuse:
// WRONG: Add inside goroutine may not execute before Wait
go func() {
wg.Add(1) // race: Wait may see counter=0 and return
defer wg.Done()
work()
}()
wg.Wait()
// RIGHT: Add before launching goroutine
wg.Add(1)
go func() {
defer wg.Done()
work()
}()
wg.Wait()
3. Standard Library Deep Dive
3.1 net/http
Handler interface and ServeMux:
type MyHandler struct{}
func (h *MyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
fmt.Fprintf(w, `{"message": "hello"}`)
}
mux := http.NewServeMux()
mux.Handle("/api/", &MyHandler{})
mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
})
http.ListenAndServe(":8080", mux)
Middleware pattern:
func loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
next.ServeHTTP(w, r)
log.Printf("%s %s %s", r.Method, r.URL.Path, time.Since(start))
})
}
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
// Chain
mux := http.NewServeMux()
mux.HandleFunc("/api/hello", helloHandler)
handler := loggingMiddleware(authMiddleware(mux))
http.ListenAndServe(":8080", handler)
HTTP client with proper configuration:
client := &http.Client{
Timeout: 30 * time.Second,
Transport: &http.Transport{
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10,
IdleConnTimeout: 90 * time.Second,
TLSHandshakeTimeout: 10 * time.Second,
DisableCompression: false,
},
CheckRedirect: func(req *http.Request, via []*http.Request) error {
if len(via) >= 10 {
return fmt.Errorf("too many redirects")
}
return nil
},
}
resp, err := client.Get("https://api.example.com/data")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
body, _ := io.ReadAll(resp.Body)
log.Printf("unexpected status %d: %s", resp.StatusCode, body)
return
}
var data MyData
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
log.Printf("decode error: %v", err)
return
}
httptest for testing:
func TestHandler(t *testing.T) {
// Test a handler directly
req := httptest.NewRequest("GET", "/api/hello", nil)
w := httptest.NewRecorder()
myHandler.ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Errorf("expected 200, got %d", w.Code)
}
var resp map[string]string
if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
t.Fatal(err)
}
}
func TestClientIntegration(t *testing.T) {
// Test against a real server
server := httptest.NewServer(http.HandlerFunc(realHandler))
defer server.Close()
resp, err := http.Get(server.URL + "/api/hello")
if err != nil {
t.Fatal(err)
}
defer resp.Body.Close()
// assert on resp
}
3.2 encoding/json
type Record struct {
Name string `json:"name"`
Email string `json:"email,omitempty"` // omitted if empty
Age int `json:"age,string"` // encoded as string "30"
internal string `json:"-"` // never marshaled/unmarshaled
}
// Marshal
data, err := json.Marshal(records)
// MarshalIndent for human-readable output
data, err := json.MarshalIndent(records, "", " ")
// Unmarshal
var records []Record
err := json.Unmarshal(data, &records)
Custom marshal/unmarshal:
func (r Record) MarshalJSON() ([]byte, error) {
type Alias Record // avoid infinite recursion
return json.Marshal(struct {
Alias
DisplayName string `json:"display_name"`
}{
Alias: Alias(r),
DisplayName: r.Name + " <" + r.Email + ">",
})
}
func (r *Record) UnmarshalJSON(data []byte) error {
type Alias Record
aux := struct {
*Alias
}{Alias: (*Alias)(r)}
return json.Unmarshal(data, &aux)
}
Partial decode with RawMessage:
type Envelope struct {
Type string `json:"type"`
Payload json.RawMessage `json:"payload"` // defer decoding
}
var env Envelope
json.Unmarshal(data, &env)
switch env.Type {
case "user":
var user User
json.Unmarshal(env.Payload, &user)
case "order":
var order Order
json.Unmarshal(env.Payload, &order)
}
Decoder for streams and strict parsing:
dec := json.NewDecoder(resp.Body)
dec.DisallowUnknownFields() // reject unknown fields
var v MyType
if err := dec.Decode(&v); err != nil {
log.Printf("decode: %v", err)
}
// Decode stream of JSON objects (e.g., NDJSON)
dec := json.NewDecoder(reader)
for {
var obj MyType
if err := dec.Decode(&obj); err == io.EOF {
break
} else if err != nil {
log.Printf("decode: %v", err)
continue
}
process(obj)
}
Encoder for streams:
enc := json.NewEncoder(w)
for _, obj := range objects {
if err := enc.Encode(obj); err != nil {
log.Printf("encode: %v", err)
return
}
}
3.3 database/sql
// Open the pool — does NOT connect; first query will
db, err := sql.Open("postgres", "postgres://user:pass@localhost/db?sslmode=disable")
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Pool tuning
db.SetMaxOpenConns(25) // max simultaneous connections
db.SetMaxIdleConns(10) // max idle connections in pool
db.SetConnMaxLifetime(5 * time.Minute) // max lifetime per connection
db.SetConnMaxIdleTime(1 * time.Minute) // max idle time per connection
// Ping to verify connection
if err := db.PingContext(ctx); err != nil {
log.Fatal(err)
}
Queries:
// QueryRow — single row
var name string
var created time.Time
err := db.QueryRowContext(ctx,
"SELECT name, created_at FROM users WHERE id = $1", userID,
).Scan(&name, &created)
if errors.Is(err, sql.ErrNoRows) {
// not found
} else if err != nil {
// error
}
// Query — multiple rows
rows, err := db.QueryContext(ctx,
"SELECT id, name FROM users WHERE active = $1", true,
)
if err != nil {
return err
}
defer rows.Close() // ALWAYS close; must be called even on error
for rows.Next() {
var id int64
var name string
if err := rows.Scan(&id, &name); err != nil {
return err
}
fmt.Println(id, name)
}
if err := rows.Err(); err != nil { // check final error after loop
return err
}
// Exec — INSERT/UPDATE/DELETE
result, err := db.ExecContext(ctx,
"INSERT INTO users (name, email) VALUES ($1, $2)", name, email,
)
if err != nil {
return err
}
id, _ := result.LastInsertId() // not supported by postgres
rowsAffected, _ := result.RowsAffected()
Transactions:
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
if err != nil {
return err
}
defer tx.Rollback() // no-op after Commit
_, err = tx.ExecContext(ctx,
"UPDATE accounts SET balance = balance - $1 WHERE id = $2", amount, fromID,
)
if err != nil {
return err
}
_, err = tx.ExecContext(ctx,
"UPDATE accounts SET balance = balance + $1 WHERE id = $2", amount, toID,
)
if err != nil {
return err
}
if err := tx.Commit(); err != nil {
return err
}
// after Commit, deferred Rollback is a no-op
Prepared statements reuse query plans:
stmt, err := db.PrepareContext(ctx, "SELECT name FROM users WHERE id = $1")
if err != nil {
return err
}
defer stmt.Close()
for _, id := range ids {
var name string
stmt.QueryRowContext(ctx, id).Scan(&name)
}
Nullable types:
var email sql.NullString
var deletedAt sql.NullTime
var credits sql.NullInt64
var rating sql.NullFloat64
var verified sql.NullBool
err := db.QueryRowContext(ctx,
"SELECT email, deleted_at, credits FROM users WHERE id = $1", userID,
).Scan(&email, &deletedAt, &credits)
if email.Valid {
fmt.Println("email:", email.String)
}
if deletedAt.Valid {
fmt.Println("deleted:", deletedAt.Time)
}
3.4 io
The io.Reader and io.Writer interfaces are Go's universal I/O abstraction:
type Reader interface {
Read(p []byte) (n int, err error)
}
type Writer interface {
Write(p []byte) (n int, err error)
}
Key functions:
// Copy all data from reader to writer
written, err := io.Copy(dst, src)
// Copy up to N bytes
written, err := io.CopyN(dst, src, 1024)
// Read all bytes from reader
data, err := io.ReadAll(reader)
// TeeReader: reads from r and writes to w simultaneously
// Useful for logging request bodies without consuming them
var buf bytes.Buffer
tee := io.TeeReader(r.Body, &buf)
body, _ := io.ReadAll(tee)
// MultiWriter: writes to multiple writers at once
var logBuf bytes.Buffer
mwriter := io.MultiWriter(os.Stdout, &logBuf)
fmt.Fprintf(mwriter, "hello\n")
// LimitReader: read at most N bytes
limited := io.LimitReader(r.Body, 1<<20) // 1MB limit
// Pipe: in-memory synchronous pipe (writer blocks until reader reads)
pr, pw := io.Pipe()
go func() {
defer pw.Close()
json.NewEncoder(pw).Encode(data)
}()
var decoded MyType
json.NewDecoder(pr).Decode(&decoded)
3.5 os
File operations:
// Read entire file
data, err := os.ReadFile("/path/to/file")
// Write entire file (creates or truncates)
err := os.WriteFile("/path/to/file", data, 0644)
// Open for reading
f, err := os.Open("/path/to/file")
defer f.Close()
// Open for writing (create/truncate)
f, err := os.Create("/path/to/file")
defer f.Close()
// Open with flags
f, err := os.OpenFile("/path/to/file", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
defer f.Close()
// Stat
info, err := os.Stat("/path/to/file")
info.IsDir()
info.Mode()
info.Size()
info.ModTime()
// Directory operations
os.Mkdir("/newdir", 0755)
os.MkdirAll("/path/to/newdir", 0755) // creates parents
os.Remove("/file")
os.RemoveAll("/dir") // removes recursively
// File mode
os.Chmod("/file", 0755)
os.Chown("/file", uid, gid)
// Environment
os.Getenv("PATH")
os.Setenv("KEY", "value")
os.LookupEnv("KEY") // returns (value, exists)
os.Environ() // []string of "KEY=VALUE"
// Temp files/dirs
f, err := os.CreateTemp("", "prefix-*") // /tmp/prefix-abc123
dir, err := os.MkdirTemp("", "prefix-*")
// User cache/config dirs
dir, err := os.UserCacheDir() // ~/Library/Caches (macOS)
dir, err := os.UserConfigDir() // ~/Library/Application Support (macOS)
dir, err := os.UserHomeDir() // ~
Signal handling:
sigCh := make(chan os.Signal, 1) // buffer important — don't block signal delivery
signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
go func() {
sig := <-sigCh
log.Printf("received signal %v, shutting down", sig)
cancel() // trigger graceful shutdown
}()
// Reset specific signal handling to default
signal.Reset(syscall.SIGINT)
Subprocesses with os/exec:
// Simple command
cmd := exec.CommandContext(ctx, "git", "log", "--oneline", "-n", "5")
output, err := cmd.Output() // captures stdout, waits for completion
// ⚠️ cmd.Output() buffers all of stdout in memory — use for small output only
// Stream output (for large output)
cmd := exec.CommandContext(ctx, "long-running-process")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
log.Printf("command failed: %v", err)
}
// Capture stdout with pipe
cmd := exec.CommandContext(ctx, "prog")
stdout, _ := cmd.StdoutPipe()
cmd.Start()
scanner := bufio.NewScanner(stdout)
for scanner.Scan() {
process(scanner.Text())
}
cmd.Wait()
// Set environment
cmd.Env = append(os.Environ(),
"CGO_ENABLED=0",
"GOOS=linux",
)
3.6 crypto
// Secure random (use crypto/rand, NEVER math/rand)
import "crypto/rand"
// Random bytes
buf := make([]byte, 32)
if _, err := rand.Read(buf); err != nil {
log.Fatal(err)
}
token := hex.EncodeToString(buf)
// SHA-256
h := sha256.Sum256(data)
fmt.Printf("%x\n", h)
// HMAC
mac := hmac.New(sha256.New, key)
mac.Write(data)
signature := mac.Sum(nil)
// Verify: hmac.Equal(signature, expected)
// Constant-time comparison (for MACs, tokens, signatures)
if subtle.ConstantTimeCompare(receivedMAC, expectedMAC) != 1 {
return errors.New("invalid MAC")
}
// NEVER use == for security-sensitive comparisons — timing attack
// AES-GCM (authenticated encryption)
func encrypt(plaintext, key []byte) ([]byte, error) {
block, err := aes.NewCipher(key) // key must be 16 (AES-128), 24, or 32 bytes
if err != nil {
return nil, err
}
aead, err := cipher.NewGCM(block)
if err != nil {
return nil, err
}
nonce := make([]byte, aead.NonceSize())
if _, err := rand.Read(nonce); err != nil {
return nil, err
}
ciphertext := aead.Seal(nonce, nonce, plaintext, nil)
return ciphertext, nil
}
func decrypt(ciphertext, key []byte) ([]byte, error) {
block, err := aes.NewCipher(key)
if err != nil {
return nil, err
}
aead, err := cipher.NewGCM(block)
if err != nil {
return nil, err
}
nonceSize := aead.NonceSize()
if len(ciphertext) < nonceSize {
return nil, errors.New("ciphertext too short")
}
nonce, ciphertext := ciphertext[:nonceSize], ciphertext[nonceSize:]
return aead.Open(nil, nonce, ciphertext, nil)
}
// Password hashing (argon2)
import "golang.org/x/crypto/argon2"
hash := argon2.IDKey([]byte(password), salt, 1, 64*1024, 4, 32)
3.7 testing
func TestDivide(t *testing.T) {
t.Helper() // attribute failures to the caller's line
tests := []struct {
name string
a, b int
expected int
wantErr bool
}{
{"positive", 10, 2, 5, false},
{"negative", -10, 2, -5, false},
{"by zero", 10, 0, 0, true},
}
for _, tt := range tests {
tt := tt // capture (Go < 1.22)
t.Run(tt.name, func(t *testing.T) {
t.Parallel() // tests within this table run in parallel
result, err := Divide(tt.a, tt.b)
if tt.wantErr && err == nil {
t.Fatal("expected error, got nil")
}
if !tt.wantErr && err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result != tt.expected {
t.Errorf("Divide(%d, %d) = %d; want %d",
tt.a, tt.b, result, tt.expected)
}
})
}
}
// t.Cleanup vs defer — t.Cleanup runs at test end even if t.Parallel
func TestWithTempDir(t *testing.T) {
dir := t.TempDir() // auto-cleanup
t.Setenv("HOME", dir) // auto-restore
t.Cleanup(func() {
// runs when test and all subtests finish
log.Println("cleanup after all subtests")
})
}
3.8 time
now := time.Now()
elapsed := time.Since(start)
// ⚠️ time.After leaks — use time.NewTimer + Stop instead
// WRONG: timer cannot be stopped, leaks until it fires
select {
case <-time.After(5 * time.Second):
fmt.Println("timeout")
}
// RIGHT: NewTimer can be stopped
timer := time.NewTimer(5 * time.Second)
defer timer.Stop()
select {
case <-timer.C:
fmt.Println("timeout")
case result := <-work:
if !timer.Stop() {
<-timer.C // drain the channel
}
}
// Ticker for periodic work
ticker := time.NewTicker(1 * time.Second)
defer ticker.Stop()
for {
select {
case <-ticker.C:
doWork()
case <-ctx.Done():
return
}
}
// Parsing and formatting — reference time is Mon Jan 2 15:04:05 MST 2006
// (each part is distinct: 1-2-3-4-5-6-7)
t, err := time.Parse("2006-01-02 15:04:05", "2024-03-15 14:30:00")
s := t.Format("January 2, 2006 at 3:04pm") // "March 15, 2024 at 2:30pm"
s = t.Format(time.RFC3339) // "2024-03-15T14:30:00Z"
// Duration
d, _ := time.ParseDuration("2h30m")
sleep := 5 * time.Second + 300*time.Millisecond
3.9 reflect
Use sparingly. Reflection is slow, panic-prone, and bypasses type safety.
// TypeOf and ValueOf
t := reflect.TypeOf(x)
v := reflect.ValueOf(x)
// Struct field iteration
t := reflect.TypeOf(user)
for i := 0; i < t.NumField(); i++ {
field := t.Field(i)
tag := field.Tag.Get("json")
value := v.Field(i).Interface()
fmt.Printf("%s (json:%s) = %v\n", field.Name, tag, value)
}
// Setting a value through reflection (requires addressable value)
func setField(v any, name string, value any) error {
rv := reflect.ValueOf(v)
if rv.Kind() != reflect.Ptr || rv.Elem().Kind() != reflect.Struct {
return fmt.Errorf("expected pointer to struct")
}
field := rv.Elem().FieldByName(name)
if !field.IsValid() {
return fmt.Errorf("field %s not found", name)
}
if !field.CanSet() {
return fmt.Errorf("field %s cannot be set (unexported)", name)
}
field.Set(reflect.ValueOf(value))
return nil
}
3.10 unsafe
Rules for unsafe.Pointer conversions:
*T → unsafe.Pointer → any pointer type — validuintptr → unsafe.Pointer — invalid (use unsafe.Add Go 1.17+)uintptr is a plain integer; GC can move the object — never store
uintptr across allocation boundaries
// Checking struct layout
fmt.Println(unsafe.Sizeof(MyStruct{}))
fmt.Println(unsafe.Offsetof(MyStruct{}.Field))
// Go 1.17+: unsafe.Slice and unsafe.String (zero-copy conversions)
b := []byte("hello world")
s := unsafe.String(&b[0], len(b)) // byte slice → string, no copy (Go 1.20+)
s := "hello"
b := unsafe.Slice(unsafe.StringData(s), len(s)) // string → byte slice, no copy (Go 1.20+)
// ⚠️ Both are read-only — mutating the result is undefined behaviour
4. Testing & Benchmarking
4.1 Test Flags
go test ./... # all packages
go test -v ./... # verbose
go test -run TestFoo ./... # run tests matching regex
go test -run "TestFoo/edge" ./... # run specific subtest
go test -count=1 ./... # disable test caching
go test -count=5 ./... # run 5 times (flake detection)
go test -race ./... # data race detector
go test -cover ./... # coverage percentage
go test -coverprofile=cover.out ./... # write coverage profile
go test -coverpkg=./... ./... # include all packages in coverage
go test -shuffle=on ./... # randomize test order
go test -shuffle=1234567890 ./... # deterministic shuffle (for replay)
go test -timeout 30s ./... # timeout (default 10m)
go test -failfast ./... # stop on first failure
go test -short ./... # skip long-running tests
go test -parallel 4 ./... # max parallel tests
go test -json ./... # machine-readable output
4.2 Benchmarks
func BenchmarkSHA256(b *testing.B) {
data := []byte("hello world")
b.ResetTimer() // exclude setup from measurement
for i := 0; i < b.N; i++ {
sha256.Sum256(data)
}
}
func BenchmarkReadFile(b *testing.B) {
for i := 0; i < b.N; i++ {
b.StopTimer()
os.WriteFile("/tmp/bench", []byte("data"), 0644)
b.StartTimer()
_, err := os.ReadFile("/tmp/bench")
if err != nil {
b.Fatal(err)
}
}
}
func BenchmarkAlloc(b *testing.B) {
b.ReportAllocs() // report memory allocations
for i := 0; i < b.N; i++ {
_ = make([]byte, 1024)
}
}
Run with:
go test -bench=. ./...
go test -bench=. -benchmem ./... # memory allocations
go test -bench=. -benchtime=10s ./... # custom duration
go test -bench=. -count=5 ./... # multiple runs
go test -bench=. -cpuprofile=cpu.out ./.. # CPU profile
go test -bench=. -memprofile=mem.out ./.. # memory profile
# Compare benchmarks with benchstat
go test -bench=. -count=10 ./... > old.txt
# make changes
go test -bench=. -count=10 ./... > new.txt
benchstat old.txt new.txt
4.3 Fuzzing (Go 1.18+)
func FuzzDivide(f *testing.F) {
// Seed corpus
f.Add(10, 2)
f.Add(-10, 5)
f.Add(0, 1)
f.Fuzz(func(t *testing.T, a, b int) {
if b == 0 {
_, err := Divide(a, b)
if err == nil {
t.Error("expected error for divide by zero")
}
return
}
result, err := Divide(a, b)
if err != nil {
t.Errorf("unexpected error: %v", err)
}
if result*b != a {
t.Errorf("Divide(%d, %d) = %d; not reversible", a, b, result)
}
})
}
Run with:
go test -fuzz=FuzzDivide ./...
go test -fuzz=FuzzDivide -fuzztime=30s ./...
go test -fuzz=FuzzDivide -fuzzminimizetime=10s ./...
4.4 Table-Driven Tests with t.Run
func TestParsePort(t *testing.T) {
tests := []struct {
name string
input string
wantPort int
wantError bool
}{
{name: "valid port", input: ":8080", wantPort: 8080, wantError: false},
{name: "no colon", input: "8080", wantPort: 0, wantError: true},
{name: "negative port", input: ":-1", wantPort: 0, wantError: true},
{name: "too large", input: ":65536", wantPort: 0, wantError: true},
}
for _, tt := range tests {
tt := tt
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
port, err := ParsePort(tt.input)
if tt.wantError && err == nil {
t.Fatal("expected error")
}
if !tt.wantError && err != nil {
t.Fatalf("unexpected error: %v", err)
}
if port != tt.wantPort {
t.Errorf("got %d, want %d", port, tt.wantPort)
}
})
}
}
4.5 Test Helpers
t.Helper() marks the function as a test helper so stack traces attribute
failures to the caller's line — not the helper's.
func assertEqual[T comparable](t *testing.T, got, want T) {
t.Helper()
if got != want {
t.Errorf("got %v, want %v", got, want)
}
}
func assertNoError(t *testing.T, err error) {
t.Helper()
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
4.6 TestMain
For global setup/teardown across all tests in a package:
func TestMain(m *testing.M) {
// Setup
setupDB()
defer teardownDB()
// Run tests
os.Exit(m.Run())
}
⚠️ Only one TestMain per package. t.Cleanup and t.TempDir are usually
better — avoid global state.
4.7 Golden Files
Store expected outputs in testdata/ — the standard location Go tools
ignore for regular builds.
func TestRender(t *testing.T) {
golden := filepath.Join("testdata", "output.json")
got := Render(input)
if *update { // go test -args -update
os.WriteFile(golden, got, 0644)
return
}
want, err := os.ReadFile(golden)
if err != nil {
t.Fatalf("error reading golden file: %v", err)
}
if string(got) != string(want) {
t.Errorf("output mismatch:\ngot:\n%s\nwant:\n%s\n", got, want)
}
}
go:embed for embedding test fixtures:
import _ "embed"
//go:embed testdata/input.json
var inputFixture []byte
func TestParse(t *testing.T) {
result, err := Parse(inputFixture)
assertNoError(t, err)
// ...
}
4.8 Integration Tests with Build Tags
//go:build integration
package mypkg_test
func TestDatabaseIntegration(t *testing.T) {
if testing.Short() {
t.Skip("skipping integration test in short mode")
}
db, err := sql.Open("postgres", os.Getenv("TEST_DATABASE_URL"))
if err != nil {
t.Fatal(err)
}
defer db.Close()
// ...
}
Run with:
go test -tags=integration ./...
go test -tags=integration -short ./... # skip long tests
5. Build & Tooling
5.1 go build
go build -o myapp ./cmd/myapp # output binary name
go build -ldflags "-s -w" ./... # strip debug info (smaller binary)
go build -ldflags "-X main.version=1.0.0" . # inject version at link time
go build -tags integration ./... # include files with build tag
go build -tags "integration debug" ./... # multiple tags (AND)
GOOS=linux GOARCH=arm64 go build ./... # cross-compile
go build -trimpath ./... # reproducible builds (strip filesystem paths)
go build -gcflags="-m" ./... # escape analysis output
go build -gcflags="-N -l" ./... # disable optimizations + inlining (for debugging)
go build -race -o myapp ./... # build with race detector
go build -buildmode=c-shared -o lib.so ./.. # build as shared library
go build -buildmode=plugin -o plugin.so . # build as Go plugin
5.2 go install
go install builds and caches the binary in $GOPATH/bin (or $GOBIN).
Unlike go build, the binary is cached and reused.
go install ./cmd/myapp # install from local module
go install golang.org/x/tools/cmd/goimports@latest # install specific tool
5.3 go mod
go mod init github.com/user/repo # initialize module
go mod tidy # add missing, remove unused deps
go mod tidy -e # ignore errors
go mod vendor # create vendor/ directory
go mod verify # verify checksums in go.sum
go mod download # prefetch all dependencies
go mod download -json # JSON output
go mod graph # print dependency graph
go mod why -m golang.org/x/sync # why is this module needed?
go mod edit -replace old=new # add replace directive
go mod edit -require module@version # add require directive
go mod edit -droprequire module # remove require directive
go mod edit -go 1.22 # set go directive
go.sum is a lockfile — commit it. It records the checksums of all modules in
the dependency graph. go mod verify checks every entry.
5.4 go workspaces (Go 1.18+)
For multi-module development:
go work init ./module1 ./module2 # create go.work
go work use ./module3 # add module
go work sync # sync go.work with module go.mod files
go.work should NOT be committed to version control (by convention) — it's
for local development. CI uses the individual go.mod files.
5.5 Code Quality Tools
go vet — built-in static analysis:
go vet ./... # all checks
go vet -copylocks ./... # locks passed by value
go vet -loopclosure ./... # loop variable capture (Go <1.22)
go vet -printf ./... # printf format string issues
go vet -shadow ./... # variable shadowing (Go 1.23+, was -shadow)
go vet -nilness ./... # nilness analysis (Go 1.19+)
go vet -unusedwrite ./... # unused writes
staticcheck — the standard third-party linter:
go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...
# Key checks (SAxxxx):
# SA1000: regexp.MustCompile called with invalid pattern
# SA1006: fmt.Printf with dynamic format string and no arguments
# SA1019: deprecated identifier
# SA4006: value assigned but never read
# SA5001: defer in loop
# SA9004: only the first constant in group has explicit type
golangci-lint — aggregator running dozens of linters:
golangci-lint run ./...
golangci-lint run --enable-all --disable staticcheck ./...
golangci-lint run --new-from-rev=HEAD~1 # only check new code
Key linters enabled by default: errcheck, gosimple, govet, ineffassign,
staticcheck, unused.
Additional linters to enable: revive, gosec, misspell, gocritic,
gofumpt, gci, goimports.
Formatter:
gofmt -w . # standard formatter
gofumpt -w . # stricter gofmt (preferred)
goimports -w . # format + organize imports
gci write . # import grouping (stdlib → third-party → local)
5.6 Profiling with pprof
// In your application:
import _ "net/http/pprof"
// Then: go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
Command-line profiling:
go test -cpuprofile=cpu.out -bench=. ./...
go tool pprof cpu.out
(pprof) top
(pprof) list functionName
(pprof) web # opens browser graph (requires graphviz)
go test -memprofile=mem.out -bench=. ./...
go tool pprof mem.out
(pprof) top
(pprof) alloc_space # cumulative allocations
go tool pprof -http :8080 cpu.out # interactive web UI
Profile types:
| Profile | Command | What it measures |
|---|
| CPU | -cpuprofile=cpu.out | Where CPU time is spent |
| Heap | -memprofile=mem.out | Current heap allocations |
| Alloc | pprof alloc_space | Cumulative allocations |
| Goroutine | /debug/pprof/goroutine | Goroutine stack traces |
| Block | /debug/pprof/block | Blocking on synchronization |
| Mutex | /debug/pprof/mutex | Mutex contention |
5.7 Execution Trace
go test -trace=trace.out ./...
go tool trace trace.out # opens browser with trace viewer
The trace shows goroutine scheduling, GC events, network blocking, and system
calls — useful for latency analysis.
5.8 Debugging with Delve
dlv debug ./cmd/myapp # debug binary
dlv attach <PID> # attach to running process
dlv --headless --listen :2345 ./.. # headless server for IDE integration
dlv test ./... # debug tests
# Common dlv commands:
(dlv) break main.go:42 # set breakpoint
(dlv) condition 1 userID == 123 # conditional breakpoint
(dlv) continue # resume execution
(dlv) next # step over
(dlv) step # step into
(dlv) print variable # print value
(dlv) goroutines # list goroutines
(dlv) goroutine 5 # switch to goroutine 5
(dlv) stack # print stack trace
(dlv) frame 2 # switch to frame 2
(dlv) locals # print local variables
5.9 Live Reload
Using air:
# .air.toml
[build]
cmd = "go build -o ./tmp/main ./cmd/server"
bin = "./tmp/main"
full_bin = "APP_ENV=dev ./tmp/main"
include_ext = ["go", "tpl", "tmpl", "html"]
exclude_dir = ["tmp", "vendor", "node_modules"]
delay = 1000
stop_on_error = true
air -c .air.toml
5.10 Container Builds
Multi-stage Dockerfile:
FROM golang:1.24 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server ./cmd/server
FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app/server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]
ko — build Go apps as container images without Dockerfile:
ko build ./cmd/server
ko build -B ./cmd/server --platform=linux/amd64,linux/arm64
GoReleaser — cross-compile, package, and release:
# .goreleaser.yml
builds:
- env: [CGO_ENABLED=0]
goos: [linux, darwin, windows]
goarch: [amd64, arm64]
ldflags: [-s -w -X main.version={{ .Version }}]
archives:
- format: tar.gz
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
checksum:
name_template: "checksums.txt"
changelog:
sort: asc
6. Security
6.1 SQL Injection Prevention
Always use placeholders. Never concatenate user input into SQL.
// RIGHT — placeholders prevent injection
rows, err := db.QueryContext(ctx,
"SELECT id, name FROM users WHERE email = $1", userInput,
)
// WRONG — SQL injection vulnerability
query := fmt.Sprintf("SELECT id, name FROM users WHERE email = '%s'", userInput)
rows, err := db.QueryContext(ctx, query)
For dynamic column/table names, use a whitelist:
var allowedColumns = map[string]bool{
"id": true, "name": true, "email": true, "created_at": true,
}
func listUsers(db *sql.DB, orderBy string) ([]User, error) {
if !allowedColumns[orderBy] {
return nil, fmt.Errorf("invalid column: %s", orderBy)
}
// Safe: orderBy is from a whitelist, not user input
query := fmt.Sprintf("SELECT id, name, email FROM users ORDER BY %s", orderBy)
rows, err := db.QueryContext(context.Background(), query)
// ...
}
6.2 Path Traversal Prevention
// Clean the path
safe := filepath.Clean(userInput)
// Check the cleaned path stays within the base directory
func safeRead(baseDir, userPath string) ([]byte, error) {
fullPath := filepath.Join(baseDir, filepath.Clean(userPath))
if !strings.HasPrefix(fullPath, filepath.Clean(baseDir)+string(os.PathSeparator)) {
return nil, fmt.Errorf("path traversal attempt: %s", userPath)
}
return os.ReadFile(fullPath)
}
// Or use io/fs.ValidPath (Go 1.22+) for fs.FS operations
if !fs.ValidPath(userPath) {
return nil, fmt.Errorf("invalid path: %s", userPath)
}
6.3 Template Injection
// RIGHT — html/template auto-escapes by context
import "html/template"
tmpl := template.Must(template.New("page").Parse(`
<h1>{{.Title}}</h1>
<p>{{.Body}}</p>
<a href="{{.URL}}">link</a>
`))
// Title, Body, and URL are auto-escaped for their HTML context
// WRONG — text/template does NOT escape
import "text/template"
// text/template output goes directly to output — NEVER for HTML
6.4 Cryptographic Best Practices
// Random tokens
import "crypto/rand"
// NOT math/rand — that's deterministic, not secure
func generateToken() (string, error) {
b := make([]byte, 32)
if _, err := rand.Read(b); err != nil {
return "", err
}
return base64.RawURLEncoding.EncodeToString(b), nil
}
// Constant-time comparison for any security-sensitive comparison
// Not just HMACs — tokens, API keys, any secret comparison
func verifyToken(received, expected string) bool {
return subtle.ConstantTimeCompare([]byte(received), []byte(expected)) == 1
}
// Password hashing with argon2id (recommended)
import "golang.org/x/crypto/argon2"
func hashPassword(password string, salt []byte) []byte {
return argon2.IDKey([]byte(password), salt,
1, // iterations (time parameter)
64*1024, // memory (64MB)
4, // threads (parallelism)
32, // key length
)
}
// Store the salt alongside the hash (prepend or use encoded format)
// bcrypt fallback (simpler API, fixed params)
import "golang.org/x/crypto/bcrypt"
hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
err = bcrypt.CompareHashAndPassword(hash, []byte(password))
TLS configuration:
tlsConfig := &tls.Config{
MinVersion: tls.VersionTLS12,
// Prefer modern cipher suites — Go's defaults are already good
// Explicitly disable weak ciphers if needed
CurvePreferences: []tls.CurveID{tls.X25519, tls.CurveP256},
}
server := &http.Server{
Addr: ":443",
TLSConfig: tlsConfig,
}
6.5 Input Validation
import "regexp"
// Whitelist validation — define what IS allowed
var validUsername = regexp.MustCompile(`^[a-zA-Z0-9_-]{3,32}$`)
var validEmail = regexp.MustCompile(`^[^\s@]+@[^\s@]+\.[^\s@]+$`)
func validateUsername(s string) bool {
return validUsername.MatchString(s)
}
// For struct validation, use the validator package
import "github.com/go-playground/validator/v10"
type CreateUserRequest struct {
Name string `validate:"required,min=3,max=50"`
Email string `validate:"required,email"`
Age int `validate:"gte=0,lte=150"`
}
validate := validator.New()
if err := validate.Struct(req); err != nil {
return err
}
6.6 Memory Safety
Go is memory-safe by default — no buffer overflows (bounds-checked slices),
no use-after-free (GC), no dangling pointers (escape analysis ensures
liveness). The unsafe package is the sole exception.
// Slice capacity vs length — classic confusion
s := make([]byte, 5, 10)
fmt.Println(len(s)) // 5
fmt.Println(cap(s)) // 10
// Truncate while keeping capacity: s = s[:len(s)]
s = s[:len(s)] // keeps capacity=10
// Truncate to zero: s = s[:0]
s = s[:0] // len=0, cap=10 — backing array retained
// Release backing array: s = nil
s = nil // len=0, cap=0 — GC collects backing array
6.7 Deserialization Safety
// encoding/gob is unsafe with untrusted input — gob can call methods during decode
// NEVER: gob.NewDecoder(untrusted).Decode(&v)
// json.Decoder with strict settings
dec := json.NewDecoder(untrustedInput)
dec.DisallowUnknownFields()
// XML with caution
d := xml.NewDecoder(untrustedInput)
d.Strict = true
// YAML: use yaml.Unmarshal with a known type, never yaml.Unmarshal(..., &any)
// yaml.v2's Unmarshal into interface{} is dangerous (like JSON into map[string]any)
6.8 HTTP Security
server := &http.Server{
Addr: ":8080",
ReadTimeout: 5 * time.Second, // from connection accept to request body read
WriteTimeout: 10 * time.Second, // from request header read to response write
IdleTimeout: 120 * time.Second, // keep-alive timeout
MaxHeaderBytes: 1 << 20, // 1 MB, prevent header blowup
}
// TimeoutHandler wraps slow handlers
timeoutHandler := http.TimeoutHandler(myHandler, 5*time.Second, "handler timed out")
// Security headers middleware
func securityHeaders(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-Content-Type-Options", "nosniff")
w.Header().Set("X-Frame-Options", "DENY")
w.Header().Set("Content-Security-Policy",
"default-src 'self'; script-src 'self'; style-src 'self'")
w.Header().Set("Strict-Transport-Security",
"max-age=31536000; includeSubDomains")
next.ServeHTTP(w, r)
})
}
7. Project Structure
7.1 Standard Layout
myproject/
├── cmd/ # Main applications
│ ├── server/main.go # API server binary
│ ├── worker/main.go # Background worker binary
│ └── cli/main.go # CLI tool binary
├── internal/ # Private application code (Go enforces unimportability)
│ ├── app/
│ │ ├── app.go # Application struct, wiring, lifecycle
│ │ └── middleware.go
│ ├── handler/
│ │ ├── user.go # HTTP handlers per domain
│ │ └── product.go
│ ├── service/
│ │ ├── user.go # Business logic
│ │ └── auth.go
│ └── repository/
│ ├── user.go # Data access
│ └── dberrors.go
├── pkg/ # Public library code (importable externally)
│ ├── auth/
│ └── pagination/
├── api/ # API definitions
│ ├── proto/ # protobuf definitions
│ │ └── user/v1/
│ │ └── user.proto
│ └── openapi/ # OpenAPI/Swagger specs
├── web/ # Web assets
│ ├── static/
│ └── templates/
├── configs/ # Configuration files
│ ├── config.yaml
│ └── config.prod.yaml
├── scripts/ # Build, install, analysis scripts
│ ├── build.sh
│ └── migrate.sh
├── build/ # CI/CD configuration
│ ├── Dockerfile
│ └── ci/
│ └── .github/workflows/
├── deployments/ # Deployment configs
│ ├── kubernetes/
│ └── terraform/
├── test/ # External test data
│ └── testdata/
├── docs/ # Design docs, README
├── go.mod
├── go.sum
└── Makefile
7.2 Module Naming
go mod init github.com/organization/project
# or for internal tools:
go mod init company.com/internal/tool
7.3 Go Workspaces
Multi-module repositories use go.work:
├── go.work
├── server/
│ ├── go.mod (github.com/org/monorepo/server)
│ └── main.go
├── shared/
│ ├── go.mod (github.com/org/monorepo/shared)
│ └── types.go
└── proto/
├── go.mod (github.com/org/monorepo/proto)
└── user.proto
go work init ./server ./shared ./proto
Do not commit go.work — it's for local development.
7.4 Platform-Specific Files
Go automatically selects files by GOOS and GOARCH:
file.go # always compiled
file_linux.go # only on linux
file_darwin.go # only on macOS
file_windows.go # only on Windows
file_amd64.go # only on amd64
file_arm64.go # only on arm64
file_linux_amd64.go # only on linux/amd64
file_linux_amd64_test.go # test, only on linux/amd64
7.5 Internal Visibility
Packages under internal/ can only be imported by code rooted at the
module path containing the internal directory. The Go toolchain enforces
this at compile time.
github.com/org/project/
├── internal/auth/ # only importable by code under github.com/org/project/
├── cmd/server/ # can import internal/auth
└── pkg/public/ # can import internal/auth
7.6 cgo
Call C code from Go. Use only when necessary — cgo breaks cross-compilation,
slows builds, and complicates deployment.
/*
#cgo CFLAGS: -I/usr/local/include
#cgo LDFLAGS: -L/usr/local/lib -lmylib
#include <stdlib.h>
#include <mylib.h>
*/
import "C"
import "unsafe"
func CallCLibrary(input string) string {
cInput := C.CString(input) // Go string → C string (allocates)
defer C.free(unsafe.Pointer(cInput)) // MUST free
cResult := C.my_function(cInput)
result := C.GoString(cResult) // C string → Go string (copies)
return result
}
Key cgo rules:
| Rule | Detail |
|---|
| C.CString | Allocates C memory — call C.free after |
| C.GoString | Copies data — original C memory can be freed |
| C.GoBytes | Copies C byte array to Go slice |
| unsafe.Pointer | Bridge between Go pointers and C void* |
| CGO_ENABLED=0 | Disable cgo for pure Go builds |
| -buildmode=c-shared | Build Go as a C shared library (.so/.dylib) |
// Exporting Go functions to C
//export Multiply
func Multiply(a, b int) int {
return a * b
}
// Build: CGO_ENABLED=1 go build -buildmode=c-shared -o libmath.so
cgo limitations: no cross-compilation without a cross-C-toolchain; each cgo
call locks the calling goroutine to an OS thread; significantly slower builds.
8. Performance Patterns
8.1 sync.Pool
Reuse temporary objects to reduce GC pressure. The pool may clear objects at
each GC cycle — never assume a pooled object will survive.
var bufferPool = sync.Pool{
New: func() any {
return new(bytes.Buffer)
},
}
func process(data []byte) {
buf := bufferPool.Get().(*bytes.Buffer)
defer func() {
buf.Reset()
bufferPool.Put(buf)
}()
buf.Write(data)
// use buf...
}
// Pool for slices
var slicePool = sync.Pool{
New: func() any {
s := make([]byte, 0, 4096)
return &s
},
}
func getBuf() *[]byte {
return slicePool.Get().(*[]byte)
}
func putBuf(b *[]byte) {
*b = (*b)[:0] // reset length, keep capacity
slicePool.Put(b)
}
When to use: high-allocation-rate temporary objects with similar lifetimes.
When NOT to use: long-lived objects, objects with varying sizes (capacity
mismatch wastes memory), objects that must never be zeroed.
8.2 strings.Builder
For building strings in loops, strings.Builder avoids repeated allocations:
// SLOW: each + allocates a new string
var s string
for _, item := range items {
s += item.Name + ","
}
// FAST: single allocation
var b strings.Builder
b.Grow(estimatedSize) // avoid reallocations if you know the size
for _, item := range items {
b.WriteString(item.Name)
b.WriteByte(',')
}
s := b.String()
8.3 Pre-allocating Slices and Maps
// Pre-allocate slice capacity to avoid reallocation
const nItems = 1000
ids := make([]int64, 0, nItems) // len=0, cap=1000
for rows.Next() {
var id int64
rows.Scan(&id)
ids = append(ids, id)
}
// Bulk append
final := make([]int, 0, len(a)+len(b)+len(c))
final = append(final, a...)
final = append(final, b...)
final = append(final, c...)
// Pre-size map when count is known
// Only use if you know the approximate size — over-sizing wastes memory
users := make(map[int64]*User, estimatedCount)
8.4 Escape Analysis
The compiler decides whether a variable lives on the stack or heap. Use
-gcflags="-m" to see what escapes:
go build -gcflags="-m" ./... 2>&1 | grep "escapes to heap"
What causes escape:
- Returning a pointer to a local variable
- Storing a value in an
interface{} (or any)
- Passing a value to
fmt.Println (variadic interface{})
- Closures that reference local variables
- Sending pointers on channels
- Storing values in global variables
// ESCAPES: pointer to local returned
func newInt() *int { x := 42; return &x }
// DOES NOT ESCAPE: value returned by copy
func getInt() int { x := 42; return x }
// ESCAPES: interface boxing
func print(v any) { fmt.Println(v) }
print(42) // 42 escapes to heap (boxed in interface{})
8.5 Memory Pitfalls
Slice retaining backing array:
// s2 keeps the entire backing array of s1 alive
s1 := make([]byte, 1<<20) // 1MB
s2 := s1[:100] // s2's backing array is still 1MB
// Fix: copy to a new slice
s2 := make([]byte, 100)
copy(s2, s1[:100])
// s1's backing array can now be GC'd if no other references exist
Goroutine memory:
1 goroutine = ~2KB stack (grows as needed; starts at 2KB)
1M goroutines = ~2GB stack memory alone
Context switching overhead grows with goroutines > logical CPUs
Channel is not always best — for simple shared-state locking, sync.Mutex is
faster than an unbuffered channel (no goroutine switch).
8.6 map vs switch
For small N (≤ ~8), a switch on int/string is faster than a map lookup.
The switch compiles to a jump table; the map requires hashing.
// For 3-5 cases: switch is faster
switch key {
case "create":
return handleCreate()
case "update":
return handleUpdate()
case "delete":
return handleDelete()
default:
return handleUnknown()
}
// For 100+ cases: map is more readable and reasonable speed
handlers := map[string]func() error{
"create": handleCreate,
"update": handleUpdate,
// ...
}
if h, ok := handlers[key]; ok {
return h()
}
9. Popular Ecosystem
9.1 Web Frameworks
net/http (stdlib) — always the right starting point:
mux := http.NewServeMux()
mux.HandleFunc("GET /api/users/{id}", handleGetUser) // Go 1.22+ method+pattern
mux.HandleFunc("POST /api/users", handleCreateUser)
http.ListenAndServe(":8080", mux)
chi — lightweight, idiomatic, middleware-composable:
r := chi.NewRouter()
r.Use(middleware.Logger)
r.Use(middleware.Recoverer)
r.Use(middleware.Timeout(30 * time.Second))
r.Route("/api/users", func(r chi.Router) {
r.Get("/", listUsers)
r.Post("/", createUser)
r.Route("/{userID}", func(r chi.Router) {
r.Use(UserCtx) // middleware scoped to this subrouter
r.Get("/", getUser)
r.Put("/", updateUser)
r.Delete("/", deleteUser)
})
})
http.ListenAndServe(":8080", r)
gin — fast, with binding and validation:
r := gin.Default()
r.GET("/api/users/:id", func(c *gin.Context) {
id := c.Param("id")
user, err := svc.GetUser(c, id)
if err != nil {
c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
return
}
c.JSON(http.StatusOK, user)
})
r.POST("/api/users", func(c *gin.Context) {
var req CreateUserReq
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
user, err := svc.CreateUser(c, req)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
return
}
c.JSON(http.StatusCreated, user)
})
9.2 Database and ORM
sqlx — extends database/sql with struct scanning:
type User struct {
ID int64 `db:"id"`
Name string `db:"name"`
Email string `db:"email"`
}
db, _ := sqlx.Connect("postgres", dsn)
var users []User
db.SelectContext(ctx, &users, "SELECT id, name, email FROM users WHERE active = $1", true)
var user User
db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE id = $1", id)
result, _ := db.NamedExecContext(ctx,
"INSERT INTO users (name, email) VALUES (:name, :email)", user,
)
pgx — PostgreSQL driver with connection pool:
pool, _ := pgxpool.New(ctx, dsn)
defer pool.Close()
var name string
err := pool.QueryRow(ctx,
"SELECT name FROM users WHERE id = $1", userID,
).Scan(&name)
rows, _ := pool.Query(ctx,
"SELECT id, name FROM users WHERE active = $1", true,
)
defer rows.Close()
for rows.Next() {
var id int64
var name string
rows.Scan(&id, &name)
}
sqlc — code generation from SQL (type-safe, great performance):
-- query.sql
-- name: GetUser :one
SELECT id, name, email FROM users WHERE id = $1;
-- name: ListActiveUsers :many
SELECT id, name FROM users WHERE active = $1;
-- name: CreateUser :exec
INSERT INTO users (name, email) VALUES ($1, $2);
// Generated code
queries := db.New(conn)
user, err := queries.GetUser(ctx, 42)
users, err := queries.ListActiveUsers(ctx, true)
err = queries.CreateUser(ctx, db.CreateUserParams{Name: "Alice", Email: "alice@example.com"})
gorm (popular but not idiomatic Go — prefer sqlc or sqlx):
db, _ := gorm.Open(postgres.Open(dsn), &gorm.Config{})
db.AutoMigrate(&User{}, &Order{})
var user User
db.Where("email = ?", email).First(&user)
db.Where("id = ?", id).Delete(&User{})
// Preload associations (N+1 by default unless you Preload)
db.Preload("Orders").Find(&users)
9.3 gRPC
Protobuf definition:
syntax = "proto3";
package user.v1;
option go_package = "github.com/org/project/api/user/v1;userv1";
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse);
rpc ListUsers(ListUsersRequest) returns (stream User); // server streaming
rpc CreateUser(stream CreateUserRequest) returns (CreateUserResponse); // client streaming
rpc Chat(stream ChatMessage) returns (stream ChatMessage); // bidirectional
}
message GetUserRequest {
string user_id = 1;
}
message GetUserResponse {
string user_id = 1;
string name = 2;
