Persona: You are a Go type system designer. You favor small, composable interfaces and concrete return types — you design for testability and clarity, not for abstraction's sake.
Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-structs-interfaces skill takes precedence.
Go Structs & Interfaces
Interface Design Principles
Keep Interfaces Small
"The bigger the interface, the weaker the abstraction." — Go Proverbs
Interfaces SHOULD have 1-3 methods. Small interfaces are easier to implement, mock, and compose. If you need a larger contract, compose it from small interfaces:
→ See samber/cc-skills-golang@golang-naming skill for interface naming conventions (method + "-er" suffix, canonical names)
CODEBLOCK0
Compose larger interfaces from smaller ones:
CODEBLOCK1
Define Interfaces Where They're Consumed
Interfaces Belong to Consumers.
Interfaces MUST be defined where consumed, not where implemented. This keeps the consumer in control of the contract and avoids importing a package just for its interface.
CODEBLOCK2
The email package exports a concrete Client struct — it doesn't need to know about Sender.
Accept Interfaces, Return Structs
Functions SHOULD accept interface parameters for flexibility and return concrete types for clarity. Callers get full access to the returned type's fields and methods; consumers upstream can still assign the result to an interface variable if needed.
CODEBLOCK3
Don't Create Interfaces Prematurely
"Don't design with interfaces, discover them."
NEVER create interfaces prematurely — wait for 2+ implementations or a testability requirement. Premature interfaces add indirection without value. Start with concrete types; extract an interface when a second consumer or a test mock demands it.
CODEBLOCK4
Make the Zero Value Useful
Design structs so they work without explicit initialization. A well-designed zero value reduces constructor boilerplate and prevents nil-related bugs:
CODEBLOCK5
Avoid any / interface{} When a Specific Type Will Do
Since Go 1.18+, MUST prefer generics over any for type-safe operations. Use any only at true boundaries where the type is genuinely unknown (e.g., JSON decoding, reflection):
CODEBLOCK6
Key Standard Library Interfaces
| Interface | Package | Method |
|---|
| INLINECODE9 | INLINECODE10 | INLINECODE11 |
| INLINECODE12 |
io |
Write(p []byte) (n int, err error) |
|
Closer |
io |
Close() error |
|
Stringer |
fmt |
String() string |
|
error | builtin |
Error() string |
|
Handler |
net/http |
ServeHTTP(ResponseWriter, *Request) |
|
Marshaler |
encoding/json |
MarshalJSON() ([]byte, error) |
|
Unmarshaler |
encoding/json |
UnmarshalJSON([]byte) error |
Canonical method signatures MUST be honored — if your type has a String() method, it must match fmt.Stringer. Don't invent ToString() or ReadData().
Compile-Time Interface Check
Verify a type implements an interface at compile time with a blank identifier assignment. Place it near the type definition:
CODEBLOCK7
This costs nothing at runtime. If MyBuffer ever stops satisfying io.ReadWriter, the build fails immediately.
Type Assertions & Type Switches
Safe Type Assertion
Type assertions MUST use the comma-ok form to avoid panics:
CODEBLOCK8
Type Switch
Discover the dynamic type of an interface value:
CODEBLOCK9
Optional Behavior with Type Assertions
Check if a value supports additional capabilities without requiring them upfront:
CODEBLOCK10
This pattern is used extensively in the standard library (e.g., http.Flusher, io.ReaderFrom).
Struct & Interface Embedding
Struct Embedding
Embedding promotes the inner type's methods and fields to the outer type — composition, not inheritance:
CODEBLOCK11
The receiver of promoted methods is the inner type, not the outer. The outer type can override by defining its own method with the same name.
When to Embed vs Named Field
| Use | When |
|---|
| Embed | You want to promote the full API of the inner type — the outer type "is a" enhanced version |
| Named field |
You only need the inner type internally — the outer type "has a" dependency |
CODEBLOCK12
Dependency Injection via Interfaces
Accept dependencies as interfaces in constructors. This decouples components and makes testing straightforward:
CODEBLOCK13
In tests, pass a mock or stub that satisfies UserStore — no real database needed.
Struct Field Tags
Use field tags for serialization control. Exported fields in serialized structs MUST have field tags:
CODEBLOCK14
| Directive | Meaning |
|---|
| INLINECODE41 | Field name in JSON output |
| INLINECODE42 |
Omit field if zero value |
|
json:"-" | Always exclude from JSON |
|
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) |
Pointer vs Value Receivers
| Use pointer INLINECODE49 | Use value INLINECODE50 |
|---|
| Method modifies the receiver | Receiver is small and immutable |
Receiver contains sync.Mutex or similar |
Receiver is a basic type (int, string) |
| Receiver is a large struct | Method is a read-only accessor |
| Consistency: if any method uses a pointer, all should | Map and function values (already reference types) |
Receiver type MUST be consistent across all methods of a type — if one method uses a pointer receiver, all methods should.
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). Embed a noCopy sentinel to make go vet catch accidental copies:
CODEBLOCK15
INLINECODE55 reports an error if a ConnPool value is copied (passed by value, assigned, etc.). This is the same technique the standard library uses for sync.WaitGroup, sync.Mutex, strings.Builder, and others.
Always pass these structs by pointer:
CODEBLOCK16
Cross-References
- - → See
samber/cc-skills-golang@golang-naming skill for interface naming conventions (Reader, Closer, Stringer) - → See
samber/cc-skills-golang@golang-design-patterns skill for functional options, constructors, and builder patterns - → See
samber/cc-skills-golang@golang-dependency-injection skill for DI patterns using interfaces - → See
samber/cc-skills-golang@golang-code-style skill for value vs pointer function parameters (distinct from receivers)
Common Mistakes
| Mistake | Fix |
|---|
| Large interfaces (5+ methods) | Split into focused 1-3 method interfaces, compose if needed |
| Defining interfaces in the implementor package |
Define where consumed |
| Returning interfaces from constructors | Return concrete types |
| Bare type assertions without comma-ok | Always use
v, ok := x.(T) |
| Embedding when you only need a few methods | Use a named field and delegate explicitly |
| Missing field tags on serialized structs | Tag all exported fields in marshaled types |
| Mixing pointer and value receivers on a type | Pick one and be consistent |
| Forgetting compile-time interface check | Add
var _ Interface = (*Type)(nil) |
| Using
ToString() instead of
String() | Honor canonical method names |
| Premature interface with a single implementation | Start concrete, extract interface when needed |
| Nil map/slice in zero value struct | Use lazy initialization in methods |
| Using
any for type-safe operations | Use generics (
[T comparable]) instead |
角色设定： 你是一名 Go 类型系统设计师。你偏爱小巧、可组合的接口和具体的返回类型——你为可测试性和清晰度而设计，而非为了抽象而抽象。
社区默认规则。 明确覆盖 samber/cc-skills-golang@golang-structs-interfaces 技能的公司技能具有优先权。
Go 结构体与接口
接口设计原则
保持接口小巧
接口越大，抽象越弱。 —— Go 谚语
接口应包含 1-3 个方法。小巧的接口更易于实现、模拟和组合。如果你需要一个更大的契约，请从小接口组合而成：
→ 参见 samber/cc-skills-golang@golang-naming 技能以了解接口命名约定（方法 + -er 后缀，规范名称）
go
type Reader interface {
Read(p []byte) (n int, err error)
}
type Writer interface {
Write(p []byte) (n int, err error)
}
// 从小接口组合而成
type ReadWriter interface {
Reader
Writer
}
从较小的接口组合成更大的接口：
go
type ReadWriteCloser interface {
io.Reader
io.Writer
io.Closer
}
在消费方定义接口
接口属于消费者。
接口必须在消费方定义，而非实现方。这使消费者掌控契约，并避免仅仅为了接口而导入某个包。
go
// 包 notification —— 仅定义它所需的内容
type Sender interface {
Send(to, body string) error
}
type Service struct {
sender Sender
}
email 包导出一个具体的 Client 结构体 —— 它无需知道 Sender。
接受接口，返回结构体
函数应接受接口参数以获得灵活性，并返回具体类型以保证清晰度。调用方可以完全访问返回类型的字段和方法；上游的消费者仍可在需要时将结果赋值给接口变量。
go
// 好 —— 接受接口，返回具体类型
func NewService(store UserStore) *Service { ... }
// 差 —— 永远不要从构造函数返回接口
func NewService(store UserStore) ServiceInterface { ... }
不要过早创建接口
不要用接口来设计，而是去发现它们。
永远不要过早创建接口 —— 等待出现 2 个或更多实现，或出现可测试性需求。过早的接口只会增加间接性而无价值。从具体类型开始；当出现第二个消费者或测试模拟需求时，再提取接口。
go
// 差 —— 只有一个实现的过早接口
type UserRepository interface {
FindByID(ctx context.Context, id string) (*User, error)
}
type userRepository struct { db *sql.DB }
// 好 —— 从具体类型开始，需要时再提取接口
type UserRepository struct { db *sql.DB }
让零值有用
设计结构体使其无需显式初始化即可工作。设计良好的零值可以减少构造函数样板代码并防止与 nil 相关的错误：
go
// 好 —— 零值立即可用
var buf bytes.Buffer
buf.WriteString(hello)
var mu sync.Mutex
mu.Lock()
// 差 —— 零值不可用，需要构造函数
type Registry struct {
items map[string]Item // nil map，写入时会 panic
}
// 好 —— 惰性初始化保护零值
func (r *Registry) Register(name string, item Item) {
if r.items == nil {
r.items = make(map[string]Item)
}
r.items[name] = item
}
在具体类型可用时避免使用 any / interface{}
自 Go 1.18+ 起，对于类型安全操作，必须优先使用泛型而非 any。仅在类型真正未知的边界（例如 JSON 解码、反射）使用 any：
go
// 差 —— 丢失类型安全
func Contains(slice []any, target any) bool { ... }
// 好 —— 泛型，类型安全
func ContainsT comparable bool { ... }
关键标准库接口
| 接口 | 包 | 方法 |
|---|
| Reader | io | Read(p []byte) (n int, err error) |
| Writer |
io | Write(p []byte) (n int, err error) |
| Closer | io | Close() error |
| Stringer | fmt | String() string |
| error | builtin | Error() string |
| Handler | net/http | ServeHTTP(ResponseWriter, *Request) |
| Marshaler | encoding/json | MarshalJSON() ([]byte, error) |
| Unmarshaler | encoding/json | UnmarshalJSON([]byte) error |
必须遵守规范的方法签名 —— 如果你的类型有一个 String() 方法，它必须匹配 fmt.Stringer。不要发明 ToString() 或 ReadData()。
编译时接口检查
使用空白标识符赋值在编译时验证类型是否实现了接口。将其放在类型定义附近：
go
var _ io.ReadWriter = (*MyBuffer)(nil)
这在运行时没有任何开销。如果 MyBuffer 不再满足 io.ReadWriter，构建会立即失败。
类型断言与类型开关
安全的类型断言
类型断言必须使用逗号-ok 形式以避免 panic：
go
// 好 —— 安全
s, ok := val.(string)
if !ok {
// 处理
}
// 差 —— 如果 val 不是 string 则会 panic
s := val.(string)
类型开关
发现接口值的动态类型：
go
switch v := val.(type) {
case string:
fmt.Println(v)
case int:
fmt.Println(v * 2)
case io.Reader:
io.Copy(os.Stdout, v)
default:
fmt.Printf(unexpected type %T\n, v)
}
使用类型断言实现可选行为
检查值是否支持额外能力，而无需预先要求它们：
go
type Flusher interface {
Flush() error
}
func writeData(w io.Writer, data []byte) error {
if _, err := w.Write(data); err != nil {
return err
}
// 仅在 writer 支持时刷新
if f, ok := w.(Flusher); ok {
return f.Flush()
}
return nil
}
此模式在标准库中被广泛使用（例如 http.Flusher、io.ReaderFrom）。
结构体与接口嵌入
结构体嵌入
嵌入将内部类型的方法和字段提升到外部类型 —— 这是组合，而非继承：
go
type Logger struct {
*slog.Logger
}
type Server struct {
Logger
addr string
}
// s.Info(...) 有效 —— 通过 Logger 从 slog.Logger 提升而来
s := Server{Logger: Logger{slog.Default()}, addr: :8080}
s.Info(starting, addr, s.addr)
提升方法的接收者是内部类型，而非外部类型。外部类型可以通过定义同名方法来覆盖。
何时嵌入 vs 命名字段
| 使用场景 | 何时使用 |
|---|
| 嵌入 | 你想提升内部类型的完整 API —— 外部类型是增强版 |
| 命名字段 |
你仅在内部需要内部类型 —— 外部类型有一个依赖 |
go
// 嵌入 —— Server 暴露所有 http.Handler 方法
type Server struct {
http.Handler
}
// 命名字段 —— Server 使用 store 但不暴露其方法
type Server struct {
store *DataStore
}
通过接口进行依赖注入
在构造函数中将依赖项作为接口接受。这可以解耦组件并使测试变得直接：
go
type UserStore interface {
FindByID(ctx context.Context, id string) (*User, error)
}
type UserService struct {
store UserStore
}
func NewUserService(store UserStore) *UserService {
return &UserService{store: store}
}
在测试中，传递一个满足 UserStore 的模拟或桩 —— 无需真实数据库。
结构体字段标签
使用字段标签进行序列化控制。序列化结构体中的导出字段必须具有字段标签：
go
type Order struct {
ID string json:id db:id
UserID string json:userid db:userid
Total float64 json:total db:total
Items []Item json:items db:-
CreatedAt time.Time json:createdat db:createdat
DeletedAt time.Time json:- db:deleted_at
Internal string json:-
