Go Development (1.25+)
Core Principles
- Stdlib first: External deps only when justified
- Concrete types: Define interfaces at consumer, return structs
- Composition: Over inheritance, always
- Fail fast: Clear errors with context
- Simple: The obvious solution is usually correct
Quick Patterns
Error Handling
if err := doThing(); err != nil {
return fmt.Errorf("do thing: %w", err)
}
Struct with Options
type Server struct {
addr string
timeout time.Duration
}
func NewServer(addr string, opts ...Option) *Server {
s := &Server{addr: addr, timeout: 30 * time.Second}
for _, opt := range opts {
opt(s)
}
return s
}
Table-Driven Tests
tests := []struct {
name string
input string
want string
wantErr bool
}{
{"valid", "hello", "HELLO", false},
{"empty", "", "", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := Process(tt.input)
if tt.wantErr {
require.Error(t, err)
return
}
require.NoError(t, err)
assert.Equal(t, tt.want, got)
})
}
Go 1.25 Features
- testing/synctest: Deterministic concurrent testing with simulated clock
- encoding/json/v2: Experimental, 3-10x faster (GOEXPERIMENT=jsonv2)
- runtime/trace.FlightRecorder: Production trace capture on-demand
- Container-aware GOMAXPROCS: Auto-detects cgroup limits
- GreenTea GC: Experimental, lower latency (GOEXPERIMENT=greenteagc)
References
- PATTERNS.md - Detailed code patterns
- TESTING.md - Testing strategies with testify/mockery
- CLI.md - CLI application patterns
Tooling
go build ./... # Build
go test -race ./... # Test with race detector
golangci-lint run # Lint
mockery --all # Generate mocks
Gotchas
nil channel sends/receives block forever; closed channel receives return zero value immediately — select with a nil channel case disables that case, useful pattern but easy to do accidentally.defer captures arguments at the call site, not at execution — defer fmt.Println(time.Now()) captures NOW, not the deferred time.- Pre-Go 1.22 for-loop variable capture closures over ONE variable across all iterations — the goroutine-in-loop bug. Go 1.22 changed semantics; old habits create subtle bugs in mixed-version code.
errors.Is walks Unwrap() chains, BUT if a wrapped error implements Is(target error) bool itself, that custom Is wins over walking — confusing when migrating from xerrors.sync.Pool items can be GC'd between Get and the next Put — never rely on a Pool to retain state.
1---2name: writing-go3description: Idiomatic Go 1.25+ development. Use when writing Go code, designing APIs, discussing Go patterns, or reviewing Go implementations. Emphasizes stdlib, concrete types, simple error handling, and minimal dependencies.4---5
6# Go Development (1.25+)
7
8## Core Principles
9
10- **Stdlib first**: External deps only when justified
11- **Concrete types**: Define interfaces at consumer, return structs
12- **Composition**: Over inheritance, always
13- **Fail fast**: Clear errors with context
14- **Simple**: The obvious solution is usually correct
15
16## Quick Patterns
17
18### Error Handling
19
20```go
21if err := doThing(); err != nil {
22 return fmt.Errorf("do thing: %w", err)
23}
24```
25
26### Struct with Options
27
28```go
29type Server struct {
30 addr string
31 timeout time.Duration
32}
33
34func NewServer(addr string, opts ...Option) *Server {
35 s := &Server{addr: addr, timeout: 30 * time.Second}
36 for _, opt := range opts {
37 opt(s)
38 }
39 return s
40}
41```
42
43### Table-Driven Tests
44
45```go
46tests := []struct {
47 name string
48 input string
49 want string
50 wantErr bool
51}{
52 {"valid", "hello", "HELLO", false},
53 {"empty", "", "", true},
54}
55for _, tt := range tests {
56 t.Run(tt.name, func(t *testing.T) {
57 got, err := Process(tt.input)
58 if tt.wantErr {
59 require.Error(t, err)
60 return
61 }
62 require.NoError(t, err)
63 assert.Equal(t, tt.want, got)
64 })
65}
66```
67
68## Go 1.25 Features
69
70- **testing/synctest**: Deterministic concurrent testing with simulated clock
71- **encoding/json/v2**: Experimental, 3-10x faster (GOEXPERIMENT=jsonv2)
72- **runtime/trace.FlightRecorder**: Production trace capture on-demand
73- **Container-aware GOMAXPROCS**: Auto-detects cgroup limits
74- **GreenTea GC**: Experimental, lower latency (GOEXPERIMENT=greenteagc)
75
76## References
77
78- [PATTERNS.md](PATTERNS.md) - Detailed code patterns
79- [TESTING.md](TESTING.md) - Testing strategies with testify/mockery
80- [CLI.md](CLI.md) - CLI application patterns
81
82## Tooling
83
84```bash
85go build ./... # Build
86go test -race ./... # Test with race detector
87golangci-lint run # Lint
88mockery --all # Generate mocks
89```
90
91---
92
93## Gotchas
94
95- **`nil` channel sends/receives block forever; closed channel receives return zero value immediately** — `select` with a nil channel case disables that case, useful pattern but easy to do accidentally.
96- **`defer` captures arguments at the call site, not at execution** — `defer fmt.Println(time.Now())` captures NOW, not the deferred time.
97- **Pre-Go 1.22 for-loop variable capture closures over ONE variable across all iterations** — the goroutine-in-loop bug. Go 1.22 changed semantics; old habits create subtle bugs in mixed-version code.
98- **`errors.Is` walks `Unwrap()` chains, BUT if a wrapped error implements `Is(target error) bool` itself, that custom Is wins over walking** — confusing when migrating from xerrors.
99- **`sync.Pool` items can be GC'd between `Get` and the next `Put`** — never rely on a Pool to retain state.
julianobarbosa