go-defensive-coding
Prevent panics, silent corruption, and subtle runtime bugs in Go: typed-nil interfaces, slice aliasing, integer overflow on conversion, float comparison, defer in loops, defensive copying at API boundaries, and zero-value design. Use when hardening code against crashes, reviewing for nil-safety, converting between numeric types, or deciding what to copy at a package boundary. Trigger examples: "nil pointer panic", "why is my error not nil", "slice aliasing", "integer overflow", "compare floats", "defer in a loop", "defensive copy", "make this crash-proof". Not for: data races and goroutine lifecycle (go-concurrency-review), injection and auth (go-security-audit), a panic that already happened (go-troubleshooting).
eduardo-sl · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add eduardo-sl/go-agent-skills --skill go-defensive-coding技能说明
name: go-defensive-coding description: > Prevent panics, silent corruption, and subtle runtime bugs in Go: typed-nil interfaces, slice aliasing, integer overflow on conversion, float comparison, defer in loops, defensive copying at API boundaries, and zero-value design. Use when hardening code against crashes, reviewing for nil-safety, converting between numeric types, or deciding what to copy at a package boundary. Trigger examples: "nil pointer panic", "why is my error not nil", "slice aliasing", "integer overflow", "compare floats", "defer in a loop", "defensive copy", "make this crash-proof". Not for: data races and goroutine lifecycle (go-concurrency-review), injection and auth (go-security-audit), a panic that already happened (go-troubleshooting). user-invocable: true license: MIT compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain. golangci-lint and gosec are optional, for enforcing the rules below. allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(gofmt:) Bash(golangci-lint:) Bash(gosec:) metadata: author: eduardo-sl version: "1.1.1"
Go Defensive Coding
Go has no exceptions and no null-safety in the type system. Every trap below compiles cleanly, passes review, and fails in production.
Detailed reference material, loaded on demand:
references/nil-and-aliasing.md— the full typed-nil rules, slice aliasing scenarios, and memory retention.references/numeric-safety.md— conversion range checks, overflow detection, float and time comparison.
Read a reference file only when the section below is not enough.
Operating Modes
- Harden — you are writing or changing code. Apply every rule as you go.
- Review — you are auditing existing code. Report findings with severity (🔴 panic or corruption, 🟡 latent bug, 🟢 style) and cite file:line.
1. The Typed-Nil Interface Trap
A non-nil interface can hold a nil pointer. This is the single most common source of "impossible" nil checks in Go.
type NotFoundError struct{ ID string }
func (e *NotFoundError) Error() string { return "not found: " + e.ID }
// ❌ Bad — returns a non-nil error even on success
func find(id string) error {
var err *NotFoundError // typed nil
if id == "" {
err = &NotFoundError{ID: id}
}
return err // interface is (type=*NotFoundError, value=nil) — NOT nil
}
// ✅ Good — return the untyped nil literal
func find(id string) error {
if id == "" {
return &NotFoundError{ID: id}
}
return nil
}
Rules:
- Never declare a concrete error/pointer variable and return it as an
interface. Return
nilexplicitly on the success path. - Never store a possibly-nil concrete pointer in an
error,io.Reader, or any interface-typed struct field. go vet'snilnessanalyzer catches some of these. It does not catch all.
2. Nil Map, Slice, and Channel Behaviour
Memorise this table — half of these are safe and half panic or hang.
| Operation | nil map | nil slice | nil channel |
|---|---|---|---|
| Read / receive | zero value | index panics | blocks forever |
| Write / send | panics | append works | blocks forever |
len / cap | 0 | 0 | 0 |
range | zero iterations | zero iterations | blocks forever |
close | n/a | n/a | panics |
// ✅ A nil slice is a valid empty slice — do not guard append
var out []string
out = append(out, "a")
// ❌ A nil map is read-only
var m map[string]int
m["k"] = 1 // panic: assignment to entry in nil map
// ✅ Initialise every map before writing
m := make(map[string]int)
Return nil slices, not []T{}. They marshal identically in JSON for
encoding/json when the field is omitempty, and cost no allocation.
Return an empty non-nil map only when the caller is documented to write to it.
3. Slice Aliasing
A slice is a view. append writes through that view whenever capacity
allows, mutating data the caller still owns.
a := []int{1, 2, 3, 4}
b := a[:2]
b = append(b, 99) // ❌ overwrites a[2]; a is now [1 2 99 4]
// ✅ Full slice expression caps the view — append must reallocate
b := a[:2:2]
b = append(b, 99) // a is untouched
Apply this whenever you hand a subslice to code you do not control, and whenever a struct field holds a subslice of a larger buffer.
A subslice also keeps the entire backing array alive. To release a large
buffer, copy what you need: head := slices.Clone(buf[:64]).
4. Defensive Copying at Boundaries
Slices and maps are reference types. Storing or returning one without a copy hands out a mutable handle to your internals.
type Config struct{ hosts []string }
// ❌ Bad — caller can mutate our state, both ways
func NewConfig(hosts []string) *Config { return &Config{hosts: hosts} }
func (c *Config) Hosts() []string { return c.hosts }
// ✅ Good — copy in, copy out
func NewConfig(hosts []string) *Config {
return &Config{hosts: slices.Clone(hosts)}
}
func (c *Config) Hosts() []string { return slices.Clone(c.hosts) }
Use maps.Clone for maps. Both are shallow — a []*User clone still shares
the pointed-to users.
Copy when the value is retained past the call or exposed to a caller. Do not copy a slice you only read inside the function; that is wasted allocation.
Preventing accidental copies
A struct containing a sync.Mutex, sync.WaitGroup, or atomic.Int64 must
never be copied — the copy gets its own independent lock, and both halves
believe they are synchronised.
// ❌ Bad — the receiver is a copy, so the mutex protects nothing
func (c Counter) Value() int { ... }
// ❌ Bad — passing by value copies the mutex
func report(c Counter) { ... }
go vet's copylocks analyzer catches these. For types that must not be
copied but hold no lock, embed a noCopy marker so vet catches them too:
type noCopy struct{}
func (*noCopy) Lock() {}
func (*noCopy) Unlock() {}
type Tr
阅读完整来源 ↗