samber/cc-skills-golang / skills/golang-structs-interfaces
golang-structs-interfaces
VerifiedGolang struct and interface design patterns — composition, embedding, type assertions, type switches, interface segregation, dependency injection via interfaces, struct field tags, and pointer vs value receivers. Use this skill when designing Go types, defining or implementing interfaces, embedding structs or interfaces, writing type assertions or type switches, adding struct field tags for JSON/YAML/DB serialization, or choosing between pointer and value receivers. Also use when the user asks about "accept interfaces, return structs", compile-time interface checks, or composing small interfaces into larger ones.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.9 KB |
| evals/evals.json | config | 13.3 KB |
| references/struct-fields.md | markdown | 3.7 KB |
| references/type-assertions.md | markdown | 2.2 KB |
references/struct-fields.md
View on GitHub# Struct Fields: Tags and Copy Safety
## Struct Field Tags
Field tags drive every reflection-based encoder and decoder. Exported fields in serialized structs MUST have field tags — without one, the encoder falls back to the Go field name, so renaming a field silently changes the wire format:
```go
type Order struct {
ID string `json:"id" db:"id"`
UserID string `json:"user_id" db:"user_id"`
Total float64 `json:"total" db:"total"`
Items []Item `json:"items" db:"-"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
DeletedAt time.Time `json:"-" db:"deleted_at"`
Internal string `json:"-" db:"-"`
}
```
| Directive | Meaning |
| ----------------------- | ------------------------------------------- |
| `json:"name"` | Field name in JSON output |
| `json:"name,omitempty"` | Omit field if zero value |
| `json:"name,omitzero"` | Omit field if zero (Go 1.24+, type-aware) |
| `json:"-"` | Always exclude from JSON |
| `json:"-,"` | Field literally named `-` |
| `json:",string"` | Encode number/bool as JSON string |
| `db:"column"` | Database column mapping (sqlx, etc.) |
| `yaml:"name"` | YAML field name |
| `xml:"name,attr"` | XML attribute |
| `validate:"required"` | Struct validation (go-playground/validator) |
Notes that bite in production:
- **Unexported fields are never serialized**, tag or not. A tag on an unexported field is dead weight and `go vet` flags the malformed ones only.
- **`omitempty` is length/zero based, not semantic.** It drops `0`, `""`, and `false`, so an explicit "zero" value becomes indistinguishable from "absent". Use a pointer, `mo.Option[T]`, or `omitzero` (Go 1.24+) when the difference matters.
- **Tag syntax is unchecked at compile time.** A missing backtick or a `json: "id"` with a stray space produces a silently ignored tag. `go vet`'s `structtag` analyzer catches malformed tags — run it in CI.
**Diagnose:** 1- `go vet ./...` — the `structtag` analyzer reports malformed or duplicated tags 2- round-trip test: marshal, unmarshal, compare — catches field-name drift the compiler cannot see
## Preventing Struct Copies with `noCopy`
Some structs must never be copied after first use (e.g., those containing a mutex, a channel, or internal pointers) — copying duplicates the lock state, so two goroutines end up guarding two different mutexes and the invariant silently disappears. Embed a `noCopy` sentinel to make `go vet` catch accidental copies:
```go
// noCopy may be added to structs which must not be copied after first use.
// See https://pkg.go.dev/sync#noCopy
type noCopy struct{}
func (*noCopy) Lock() {}
func (*noCopy) Unlock() {}
type ConnPool struct {
noCopy noCopy
mu sync.Mutex
conns []*Conn
}
```
`go vet` reports an error if a `ConnPool` value is copied (passed by value, assigned, returned by value, ranged over). The detection is purely name-based: `vet`'s `copylocks` analyzer flags any type whose fields implement `Lock`/`Unlock`. This is the same technique the standard library uses for `sync.WaitGroup`, `sync.Mutex`, `strings.Builder`, and others.
Pass these structs by pointer:
```go
// Good
func process(pool *ConnPool) { ... }
// Bad — go vet will flag this
func process(pool ConnPool) { ... }
```
**Diagnose:** 1- `go vet ./...` — `copylocks` reports every value copy of a lock-bearing struct 2- `go test -race ./...` — surfaces the data races a silent copy introduces
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |