tomevault-io Go Patterns Skill
Idiomatic Go for production systems. Focuses on simplicity, explicitness, and composition.
When to Activate
Activate when:
- Writing new Go packages or services
- Reviewing Go code for idiom and correctness
- Designing concurrent processing pipelines
- Debugging goroutine leaks or race conditions
- Setting up module structure or build configuration
Error Handling
Go errors are values. Handle them at the point where you have enough context to act.
Wrapping and Unwrapping
import "errors"
import "fmt"
// Wrap with %w to preserve the chain
func loadConfig(path string) (*Config, error) {
data, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("loadConfig %q: %w", path, err)
}
// ...
}
// Inspect with errors.Is (sentinel) and errors.As (type)
var ErrNotFound = errors.New("not found")
if err := loadConfig("app.yaml"); err != nil {
if errors.Is(err, os.ErrNotExist) {
// file missing
}
var pathErr *os.PathError
if errors.As(err, &pathErr) {
log.Printf("path problem: %s", pathErr.Path)
}
}
Sentinel Errors
// Define at package level, exported when callers need to check
var (
ErrNotFound = errors.New("not found")
ErrPermission = errors.New("permission denied")
)
// Prefer typed errors when you need to attach data
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("validation: %s %s", e.Field, e.Message)
}
Error String Conventions
// ✅ lowercase, no trailing punctuation
errors.New("connection refused")
fmt.Errorf("user %d not found", id)
// ❌ uppercase or punctuation
errors.New("Connection refused.")
Interface Design
Keep interfaces small. A one-method interface is a feature, not a limitation.
The io.Reader / io.Writer Pattern
// Standard library interfaces — use them where they fit
type Reader interface {
Read(p []byte) (n int, err error)
}
type Writer interface {
Write(p []byte) (n int, err error)
}
// Compose for more complex contracts
type ReadWriter interface {
Reader
Writer
}
// Accept interfaces, return concrete types
func Process(r io.Reader) ([]byte, error) {
return io.ReadAll(r)
}
// os.File, bytes.Buffer, http.Response.Body all satisfy io.Reader
Define Interfaces at the Consumer
// ❌ Defining in the producer package forces coupling
package store
type Repository interface { ... } // in the store package
// ✅ Define in the consumer package
package service
type userStore interface {
FindByID(ctx context.Context, id int64) (*User, error)
Save(ctx context.Context, u *User) error
}
type UserService struct {
store userStore
}
Single-Method Naming
// Verb + "er" for single-method interfaces
type Reader interface { Read(...) }
type Writer interface { Write(...) }
type Stringer interface { String() string }
type Closer interface { Close() error }
type Handler interface { ServeHTTP(...) }
Goroutines and Channels
Worker Pool Pattern
func workerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
results := make(chan Result)
var wg sync.WaitGroup
wg.Add(workers)
for range workers {
go func() {
defer wg.Done()
for job := range jobs {
select {
case results <- process(job):
case <-ctx.Done():
return
}
}
}()
}
go func() {
wg.Wait()
close(results)
}()
return results
}
Fan-Out / Fan-In
// Fan-out: send work to N goroutines
func fanOut(in <-chan int, n int) []<-chan int {
outs := make([]<-chan int, n)
for i := range n {
ch := make(chan int)
outs[i] = ch
go func() {
defer close(ch)
for v := range in {
ch <- v * 2
}
}()
}
return outs
}
// Fan-in: merge N channels into one
func merge(channels ...<-chan int) <-chan int {
out := make(chan int)
var wg sync.WaitGroup
wg.Add(len(channels))
for _, ch := range channels {
go func(c <-chan int) {
defer wg.Done()
for v := range c {
out <- v
}
}(ch)
}
go func() {
wg.Wait()
close(out)
}()
return out
}
Select and Context Cancellation
func doWork(ctx context.Context) error {
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return ctx.Err()
case t := <-ticker.C:
if err := tick(t); err != nil {
return fmt.Errorf("tick: %w", err)
}
}
}
}
Channel Ownership Rule
The goroutine that creates a channel is responsible for closing it. Closing a channel from a reader or having multiple goroutines close the same channel causes panics.
Struct Embedding vs Composition
Embedding for Behaviour Promotion
type Logger struct {
level string
}
func (l *Logger) Log(msg string) {
fmt.Printf("[%s] %s\n", l.level, msg)
}
type Server struct {
Logger // promotes Log method
addr string
}
s := Server{Logger: Logger{level: "INFO"}, addr: ":8080"}
s.Log("starting") // calls s.Logger.Log
Prefer Explicit Fields for Data
// ❌ Embedding for data models creates implicit API surface
type FullUser struct {
User // every User field/method becomes part of FullUser's API
Profile
}
// ✅ Explicit fields make dependencies obvious
type FullUser struct {
User User
Profile Profile
}
defer, panic, recover
defer — Always for Cleanup
func writeFile(path string, data []byte) error {
f, err := os.Create(path)
if err != nil {
return err
}
defer f.Close() // runs even if Write returns error
_, err = f.Write(data)
return err
}
// defer evaluates arguments immediately — useful for timing
func trace(name string) func() {
start := time.Now()
return func() { log.Printf("%s: %v", name, time.Since(start)) }
}
defer trace("expensiveOp")()
panic / recover — Only at Boundaries
// Use panic only for programmer errors (invariant violations)
func mustPositive(n int) int {
if n <= 0 {
panic(fmt.Sprintf("expected positive, got %d", n))
}
return n
}
// Recover at the top of a goroutine or HTTP handler to convert to error
func safeExec(fn func()) (err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic: %v", r)
}
}()
fn()
return nil
}
Never use panic/recover as a substitute for regular error handling.
Table-Driven Tests
func TestParseDate(t *testing.T) {
cases := []struct {
name string
input string
want time.Time
wantErr bool
}{
{
name: "ISO format",
input: "2024-01-15",
want: time.Date(2024, 1, 15, 0, 0, 0, 0, time.UTC),
},
{
name: "empty string",
input: "",
wantErr: true,
},
{
name: "invalid format",
input: "15/01/2024",
wantErr: true,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got, err := ParseDate(tc.input)
if (err != nil) != tc.wantErr {
t.Fatalf("ParseDate(%q) error = %v, wantErr %v", tc.input, err, tc.wantErr)
}
if !tc.wantErr && !got.Equal(tc.want) {
t.Errorf("ParseDate(%q) = %v, want %v", tc.input, got, tc.want)
}
})
}
}
Go Modules
go.mod Structure
module github.com/org/myservice
go 1.23
require (
github.com/some/dep v1.2.3
)
Workspace Mode (go.work) for Multi-Module Repos
go 1.23
use (
./cmd/api
./internal/core
./pkg/client
)
go work init ./cmd/api ./internal/core
go work use ./pkg/client
Module Commands
go mod tidy # add missing, remove unused
go mod vendor # copy deps to vendor/
go get github.com/x@v1.2.3 # add or upgrade
go mod why github.com/x # explain why dep is needed
sync Package
var mu sync.Mutex
mu.Lock()
defer mu.Unlock()
// RWMutex — many readers, one writer
var rw sync.RWMutex
rw.RLock()
defer rw.RUnlock()
// WaitGroup — wait for goroutines to finish
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
// ...
}()
wg.Wait()
// Once — run exactly once (e.g., lazy init)
var once sync.Once
var instance *DB
func getDB() *DB {
once.Do(func() { instance = newDB() })
return instance
}
// Atomic operations — simple counters without a mutex
var counter atomic.Int64
counter.Add(1)
n := counter.Load()
Build Tags
//go:build linux && amd64
package platform
// This file only compiles on 64-bit Linux.
func pageSize() int { return 4096 }
go build -tags integration ./...
go test -tags integration ./...
Common Pitfalls
Goroutine Leaks
// ❌ Nothing reads from results — goroutines block forever
func leak() {
results := make(chan int)
go func() { results <- compute() }()
// forgot to read results
}
// ✅ Always ensure goroutines can exit — use buffered channels or context
func noLeak(ctx context.Context) {
results := make(chan int, 1)
go func() {
select {
case results <- compute():
case <-ctx.Done():
}
}()
}
nil Interface vs nil Pointer
// ❌ Returning a typed nil as an interface is NOT nil
func getErr() error {
var p *os.PathError = nil
return p // error interface is not nil!
}
// ✅ Return untyped nil
func getErr() error {
return nil
}
Map Race Conditions
// ❌ Concurrent read/write on map causes data race
m := map[string]int{}
go func() { m["a"] = 1 }()
go func() { _ = m["a"] }()
// ✅ Use sync.Map or protect with a mutex
var mu sync.RWMutex
mu.Lock()
m["a"] = 1
mu.Unlock()
Source: DVNghiem/FlowDeck — distributed by TomeVault.