cxuu/golang-skills

go-interfaces

Use when defining or implementing Go interfaces, designing abstractions, creating mockable boundaries for testing, or composing types through embedding.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/cxuu/golang-skills --skill go-interfaces

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

Go Interfaces and Composition

Resource Routing

  • scripts/check-interface-compliance.sh - Run as a heuristic to find exported interfaces that may need compile-time assertions.
  • scripts/check-interface-compliance.go - Implementation helper invoked by check-interface-compliance.sh; patch this when changing method-set analysis.
  • references/EMBEDDING.md - Read when embedding interfaces or structs in public APIs.
  • references/RECEIVER-TYPE.md - Read when pointer/value receivers affect interface satisfaction.

Accept Interfaces, Return Concrete Types

Interfaces belong in the package that consumes values, not the package that implements them. Return concrete (usually pointer or struct) types from constructors so new methods can be added without refactoring.

go
// Good: consumer defines the interface it needs
package consumer

type Thinger interface { Thing() bool }

func Foo(t Thinger) string { ... }
go
// Good: producer returns concrete type
package producer

type Thinger struct{ ... }
func (t Thinger) Thing() bool { ... }
func NewThinger() Thinger { return Thinger{ ... } }
go
// Bad: producer defines and returns its own interface
package producer

type Thinger interface { Thing() bool }
type defaultThinger struct{ ... }
func NewThinger() Thinger { return defaultThinger{ ... } }

Do not define interfaces before they are used. Without a realistic example of usage, it is too difficult to see whether an interface is even necessary.


Generality: Hide Implementation, Expose Interface

If a type exists only to implement an interface with no exported methods beyond that interface, return the interface from constructors to hide the implementation:

go
func NewHash() hash.Hash32 {
    return &myHash{}  // unexported type
}

Benefits: implementation can change without affecting callers, substituting algorithms requires only changing the constructor call.


Type Assertions: Comma-Ok Idiom

Without checking, a failed assertion causes a runtime panic. Always use the comma-ok idiom to test safely:

go
str, ok := value.(string)
if ok {
    fmt.Printf("string value is: %q\n", str)
}

To check if a value implements an interface:

go
if _, ok := val.(json.Marshaler); ok {
    fmt.Printf("value %v implements json.Marshaler\n", val)
}

Type Switch

It's idiomatic to reuse the variable name (t := t.(type)) — the variable has the correct type in each case branch. When a case lists multiple types (case int, int64:), the variable has the interface type.


Embedding

Avoid embedding types in public structs — the inner type's full method set becomes part of your public API. Use unexported fields instead.


Interface Satisfaction Checks

Use a blank identifier assignment to verify a type implements an interface at compile time:

go
var _ json.Marshaler = (*RawMessage)(nil)

This causes a compile error if *RawMessage doesn't implement json.Marshaler.

Use this pattern when:

  • There are no static conversions that would verify the interface automatically
  • The type must satisfy an interface for correct behavior (e.g., custom JSON

marshaling)

  • Interface changes should break compilation, not silently degrade

Don't add these checks for every interface — only when no other static conversion would catch the error.

Validation: After defining interfaces or implementations, run bash scripts/check-interface-compliance.sh to verify all concrete types have compile-time var _ I = (*T)(nil) checks.

Receiver Type

If in doubt, use a pointer receiver. Don't mix receiver types on a single type — if any method needs a pointer, use pointers for all methods. Use value receivers only for small, immutable types (Point, time.Time) or basic types.


Quick Reference

ConceptPatternNotes
Consumer owns interfaceDefine interfaces where usedNot in the implementing package
Safe type assertionv, ok := x.(Type)Returns zero value + false
Type switchswitch v := x.(type)Variable has correct type per case
Interface embeddingtype RW interface { Reader; Writer }Union of methods
Struct embeddingtype S struct { *T }Promotes T's methods
Interface checkvar _ I = (*T)(nil)Compile-time verification
GeneralityReturn interface from constructorHide implementation

Related Skills

  • Interface naming: See go-naming when naming interfaces (the -er suffix convention) or choosing receiver names
  • Error types: See go-error-handling when implementing the error interface, custom error types, or errors.As matching
  • Generics vs interfaces: See go-generics when deciding whether generics are needed or an interface already suffices
  • Functional options: See go-functional-options when using an interface-based Option pattern for flexible constructors
  • Defensive boundaries: See go-defensive when interface assertions are one part of a broader API-boundary hardening pass
du même dépôt

Autres Skills

Tous les Skills
cxuu
Communauté

go-code-review

Use when reviewing Go code or checking code against community style standards. Also use proactively before submitting a Go PR or when reviewing any Go code changes, even if the user doesn't explicitly request a style review. Does not cover language-specific syntax — delegates to specialized skills.

Installations / 1h
2
GitHub Stars
189
Mis à jour
20 juin
cxuu
Communauté

go-concurrency

Use when writing concurrent Go code — goroutines, channels, mutexes, or thread-safety guarantees. Also use when parallelizing work, fixing data races, or protecting shared state, even if the user doesn't explicitly mention concurrency primitives. Does not cover context.Context patterns (see go-context).

Installations / 1h
2
GitHub Stars
189
Mis à jour
20 juin
cxuu
Communauté

go-context

Use when working with context.Context in Go — placement in signatures, propagating cancellation and deadlines, and storing values in context vs parameters. Also use when cancelling long-running operations, setting timeouts, or passing request-scoped data, even if they don't mention context.Context directly. Does not cover goroutine lifecycle or sync primitives (see go-concurrency).

Installations / 1h
2
GitHub Stars
189
Mis à jour
20 juin
cxuu
Communauté

go-control-flow

Use when writing conditionals, loops, or switch statements in Go — including if with initialization, early returns, for loop forms, range, switch, type switches, and blank identifier patterns. Also use when writing a simple if/else or for loop, even if the user doesn't mention guard clauses or variable scoping. Does not cover error flow patterns (see go-error-handling).

Installations / 1h
2
GitHub Stars
189
Mis à jour
20 juin