feat: initial Go patterns guide from stdlib + Kubernetes source study
9 pattern files covering stdlib (structs, interfaces, API conventions, docs, style), Kubernetes (controller/reconciler, informer/cache, leader election, code generation), comparison (stdlib vs K8s approaches), and anti-patterns. All patterns cite exact source files and line numbers.
This commit is contained in:
Rodin
@@ -0,0 +1,325 @@
|
||||
# Stdlib vs Kubernetes: Where K8s Does Things Differently
|
||||
|
||||
## 1. Concurrency: Channels vs. Condition Variables + Sets
|
||||
|
||||
### Stdlib approach
|
||||
Go stdlib idiom: communicate via channels. A worker pool typically uses a `chan T` for work items.
|
||||
|
||||
```go
|
||||
// Typical stdlib pattern:
|
||||
jobs := make(chan Job, 100)
|
||||
for i := 0; i < workers; i++ {
|
||||
go func() {
|
||||
for job := range jobs {
|
||||
process(job)
|
||||
}
|
||||
}()
|
||||
}
|
||||
```
|
||||
|
||||
### Kubernetes approach
|
||||
The workqueue uses `sync.Cond` + `sets.Set` instead of channels.
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/util/workqueue/queue.go` (lines 190–300)
|
||||
|
||||
```go
|
||||
type Typed[t comparable] struct {
|
||||
queue Queue[t]
|
||||
dirty sets.Set[t] // Items needing processing
|
||||
processing sets.Set[t] // Items currently being processed
|
||||
cond *sync.Cond // Notification mechanism
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
Channels don't deduplicate. If you send the same key twice to a channel, it gets processed twice. K8s needs:
|
||||
- **Deduplication**: same object modified 5 times → process once with latest state
|
||||
- **Re-entrant marking**: if modified during processing, re-queue after Done()
|
||||
- **Inspection**: can query queue length, processing count for metrics
|
||||
|
||||
A channel-based design would require a separate dedup layer anyway, losing its simplicity advantage.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error Handling: Single Errors vs. Error Aggregation
|
||||
|
||||
### Stdlib approach
|
||||
Return a single error. Wrap with `fmt.Errorf("...: %w", err)`.
|
||||
|
||||
### Kubernetes approach
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/util/errors/errors.go` (lines 34–100)
|
||||
|
||||
```go
|
||||
type Aggregate interface {
|
||||
error
|
||||
Errors() []error
|
||||
Is(error) bool
|
||||
}
|
||||
|
||||
func NewAggregate(errlist []error) Aggregate {
|
||||
// Filters nils, deduplicates messages
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
A controller sync often does multiple operations (create 3 pods, update 2 services). You want to attempt all of them, not fail fast on the first error. Error aggregation collects all failures so the user sees the full picture.
|
||||
|
||||
**Also**: the `Aggregate` interface properly implements `errors.Is()` by checking if *any* contained error matches — which `errors.Join` didn't originally support well.
|
||||
|
||||
---
|
||||
|
||||
## 3. Retry: stdlib has nothing; K8s has structured retry
|
||||
|
||||
### Stdlib approach
|
||||
There's no retry utility in stdlib. You write your own loop.
|
||||
|
||||
### Kubernetes approach
|
||||
**Source:** `staging/src/k8s.io/client-go/util/retry/util.go` (lines 30–100)
|
||||
|
||||
```go
|
||||
var DefaultRetry = wait.Backoff{
|
||||
Steps: 5,
|
||||
Duration: 10 * time.Millisecond,
|
||||
Factor: 1.0,
|
||||
Jitter: 0.1,
|
||||
}
|
||||
|
||||
func RetryOnConflict(backoff wait.Backoff, fn func() error) error {
|
||||
// Retries only on HTTP 409 Conflict
|
||||
return OnError(backoff, errors.IsConflict, fn)
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
In a distributed system, retries are *the* primary reliability mechanism. Stdlib doesn't provide them because stdlib targets single-machine programs. Kubernetes needs:
|
||||
- Configurable backoff (steps, factor, jitter, cap)
|
||||
- Condition-based retry (retry only on specific error types)
|
||||
- Context-aware cancellation
|
||||
|
||||
---
|
||||
|
||||
## 4. Polling: time.Ticker vs. Contextual Loop With Crash Protection
|
||||
|
||||
### Stdlib approach
|
||||
```go
|
||||
ticker := time.NewTicker(interval)
|
||||
defer ticker.Stop()
|
||||
for range ticker.C {
|
||||
doWork()
|
||||
}
|
||||
```
|
||||
|
||||
### Kubernetes approach
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/util/wait/backoff.go` (lines 240–260), `loop.go` (lines 38–80)
|
||||
|
||||
```go
|
||||
func BackoffUntilWithContext(ctx context.Context, f func(ctx context.Context), backoff BackoffManager, sliding bool) {
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return
|
||||
default:
|
||||
}
|
||||
if !sliding { t = backoff.Backoff() }
|
||||
func() {
|
||||
defer runtime.HandleCrashWithContext(ctx)
|
||||
f(ctx)
|
||||
}()
|
||||
if sliding { t = backoff.Backoff() }
|
||||
// ... wait for timer or context cancellation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
- **Crash protection**: a panic in `doWork()` shouldn't kill the whole process
|
||||
- **Sliding vs non-sliding**: controls whether interval includes execution time
|
||||
- **Context cancellation**: allows clean shutdown
|
||||
- **Jitter**: prevents thundering herd when many controllers sync at similar intervals
|
||||
- **Double-check for cancellation**: Go's select is non-deterministic, so short timers can "win" against a cancelled context
|
||||
|
||||
---
|
||||
|
||||
## 5. Graceful Shutdown: http.Server.Shutdown vs. Multi-Phase Orchestration
|
||||
|
||||
### Stdlib approach (net/http)
|
||||
**Source:** `/tmp/go-src/src/net/http/server.go` (lines 3221–3260)
|
||||
|
||||
```go
|
||||
func (s *Server) Shutdown(ctx context.Context) error {
|
||||
s.inShutdown.Store(true)
|
||||
s.closeListenersLocked()
|
||||
// Poll for idle connections
|
||||
for {
|
||||
if s.closeIdleConns() { return nil }
|
||||
select {
|
||||
case <-ctx.Done(): return ctx.Err()
|
||||
case <-timer.C: timer.Reset(nextPollInterval())
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Kubernetes approach
|
||||
**Source:** `pkg/controller/deployment/deployment_controller.go` (lines 171–196)
|
||||
|
||||
```go
|
||||
func (dc *DeploymentController) Run(ctx context.Context, workers int) {
|
||||
defer utilruntime.HandleCrash()
|
||||
dc.eventBroadcaster.StartStructuredLogging(3)
|
||||
dc.eventBroadcaster.StartRecordingToSink(...)
|
||||
defer dc.eventBroadcaster.Shutdown()
|
||||
|
||||
var wg sync.WaitGroup
|
||||
defer func() {
|
||||
dc.queue.ShutDown() // Stop accepting new work
|
||||
wg.Wait() // Wait for workers to finish
|
||||
}()
|
||||
|
||||
// Gate: don't start until caches are synced
|
||||
if !cache.WaitForNamedCacheSyncWithContext(ctx, ...) { return }
|
||||
|
||||
for i := 0; i < workers; i++ {
|
||||
wg.Go(func() {
|
||||
wait.UntilWithContext(ctx, dc.worker, time.Second)
|
||||
})
|
||||
}
|
||||
<-ctx.Done() // Block until context cancelled
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
Stdlib's shutdown is **reactive** (wait for connections to drain). Kubernetes' shutdown is **multi-phase orchestrated**:
|
||||
1. Stop accepting new events (close watch connections)
|
||||
2. Drain the work queue (process remaining items)
|
||||
3. Wait for in-flight syncs to complete
|
||||
4. Shut down event recorders
|
||||
|
||||
The queue's `ShutDownWithDrain()` is the K8s-specific innovation: it waits until all in-flight items call `Done()`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Type Systems: interfaces vs. Runtime Type Registry
|
||||
|
||||
### Stdlib approach
|
||||
Interfaces for polymorphism. If you need to serialize, use `encoding/json` with struct tags.
|
||||
|
||||
### Kubernetes approach
|
||||
A full runtime type registry (Scheme) that maps between GVK strings and Go types.
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/runtime/scheme.go`
|
||||
|
||||
### Why K8s is different
|
||||
Stdlib's `encoding/json` requires knowing the concrete type at compile time. Kubernetes must:
|
||||
- Deserialize objects from the network without knowing their type in advance
|
||||
- Convert between API versions (`v1beta1.Deployment` → `v1.Deployment`)
|
||||
- Support third-party types (CRDs) that don't exist at compile time
|
||||
- Apply defaulting and validation based on type metadata
|
||||
|
||||
This forces a **runtime type system layered on top of Go's static types**.
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing: httptest vs. Fake Clients + Reactors
|
||||
|
||||
### Stdlib approach
|
||||
`net/http/httptest` provides a test server. You make real HTTP calls against it.
|
||||
|
||||
### Kubernetes approach
|
||||
Fake clientsets with reactor chains:
|
||||
```go
|
||||
// Generated fake clients intercept API calls
|
||||
fakeClient := fake.NewSimpleClientset(existingObjects...)
|
||||
fakeClient.PrependReactor("create", "pods", func(action testing.Action) (bool, runtime.Object, error) {
|
||||
// Custom test behavior
|
||||
return true, nil, fmt.Errorf("simulated error")
|
||||
})
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
Testing a controller doesn't require a running API server. The fake client + informer pattern lets you:
|
||||
- Inject specific starting states
|
||||
- Simulate failures at specific operations
|
||||
- Run synchronously (no network delay)
|
||||
- Test the controller logic in isolation
|
||||
|
||||
---
|
||||
|
||||
## 8. Lifecycle: main() returns vs. Infinite Reconciliation
|
||||
|
||||
### Stdlib pattern
|
||||
Programs start, do work, return.
|
||||
|
||||
### Kubernetes pattern
|
||||
Controllers start and run *forever*, continuously reconciling.
|
||||
|
||||
```go
|
||||
// The fundamental difference: stdlib programs terminate, controllers don't
|
||||
func main() {
|
||||
// Stdlib: do work, exit
|
||||
result := compute()
|
||||
fmt.Println(result)
|
||||
}
|
||||
|
||||
// Kubernetes: infinite loop with eventual consistency
|
||||
func (c *Controller) Run(ctx context.Context) {
|
||||
// Run forever until context cancelled
|
||||
for i := 0; i < workers; i++ {
|
||||
go wait.UntilWithContext(ctx, c.worker, time.Second)
|
||||
}
|
||||
<-ctx.Done()
|
||||
}
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
The real world is adversarial. Networks fail, nodes die, humans make mistakes. A one-shot program can't handle drift. The reconciliation loop is Kubernetes' answer to the CAP theorem: you can't guarantee consistency in a single call, but you can achieve it *eventually* through repetition.
|
||||
|
||||
---
|
||||
|
||||
## 9. Shared State: Package-Level vs. Shared Informer Cache
|
||||
|
||||
### Stdlib approach
|
||||
Package-level variables, or pass state through function parameters.
|
||||
|
||||
### Kubernetes approach
|
||||
The SharedInformerFactory creates a single in-memory cache per resource type, shared by all controllers in the process.
|
||||
|
||||
```go
|
||||
// All controllers share ONE watch and ONE cache per resource:
|
||||
informerFactory := informers.NewSharedInformerFactory(client, resyncPeriod)
|
||||
deployInformer := informerFactory.Apps().V1().Deployments()
|
||||
|
||||
// Controller A and B both get events from the same informer
|
||||
deployInformer.Informer().AddEventHandler(controllerA)
|
||||
deployInformer.Informer().AddEventHandler(controllerB)
|
||||
```
|
||||
|
||||
### Why K8s is different
|
||||
Without sharing:
|
||||
- 20 controllers × watch for Pods = 20 TCP connections to API server
|
||||
- 20 copies of all Pods in memory
|
||||
|
||||
With SharedInformerFactory:
|
||||
- 1 TCP connection for Pods
|
||||
- 1 copy in memory
|
||||
- Events fanned out to all registered handlers
|
||||
|
||||
---
|
||||
|
||||
## 10. Configuration: Flags/Env vs. Feature Gates
|
||||
|
||||
### Stdlib approach
|
||||
`flag` package, environment variables, config files.
|
||||
|
||||
### Kubernetes approach
|
||||
Feature gates: a versioned, lifecycle-aware configuration system.
|
||||
|
||||
### Why K8s is different
|
||||
Stdlib's flag package is for a single binary. Kubernetes has:
|
||||
- Hundreds of features in various stages of maturity
|
||||
- Features that must be consistent across control plane components
|
||||
- Features that need to be enabled/disabled without redeployment
|
||||
- Features with dependencies on other features
|
||||
- Automated testing that exercises all combinations
|
||||
|
||||
Feature gates encode *maturity* (alpha/beta/GA) alongside the boolean value, something `flag.Bool` can never express.
|
||||
@@ -0,0 +1,405 @@
|
||||
# Kubernetes-Specific Patterns
|
||||
|
||||
## 1. Controller / Reconciler Pattern
|
||||
|
||||
**Source:** `pkg/controller/deployment/deployment_controller.go` (lines 65–530)
|
||||
|
||||
### What it does
|
||||
The controller pattern is the central design pattern of Kubernetes. Every controller watches a set of resources, maintains a work queue, and reconciles desired state with actual state through a sync loop.
|
||||
|
||||
### Why
|
||||
Distributed systems can't guarantee that a single API call will bring the world to desired state. The controller pattern provides eventual consistency by continuously reconciling — it handles missed events, partial failures, and concurrent modifications.
|
||||
|
||||
### Structure
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:65-95
|
||||
type DeploymentController struct {
|
||||
rsControl controller.RSControlInterface
|
||||
client clientset.Interface
|
||||
|
||||
// Testability: sync handler is injectable
|
||||
syncHandler func(ctx context.Context, dKey string) error
|
||||
enqueueDeployment func(deployment *apps.Deployment)
|
||||
|
||||
// Listers: read from local cache, not API server
|
||||
dLister appslisters.DeploymentLister
|
||||
rsLister appslisters.ReplicaSetLister
|
||||
podLister corelisters.PodLister
|
||||
|
||||
// Synced funcs: gate processing until caches are warm
|
||||
dListerSynced cache.InformerSynced
|
||||
rsListerSynced cache.InformerSynced
|
||||
|
||||
// Work queue: rate-limited, deduplicating
|
||||
queue workqueue.TypedRateLimitingInterface[string]
|
||||
}
|
||||
```
|
||||
|
||||
### The Canonical Worker Loop
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:481-515
|
||||
func (dc *DeploymentController) worker(ctx context.Context) {
|
||||
for dc.processNextWorkItem(ctx) {
|
||||
}
|
||||
}
|
||||
|
||||
func (dc *DeploymentController) processNextWorkItem(ctx context.Context) bool {
|
||||
key, quit := dc.queue.Get()
|
||||
if quit {
|
||||
return false
|
||||
}
|
||||
defer dc.queue.Done(key)
|
||||
|
||||
err := dc.syncHandler(ctx, key)
|
||||
dc.handleErr(ctx, err, key)
|
||||
return true
|
||||
}
|
||||
|
||||
func (dc *DeploymentController) handleErr(ctx context.Context, err error, key string) {
|
||||
if err == nil || errors.HasStatusCause(err, v1.NamespaceTerminatingCause) {
|
||||
dc.queue.Forget(key) // Success: clear rate limiter
|
||||
return
|
||||
}
|
||||
if dc.queue.NumRequeues(key) < maxRetries {
|
||||
dc.queue.AddRateLimited(key) // Retry with backoff
|
||||
return
|
||||
}
|
||||
utilruntime.HandleError(err)
|
||||
dc.queue.Forget(key) // Give up after maxRetries
|
||||
}
|
||||
```
|
||||
|
||||
### Key Properties
|
||||
1. **Level-triggered, not edge-triggered** — the sync loop reads current state, not diffs
|
||||
2. **Idempotent** — running sync twice produces the same result
|
||||
3. **Key-based deduplication** — the workqueue coalesces multiple events for the same object
|
||||
4. **Bounded retries** — exponential backoff with a max retry count (15 retries = ~82s max delay)
|
||||
|
||||
---
|
||||
|
||||
## 2. Informer + Cache + Workqueue Combo
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/tools/cache/shared_informer.go` (lines 144–283), `staging/src/k8s.io/client-go/informers/factory.go` (lines 57–250)
|
||||
|
||||
### What it does
|
||||
The Informer provides a local read cache of API server state, backed by a List+Watch connection. The SharedInformerFactory ensures only one informer per resource type exists per process, preventing duplicate watches.
|
||||
|
||||
### Why
|
||||
- **Reduces API server load**: controllers read from local cache (Listers) instead of hitting the API
|
||||
- **Reduces latency**: events are delivered via callbacks, no polling
|
||||
- **Memory efficiency**: shared informers prevent N controllers from opening N watches
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
API Server
|
||||
│
|
||||
├── List (initial sync)
|
||||
│
|
||||
└── Watch (streaming updates)
|
||||
│
|
||||
▼
|
||||
SharedIndexInformer
|
||||
├── local Store (thread-safe cache)
|
||||
├── Indexer (secondary indexes)
|
||||
└── Event Handlers → [Controller1, Controller2, ...]
|
||||
│
|
||||
▼
|
||||
WorkQueue
|
||||
│
|
||||
▼
|
||||
worker goroutines
|
||||
```
|
||||
|
||||
### SharedInformerFactory Pattern
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/informers/factory.go:57-77
|
||||
type sharedInformerFactory struct {
|
||||
client kubernetes.Interface
|
||||
lock sync.Mutex
|
||||
informers map[reflect.Type]cache.SharedIndexInformer
|
||||
startedInformers map[reflect.Type]bool
|
||||
wg sync.WaitGroup
|
||||
shuttingDown bool
|
||||
}
|
||||
```
|
||||
|
||||
### Registration via Event Handlers
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:117-146
|
||||
dInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
|
||||
AddFunc: func(obj interface{}) { dc.addDeployment(logger, obj) },
|
||||
UpdateFunc: func(oldObj, newObj interface{}) { dc.updateDeployment(logger, oldObj, newObj) },
|
||||
DeleteFunc: func(obj interface{}) { dc.deleteDeployment(logger, obj) },
|
||||
})
|
||||
```
|
||||
|
||||
### Cache Sync Gate
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:189
|
||||
if !cache.WaitForNamedCacheSyncWithContext(ctx, dc.dListerSynced, dc.rsListerSynced, dc.podListerSynced) {
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Workqueue: Typed Rate-Limiting Queue
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/util/workqueue/queue.go` (lines 33–370), `rate_limiting_queue.go`
|
||||
|
||||
### What it does
|
||||
A concurrent-safe work queue with three critical properties:
|
||||
1. **Deduplication** (dirty set) — same item added twice results in one processing
|
||||
2. **Re-entrancy** (processing set) — if an item is added while being processed, it's re-queued after Done()
|
||||
3. **Rate limiting** — exponential backoff on failures
|
||||
|
||||
### Why
|
||||
In a controller, multiple events may fire for the same object in rapid succession. Without deduplication, you'd process stale intermediate states. The dirty/processing set design ensures you always process the latest state while never losing notifications.
|
||||
|
||||
### The Dirty/Processing Dance
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/util/workqueue/queue.go:227-252
|
||||
func (q *Typed[T]) Add(item T) {
|
||||
q.cond.L.Lock()
|
||||
defer q.cond.L.Unlock()
|
||||
if q.shuttingDown { return }
|
||||
if q.dirty.Has(item) {
|
||||
if !q.processing.Has(item) {
|
||||
q.queue.Touch(item) // Allow priority changes
|
||||
}
|
||||
return // Already marked for processing
|
||||
}
|
||||
q.dirty.Insert(item)
|
||||
if q.processing.Has(item) {
|
||||
return // Being processed, will re-queue on Done()
|
||||
}
|
||||
q.queue.Push(item)
|
||||
q.cond.Signal()
|
||||
}
|
||||
|
||||
func (q *Typed[T]) Done(item T) {
|
||||
q.cond.L.Lock()
|
||||
defer q.cond.L.Unlock()
|
||||
q.processing.Delete(item)
|
||||
if q.dirty.Has(item) {
|
||||
q.queue.Push(item) // Was modified during processing
|
||||
q.cond.Signal()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rate-Limited Requeue
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/util/workqueue/rate_limiting_queue.go:120-122
|
||||
func (q *rateLimitingType[T]) AddRateLimited(item T) {
|
||||
q.TypedDelayingInterface.AddAfter(item, q.rateLimiter.When(item))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Tombstone Pattern (DeletedFinalStateUnknown)
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/tools/cache/delta_fifo.go` (lines 797–801)
|
||||
|
||||
### What it does
|
||||
When a watch disconnects and reconnects, some delete events may be missed. The DeltaFIFO synthesizes a `DeletedFinalStateUnknown` ("tombstone") containing the last known state of the object.
|
||||
|
||||
### Why
|
||||
Without this, controllers would never learn about deletions that happened during disconnects.
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/tools/cache/delta_fifo.go:797-801
|
||||
type DeletedFinalStateUnknown struct {
|
||||
Key string
|
||||
Obj interface{}
|
||||
}
|
||||
```
|
||||
|
||||
### How controllers handle it
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:210-224
|
||||
func (dc *DeploymentController) deleteDeployment(logger klog.Logger, obj interface{}) {
|
||||
d, ok := obj.(*apps.Deployment)
|
||||
if !ok {
|
||||
tombstone, ok := obj.(cache.DeletedFinalStateUnknown)
|
||||
if !ok {
|
||||
utilruntime.HandleError(fmt.Errorf("couldn't get object from tombstone %#v", obj))
|
||||
return
|
||||
}
|
||||
d, ok = tombstone.Obj.(*apps.Deployment)
|
||||
if !ok {
|
||||
utilruntime.HandleError(fmt.Errorf("tombstone contained object that is not a Deployment %#v", obj))
|
||||
return
|
||||
}
|
||||
}
|
||||
dc.enqueueDeployment(d)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Controller Expectations Pattern
|
||||
|
||||
**Source:** `pkg/controller/controller_utils.go` (lines 130–315)
|
||||
|
||||
### What it does
|
||||
Expectations track pending creates/deletes to prevent controllers from taking action on stale cache state. A controller won't sync until its expectations are satisfied or expired.
|
||||
|
||||
### Why
|
||||
Between a controller issuing a create and the informer cache reflecting that new object, there's a window where the controller might create duplicates. Expectations close this gap.
|
||||
|
||||
```go
|
||||
// pkg/controller/controller_utils.go:153-173
|
||||
type ControllerExpectationsInterface interface {
|
||||
GetExpectations(controllerKey string) (*ControlleeExpectations, bool, error)
|
||||
SatisfiedExpectations(logger klog.Logger, controllerKey string) bool
|
||||
DeleteExpectations(logger klog.Logger, controllerKey string)
|
||||
SetExpectations(logger klog.Logger, controllerKey string, add, del int) error
|
||||
ExpectCreations(logger klog.Logger, controllerKey string, adds int) error
|
||||
ExpectDeletions(logger klog.Logger, controllerKey string, dels int) error
|
||||
CreationObserved(logger klog.Logger, controllerKey string)
|
||||
DeletionObserved(logger klog.Logger, controllerKey string)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. OwnerReference / Controller Ref Manager Pattern
|
||||
|
||||
**Source:** `pkg/controller/controller_ref_manager.go` (lines 37–80)
|
||||
|
||||
### What it does
|
||||
Implements garbage collection ownership through OwnerReferences. The ControllerRefManager handles adopting orphaned resources and releasing resources that no longer match.
|
||||
|
||||
### Why
|
||||
Multiple controllers may create children. The ownership model ensures exactly one controller owns each child, enabling garbage collection and preventing conflicts.
|
||||
|
||||
```go
|
||||
// pkg/controller/controller_ref_manager.go:37-50
|
||||
type BaseControllerRefManager struct {
|
||||
Controller metav1.Object
|
||||
Selector labels.Selector
|
||||
canAdoptErr error
|
||||
canAdoptOnce sync.Once // Lazy, one-shot adoption check
|
||||
CanAdoptFunc func(ctx context.Context) error
|
||||
}
|
||||
|
||||
// The claim logic: adopt if matching and orphaned, release if owned but not matching
|
||||
func (m *BaseControllerRefManager) ClaimObject(ctx context.Context, obj metav1.Object,
|
||||
match func(metav1.Object) bool,
|
||||
adopt, release func(context.Context, metav1.Object) error) (bool, error) {
|
||||
controllerRef := metav1.GetControllerOfNoCopy(obj)
|
||||
if controllerRef != nil {
|
||||
if controllerRef.UID != m.Controller.GetUID() {
|
||||
return false, nil // Owned by someone else
|
||||
}
|
||||
if match(obj) {
|
||||
return true, nil // Already ours and matches
|
||||
}
|
||||
// Ours but no longer matches → release
|
||||
}
|
||||
// Orphan → adopt if matches
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Leader Election Pattern
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/tools/leaderelection/leaderelection.go` (lines 116–230)
|
||||
|
||||
### What it does
|
||||
Provides distributed mutex semantics using a Kubernetes resource (Lease) as the lock. Only one instance of a controller runs actively; others are hot standbys.
|
||||
|
||||
### Why
|
||||
Controller-manager runs multiple replicas for HA. Only one should reconcile to avoid conflicts.
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/tools/leaderelection/leaderelection.go:116-163
|
||||
type LeaderElectionConfig struct {
|
||||
Lock rl.Interface
|
||||
LeaseDuration time.Duration // Default 15s — how long a lease is valid
|
||||
RenewDeadline time.Duration // Default 10s — how long leader retries renewal
|
||||
RetryPeriod time.Duration // Default 2s — how often candidates check
|
||||
Callbacks LeaderCallbacks
|
||||
ReleaseOnCancel bool
|
||||
}
|
||||
|
||||
type LeaderCallbacks struct {
|
||||
OnStartedLeading func(context.Context)
|
||||
OnStoppedLeading func()
|
||||
OnNewLeader func(identity string)
|
||||
}
|
||||
|
||||
// staging/src/k8s.io/client-go/tools/leaderelection/leaderelection.go:211-226
|
||||
func (le *LeaderElector) Run(ctx context.Context) {
|
||||
defer runtime.HandleCrashWithContext(ctx)
|
||||
defer le.config.Callbacks.OnStoppedLeading()
|
||||
if !le.acquire(ctx) {
|
||||
return
|
||||
}
|
||||
ctx, cancel := context.WithCancel(ctx)
|
||||
defer cancel()
|
||||
go le.config.Callbacks.OnStartedLeading(ctx)
|
||||
le.renew(ctx)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Feature Gates Pattern
|
||||
|
||||
**Source:** `pkg/features/kube_features.go` (lines 34–2811), `staging/src/k8s.io/client-go/features/features.go` (lines 34–80)
|
||||
|
||||
### What it does
|
||||
A global registry of boolean flags that control feature rollout. Features progress through Alpha → Beta → GA → Deprecated lifecycle stages.
|
||||
|
||||
### Why
|
||||
Kubernetes serves thousands of clusters. Features must be safe to enable/disable at runtime across versions. Feature gates provide:
|
||||
- Progressive rollout (alpha off by default, beta on, GA locked)
|
||||
- Per-version semantics (a feature may become beta in v1.28)
|
||||
- Testing isolation
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/features/features.go:50-70
|
||||
type Feature string
|
||||
|
||||
type FeatureSpec struct {
|
||||
Default bool
|
||||
LockToDefault bool
|
||||
PreRelease prerelease
|
||||
Version *version.Version
|
||||
}
|
||||
|
||||
type Gates interface {
|
||||
Enabled(key Feature) bool
|
||||
}
|
||||
|
||||
// pkg/features/kube_features.go:50-58 (example feature definition)
|
||||
const (
|
||||
AllowDNSOnlyNodeCSR featuregate.Feature = "AllowDNSOnlyNodeCSR"
|
||||
// ... 2700+ lines of feature definitions
|
||||
)
|
||||
```
|
||||
|
||||
### Registration at init()
|
||||
|
||||
```go
|
||||
// pkg/features/kube_features.go:2798-2811
|
||||
func init() {
|
||||
ca := &clientAdapter{utilfeature.DefaultMutableFeatureGate}
|
||||
runtime.Must(clientfeatures.AddVersionedFeaturesToExistingFeatureGates(ca))
|
||||
clientfeatures.ReplaceFeatureGates(ca)
|
||||
runtime.Must(utilfeature.DefaultMutableFeatureGate.AddVersioned(defaultVersionedKubernetesFeatureGates))
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,369 @@
|
||||
# Production Go Patterns (from Kubernetes)
|
||||
|
||||
Patterns for building large-scale Go codebases that go beyond what stdlib teaches you.
|
||||
|
||||
## 1. Code Generation Pattern
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/runtime/zz_generated.deepcopy.go`, `staging/src/k8s.io/client-go/informers/apps/v1/deployment.go`
|
||||
|
||||
### What it does
|
||||
Kubernetes generates massive amounts of boilerplate code from annotations on types:
|
||||
- `deepcopy-gen` → DeepCopy/DeepCopyInto methods
|
||||
- `informer-gen` → typed informers (List/Watch/Lister per resource)
|
||||
- `client-gen` → typed client sets
|
||||
- `lister-gen` → typed lister interfaces
|
||||
- `conversion-gen` → version conversion functions
|
||||
- `defaulter-gen` → defaulting functions
|
||||
|
||||
### Why
|
||||
At Kubernetes scale (~50 resource types × multiple versions), hand-writing deep copy, client wrappers, and conversion code is:
|
||||
1. Error-prone (forgetting to copy a new field breaks everything)
|
||||
2. Unmaintainable (thousands of nearly-identical files)
|
||||
3. Not verifiable by human review
|
||||
|
||||
### How it works
|
||||
|
||||
Annotations drive generation:
|
||||
```go
|
||||
// +k8s:deepcopy-gen=true
|
||||
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
|
||||
type RawExtension struct { ... }
|
||||
```
|
||||
|
||||
Generated output uses `zz_generated.` prefix (convention for "don't edit"):
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/runtime/zz_generated.deepcopy.go:22
|
||||
// Code generated by deepcopy-gen. DO NOT EDIT.
|
||||
package runtime
|
||||
|
||||
func (in *RawExtension) DeepCopyInto(out *RawExtension) {
|
||||
*out = *in
|
||||
if in.Raw != nil {
|
||||
in, out := &in.Raw, &out.Raw
|
||||
*out = make([]byte, len(*in))
|
||||
copy(*out, *in)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Generated informers (note the header comment):
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/informers/apps/v1/deployment.go:20
|
||||
// Code generated by informer-gen. DO NOT EDIT.
|
||||
```
|
||||
|
||||
### Key Insight
|
||||
**Stdlib has no code generation culture.** stdlib keeps things small enough that hand-writing works. Kubernetes proves that once you cross ~20 types with shared behavior, code gen is the only sane path.
|
||||
|
||||
---
|
||||
|
||||
## 2. The Scheme / Type Registry Pattern
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/runtime/scheme.go` (lines 38–100), `scheme_builder.go`
|
||||
|
||||
### What it does
|
||||
The Scheme is a runtime type registry that maps:
|
||||
- `GroupVersionKind` → Go type (`reflect.Type`)
|
||||
- Go type → `[]GroupVersionKind`
|
||||
- Provides serialization, defaulting, conversion, and validation dispatch
|
||||
|
||||
### Why
|
||||
Kubernetes has 50+ resource types across 15+ API groups, each with multiple versions. The Scheme provides:
|
||||
- **Dynamic dispatch**: serialize any Object without knowing its concrete type
|
||||
- **Version conversion**: convert between v1 and v1beta1 transparently
|
||||
- **Pluggability**: third-party resources register into the same system
|
||||
|
||||
### Structure
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/runtime/scheme.go:38-98
|
||||
type Scheme struct {
|
||||
gvkToType map[schema.GroupVersionKind]reflect.Type
|
||||
typeToGVK map[reflect.Type][]schema.GroupVersionKind
|
||||
unversionedTypes map[reflect.Type]schema.GroupVersionKind
|
||||
defaulterFuncs map[reflect.Type]func(interface{})
|
||||
validationFuncs map[reflect.Type]func(ctx, op, obj, oldObj) field.ErrorList
|
||||
converter *conversion.Converter
|
||||
versionPriority map[string][]string
|
||||
}
|
||||
```
|
||||
|
||||
### SchemeBuilder Pattern
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/runtime/scheme_builder.go:23-48
|
||||
type SchemeBuilder []func(*Scheme) error
|
||||
|
||||
func (sb *SchemeBuilder) AddToScheme(s *Scheme) error {
|
||||
for _, f := range *sb {
|
||||
if err := f(s); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (sb *SchemeBuilder) Register(funcs ...func(*Scheme) error) {
|
||||
*sb = append(*sb, f)
|
||||
}
|
||||
```
|
||||
|
||||
### How Registration Works
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/runtime/scheme.go:151-160
|
||||
func (s *Scheme) AddKnownTypes(gv schema.GroupVersion, types ...Object) {
|
||||
for _, obj := range types {
|
||||
t := reflect.TypeOf(obj)
|
||||
if t.Kind() != reflect.Pointer {
|
||||
panic("All types must be pointers to structs.")
|
||||
}
|
||||
t = t.Elem()
|
||||
s.AddKnownTypeWithName(gv.WithKind(t.Name()), obj)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Insight
|
||||
This is Java's ServiceLoader / dependency injection adapted for Go's type system. Stdlib uses interfaces; Kubernetes needs a **runtime type system on top of Go's static type system** because API objects must be dynamically dispatched across version boundaries.
|
||||
|
||||
---
|
||||
|
||||
## 3. The runtime.Object Interface
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/runtime/interfaces.go` (lines 333–342)
|
||||
|
||||
### What it does
|
||||
Every Kubernetes API object must implement this two-method interface:
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/runtime/interfaces.go:337-341
|
||||
type Object interface {
|
||||
GetObjectKind() schema.ObjectKind
|
||||
DeepCopyObject() Object
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
- `GetObjectKind()` — allows the serialization layer to determine what type an object is without reflection
|
||||
- `DeepCopyObject()` — enables safe concurrent access (informer cache is shared; mutations must happen on copies)
|
||||
|
||||
### Key Insight
|
||||
**This is the foundation of Kubernetes' extensibility.** Any Go struct that satisfies these two methods can participate in the entire API machinery — serialization, storage, admission, informers, etc. CRDs generate code that implements this interface.
|
||||
|
||||
---
|
||||
|
||||
## 4. Deep Copy Everywhere
|
||||
|
||||
**Source:** Generated code in `zz_generated.deepcopy.go` files throughout the tree
|
||||
|
||||
### What it does
|
||||
Every API type has generated `DeepCopy()` and `DeepCopyInto()` methods that create true deep copies including nested slices, maps, and pointer fields.
|
||||
|
||||
### Why
|
||||
The informer cache is shared across all controllers in a process. If controller A gets an object from the cache and mutates it, controller B would see corrupted data. Deep copy provides the isolation guarantee.
|
||||
|
||||
```go
|
||||
// Usage pattern in controllers:
|
||||
deployment := deploymentFromCache.DeepCopy()
|
||||
deployment.Spec.Replicas = ptr.To[int32](3)
|
||||
_, err := client.AppsV1().Deployments(ns).Update(ctx, deployment, metav1.UpdateOptions{})
|
||||
```
|
||||
|
||||
### Key Insight
|
||||
Stdlib rarely needs deep copy because stdlib objects are typically owned by one goroutine. Kubernetes has a **shared read cache** (the informer store) that necessitates copy-on-write semantics at the application level.
|
||||
|
||||
---
|
||||
|
||||
## 5. Graceful Shutdown with Priority Classes
|
||||
|
||||
**Source:** `pkg/kubelet/nodeshutdown/nodeshutdown_manager_linux.go` (lines 23–100)
|
||||
|
||||
### What it does
|
||||
When a node is shutting down, pods are terminated in priority order. Critical pods (system-node-critical) get more grace time than regular pods.
|
||||
|
||||
### Why
|
||||
A hard kill of all pods simultaneously would lose important work. Priority-based graceful shutdown preserves the most important workloads longest.
|
||||
|
||||
```go
|
||||
// pkg/kubelet/nodeshutdown/nodeshutdown_manager_linux.go:66-90
|
||||
type managerImpl struct {
|
||||
logger klog.Logger
|
||||
recorder record.EventRecorder
|
||||
getPods eviction.ActivePodsFunc
|
||||
syncNodeStatus func(context.Context)
|
||||
dbusCon dbusInhibiter
|
||||
inhibitLock systemd.InhibitLock
|
||||
nodeShuttingDownMutex sync.Mutex
|
||||
nodeShuttingDownNow bool
|
||||
podManager *podManager
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Context as Logger Carrier
|
||||
|
||||
**Source:** `pkg/controller/deployment/deployment_controller.go` (lines 106, 179, 500)
|
||||
|
||||
### What it does
|
||||
Kubernetes passes structured loggers through context:
|
||||
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:179
|
||||
logger := klog.FromContext(ctx)
|
||||
logger.Info("Starting controller", "controller", "deployment")
|
||||
```
|
||||
|
||||
### Why
|
||||
At scale, you need structured logging with:
|
||||
- Consistent key-value pairs (controller name, object reference)
|
||||
- Verbosity levels (`logger.V(4).Info(...)`)
|
||||
- No global state (context carries the logger configured by the caller)
|
||||
|
||||
### Key Insight
|
||||
Stdlib's `log` package is global. Kubernetes uses context-based structured logging (`klog.FromContext`) to allow each call chain to carry its own logger configuration. This enables filtering by controller, verbosity tuning per-component, and correlation.
|
||||
|
||||
---
|
||||
|
||||
## 7. Functional Options for Configuration
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/informers/factory.go` (lines 83–127)
|
||||
|
||||
### What it does
|
||||
The SharedInformerFactory uses functional options for configuration:
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/client-go/informers/factory.go:57
|
||||
type SharedInformerOption func(*sharedInformerFactory) *sharedInformerFactory
|
||||
|
||||
func WithNamespace(namespace string) SharedInformerOption {
|
||||
return func(factory *sharedInformerFactory) *sharedInformerFactory {
|
||||
factory.namespace = namespace
|
||||
return factory
|
||||
}
|
||||
}
|
||||
|
||||
func WithTransform(transform cache.TransformFunc) SharedInformerOption {
|
||||
return func(factory *sharedInformerFactory) *sharedInformerFactory {
|
||||
factory.transform = transform
|
||||
return factory
|
||||
}
|
||||
}
|
||||
|
||||
func NewSharedInformerFactoryWithOptions(client kubernetes.Interface, defaultResync time.Duration, options ...SharedInformerOption) SharedInformerFactory {
|
||||
factory := &sharedInformerFactory{...}
|
||||
for _, opt := range options {
|
||||
factory = opt(factory)
|
||||
}
|
||||
return factory
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
APIs evolve. Adding a new configuration option shouldn't break callers. Functional options provide:
|
||||
- Backward compatibility (new options don't change existing signatures)
|
||||
- Self-documenting (each option is a named function)
|
||||
- Composability (options can be collected and applied conditionally)
|
||||
|
||||
---
|
||||
|
||||
## 8. Type-Safe Generics in Critical Paths
|
||||
|
||||
**Source:** `staging/src/k8s.io/client-go/util/workqueue/queue.go` (lines 33–200), `staging/src/k8s.io/client-go/gentype/type.go` (lines 33–120)
|
||||
|
||||
### What it does
|
||||
Both workqueue and gentype use Go generics (1.18+) to provide type-safe interfaces while maintaining backward compatibility via type aliases:
|
||||
|
||||
```go
|
||||
// Workqueue: type-safe queue
|
||||
type TypedInterface[T comparable] interface {
|
||||
Add(item T)
|
||||
Get() (item T, shutdown bool)
|
||||
Done(item T)
|
||||
}
|
||||
|
||||
// Type alias for backward compat
|
||||
type Type = Typed[any]
|
||||
|
||||
// Gentype: type-safe client
|
||||
type Client[T objectWithMeta] struct {
|
||||
resource string
|
||||
client rest.Interface
|
||||
namespace string
|
||||
newObject func() T
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
Before generics, Kubernetes used `interface{}` everywhere, requiring type assertions at every boundary. Generics eliminate entire classes of runtime panics and make the code self-documenting.
|
||||
|
||||
### Key Insight
|
||||
This is a migration pattern: introduce the generic version alongside the deprecated `interface{}` version using type aliases. Callers migrate at their own pace.
|
||||
|
||||
---
|
||||
|
||||
## 9. HandleCrash — Structured Panic Recovery
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go` (lines 30–120)
|
||||
|
||||
### What it does
|
||||
A standardized `defer HandleCrash()` pattern that:
|
||||
1. Catches panics
|
||||
2. Logs them with proper stack attribution
|
||||
3. Invokes registered panic handlers
|
||||
4. Optionally re-panics (controlled by `ReallyCrash` flag)
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go:78-82
|
||||
func HandleCrashWithContext(ctx context.Context, additionalHandlers ...func(context.Context, interface{})) {
|
||||
if r := recover(); r != nil {
|
||||
handleCrash(ctx, r, additionalHandlers...)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
In a production system with hundreds of goroutines, an unrecovered panic in one kills the entire process. HandleCrash provides a standardized recovery point that:
|
||||
- Logs the panic with caller attribution
|
||||
- Allows cleanup handlers (shutdown gracefully)
|
||||
- In tests, can be configured to not actually crash
|
||||
|
||||
### Key Insight
|
||||
Stdlib's approach is "let it crash." Kubernetes' approach is "catch it, log it, let the controller retry on the next sync." This is only safe because the controller pattern is idempotent.
|
||||
|
||||
---
|
||||
|
||||
## 10. ContextForChannel — Bridge Pattern
|
||||
|
||||
**Source:** `staging/src/k8s.io/apimachinery/pkg/util/wait/wait.go` (lines 120–145)
|
||||
|
||||
### What it does
|
||||
Bridges the older `<-chan struct{}` stop pattern to the modern `context.Context` pattern:
|
||||
|
||||
```go
|
||||
// staging/src/k8s.io/apimachinery/pkg/util/wait/wait.go:120-142
|
||||
func ContextForChannel(parentCh <-chan struct{}) context.Context {
|
||||
return channelContext{stopCh: parentCh}
|
||||
}
|
||||
|
||||
type channelContext struct {
|
||||
stopCh <-chan struct{}
|
||||
}
|
||||
|
||||
func (c channelContext) Done() <-chan struct{} { return c.stopCh }
|
||||
func (c channelContext) Err() error {
|
||||
select {
|
||||
case <-c.stopCh:
|
||||
return context.Canceled
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
Kubernetes predates `context.Context` (which arrived in Go 1.7). Millions of lines of code use `stopCh <-chan struct{}`. Rather than a big-bang rewrite, this adapter allows gradual migration.
|
||||
|
||||
### Key Insight
|
||||
**Large codebases can't do breaking API changes atomically.** This bridge pattern is how you evolve from one idiom to another over years without breaking everything at once.
|
||||
@@ -0,0 +1,374 @@
|
||||
# API Conventions in the Go Standard Library
|
||||
|
||||
## 1. The Must Pattern
|
||||
|
||||
**Pattern name:** MustXxx (Panic on Error)
|
||||
|
||||
**Source citation:** `regexp/regexp.go` lines 310–320, `text/template/helper.go` lines 19–30
|
||||
|
||||
**What it does:** A function wraps a fallible constructor and panics if the error
|
||||
is non-nil. Named `MustXxx` or `Must` (when wrapping a generic `(T, error)` pair).
|
||||
|
||||
**Why:** Safe initialization of package-level variables at program startup. Since
|
||||
`var` initializers can't handle errors, `Must` converts programmer errors (bad
|
||||
regex literals, bad templates) into immediate panics that surface during init.
|
||||
|
||||
**Anti-pattern:** Using Must in runtime code where the input is dynamic/user-provided;
|
||||
panicking on recoverable errors; naming it something other than Must (e.g., `PanicOnError`).
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// regexp/regexp.go:310-320
|
||||
// MustCompile is like [Compile] but panics if the expression cannot be parsed.
|
||||
// It simplifies safe initialization of global variables holding compiled regular
|
||||
// expressions.
|
||||
func MustCompile(str string) *Regexp {
|
||||
regexp, err := Compile(str)
|
||||
if err != nil {
|
||||
panic(`regexp: Compile(` + quote(str) + `): ` + err.Error())
|
||||
}
|
||||
return regexp
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// text/template/helper.go:19-30
|
||||
// Must is a helper that wraps a call to a function returning ([*Template], error)
|
||||
// and panics if the error is non-nil. It is intended for use in variable
|
||||
// initializations such as
|
||||
//
|
||||
// var t = template.Must(template.New("name").Parse("text"))
|
||||
func Must(t *Template, err error) *Template {
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return t
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Compile / MustCompile Pair
|
||||
|
||||
**Pattern name:** Fallible Constructor + Must Wrapper
|
||||
|
||||
**Source citation:** `regexp/regexp.go` lines 130–131, 310–320
|
||||
|
||||
**What it does:** The real constructor returns `(*T, error)`. A parallel `Must` variant
|
||||
wraps it for use in global variable initialization.
|
||||
|
||||
**Why:** Separates concerns: `Compile` is for runtime use where errors are handled;
|
||||
`MustCompile` is for compile-time-known values where failure is a programming bug.
|
||||
|
||||
**Anti-pattern:** Only providing the Must variant (no way to handle errors gracefully);
|
||||
only providing the error variant (verbose for package-level vars).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// regexp/regexp.go:130-131
|
||||
func Compile(expr string) (*Regexp, error) {
|
||||
return compile(expr, syntax.Perl, false)
|
||||
}
|
||||
|
||||
// regexp/regexp.go:310-315
|
||||
func MustCompile(str string) *Regexp {
|
||||
regexp, err := Compile(str)
|
||||
if err != nil {
|
||||
panic(`regexp: Compile(` + quote(str) + `): ` + err.Error())
|
||||
}
|
||||
return regexp
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. XxxWithContext Variant
|
||||
|
||||
**Pattern name:** WithContext Function Overload
|
||||
|
||||
**Source citation:** `net/http/request.go` lines 867–869, 894–930
|
||||
|
||||
**What it does:** Provides two function variants: `NewRequest` (uses `context.Background()`)
|
||||
and `NewRequestWithContext` (accepts an explicit context). The simple version delegates
|
||||
to the context-aware one.
|
||||
|
||||
**Why:** Context was added after the original API was established. The `WithContext`
|
||||
variant enables cancellation and deadlines; the plain variant preserves backward
|
||||
compatibility and ergonomics for the common case.
|
||||
|
||||
**Anti-pattern:** Breaking the existing API signature; always requiring context even
|
||||
for fire-and-forget uses; naming it `NewRequestCtx`.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/request.go:867-869
|
||||
func NewRequest(method, url string, body io.Reader) (*Request, error) {
|
||||
return NewRequestWithContext(context.Background(), method, url, body)
|
||||
}
|
||||
|
||||
// net/http/request.go:894+
|
||||
func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error) {
|
||||
// full implementation...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Nil-Opts Convention (Optional Config Pointer)
|
||||
|
||||
**Pattern name:** `*Options` Parameter — Nil Means Defaults
|
||||
|
||||
**Source citation:** `log/slog/text_handler.go` lines 28–42, `log/slog/handler.go` lines 135–175
|
||||
|
||||
**What it does:** A constructor accepts a pointer to an options struct. If the pointer
|
||||
is nil, all defaults apply. The constructor internally substitutes a zero-value struct.
|
||||
|
||||
**Why:** Keeps the simple case clean (`NewTextHandler(os.Stderr, nil)`) while allowing
|
||||
full customization. The pointer type signals "this entire argument is optional."
|
||||
|
||||
**Anti-pattern:** Requiring a non-nil options struct even with zero customization;
|
||||
using variadic functional options when a simple struct suffices.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// log/slog/text_handler.go:28-42
|
||||
// NewTextHandler creates a [TextHandler] that writes to w,
|
||||
// using the given options.
|
||||
// If opts is nil, the default options are used.
|
||||
func NewTextHandler(w io.Writer, opts *HandlerOptions) *TextHandler {
|
||||
if opts == nil {
|
||||
opts = &HandlerOptions{}
|
||||
}
|
||||
return &TextHandler{
|
||||
&commonHandler{
|
||||
json: false,
|
||||
w: w,
|
||||
opts: *opts,
|
||||
mu: &sync.Mutex{},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Builder Pattern (Accumulate + Finalize)
|
||||
|
||||
**Pattern name:** Builder (Write Methods + String/Bytes Finalizer)
|
||||
|
||||
**Source citation:** `strings/builder.go` lines 14–113
|
||||
|
||||
**What it does:** A zero-value struct accumulates data via Write/WriteByte/WriteString
|
||||
methods, then produces a final result via String(). The builder is not reusable after
|
||||
a copyCheck-protected modification.
|
||||
|
||||
**Why:** Avoids repeated string concatenation (O(n²) allocations). The zero value is
|
||||
ready to use. Implements `io.Writer` so it integrates with `fmt.Fprintf`, etc.
|
||||
|
||||
**Anti-pattern:** Allocating on every append; requiring explicit initialization;
|
||||
not implementing standard interfaces (`io.Writer`).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// strings/builder.go:14-16
|
||||
// A Builder is used to efficiently build a string using [Builder.Write] methods.
|
||||
// It minimizes memory copying. The zero value is ready to use.
|
||||
// Do not copy a non-zero Builder.
|
||||
type Builder struct {
|
||||
addr *Builder
|
||||
buf []byte
|
||||
}
|
||||
|
||||
// strings/builder.go:92-96
|
||||
func (b *Builder) WriteString(s string) (int, error) {
|
||||
b.copyCheck()
|
||||
b.buf = append(b.buf, s...)
|
||||
return len(s), nil
|
||||
}
|
||||
|
||||
// strings/builder.go:48-50
|
||||
func (b *Builder) String() string {
|
||||
return unsafe.String(unsafe.SliceData(b.buf), len(b.buf))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Layered API (Convenience → Full Control)
|
||||
|
||||
**Pattern name:** Convenience Wrappers over Configurable Core
|
||||
|
||||
**Source citation:** `os/file.go` lines 385–415
|
||||
|
||||
**What it does:** Simple functions (`Open`, `Create`) delegate to the fully configurable
|
||||
`OpenFile` with pre-set flags. Users choose their level of control.
|
||||
|
||||
**Why:** 90% of file opens are reads or creates. Layered APIs serve the common case
|
||||
without hiding power. The naming makes intent clear.
|
||||
|
||||
**Anti-pattern:** Only exposing the full-power version; making users learn flag
|
||||
constants for simple reads; duplicating implementation across convenience functions.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// os/file.go:389-393
|
||||
// Open opens the named file for reading.
|
||||
func Open(name string) (*File, error) {
|
||||
return OpenFile(name, O_RDONLY, 0)
|
||||
}
|
||||
|
||||
// os/file.go:399-403
|
||||
// Create creates or truncates the named file.
|
||||
func Create(name string) (*File, error) {
|
||||
return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
|
||||
}
|
||||
|
||||
// os/file.go:410+ (the general form)
|
||||
func OpenFile(name string, flag int, perm FileMode) (*File, error) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Package-Level Functions Delegating to DefaultXxx
|
||||
|
||||
**Pattern name:** Convenience Package Functions
|
||||
|
||||
**Source citation:** `net/http/client.go` line 109, implied by `http.Get`, `http.Post`
|
||||
|
||||
**What it does:** Top-level functions like `http.Get(url)` call methods on the
|
||||
`DefaultClient`. Users can bypass by creating their own `Client`.
|
||||
|
||||
**Why:** Makes the simple case trivial (one-liner HTTP requests). No import of
|
||||
constructors or setup needed. The package "just works" for basic usage.
|
||||
|
||||
**Anti-pattern:** Not providing convenience functions (forcing explicit construction
|
||||
even for prototyping); making the default's behavior non-obvious.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/client.go:109
|
||||
var DefaultClient = &Client{}
|
||||
|
||||
// net/http/client.go (implied pattern):
|
||||
// func Get(url string) (resp *Response, err error) {
|
||||
// return DefaultClient.Get(url)
|
||||
// }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Register Pattern (Pluggable Algorithms)
|
||||
|
||||
**Pattern name:** RegisterXxx for Side-Effect Imports
|
||||
|
||||
**Source citation:** `crypto/crypto.go` lines 145–150
|
||||
|
||||
**What it does:** A `RegisterHash(h Hash, f func() hash.Hash)` function allows
|
||||
algorithm implementations in sub-packages to register themselves via `init()`.
|
||||
The main package dispatches based on the registered factories.
|
||||
|
||||
**Why:** Decouples the algorithm registry from specific implementations. Users import
|
||||
only the algorithms they need (e.g., `_ "crypto/sha256"`). Reduces binary size and
|
||||
avoids circular dependencies.
|
||||
|
||||
**Anti-pattern:** Hard-coding all implementations; requiring explicit constructor calls
|
||||
for each algorithm; using global mutable state without clear ownership.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// crypto/crypto.go:145-150
|
||||
func RegisterHash(h Hash, f func() hash.Hash) {
|
||||
if h == 0 || h >= maxHash {
|
||||
panic("crypto: RegisterHash of unknown hash function")
|
||||
}
|
||||
hashes[h] = f
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Graceful Shutdown Pattern
|
||||
|
||||
**Pattern name:** Close vs Shutdown (Immediate vs Graceful)
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 3171–3220 (Close), 3221+ (Shutdown)
|
||||
|
||||
**What it does:** Provides both `Close()` (immediate, forceful) and `Shutdown(ctx)`
|
||||
(graceful, waits for in-flight requests). The context on Shutdown provides a
|
||||
timeout mechanism.
|
||||
|
||||
**Why:** Different operational scenarios need different termination semantics.
|
||||
Graceful shutdown is critical for production services; immediate close is needed for
|
||||
tests and emergency stops.
|
||||
|
||||
**Anti-pattern:** Only providing one shutdown mode; not accepting a context for
|
||||
timeout control; leaking goroutines on shutdown.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:3171-3175
|
||||
func (s *Server) Close() error {
|
||||
s.inShutdown.Store(true)
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
err := s.closeListenersLocked()
|
||||
// ... forcefully closes all active connections
|
||||
}
|
||||
|
||||
// net/http/server.go:3221+
|
||||
// Shutdown gracefully shuts down the server without interrupting any
|
||||
// active connections.
|
||||
func (s *Server) Shutdown(ctx context.Context) error {
|
||||
s.inShutdown.Store(true)
|
||||
// ... closes listeners, waits for idle, respects ctx deadline
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Channel-Based Timer/Ticker API
|
||||
|
||||
**Pattern name:** NewXxx Returning Channel-Bearing Struct
|
||||
|
||||
**Source citation:** `time/tick.go` lines 16–45, `time/sleep.go` lines 89–155
|
||||
|
||||
**What it does:** `NewTicker(d)` and `NewTimer(d)` return structs with a `C <-chan Time`
|
||||
field. Consumers select on the channel to receive time events.
|
||||
|
||||
**Why:** Integrates time-based events with Go's concurrency primitives (select).
|
||||
The channel-based API composes naturally with other goroutine patterns.
|
||||
|
||||
**Anti-pattern:** Callback-based timer APIs that don't compose with select; exposing
|
||||
the send side of the channel; not documenting goroutine safety.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// time/tick.go:16-18
|
||||
type Ticker struct {
|
||||
C <-chan Time // The channel on which the ticks are delivered.
|
||||
initTicker bool
|
||||
}
|
||||
|
||||
// time/tick.go:36-45
|
||||
func NewTicker(d Duration) *Ticker {
|
||||
if d <= 0 {
|
||||
panic("non-positive interval for NewTicker")
|
||||
}
|
||||
c := make(chan Time, 1)
|
||||
t := (*Ticker)(unsafe.Pointer(newTimer(when(d), int64(d), sendTime, c, syncTimer(c))))
|
||||
t.C = c
|
||||
return t
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,342 @@
|
||||
# Documentation Patterns in the Go Standard Library
|
||||
|
||||
## 1. Package Documentation (doc.go or Package Comment)
|
||||
|
||||
**Pattern name:** Package Doc Comment
|
||||
|
||||
**Source citation:** `net/http/doc.go` lines 6–30, `os/file.go` lines 5–43, `log/slog/doc.go` lines 6–30
|
||||
|
||||
**What it does:** The first file in a package (by convention `doc.go`, or the main
|
||||
source file) starts with a `// Package xxx ...` comment that explains the package's
|
||||
purpose, key types, and typical usage patterns.
|
||||
|
||||
**Why:** This is the first thing users see in `go doc <pkg>` and on pkg.go.dev. It
|
||||
sets context, teaches the mental model, and provides copy-paste examples.
|
||||
|
||||
**Anti-pattern:** No package comment; package comment that just restates the package
|
||||
name ("Package http provides http"); putting documentation in README instead of code.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/doc.go:6-12
|
||||
/*
|
||||
Package http provides HTTP client and server implementations.
|
||||
|
||||
[Get], [Head], [Post], and [PostForm] make HTTP (or HTTPS) requests:
|
||||
|
||||
resp, err := http.Get("http://example.com/")
|
||||
...
|
||||
*/
|
||||
```
|
||||
|
||||
```go
|
||||
// os/file.go:5-43
|
||||
// Package os provides a platform-independent interface to operating system
|
||||
// functionality. The design is Unix-like, although the error handling is
|
||||
// Go-like; failing calls return values of type error rather than error numbers.
|
||||
// Often, more information is available within the error. For example,
|
||||
// if a call that takes a file name fails, such as [Open] or [Stat], the error
|
||||
// will include the failing file name when printed and will be of type
|
||||
// [*PathError], which may be unpacked for more information.
|
||||
```
|
||||
|
||||
```go
|
||||
// log/slog/doc.go:6-10
|
||||
/*
|
||||
Package slog provides structured logging,
|
||||
in which log records include a message,
|
||||
a severity level, and various other attributes
|
||||
expressed as key-value pairs.
|
||||
*/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Section Headers in Package Docs
|
||||
|
||||
**Pattern name:** `# Heading` in Doc Comments
|
||||
|
||||
**Source citation:** `os/file.go` lines 37–43, `net/http/doc.go` (multiple sections)
|
||||
|
||||
**What it does:** Uses `# Section Name` within the package doc comment to organize
|
||||
long documentation into navigable sections.
|
||||
|
||||
**Why:** Large packages need structure. Section headers render as links in pkg.go.dev
|
||||
and provide a scannable table of contents.
|
||||
|
||||
**Anti-pattern:** Wall-of-text package docs; using `===` or `---` (not recognized);
|
||||
too many sections (fragmenting simple docs).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// os/file.go:37
|
||||
// # Concurrency
|
||||
//
|
||||
// The methods of [File] correspond to file system operations. All are
|
||||
// safe for concurrent use.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Type/Function Comment Convention
|
||||
|
||||
**Pattern name:** `// TypeName verb...` or `// FuncName verb...`
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 64–82 (Handler), `bufio/scan.go` lines 14–27 (Scanner)
|
||||
|
||||
**What it does:** Every exported identifier's doc comment starts with the identifier
|
||||
name, followed by a verb phrase describing what it does or represents.
|
||||
|
||||
**Why:** `go doc` extracts the first sentence as a summary. Starting with the name
|
||||
ensures it reads correctly in both isolation (summary lists) and full context.
|
||||
This is enforced by convention and checked by linters.
|
||||
|
||||
**Anti-pattern:** Starting with "This function..." or "The Foo type..."; starting
|
||||
with articles ("A Handler is...") for functions (acceptable for types); omitting
|
||||
the comment entirely.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:64
|
||||
// A Handler responds to an HTTP request.
|
||||
|
||||
// bufio/scan.go:14-17
|
||||
// Scanner provides a convenient interface for reading data such as
|
||||
// a file of newline-delimited lines of text.
|
||||
|
||||
// net/http/request.go:867
|
||||
// NewRequest wraps NewRequestWithContext using context.Background.
|
||||
|
||||
// os/file.go:389-390
|
||||
// Open opens the named file for reading.
|
||||
|
||||
// regexp/regexp.go:310-312
|
||||
// MustCompile is like [Compile] but panics if the expression cannot be parsed.
|
||||
// It simplifies safe initialization of global variables holding compiled regular
|
||||
// expressions.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Doc Links (Square Bracket References)
|
||||
|
||||
**Pattern name:** `[TypeName]`, `[Package.Symbol]`, `[Method]` Links
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 65–70, `os/file.go` line 9
|
||||
|
||||
**What it does:** Doc comments use `[SymbolName]` to create hyperlinks to other
|
||||
identifiers. These render as clickable links on pkg.go.dev.
|
||||
|
||||
**Why:** Cross-references help users navigate the API. Links are concise and
|
||||
don't clutter the plain-text rendering.
|
||||
|
||||
**Anti-pattern:** Using full URLs to godoc pages; not linking related types;
|
||||
over-linking (every mention of every type).
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:65-70
|
||||
// [Handler.ServeHTTP] should write reply headers and data to the [ResponseWriter]
|
||||
// and then return. Returning signals that the request is finished; it
|
||||
// is not valid to use the [ResponseWriter] or read from the
|
||||
// [Request.Body] after or concurrently with the completion of the
|
||||
// ServeHTTP call.
|
||||
|
||||
// os/file.go:9-11
|
||||
// if a call that takes a file name fails, such as [Open] or [Stat], the error
|
||||
// will include the failing file name when printed and will be of type
|
||||
// [*PathError], which may be unpacked for more information.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Example Test Functions
|
||||
|
||||
**Pattern name:** `func ExampleXxx()` / `func ExampleType_Method()`
|
||||
|
||||
**Source citation:** `regexp/example_test.go` lines 13–28, `net/http/example_handle_test.go` lines 16–31
|
||||
|
||||
**What it does:** Functions named `Example`, `ExampleXxx`, or `ExampleType_Method`
|
||||
in `_test.go` files serve as both executable tests and documentation. They include
|
||||
an `// Output:` comment that `go test` verifies.
|
||||
|
||||
**Why:** Examples that compile, run, and are verified can never go stale. They appear
|
||||
in `go doc` and pkg.go.dev alongside the relevant symbol. They teach by showing
|
||||
real, working code.
|
||||
|
||||
**Anti-pattern:** Examples that don't compile; examples without Output comments
|
||||
(not verified); examples in README that drift from reality.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// regexp/example_test.go:13-28
|
||||
func Example() {
|
||||
// Compile the expression once, usually at init time.
|
||||
// Use raw strings to avoid having to quote the backslashes.
|
||||
var validID = regexp.MustCompile(`^[a-z]+\[[0-9]+\]$`)
|
||||
|
||||
fmt.Println(validID.MatchString("adam[23]"))
|
||||
fmt.Println(validID.MatchString("eve[7]"))
|
||||
fmt.Println(validID.MatchString("Job[48]"))
|
||||
fmt.Println(validID.MatchString("snakey"))
|
||||
// Output:
|
||||
// true
|
||||
// true
|
||||
// false
|
||||
// false
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// net/http/example_handle_test.go:16-31
|
||||
type countHandler struct {
|
||||
mu sync.Mutex // guards n
|
||||
n int
|
||||
}
|
||||
|
||||
func (h *countHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
h.n++
|
||||
fmt.Fprintf(w, "count is %d\n", h.n)
|
||||
}
|
||||
|
||||
func ExampleHandle() {
|
||||
http.Handle("/count", new(countHandler))
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Inline Code Examples in Doc Comments
|
||||
|
||||
**Pattern name:** Indented Code Blocks in Comments
|
||||
|
||||
**Source citation:** `os/file.go` lines 17–35, `time/time.go` lines 928–933
|
||||
|
||||
**What it does:** Doc comments include indented code snippets (4 spaces) that render
|
||||
as preformatted code blocks in godoc.
|
||||
|
||||
**Why:** Shows typical usage patterns directly in the doc comment without requiring
|
||||
a separate Example test function. Good for short, illustrative snippets.
|
||||
|
||||
**Anti-pattern:** Non-indented code that doesn't render as code; examples too long
|
||||
for inline (use Example functions instead); examples that reference unexported symbols.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// os/file.go:17-21
|
||||
// Here is a simple example, opening a file and reading some of it.
|
||||
//
|
||||
// file, err := os.Open("file.go") // For read access.
|
||||
// if err != nil {
|
||||
// log.Fatal(err)
|
||||
// }
|
||||
|
||||
// time/time.go:928-933
|
||||
// To count the number of units in a [Duration], divide:
|
||||
//
|
||||
// second := time.Second
|
||||
// fmt.Print(int64(second/time.Millisecond)) // prints 1000
|
||||
//
|
||||
// To convert an integer number of units to a Duration, multiply:
|
||||
//
|
||||
// seconds := 10
|
||||
// fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Deprecated Annotations
|
||||
|
||||
**Pattern name:** `// Deprecated: ...` in Doc Comments
|
||||
|
||||
**Source citation:** `net/http/server.go` line 57 (ErrWriteAfterFlush), `os/file.go` lines 93–95
|
||||
|
||||
**What it does:** A paragraph starting with `Deprecated:` marks an identifier as
|
||||
deprecated and explains what to use instead.
|
||||
|
||||
**Why:** Recognized by tooling (go vet, staticcheck, IDEs). Provides a migration
|
||||
path without breaking backward compatibility.
|
||||
|
||||
**Anti-pattern:** Removing deprecated APIs (breaks semver); deprecating without
|
||||
suggesting an alternative; using non-standard deprecation markers.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:55-57
|
||||
// Deprecated: ErrWriteAfterFlush is no longer returned by
|
||||
// anything in the net/http package. Callers should not
|
||||
// compare errors against this variable.
|
||||
ErrWriteAfterFlush = errors.New("unused")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Documentation Convention
|
||||
|
||||
**Pattern name:** "If there is an error, it will be of type [*XxxError]"
|
||||
|
||||
**Source citation:** `os/file.go` lines 388, 406
|
||||
|
||||
**What it does:** Functions document the concrete error type they return, enabling
|
||||
callers to type-assert for additional context.
|
||||
|
||||
**Why:** Go's error handling relies on type assertions and `errors.Is/As`. Knowing
|
||||
the concrete type lets callers extract structured information (path, operation,
|
||||
underlying cause).
|
||||
|
||||
**Anti-pattern:** Returning opaque errors with no documented structure; returning
|
||||
different error types from the same function without documenting which.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// os/file.go:388-390
|
||||
// Open opens the named file for reading. If successful, methods on
|
||||
// the returned file can be used for reading; the associated file
|
||||
// descriptor has mode [O_RDONLY].
|
||||
// If there is an error, it will be of type [*PathError].
|
||||
func Open(name string) (*File, error) {
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Concurrency Documentation
|
||||
|
||||
**Pattern name:** "Safe for concurrent use" / Concurrency Guarantees
|
||||
|
||||
**Source citation:** `net/http/transport.go` lines 79–80, `os/types.go` line 17, `regexp/regexp.go` lines 77–79
|
||||
|
||||
**What it does:** Doc comments explicitly state the concurrency safety of a type
|
||||
or note exceptions where concurrent use is not safe.
|
||||
|
||||
**Why:** Go programs are inherently concurrent. Without explicit documentation,
|
||||
users must guess whether a type needs external synchronization.
|
||||
|
||||
**Anti-pattern:** Leaving concurrency safety undocumented; documenting it
|
||||
inconsistently across methods; saying "thread-safe" (Java-ism, use "safe for
|
||||
concurrent use by multiple goroutines").
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/transport.go:79-80
|
||||
// Transports should be reused instead of created as needed.
|
||||
// Transports are safe for concurrent use by multiple goroutines.
|
||||
|
||||
// os/types.go:17
|
||||
// The methods of File are safe for concurrent use.
|
||||
|
||||
// regexp/regexp.go:77-79
|
||||
// A Regexp is safe for concurrent use by multiple goroutines,
|
||||
// except for configuration methods, such as [Regexp.Longest].
|
||||
```
|
||||
@@ -0,0 +1,390 @@
|
||||
# Go Interface Design Patterns
|
||||
|
||||
Patterns extracted from the Go standard library source code.
|
||||
|
||||
---
|
||||
|
||||
## 1. Small Interfaces (1-2 Methods)
|
||||
|
||||
### Source: `src/io/io.go:80-92` (Reader), `93-103` (Writer), `105-109` (Closer)
|
||||
|
||||
Go's most powerful interfaces have exactly **one method**:
|
||||
|
||||
```go
|
||||
// src/io/io.go:80-92
|
||||
type Reader interface {
|
||||
Read(p []byte) (n int, err error)
|
||||
}
|
||||
|
||||
// src/io/io.go:93-103
|
||||
type Writer interface {
|
||||
Write(p []byte) (n int, err error)
|
||||
}
|
||||
|
||||
// src/io/io.go:105-109
|
||||
type Closer interface {
|
||||
Close() error
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
Small interfaces are easy to implement and easy to compose. Any type can satisfy `io.Reader` by implementing a single method. This maximizes the number of types that can participate in the ecosystem — files, network connections, buffers, compressors, encryptors all satisfy `Reader`.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Giant interface that tries to cover everything
|
||||
type FileSystem interface {
|
||||
Open(name string) (File, error)
|
||||
Create(name string) (File, error)
|
||||
Remove(name string) error
|
||||
Stat(name string) (FileInfo, error)
|
||||
ReadDir(name string) ([]DirEntry, error)
|
||||
MkdirAll(path string, perm FileMode) error
|
||||
// ... 10 more methods
|
||||
}
|
||||
```
|
||||
|
||||
Large interfaces are hard to implement, hard to mock, and couple consumers to capabilities they don't need.
|
||||
|
||||
---
|
||||
|
||||
## 2. Interface Composition
|
||||
|
||||
### Source: `src/io/io.go:131-155`
|
||||
|
||||
Compose small interfaces into larger ones only when needed:
|
||||
|
||||
```go
|
||||
// src/io/io.go:131-134
|
||||
type ReadWriter interface {
|
||||
Reader
|
||||
Writer
|
||||
}
|
||||
|
||||
// src/io/io.go:136-139
|
||||
type ReadCloser interface {
|
||||
Reader
|
||||
Closer
|
||||
}
|
||||
|
||||
// src/io/io.go:141-144
|
||||
type WriteCloser interface {
|
||||
Writer
|
||||
Closer
|
||||
}
|
||||
|
||||
// src/io/io.go:146-150
|
||||
type ReadWriteCloser interface {
|
||||
Reader
|
||||
Writer
|
||||
Closer
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
Composition lets you express precisely what you need. A function that only reads should accept `Reader`, not `ReadWriteCloser`. Callers provide the minimum; composers build up.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Define a big interface, then use only part of it
|
||||
func processData(rw ReadWriteCloser) {
|
||||
// only calls Read... why require Write and Close?
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Accept Interfaces, Return Structs
|
||||
|
||||
### Source: `src/io/io.go:461` (LimitReader), `src/io/io.go:618` (TeeReader)
|
||||
|
||||
```go
|
||||
// src/io/io.go:461
|
||||
func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
|
||||
|
||||
// src/io/io.go:467-471
|
||||
type LimitedReader struct {
|
||||
R Reader // underlying reader
|
||||
N int64 // max bytes remaining
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// src/io/io.go:618-620
|
||||
func TeeReader(r Reader, w Writer) Reader {
|
||||
return &teeReader{r, w}
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
- **Accept interfaces**: Maximizes what callers can pass in — any `Reader` works.
|
||||
- **Return structs** (or concrete types): Gives callers access to the full type, including fields and methods not in any interface. `LimitedReader` exposes `R` and `N` publicly so callers can inspect remaining bytes.
|
||||
|
||||
The return type of `LimitReader` is `Reader` (interface), but the underlying value is `*LimitedReader` (struct). Functions like `io.Copy` can type-assert to `*LimitedReader` to optimize buffer sizes (line 425).
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Accept concrete types
|
||||
func LimitReader(r *os.File, n int64) Reader // too restrictive
|
||||
|
||||
// DON'T: Return interfaces when you have useful struct fields
|
||||
func NewServer() ServerInterface // hides useful config fields
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Interface Satisfaction as a Compile-Time Check
|
||||
|
||||
### Source: `src/io/io.go:645`, `src/net/http/server.go:4071`
|
||||
|
||||
```go
|
||||
// src/io/io.go:645
|
||||
var _ ReaderFrom = discard{}
|
||||
|
||||
// src/net/http/server.go:4071
|
||||
var _ Pusher = (*timeoutWriter)(nil)
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
These blank-identifier declarations cause a compile error if the type stops implementing the interface. They're documentation and safety net combined — no runtime cost.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Discover interface failures at runtime
|
||||
func doSomething(w ResponseWriter) {
|
||||
pusher := w.(Pusher) // panics if w doesn't implement Pusher
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Interface-Based Polymorphism (sort.Interface)
|
||||
|
||||
### Source: `src/sort/sort.go:16-41`
|
||||
|
||||
```go
|
||||
// src/sort/sort.go:16-41
|
||||
type Interface interface {
|
||||
Len() int
|
||||
Less(i, j int) bool
|
||||
Swap(i, j int)
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
The sort package defines *behavior* it needs, not data it operates on. Any collection — slices, linked lists, database result sets — can be sorted by implementing three methods. The algorithm is decoupled from the data structure.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Hardcode to a specific data type
|
||||
func Sort(data []int) // only works for []int
|
||||
func Sort(data []interface{}) // loses type safety
|
||||
```
|
||||
|
||||
Note: Since Go 1.21, `slices.SortFunc` is preferred for slices (generic + faster), but `sort.Interface` remains the pattern for non-slice collections.
|
||||
|
||||
---
|
||||
|
||||
## 6. The Adapter Pattern (HandlerFunc)
|
||||
|
||||
### Source: `src/net/http/server.go:2334-2342`
|
||||
|
||||
```go
|
||||
// src/net/http/server.go:2334-2338
|
||||
// The HandlerFunc type is an adapter to allow the use of
|
||||
// ordinary functions as HTTP handlers. If f is a function
|
||||
// with the appropriate signature, HandlerFunc(f) is a
|
||||
// Handler that calls f.
|
||||
type HandlerFunc func(ResponseWriter, *Request)
|
||||
|
||||
// src/net/http/server.go:2341-2342
|
||||
// ServeHTTP calls f(w, r).
|
||||
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
|
||||
f(w, r)
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
This bridges functions and interfaces. Any function with the right signature becomes a `Handler` via `HandlerFunc(myFunc)`. You get the simplicity of functions with the composability of interfaces.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Force users to create a struct just to implement an interface
|
||||
type myHandler struct{}
|
||||
func (h myHandler) ServeHTTP(w ResponseWriter, r *Request) {
|
||||
// just calls a function anyway
|
||||
handleHome(w, r)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Optional Interfaces (Runtime Feature Detection)
|
||||
|
||||
### Source: `src/net/http/server.go:165-175` (Flusher), `src/net/http/server.go:183-206` (Hijacker)
|
||||
|
||||
```go
|
||||
// src/net/http/server.go:165-170
|
||||
type Flusher interface {
|
||||
Flush()
|
||||
}
|
||||
|
||||
// src/net/http/server.go:183-206
|
||||
type Hijacker interface {
|
||||
Hijack() (net.Conn, *bufio.ReadWriter, error)
|
||||
}
|
||||
```
|
||||
|
||||
Usage pattern (from doc comments):
|
||||
```go
|
||||
// Handlers should always test for this ability at runtime.
|
||||
if flusher, ok := w.(Flusher); ok {
|
||||
flusher.Flush()
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
Not every `ResponseWriter` supports flushing or hijacking (HTTP/2 doesn't support Hijacker). Instead of bloating the main interface, optional capabilities are separate interfaces checked at runtime. This keeps the core interface small while allowing progressive enhancement.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Put optional capabilities in the main interface
|
||||
type ResponseWriter interface {
|
||||
Write([]byte) (int, error)
|
||||
WriteHeader(int)
|
||||
Header() Header
|
||||
Flush() // not always supported!
|
||||
Hijack() (net.Conn, *bufio.ReadWriter, error) // not always supported!
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. The Stringer Interface (Convention-Based Behavior)
|
||||
|
||||
### Source: `src/fmt/print.go:63-66`
|
||||
|
||||
```go
|
||||
// src/fmt/print.go:63-66
|
||||
type Stringer interface {
|
||||
String() string
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
`fmt` checks if a value implements `Stringer` and calls `String()` for its text representation. This is a *convention*: any type in any package can participate without importing `fmt`. The interface acts as a protocol.
|
||||
|
||||
Similarly, `GoStringer` (line 71) controls `%#v` output, and `Formatter` (line 58-61) gives total control over formatting.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Use type switches over known types
|
||||
func printThing(v any) string {
|
||||
switch v := v.(type) {
|
||||
case MyType: return v.name
|
||||
case OtherType: return v.label
|
||||
// ... must know about every type
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Interface Upgrade Pattern (WriterTo/ReaderFrom in io.Copy)
|
||||
|
||||
### Source: `src/io/io.go:410-417`
|
||||
|
||||
```go
|
||||
// src/io/io.go:410-417
|
||||
func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
|
||||
// If the reader has a WriteTo method, use it to do the copy.
|
||||
// Avoids an allocation and a copy.
|
||||
if wt, ok := src.(WriterTo); ok {
|
||||
return wt.WriteTo(dst)
|
||||
}
|
||||
// Similarly, if the writer has a ReadFrom method, use it to do the copy.
|
||||
if rf, ok := dst.(ReaderFrom); ok {
|
||||
return rf.ReadFrom(src)
|
||||
}
|
||||
// ... fallback to buffer-based copy
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
The core function works with the minimum interface (`Reader`/`Writer`) but *upgrades* behavior when richer interfaces are available. `*os.File` implements `ReadFrom` using `sendfile(2)` — zero-copy kernel transfer. The generic path works, but specialized implementations optimize transparently.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: Always use the slow generic path
|
||||
func Copy(dst Writer, src Reader) {
|
||||
buf := make([]byte, 32*1024)
|
||||
// always allocates, never leverages kernel optimizations
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. The driver.Driver Pattern (Plugin Interfaces)
|
||||
|
||||
### Source: `src/database/sql/driver/driver.go:85-97`, `104-112`
|
||||
|
||||
```go
|
||||
// src/database/sql/driver/driver.go:85-97
|
||||
type Driver interface {
|
||||
Open(name string) (Conn, error)
|
||||
}
|
||||
|
||||
// src/database/sql/driver/driver.go:104-112
|
||||
type DriverContext interface {
|
||||
OpenConnector(name string) (Connector, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Why
|
||||
|
||||
The `database/sql` package defines interfaces that driver authors implement. The base interface (`Driver`) is minimal (one method). Extended capabilities (`DriverContext`, `Pinger`, `Execer`, `Queryer`) are opt-in — the `sql` package checks for them at runtime. This allows the ecosystem to grow without breaking existing drivers.
|
||||
|
||||
### Anti-pattern
|
||||
|
||||
```go
|
||||
// DON'T: One massive interface all drivers must implement
|
||||
type Driver interface {
|
||||
Open(name string) (Conn, error)
|
||||
OpenConnector(name string) (Connector, error)
|
||||
Ping(ctx context.Context) error
|
||||
// ... every driver must implement everything, even if not supported
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary: Go Interface Design Principles
|
||||
|
||||
| Principle | Standard Library Example |
|
||||
|-----------|------------------------|
|
||||
| Keep interfaces small (1-2 methods) | `io.Reader`, `io.Writer`, `fmt.Stringer` |
|
||||
| Compose small interfaces | `io.ReadWriteCloser` |
|
||||
| Accept interfaces, return structs | `io.LimitReader`, `io.TeeReader` |
|
||||
| Use adapter types for functions | `http.HandlerFunc` |
|
||||
| Optional capabilities via separate interfaces | `http.Flusher`, `http.Hijacker` |
|
||||
| Compile-time interface checks | `var _ Interface = (*Type)(nil)` |
|
||||
| Runtime interface upgrade for optimization | `io.Copy` → `WriterTo`/`ReaderFrom` |
|
||||
| Plugin/driver interfaces start minimal | `database/sql/driver.Driver` |
|
||||
@@ -0,0 +1,404 @@
|
||||
# Struct Design Patterns in the Go Standard Library
|
||||
|
||||
## 1. Zero-Value Usability
|
||||
|
||||
**Pattern name:** Zero Value Ready
|
||||
|
||||
**Source citation:** `net/http/client.go` lines 31–35, `strings/builder.go` lines 14–16
|
||||
|
||||
**What it does:** Structs are designed so their zero value is immediately useful without
|
||||
explicit initialization. Nil fields fall back to sensible defaults at method call time.
|
||||
|
||||
**Why:** Eliminates mandatory constructors, reduces boilerplate, makes the type
|
||||
self-documenting about its defaults. Users can write `var c http.Client` and start
|
||||
making requests.
|
||||
|
||||
**Anti-pattern:** Requiring a constructor for basic use; panicking on zero-value use;
|
||||
requiring all fields be set before the type is functional.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/client.go:31-35
|
||||
// A Client is an HTTP client. Its zero value ([DefaultClient]) is a
|
||||
// usable client that uses [DefaultTransport].
|
||||
type Client struct {
|
||||
Transport RoundTripper // If nil, DefaultTransport is used.
|
||||
// ...
|
||||
}
|
||||
|
||||
// net/http/client.go:109
|
||||
var DefaultClient = &Client{}
|
||||
```
|
||||
|
||||
```go
|
||||
// strings/builder.go:14-16
|
||||
// A Builder is used to efficiently build a string using [Builder.Write] methods.
|
||||
// It minimizes memory copying. The zero value is ready to use.
|
||||
// Do not copy a non-zero Builder.
|
||||
type Builder struct {
|
||||
addr *Builder
|
||||
buf []byte
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// bytes/buffer.go:19-20
|
||||
// A Buffer is a variable-sized buffer of bytes with [Buffer.Read] and [Buffer.Write] methods.
|
||||
// The zero value for Buffer is an empty buffer ready to use.
|
||||
type Buffer struct {
|
||||
buf []byte
|
||||
off int
|
||||
lastRead readOp
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Unexported Struct with Exported Wrapper
|
||||
|
||||
**Pattern name:** Indirection via Unexported Impl
|
||||
|
||||
**Source citation:** `os/types.go` lines 16–20, `os/file_unix.go` lines 59–71
|
||||
|
||||
**What it does:** The exported type (`File`) embeds a pointer to an unexported type
|
||||
(`*file`) that holds the real implementation state. Users interact only with the
|
||||
exported wrapper.
|
||||
|
||||
**Why:** Prevents users from directly constructing or copying the implementation struct.
|
||||
Allows platform-specific implementations behind a uniform exported API. The extra
|
||||
indirection ensures finalizers close the correct descriptor.
|
||||
|
||||
**Anti-pattern:** Exporting all implementation fields; allowing users to construct
|
||||
the struct via a literal (bypassing invariants); needing platform #ifdefs in the
|
||||
public API.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// os/types.go:16-20
|
||||
// File represents an open file descriptor.
|
||||
//
|
||||
// The methods of File are safe for concurrent use.
|
||||
type File struct {
|
||||
*file // os specific
|
||||
}
|
||||
|
||||
// os/file_unix.go:59-71
|
||||
// file is the real representation of *File.
|
||||
// The extra level of indirection ensures that no clients of os
|
||||
// can overwrite this data, which could cause the finalizer
|
||||
// to close the wrong file descriptor.
|
||||
type file struct {
|
||||
pfd poll.FD
|
||||
name string
|
||||
dirinfo atomic.Pointer[dirInfo]
|
||||
nonblock bool
|
||||
stdoutOrErr bool
|
||||
appendMode bool
|
||||
inRoot bool
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Constructor Functions (NewXxx)
|
||||
|
||||
**Pattern name:** NewXxx Constructor
|
||||
|
||||
**Source citation:** `bufio/scan.go` lines 89–96, `bufio/bufio.go` lines 50–60
|
||||
|
||||
**What it does:** A package-level function `NewXxx(deps) *Xxx` constructs the type
|
||||
with required dependencies and internal defaults that can't be expressed via zero
|
||||
value alone.
|
||||
|
||||
**Why:** When a type has mandatory dependencies (e.g., an `io.Reader`), a constructor
|
||||
clearly communicates what's required. The constructor can set internal invariants
|
||||
(buffer sizes, split functions) that users shouldn't need to know about.
|
||||
|
||||
**Anti-pattern:** Forcing users to manually set unexported fields; having a constructor
|
||||
that takes 10 optional parameters (use config struct instead); requiring New when
|
||||
zero value would suffice.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// bufio/scan.go:89-96
|
||||
func NewScanner(r io.Reader) *Scanner {
|
||||
return &Scanner{
|
||||
r: r,
|
||||
split: ScanLines,
|
||||
maxTokenSize: MaxScanTokenSize,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// bufio/bufio.go:50-62
|
||||
func NewReaderSize(rd io.Reader, size int) *Reader {
|
||||
// Is it already a Reader?
|
||||
b, ok := rd.(*Reader)
|
||||
if ok && len(b.buf) >= size {
|
||||
return b
|
||||
}
|
||||
r := new(Reader)
|
||||
r.reset(make([]byte, max(size, minReadBufferSize)), rd)
|
||||
return r
|
||||
}
|
||||
|
||||
// NewReader returns a new [Reader] whose buffer has the default size.
|
||||
func NewReader(rd io.Reader) *Reader {
|
||||
return NewReaderSize(rd, defaultBufSize)
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// net/http/request.go:867-869
|
||||
func NewRequest(method, url string, body io.Reader) (*Request, error) {
|
||||
return NewRequestWithContext(context.Background(), method, url, body)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. NewXxx with Size/Options Variant
|
||||
|
||||
**Pattern name:** NewXxx / NewXxxSize Pair
|
||||
|
||||
**Source citation:** `bufio/bufio.go` lines 50, 62, 589, 607
|
||||
|
||||
**What it does:** Provides two constructors — one with defaults (`NewReader`) and one
|
||||
with explicit configuration (`NewReaderSize`). The default version calls the
|
||||
configurable one.
|
||||
|
||||
**Why:** Most users want the default; power users need control. Layering avoids a
|
||||
proliferation of constructor parameters for the common case.
|
||||
|
||||
**Anti-pattern:** Having only the complex constructor; making users guess the right
|
||||
buffer size; inconsistent naming (e.g., `NewReaderWithSize`).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// bufio/bufio.go:589-607
|
||||
func NewWriterSize(w io.Writer, size int) *Writer {
|
||||
// ...
|
||||
}
|
||||
|
||||
func NewWriter(w io.Writer) *Writer {
|
||||
return NewWriterSize(w, defaultBufSize)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Config Struct Pattern
|
||||
|
||||
**Pattern name:** Configuration Struct (Exported Fields, Nil-Means-Default)
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 3020–3120, `crypto/tls/common.go` lines 566+, `log/slog/handler.go` lines 135–175
|
||||
|
||||
**What it does:** A struct with exported, documented fields provides all
|
||||
configuration knobs. Nil/zero values always mean "use the default".
|
||||
|
||||
**Why:** Self-documenting via godoc; no need for a setter method per option; easy to
|
||||
construct partially; serializable; the zero value works. This is Go's primary
|
||||
configuration pattern (preferred over functional options in the stdlib).
|
||||
|
||||
**Anti-pattern:** Undocumented fields; requiring all fields set; using sentinel values
|
||||
other than zero/nil for defaults; providing setters when direct assignment works.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:3020-3075 (abbreviated)
|
||||
type Server struct {
|
||||
Addr string // ":http" if empty
|
||||
Handler Handler // http.DefaultServeMux if nil
|
||||
TLSConfig *tls.Config // optional
|
||||
ReadTimeout time.Duration // zero means no timeout
|
||||
WriteTimeout time.Duration // zero means no timeout
|
||||
MaxHeaderBytes int // DefaultMaxHeaderBytes if zero
|
||||
ErrorLog *log.Logger // log.Default() if nil
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// log/slog/handler.go:135-175
|
||||
type HandlerOptions struct {
|
||||
AddSource bool
|
||||
Level Leveler // LevelInfo if nil
|
||||
ReplaceAttr func(groups []string, a Attr) Attr
|
||||
}
|
||||
|
||||
// Usage: If opts is nil, the default options are used.
|
||||
func NewTextHandler(w io.Writer, opts *HandlerOptions) *TextHandler {
|
||||
if opts == nil {
|
||||
opts = &HandlerOptions{}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Interface-Based Pluggability
|
||||
|
||||
**Pattern name:** Interface Abstraction for Pluggable Implementations
|
||||
|
||||
**Source citation:** `crypto/crypto.go` lines 180–200, `net/http/transport.go` lines 66–82
|
||||
|
||||
**What it does:** Core behavior is defined via an interface. The package provides
|
||||
a default concrete implementation, but any user type satisfying the interface
|
||||
can be substituted.
|
||||
|
||||
**Why:** Decouples high-level logic from low-level implementation. Enables testing
|
||||
(mock transports), hardware integration (HSM-backed signers), and third-party
|
||||
extensions without forking the package.
|
||||
|
||||
**Anti-pattern:** Concrete-type coupling everywhere; interfaces with too many methods
|
||||
(hard to implement); accepting an interface but only ever using one implementation.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// crypto/crypto.go:180-200
|
||||
// Signer is an interface for an opaque private key that can be used for
|
||||
// signing operations. For example, an RSA key kept in a hardware module.
|
||||
type Signer interface {
|
||||
Public() PublicKey
|
||||
Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error)
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// net/http/transport.go (line 66+)
|
||||
// Transport is an implementation of [RoundTripper] that supports HTTP,
|
||||
// HTTPS, and HTTP proxies...
|
||||
// Transports should be reused instead of created as needed.
|
||||
// Transports are safe for concurrent use by multiple goroutines.
|
||||
|
||||
// net/http/client.go:59-60
|
||||
type Client struct {
|
||||
Transport RoundTripper // If nil, DefaultTransport is used.
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Copy Protection via Dynamic Check
|
||||
|
||||
**Pattern name:** copyCheck (Runtime Copy Detection)
|
||||
|
||||
**Source citation:** `strings/builder.go` lines 25–40
|
||||
|
||||
**What it does:** On first mutation, the Builder records its own address. Subsequent
|
||||
mutations compare the current receiver address against the recorded one. If they
|
||||
differ, the struct was copied — it panics.
|
||||
|
||||
**Why:** Go has no language-level move semantics. For types where copying after first
|
||||
use would cause data corruption or unsafe behavior (e.g., sharing an unsafe string
|
||||
buffer), a runtime check is the pragmatic solution.
|
||||
|
||||
**Anti-pattern:** Silently allowing copies that corrupt state; using `sync.Mutex`-style
|
||||
`noCopy` (vet catches it but it doesn't work for zero vs non-zero discrimination).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// strings/builder.go:25-40
|
||||
func (b *Builder) copyCheck() {
|
||||
if b.addr == nil {
|
||||
b.addr = (*Builder)(abi.NoEscape(unsafe.Pointer(b)))
|
||||
} else if b.addr != b {
|
||||
panic("strings: illegal use of non-zero Builder copied by value")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. DefaultXxx Singleton
|
||||
|
||||
**Pattern name:** Package-Level Default Instance
|
||||
|
||||
**Source citation:** `net/http/client.go` line 109, `net/http/transport.go` lines 47–58
|
||||
|
||||
**What it does:** The package provides a pre-configured, ready-to-use instance as
|
||||
a package-level variable. Package-level convenience functions delegate to it.
|
||||
|
||||
**Why:** Makes the simple case trivial (`http.Get(url)`) while allowing custom
|
||||
instances for advanced use. Users never need to touch the defaults unless they
|
||||
have specific requirements.
|
||||
|
||||
**Anti-pattern:** Forcing construction for basic use; not providing convenience
|
||||
functions; making the default mutable in ways that affect all users.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/client.go:108-109
|
||||
// DefaultClient is the default [Client] and is used by [Get], [Head], and [Post].
|
||||
var DefaultClient = &Client{}
|
||||
|
||||
// net/http/transport.go:47-58
|
||||
var DefaultTransport RoundTripper = &Transport{
|
||||
Proxy: ProxyFromEnvironment,
|
||||
DialContext: defaultTransportDialContext(&net.Dialer{
|
||||
Timeout: 30 * time.Second,
|
||||
KeepAlive: 30 * time.Second,
|
||||
}),
|
||||
ForceAttemptHTTP2: true,
|
||||
MaxIdleConns: 100,
|
||||
IdleConnTimeout: 90 * time.Second,
|
||||
TLSHandshakeTimeout: 10 * time.Second,
|
||||
ExpectContinueTimeout: 1 * time.Second,
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Functional Configuration via Method Chaining (Scanner Pattern)
|
||||
|
||||
**Pattern name:** Post-Construction Configuration via Methods
|
||||
|
||||
**Source citation:** `bufio/scan.go` lines 275–293
|
||||
|
||||
**What it does:** After construction with `NewScanner`, optional configuration is
|
||||
applied via methods (`Split`, `Buffer`) before the first call to `Scan`.
|
||||
|
||||
**Why:** Keeps the constructor minimal (only the required `io.Reader`). Optional
|
||||
configuration is discoverable via methods. Panics if called after scanning starts
|
||||
(enforcing a construction → configure → use lifecycle).
|
||||
|
||||
**Anti-pattern:** Trying to pass all options into the constructor; allowing
|
||||
configuration changes mid-use that corrupt state.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// bufio/scan.go:275-293
|
||||
// Buffer sets the initial buffer to use when scanning
|
||||
// and the maximum size of buffer that may be allocated during scanning.
|
||||
// ...
|
||||
// Buffer panics if it is called after scanning has started.
|
||||
func (s *Scanner) Buffer(buf []byte, max int) {
|
||||
if s.scanCalled {
|
||||
panic("Buffer called after Scan")
|
||||
}
|
||||
s.buf = buf
|
||||
s.maxTokenSize = max
|
||||
}
|
||||
|
||||
// Split sets the split function for the [Scanner].
|
||||
// ...
|
||||
// Split panics if it is called after scanning has started.
|
||||
func (s *Scanner) Split(split SplitFunc) {
|
||||
if s.scanCalled {
|
||||
panic("Split called after Scan")
|
||||
}
|
||||
s.split = split
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,464 @@
|
||||
# Code Style Patterns in the Go Standard Library
|
||||
|
||||
## 1. Naming Conventions: mixedCaps (No Underscores)
|
||||
|
||||
**Pattern name:** mixedCaps / MixedCaps
|
||||
|
||||
**Source citation:** All stdlib code (enforced by `gofmt` convention, documented in Effective Go)
|
||||
|
||||
**What it does:** All identifiers use mixedCaps (unexported) or MixedCaps (exported).
|
||||
Underscores are never used in Go names except for test helpers and generated code.
|
||||
|
||||
**Why:** Consistent casing makes code scannable. The exported/unexported distinction
|
||||
is communicated solely through initial capitalization — no separate `public`/`private`
|
||||
keywords needed.
|
||||
|
||||
**Anti-pattern:** `snake_case` names; `ALL_CAPS` for constants; Hungarian notation
|
||||
(`strName`, `iCount`).
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go — exported
|
||||
type Server struct { ... }
|
||||
func ListenAndServe(addr string, handler Handler) error
|
||||
|
||||
// net/http/server.go — unexported
|
||||
func (s *Server) shuttingDown() bool
|
||||
const shutdownPollIntervalMax = 500 * time.Millisecond
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Acronyms Are All-Caps
|
||||
|
||||
**Pattern name:** Acronym Capitalization
|
||||
|
||||
**Source citation:** `net/http/request.go` line 130 (`URL`), `net/http/server.go` line 3041 (`TLSConfig`), `encoding/json/stream.go` line 280 (`JSON`)
|
||||
|
||||
**What it does:** Acronyms and initialisms (URL, HTTP, ID, JSON, XML, HTML, TLS, TCP)
|
||||
are always fully capitalized when exported, and fully lowercased when unexported.
|
||||
|
||||
**Why:** Consistency. `URL` not `Url`, `ID` not `Id`, `HTTP` not `Http`. This
|
||||
applies even mid-word: `ServeHTTP`, `xmlEncoder`, `htmlEscape`.
|
||||
|
||||
**Anti-pattern:** `Url`, `Http`, `Json`, `Id` — mixing cases within an acronym.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/request.go:130
|
||||
URL *url.URL
|
||||
|
||||
// net/http/request.go:822
|
||||
func ParseHTTPVersion(vers string) (major, minor int, ok bool)
|
||||
|
||||
// net/http/server.go:3041
|
||||
TLSConfig *tls.Config
|
||||
|
||||
// encoding/json/stream.go:280
|
||||
var _ Marshaler = (*RawMessage)(nil)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. File Organization by Responsibility
|
||||
|
||||
**Pattern name:** One Concept Per File
|
||||
|
||||
**Source citation:** `net/http/` directory structure
|
||||
|
||||
**What it does:** Large packages split code into files by topic/type: `client.go`,
|
||||
`server.go`, `transport.go`, `request.go`, `response.go`, `cookie.go`, `header.go`,
|
||||
`fs.go`, `doc.go`. Each file is focused.
|
||||
|
||||
**Why:** Navigability. When you want to find client logic, you open `client.go`.
|
||||
Files stay manageable sizes. Related code lives together.
|
||||
|
||||
**Anti-pattern:** One giant file with everything; splitting by access level
|
||||
(`public.go` / `private.go`); splitting by method count rather than concept.
|
||||
|
||||
**File layout from `net/http/`:**
|
||||
|
||||
```
|
||||
client.go — Client type and methods
|
||||
transport.go — Transport type (low-level RoundTripper)
|
||||
server.go — Server, Handler, ServeMux
|
||||
request.go — Request type and parsing
|
||||
response.go — Response type and reading
|
||||
cookie.go — Cookie parsing and serialization
|
||||
header.go — Header type and canonicalization
|
||||
fs.go — FileServer, file serving
|
||||
doc.go — Package documentation
|
||||
clone.go — Clone helpers
|
||||
method.go — HTTP method constants
|
||||
pattern.go — URL pattern matching (ServeMux routing)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Blank Identifier for Interface Compliance
|
||||
|
||||
**Pattern name:** `var _ Interface = (*Type)(nil)`
|
||||
|
||||
**Source citation:** `io/io.go` line 645, `os/file.go` lines 747–750, `encoding/json/stream.go` lines 280–281
|
||||
|
||||
**What it does:** A package-level `var _ InterfaceName = (*ConcreteType)(nil)` declares
|
||||
that the concrete type must satisfy the interface. The compiler verifies this at
|
||||
build time.
|
||||
|
||||
**Why:** Catches interface drift at compile time without creating an instance. The
|
||||
blank identifier discards the value — this is purely a static assertion.
|
||||
|
||||
**Anti-pattern:** Relying on tests to catch interface conformance; skipping the check
|
||||
and discovering the mismatch at runtime; using reflection.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// io/io.go:645
|
||||
var _ ReaderFrom = discard{}
|
||||
|
||||
// os/file.go:747-750
|
||||
var _ fs.StatFS = dirFS("")
|
||||
var _ fs.ReadFileFS = dirFS("")
|
||||
var _ fs.ReadDirFS = dirFS("")
|
||||
var _ fs.ReadLinkFS = dirFS("")
|
||||
|
||||
// encoding/json/stream.go:280-281
|
||||
var _ Marshaler = (*RawMessage)(nil)
|
||||
var _ Unmarshaler = (*RawMessage)(nil)
|
||||
|
||||
// net/http/server.go:4071
|
||||
var _ Pusher = (*timeoutWriter)(nil)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Named Return Values
|
||||
|
||||
**Pattern name:** Named Returns for Documentation (and Defer)
|
||||
|
||||
**Source citation:** `io/io.go` lines 87, 100, 314, 387; `os/file.go` lines 140, 175
|
||||
|
||||
**What it does:** Return values are given names when the names add documentary value
|
||||
(clarifying which int is what) or when `defer` needs to modify the return value.
|
||||
|
||||
**Why:** `(n int, err error)` is immediately understandable — `n` is the byte count.
|
||||
Named returns also enable `defer func() { err = wrap(err) }()` patterns.
|
||||
|
||||
**Anti-pattern:** Naming returns for trivial functions where the types are
|
||||
self-explanatory; using named returns as implicit variables throughout the function
|
||||
body (confusing naked returns); always using naked `return` statements.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// io/io.go:87 — Interface documentation
|
||||
type Reader interface {
|
||||
Read(p []byte) (n int, err error)
|
||||
}
|
||||
|
||||
// io/io.go:100
|
||||
type Writer interface {
|
||||
Write(p []byte) (n int, err error)
|
||||
}
|
||||
|
||||
// io/io.go:387 — Named return used with defer-style logic
|
||||
func Copy(dst Writer, src Reader) (written int64, err error) {
|
||||
return copyBuffer(dst, src, nil)
|
||||
}
|
||||
|
||||
// os/file.go:140 — Named return for readability
|
||||
func (f *File) Read(b []byte) (n int, err error) {
|
||||
if err := f.checkValid("read"); err != nil {
|
||||
return 0, err
|
||||
}
|
||||
n, e := f.read(b)
|
||||
return n, f.wrapErr("read", e)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Defer for Resource Cleanup
|
||||
|
||||
**Pattern name:** `defer mu.Unlock()` / `defer f.Close()`
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 3173–3174, `net/http/example_handle_test.go` lines 21–22
|
||||
|
||||
**What it does:** Resources acquired at the top of a scope are immediately deferred
|
||||
for cleanup. Mutexes are locked then immediately `defer Unlock()`'d.
|
||||
|
||||
**Why:** Guarantees cleanup regardless of return path (early returns, panics). Keeps
|
||||
the acquire/release pair visually adjacent. Reduces bugs from forgotten unlocks.
|
||||
|
||||
**Anti-pattern:** Manual unlock at each return point; deferring in a loop (deferred
|
||||
calls accumulate until function exit); deferring expensive operations that should
|
||||
run earlier.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:3173-3174
|
||||
func (s *Server) Close() error {
|
||||
s.inShutdown.Store(true)
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
// ...
|
||||
}
|
||||
|
||||
// net/http/example_handle_test.go:21-22
|
||||
func (h *countHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
h.n++
|
||||
fmt.Fprintf(w, "count is %d\n", h.n)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Error Wrapping and Sentinel Errors
|
||||
|
||||
**Pattern name:** Sentinel Errors + Structured Error Types
|
||||
|
||||
**Source citation:** `os/error.go` lines 14–27, `os/error.go` lines 46–67
|
||||
|
||||
**What it does:** Package-level sentinel errors (`ErrNotExist`, `ErrPermission`) are
|
||||
declared as `var` for use with `errors.Is()`. Structured error types (`*PathError`,
|
||||
`*SyscallError`) carry context and implement `Unwrap()` for the errors chain.
|
||||
|
||||
**Why:** Enables programmatic error handling without string matching. `errors.Is(err, os.ErrNotExist)` works regardless of wrapping depth. Structured types let callers
|
||||
extract the operation, path, or underlying syscall error.
|
||||
|
||||
**Anti-pattern:** Comparing error strings; creating unique error types for every
|
||||
possible failure; not implementing `Unwrap`; sentinel errors as `const` (breaks
|
||||
`errors.Is` for wrapped errors — use `var`).
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// os/error.go:14-27
|
||||
var (
|
||||
ErrInvalid = fs.ErrInvalid // "invalid argument"
|
||||
ErrPermission = fs.ErrPermission // "permission denied"
|
||||
ErrExist = fs.ErrExist // "file already exists"
|
||||
ErrNotExist = fs.ErrNotExist // "file does not exist"
|
||||
ErrClosed = fs.ErrClosed // "file already closed"
|
||||
)
|
||||
|
||||
// os/error.go:46
|
||||
type PathError = fs.PathError
|
||||
|
||||
// os/error.go:49-57
|
||||
type SyscallError struct {
|
||||
Syscall string
|
||||
Err error
|
||||
}
|
||||
|
||||
func (e *SyscallError) Error() string { return e.Syscall + ": " + e.Err.Error() }
|
||||
func (e *SyscallError) Unwrap() error { return e.Err }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Receiver Naming: Short, Consistent, Never `this`/`self`
|
||||
|
||||
**Pattern name:** Single-Letter or Short Receiver Names
|
||||
|
||||
**Source citation:** All stdlib code; `net/http/server.go` uses `s` for Server, `bufio/scan.go` uses `s` for Scanner
|
||||
|
||||
**What it does:** Method receivers use 1–2 letter abbreviations of the type name,
|
||||
consistent across all methods of that type: `s` for `*Server`, `b` for `*Builder`,
|
||||
`f` for `*File`, `t` for `*Timer`.
|
||||
|
||||
**Why:** Receivers appear on every method. Short names reduce visual noise. Consistency
|
||||
within a type avoids confusion. `this`/`self` are alien to Go's conventions.
|
||||
|
||||
**Anti-pattern:** `this`, `self`, `me`; long receiver names like `server`, `scanner`;
|
||||
inconsistent receivers across methods of the same type.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go
|
||||
func (s *Server) ListenAndServe() error { ... }
|
||||
func (s *Server) Serve(l net.Listener) error { ... }
|
||||
func (s *Server) Shutdown(ctx context.Context) error { ... }
|
||||
|
||||
// strings/builder.go
|
||||
func (b *Builder) WriteString(s string) (int, error) { ... }
|
||||
func (b *Builder) String() string { ... }
|
||||
func (b *Builder) Grow(n int) { ... }
|
||||
|
||||
// os/file.go
|
||||
func (f *File) Read(b []byte) (n int, err error) { ... }
|
||||
func (f *File) Name() string { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Constants: Typed, Grouped, with iota
|
||||
|
||||
**Pattern name:** Typed Constants with iota
|
||||
|
||||
**Source citation:** `crypto/crypto.go` lines 70–85, `time/time.go` lines 936–943
|
||||
|
||||
**What it does:** Related constants are grouped in a `const ( ... )` block using
|
||||
a named type and `iota` for sequential values. Constants of the same type
|
||||
are exhaustively listed together.
|
||||
|
||||
**Why:** Type safety (can't accidentally pass an `os.Flag` where a `crypto.Hash` is
|
||||
expected). `iota` eliminates magic numbers. Grouping makes the full set visible.
|
||||
|
||||
**Anti-pattern:** Untyped numeric constants; separate `const` declarations for related
|
||||
values; using raw integers in function signatures.
|
||||
|
||||
**Code examples from source:**
|
||||
|
||||
```go
|
||||
// crypto/crypto.go:70-85
|
||||
const (
|
||||
MD4 Hash = 1 + iota
|
||||
MD5
|
||||
SHA1
|
||||
SHA224
|
||||
SHA256
|
||||
// ...
|
||||
)
|
||||
|
||||
// time/time.go:936-943
|
||||
const (
|
||||
Nanosecond Duration = 1
|
||||
Microsecond = 1000 * Nanosecond
|
||||
Millisecond = 1000 * Microsecond
|
||||
Second = 1000 * Millisecond
|
||||
Minute = 60 * Second
|
||||
Hour = 60 * Minute
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Comments: Guard Clauses Over Conditions
|
||||
|
||||
**Pattern name:** `// guards x` Field Comments
|
||||
|
||||
**Source citation:** `net/http/example_handle_test.go` line 16
|
||||
|
||||
**What it does:** When a sync primitive (mutex) protects specific fields, a brief
|
||||
comment documents what it guards: `mu sync.Mutex // guards n`.
|
||||
|
||||
**Why:** Concurrency bugs come from unclear ownership. A one-line comment makes the
|
||||
lock's scope obvious to every reader.
|
||||
|
||||
**Anti-pattern:** No documentation of what a lock protects; locks that protect
|
||||
"everything" (unclear scope); comments that restate the type.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/example_handle_test.go:16-17
|
||||
type countHandler struct {
|
||||
mu sync.Mutex // guards n
|
||||
n int
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Duration Type Pattern
|
||||
|
||||
**Pattern name:** Named Type for Semantic Units
|
||||
|
||||
**Source citation:** `time/time.go` lines 915–943
|
||||
|
||||
**What it does:** `Duration` is `type Duration int64` — a named type over a primitive.
|
||||
This gives it its own method set (`String()`, `Hours()`, `Truncate()`) and prevents
|
||||
accidental mixing with raw int64 values.
|
||||
|
||||
**Why:** Semantic meaning through the type system. You can't accidentally pass
|
||||
nanoseconds where seconds are expected. Methods provide conversion and formatting.
|
||||
Constants like `time.Second` make intent clear.
|
||||
|
||||
**Anti-pattern:** Using raw `int64` for durations; accepting `int` parameters for
|
||||
time intervals; mixing units (milliseconds in one place, seconds in another).
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// time/time.go:915
|
||||
type Duration int64
|
||||
|
||||
// time/time.go:947-949
|
||||
func (d Duration) String() string {
|
||||
var arr [32]byte
|
||||
n := d.format(&arr)
|
||||
return string(arr[n:])
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. gofmt: Non-Negotiable Formatting
|
||||
|
||||
**Pattern name:** Canonical Formatting via gofmt
|
||||
|
||||
**Source citation:** Every file in the Go standard library
|
||||
|
||||
**What it does:** All Go code is formatted with `gofmt`. Tabs for indentation, spaces
|
||||
for alignment. No style debates — the tool decides.
|
||||
|
||||
**Why:** Eliminates formatting bikesheds. All Go code looks the same regardless of
|
||||
author. Diffs show only semantic changes, never style changes. Tooling can parse
|
||||
and emit canonical code.
|
||||
|
||||
**Anti-pattern:** Manual formatting; spaces for indentation; custom alignment rules;
|
||||
checking in code that `gofmt` would modify.
|
||||
|
||||
**Key rules enforced by gofmt:**
|
||||
|
||||
- Tabs for indentation
|
||||
- Opening brace on the same line (`if x {`)
|
||||
- No optional parentheses (`if x`, not `if (x)`)
|
||||
- Aligned struct field tags
|
||||
- One blank line between top-level declarations
|
||||
- No trailing whitespace
|
||||
|
||||
---
|
||||
|
||||
## 13. Import Organization
|
||||
|
||||
**Pattern name:** Grouped Imports (stdlib / external / internal)
|
||||
|
||||
**Source citation:** `net/http/server.go` lines 8–36
|
||||
|
||||
**What it does:** Imports are organized in groups separated by blank lines:
|
||||
1. Standard library
|
||||
2. External packages (golang.org/x, third-party)
|
||||
3. Internal packages
|
||||
|
||||
The `goimports` tool enforces this automatically.
|
||||
|
||||
**Why:** Scannable at a glance. Makes dependency provenance clear (stdlib vs.
|
||||
external). Reduces merge conflicts.
|
||||
|
||||
**Code example from source:**
|
||||
|
||||
```go
|
||||
// net/http/server.go:8-36
|
||||
import (
|
||||
"bufio"
|
||||
"bytes"
|
||||
"context"
|
||||
"crypto/tls"
|
||||
"errors"
|
||||
"fmt"
|
||||
// ... more stdlib ...
|
||||
"time"
|
||||
_ "unsafe" // for linkname
|
||||
|
||||
"golang.org/x/net/http/httpguts"
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,262 @@
|
||||
# Anti-Patterns: What Kubernetes Avoids (and Why)
|
||||
|
||||
## 1. Never Mutate Shared Cache Objects
|
||||
|
||||
**What they avoid:** Modifying objects returned by Listers/Informers without deep-copying first.
|
||||
|
||||
**Why:** The informer cache is shared across all controllers. Mutating a cached object corrupts state for every other consumer.
|
||||
|
||||
**The pattern K8s enforces:**
|
||||
```go
|
||||
// WRONG — mutates shared cache
|
||||
deployment, _ := dc.dLister.Deployments(ns).Get(name)
|
||||
deployment.Spec.Replicas = ptr.To[int32](3) // CORRUPTION!
|
||||
|
||||
// RIGHT — deep copy before mutating
|
||||
deployment, _ := dc.dLister.Deployments(ns).Get(name)
|
||||
deploymentCopy := deployment.DeepCopy()
|
||||
deploymentCopy.Spec.Replicas = ptr.To[int32](3)
|
||||
```
|
||||
|
||||
**Evidence:** The `runtime.Object` interface *mandates* `DeepCopyObject()`. Every API type has generated deep copy methods. The entire architecture assumes immutable reads.
|
||||
|
||||
---
|
||||
|
||||
## 2. Never Process the Same Key Concurrently
|
||||
|
||||
**What they avoid:** Multiple goroutines syncing the same object simultaneously.
|
||||
|
||||
**Why:** Two goroutines reading the same Deployment, each computing a different desired state, then both writing → conflict errors and potential state corruption.
|
||||
|
||||
**The pattern K8s enforces:** The workqueue's `processing` set ensures a key is only handed to one worker at a time. If an item is added while being processed, it's re-queued *after* `Done()` is called:
|
||||
|
||||
```go
|
||||
// From queue.go — the processing set blocks concurrent access
|
||||
func (q *Typed[T]) Get() (item T, shutdown bool) {
|
||||
// ...
|
||||
q.processing.Insert(item) // Mark as being worked on
|
||||
q.dirty.Delete(item)
|
||||
return item, false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Never Use Edge-Triggered Logic
|
||||
|
||||
**What they avoid:** Controllers that react to *what changed* rather than *what the current state is*.
|
||||
|
||||
**Why:** Events can be missed (watch disconnects), delivered out of order, or duplicated. If your controller says "a pod was deleted, so decrement counter" rather than "count current pods and compare to desired", you'll drift.
|
||||
|
||||
**The pattern K8s enforces:** Level-triggered reconciliation. The `syncHandler` reads *current state from the cache*, computes *desired state from the spec*, and makes the world match:
|
||||
|
||||
```go
|
||||
// The sync function always reads current state, never relies on "what happened"
|
||||
func (dc *DeploymentController) syncDeployment(ctx context.Context, key string) error {
|
||||
deployment, err := dc.dLister.Deployments(namespace).Get(name)
|
||||
// Compute desired state from deployment.Spec
|
||||
// Read actual state from replicaset lister
|
||||
// Reconcile difference
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Never Forget to Call queue.Forget() on Success
|
||||
|
||||
**What they avoid:** Letting the rate limiter track items that succeeded.
|
||||
|
||||
**Why:** The rate limiter is per-item. If you never call `Forget()`, the next time the same key needs processing (even for a new event), it will be rate-limited as if it previously failed.
|
||||
|
||||
**Source:** The rate_limiting_queue.go comments explicitly warn:
|
||||
```go
|
||||
// NewTypedRateLimitingQueue constructs a new workqueue with rateLimited queuing ability
|
||||
// Remember to call Forget! If you don't, you may end up tracking failures forever.
|
||||
```
|
||||
|
||||
**The pattern K8s enforces:**
|
||||
```go
|
||||
func (dc *DeploymentController) handleErr(ctx context.Context, err error, key string) {
|
||||
if err == nil {
|
||||
dc.queue.Forget(key) // CRITICAL: clear the failure counter
|
||||
return
|
||||
}
|
||||
if dc.queue.NumRequeues(key) < maxRetries {
|
||||
dc.queue.AddRateLimited(key)
|
||||
return
|
||||
}
|
||||
dc.queue.Forget(key) // Also forget when giving up
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Never Hit the API Server in a Tight Loop
|
||||
|
||||
**What they avoid:** Direct API calls for reads. List/Get calls in hot paths.
|
||||
|
||||
**Why:** The API server is a shared resource. If 100 controllers each make 10 API calls per reconciliation at 1 sync/second, that's 1000 req/s to the API server per controller manager instance.
|
||||
|
||||
**The pattern K8s enforces:** Read from Listers (local cache), write to API server:
|
||||
```go
|
||||
// READ from cache (free, local, fast)
|
||||
deployment, err := dc.dLister.Deployments(namespace).Get(name)
|
||||
|
||||
// WRITE to API server (expensive, remote, rate-limited)
|
||||
_, err = dc.client.AppsV1().Deployments(namespace).Update(ctx, deployment, ...)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Never Sync Before Caches Are Warm
|
||||
|
||||
**What they avoid:** Processing items before the informer has done its initial List.
|
||||
|
||||
**Why:** With an empty cache, a controller might think "no pods exist, must create all of them" — causing a thundering herd of duplicate creates.
|
||||
|
||||
**The pattern K8s enforces:**
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:189
|
||||
if !cache.WaitForNamedCacheSyncWithContext(ctx,
|
||||
dc.dListerSynced, dc.rsListerSynced, dc.podListerSynced) {
|
||||
return // Don't start workers until all caches are populated
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Never Ignore Tombstones in Delete Handlers
|
||||
|
||||
**What they avoid:** Assuming delete handlers always receive the concrete type.
|
||||
|
||||
**Why:** If a watch disconnects and reconnects, missed deletes arrive as `DeletedFinalStateUnknown` (tombstones). Ignoring them means your controller never learns about those deletions.
|
||||
|
||||
**The pattern K8s enforces:**
|
||||
```go
|
||||
// Every delete handler must check for tombstones
|
||||
func (dc *DeploymentController) deleteDeployment(logger klog.Logger, obj interface{}) {
|
||||
d, ok := obj.(*apps.Deployment)
|
||||
if !ok {
|
||||
tombstone, ok := obj.(cache.DeletedFinalStateUnknown)
|
||||
if !ok {
|
||||
utilruntime.HandleError(...)
|
||||
return
|
||||
}
|
||||
d, ok = tombstone.Obj.(*apps.Deployment)
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Never Use ResourceVersion for Equality
|
||||
|
||||
**What they avoid:** Comparing ResourceVersion to check if an object changed.
|
||||
|
||||
**Why:** ResourceVersion is opaque (currently etcd's mod_revision, but this is an implementation detail). The only valid operation is "!=" to detect change.
|
||||
|
||||
**The pattern K8s uses:**
|
||||
```go
|
||||
// pkg/controller/deployment/deployment_controller.go:284-288
|
||||
func (dc *DeploymentController) updateReplicaSet(logger klog.Logger, old, cur interface{}) {
|
||||
curRS := cur.(*apps.ReplicaSet)
|
||||
oldRS := old.(*apps.ReplicaSet)
|
||||
if curRS.ResourceVersion == oldRS.ResourceVersion {
|
||||
return // Periodic resync, nothing actually changed
|
||||
}
|
||||
// ... process the real update
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Never Panic in Production Goroutines (Without Recovery)
|
||||
|
||||
**What they avoid:** Unhandled panics killing the entire controller manager.
|
||||
|
||||
**Why:** A single nil pointer in one controller's sync loop would crash all 30+ controllers running in the same process.
|
||||
|
||||
**The pattern K8s enforces:**
|
||||
```go
|
||||
// Every goroutine gets crash protection
|
||||
func (dc *DeploymentController) Run(ctx context.Context, workers int) {
|
||||
defer utilruntime.HandleCrash() // Top-level recovery
|
||||
// ...
|
||||
}
|
||||
|
||||
// And in every polling loop:
|
||||
func BackoffUntilWithContext(ctx context.Context, f func(ctx context.Context), ...) {
|
||||
func() {
|
||||
defer runtime.HandleCrashWithContext(ctx) // Per-iteration recovery
|
||||
f(ctx)
|
||||
}()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Never Block Workers Indefinitely
|
||||
|
||||
**What they avoid:** Unbounded blocking in a sync handler (e.g., waiting for a condition that may never occur).
|
||||
|
||||
**Why:** Workers are a finite pool. If one blocks forever, that's one fewer worker processing the queue. At scale, this cascades.
|
||||
|
||||
**The pattern K8s enforces:** All API calls take context (with timeouts), all waits are bounded:
|
||||
```go
|
||||
// Timeouts on API calls
|
||||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||||
defer cancel()
|
||||
_, err := client.CoreV1().Pods(ns).Create(ctx, pod, metav1.CreateOptions{})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Never Use sync.Mutex Where sync.Once Suffices
|
||||
|
||||
**What they avoid:** Full mutual exclusion for one-shot operations.
|
||||
|
||||
**Why:** `sync.Once` is semantically clearer and avoids the bug where you forget to check a "done" flag under the mutex.
|
||||
|
||||
**The pattern K8s uses:**
|
||||
```go
|
||||
// pkg/controller/controller_ref_manager.go:43-49
|
||||
type BaseControllerRefManager struct {
|
||||
canAdoptErr error
|
||||
canAdoptOnce sync.Once // One-shot lazy evaluation
|
||||
CanAdoptFunc func(ctx context.Context) error
|
||||
}
|
||||
|
||||
func (m *BaseControllerRefManager) CanAdopt(ctx context.Context) error {
|
||||
m.canAdoptOnce.Do(func() {
|
||||
if m.CanAdoptFunc != nil {
|
||||
m.canAdoptErr = m.CanAdoptFunc(ctx)
|
||||
}
|
||||
})
|
||||
return m.canAdoptErr
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Never Expose Mutable State Through Interfaces
|
||||
|
||||
**What they avoid:** Returning pointers to internal state through public interfaces.
|
||||
|
||||
**Why:** Callers can accidentally mutate internal state, creating subtle bugs that only manifest under concurrency.
|
||||
|
||||
**The pattern K8s enforces:** Listers return objects from the read-only cache. The `DeepCopy()` pattern ensures mutation safety is the caller's responsibility, not the cache's.
|
||||
|
||||
---
|
||||
|
||||
## Summary: The Philosophy
|
||||
|
||||
Kubernetes avoids these anti-patterns because of one fundamental truth: **in a distributed system, every assumption you make about state being consistent is wrong.**
|
||||
|
||||
The patterns exist because:
|
||||
1. **Events are unreliable** → level-triggered reconciliation
|
||||
2. **Reads are stale** → always compare desired vs actual
|
||||
3. **Concurrent access is inevitable** → deep copy, queue serialization
|
||||
4. **Failures are normal** → retry with backoff, graceful degradation
|
||||
5. **Resources are shared** → cache reads, rate-limit writes
|
||||
6. **Systems outlive their authors** → code generation, type registries, feature gates
|
||||
Reference in New Issue
Block a user