golang-structs-interfaces

Guides Go struct and interface design covering embedding, type assertions, receivers, and field tags.

1|Updated May 25, 2020
One-click install
npx skills add https://github.com/titaneric/dotfiles --skill golang-structs-interfaces-titaneric
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: golang-structs-interfaces
Source: https://github.com/titaneric/dotfiles/tree/main/dot_agents/skills/golang-structs-interfaces
Command: npx skills add https://github.com/titaneric/dotfiles --skill golang-structs-interfaces-titaneric

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Go developers often create oversized interfaces, return interfaces from constructors, panic on bare type assertions, or mix pointer and value receivers, leading to brittle and untestable code. This Skill encodes idiomatic Go type-system design rules so an AI coding agent produces correct struct and interface patterns by default. ## Core Features & Use Cases - Interface Design Rules: Enforces small 1-3 method interfaces defined at the consumer, the accept-interfaces-return-structs principle, and avoiding premature interfaces with a single implementation. - Type Safety Patterns: Covers comma-ok type assertions, type switches, compile-time interface checks with var _ Interface = (*Type)(nil), generics over any, and the noCopy sentinel for go vet copy detection. - Struct Design Guidance: Explains embedding vs named fields, useful zero values with lazy initialization, struct field tags for JSON/YAML/DB serialization, and pointer vs value receiver consistency. - Use Case: When asked to design a notification service depending on an email client, the agent defines a small Sender interface in the consumer package, returns a concrete struct from the constructor, and injects the dependency via the interface for easy mocking in tests. ## Quick Start Ask the agent to design a Go service with an interface-based dependency and review whether the types follow idiomatic struct and interface patterns.

Frequently Asked Questions about golang-structs-interfaces

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Where should I define interfaces in a Go project?

Define interfaces in the package that consumes them, not where they are implemented. This keeps the consumer in control of the contract and avoids importing a package just for its interface. The implementor package exports a concrete struct instead.

Should Go constructors return interfaces or structs?

Constructors should return concrete types, never interfaces. Accept interfaces as parameters for flexibility, but return structs so callers get full access to fields and methods; they can still assign the result to an interface variable if needed.

When should I use embedding vs a named field in Go structs?

Embed when you want to promote the inner type's full API, meaning the outer type is an enhanced version of it. Use a named field when the inner type is only an internal dependency whose methods should not be exposed to callers.

How do I prevent a Go struct from being copied?

Embed a noCopy sentinel struct with empty Lock and Unlock methods. go vet then flags any accidental copies, which is the same technique used by sync.Mutex, sync.WaitGroup, and strings.Builder in the standard library.

Should I use generics or any/interface{} in Go functions?

Prefer generics with constraints like comparable for type-safe operations since Go 1.18. Reserve any for true boundaries where the type is genuinely unknown, such as JSON decoding or reflection, because any loses compile-time type safety.

Can I mix pointer and value receivers on the same Go type?

No, receiver type should be consistent across all methods of a type. If any method needs a pointer receiver to mutate state, all methods should use pointer receivers, since method sets differ between T and *T and affect interface satisfaction.