Go 接口与泛型

接口定义与隐式实现、类型断言、空接口 any、nil interface 陷阱、泛型类型参数与约束、Go 1.23–1.27 泛型逐步增强（含 1.27 泛型方法解禁）完整速查。基线 go1.27.0，文中示例与输出均为实测。

1. 接口基础

接口定义

// 接口是一组方法签名的集合
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
}

// 也可以混入普通方法签名
type ReadWriteCloser interface {
    Reader
    Writer
    Close() error
}

Go 惯例：接口名以 -er 结尾（Reader、Writer、Closer、Stringer），不要加 I 或 Interface 前缀。单方法接口是 Go 的哲学——接口越大，越难复用。

接口的隐式实现（核心设计）

Go 的接口是隐式满足的——不需要显式声明 implements：

import "io"

type Reader interface {
    Read(p []byte) (n int, err error)
}

// File 没有声明"实现 Reader"，但只要它有 Read 方法，就自动满足接口
type File struct {
    data []byte
    off  int
}

func (f *File) Read(p []byte) (n int, err error) {
    if f.off >= len(f.data) {
        return 0, io.EOF
    }
    n := copy(p, f.data[f.off:])
    f.off += n
    return n, nil
}

// 随时随地使用——不需要改动 File 的代码
var r Reader = &File{data: []byte("hello")}

// 甚至可以为标准库外的类型定义接口，第三方类型只要方法齐全照样满足

对比 Java/C#：那边是"名义类型"（必须写 implements），Go 是结构类型——只看方法集是否匹配。这个差别决定了下面几条工程优势。

隐式接口的优势：

解耦：实现方不需要导入接口所在的包，os.File 从未 import 过你的包，却能传进你的函数
后验抽象：先写具体类型，用到第二家时再在使用方抽出接口，不用预先设计
最小接口：定义小而精准的接口（1–3 个方法），而不是 Java 式的大而全接口

生产里常用一个编译期断言来锁定"某类型必须满足某接口"，防止后续重构无声破坏契约：

var _ Reader = (*File)(nil)   // 若 *File 不再实现 Reader，编译直接报错

注意：标准库推崇**“在消费方定义接口”**、接口尽量小、接受接口返回结构体（Accept interfaces, return structs），这类风格取舍的完整讨论见 12-地道代码风格.md。

最常实现的几个标准接口

这四个接口覆盖了日常实现的大半场景，值得背下来：

接口	所在包	签名	用途
`Stringer`	`fmt`	`String() string`	控制 `%v` 打印格式
`error`	内建	`Error() string`	所有错误值的契约
`Reader` / `Writer`	`io`	`Read/Write(p []byte) (int, error)`	流式 IO 的通用协议
`Interface`	`sort`	`Len()/Less(i,j)/Swap(i,j)`	自定义排序

type Pair struct{ n int }

func (p Pair) String() string { return fmt.Sprintf("n=%d", p.n) }

fmt.Println(Pair{2})   // n=2（fmt 自动调用 String 方法）

2. 空接口（interface{} / any）

// Go 1.18 前
var x interface{} = "hello"

// Go 1.18+：any 是 interface{} 的别名，语义更清晰
var y any = "hello"

空接口保存任意类型——它是最广泛的接口（零方法，所有类型都满足）。

var items []any = []any{1, "two", 3.0, true}
for _, item := range items {
    fmt.Printf("type=%T value=%v\n", item, item)
}
// type=int value=1
// type=string value=two
// type=float64 value=3
// type=bool value=true

注意：值装进接口时有装箱开销（数据可能要分配到堆上，并附带一份类型信息）。热路径中避免不必要的接口装箱；泛型（§5）正是 1.18 为"既要任意类型、又不想装箱"准备的替代方案。

3. 类型断言

var x any = "hello"

s := x.(string)        // OK: s = "hello"
// n := x.(int)        // panic: interface conversion: interface {} is string, not int

str, ok := x.(string)  // str="hello", ok=true
num, ok := x.(int)     // num=0, ok=false（不 panic，双返回值形式永远安全）

if v, ok := x.(string); ok {
    fmt.Println("string:", v)
}

单返回值形式断言失败即 panic，只在"确定不可能失败"或快速原型里用；生产代码一律用 comma-ok 双返回值。

type switch（类型分支）

func describe(v any) {
    switch t := v.(type) {
    case int:
        fmt.Printf("int: %d\n", t)
    case string:
        fmt.Printf("string: %s\n", t)
    case []byte:
        fmt.Printf("[]byte: %v\n", t)
    case nil:
        fmt.Println("nil")
    default:
        fmt.Printf("unknown: %T\n", t)
    }
}

describe(42)   // int: 42

4. 接口底层实现（深入原理）

eface vs iface

以下是 Go runtime 源码（src/runtime/runtime2.go）中的两种接口表示，不是用户代码——理解它们才能解释下面所有 nil 陷阱：

// eface：空接口（无方法），只存类型 + 数据指针
type eface struct {
    _type *_type         // 具体类型的类型信息
    data  unsafe.Pointer // 数据指针
}

// iface：有方法的接口，存 tab（含方法表）+ 数据指针
type iface struct {
    tab  *itab           // 接口类型 + 具体类型 + 方法表
    data unsafe.Pointer
}

type itab struct {
    inter  *interfacetype // 接口类型信息
    _type  *_type         // 具体类型信息
    hash   uint32         // 类型哈希（用于类型断言快速比较）
    fun    [1]uintptr     // 方法表（可变大小）
}

一句话模型：接口值 = (类型, 数据) 两个字。i == nil 当且仅当两个字段都为 nil。

interface nil 陷阱

var p *int = nil
var i any = p

fmt.Println(p == nil)   // true
fmt.Println(i == nil)   // false！i 的 data 是 nil，但 _type 是 *int——typed-nil 装进接口后不再是 nil 接口

// 实测输出：
// p==nil:true i==nil:false

最常见、最阴险的出错场景在 error 返回：

type MyError struct{ Msg string }

func (e *MyError) Error() string { return e.Msg }

func getError() error {
    var err *MyError = nil
    return err            // 返回的 error 不是 nil！type=*MyError, data=nil
}

// 实测：getError() == nil 为 false——调用方 if err != nil 会误判"出错了"

修正：错误路径上直接 return nil，不要把先声明成具体指针类型的变量原样返回：

func getError() error {
    if false { // 假设这里出了问题
        return &MyError{Msg: "boom"}
    }
    return nil            // 直接返回字面量 nil
}

注意：错误处理链路里 typed-nil 还会和 errors.Is/As 纠缠，更多细节见 07-错误处理.md。

5. 泛型（Go 1.18+）

泛型函数

1.18 之前，对 int/float64 各写一份"同逻辑"函数，或者退回 interface{} 装箱：

func MaxInt(a, b int) int {         // Go 1.18 前的写法
    if a > b {
        return a
    }
    return b
}

func MaxFloat64(a, b float64) float64 {
    if a > b {
        return a
    }
    return b
}

Go 1.18+ 一个函数搞定：

import "cmp"

func Max[T cmp.Ordered](a, b T) T {
    if a > b {
        return a
    }
    return b
}

x := Max[int](3, 5)               // 显式指定类型参数
y := Max(3.14, 2.71)              // 类型推断
z := Max("abc", "xyz")            // string 也是有序类型，照样能比

fmt.Println(x, y, z)              // 实测输出：5 3.14 xyz

cmp.Ordered 是 1.21 进标准库的版本；更早期的资料里写的 golang.org/x/exp/constraints.Ordered 是同一个东西的临时住所。

泛型类型

type Stack[T any] struct {
    items []T
}

func (s *Stack[T]) Push(item T) {
    s.items = append(s.items, item)
}

func (s *Stack[T]) Pop() (T, bool) {
    if len(s.items) == 0 {
        var zero T
        return zero, false
    }
    item := s.items[len(s.items)-1]
    s.items = s.items[:len(s.items)-1]
    return item, true
}

func main() {
    s := Stack[int]{}
    s.Push(10)
    s.Push(20)
    v, _ := s.Pop()               // v = 20
    fmt.Println("stack pop:", v)  // 实测输出：stack pop: 20
}

零值惯用法：泛型里取"某类型的零值"用 var zero T，不能用 T(0)（T 未必是数值类型）。

泛型约束

约束本质仍是接口，只是允许写类型集合（type set）：

// 精确类型联合：只允许这三种类型本身，自定义类型（type MyInt int）不行
type ThreeNumber interface {
    int | int64 | float64
}

// ~ 前缀：包含所有"底层类型"是这些的类型
type Number interface {
    ~int | ~int64 | ~float64
}
func Sum[T Number](values []T) T {
    var total T
    for _, v := range values {
        total += v
    }
    return total
}

// 组合约束：类型集合 + 方法集
type ComparableHasher interface {
    comparable                     // 可比较
    Hash() uint64                  // 必须有 Hash 方法
}

// 近似约束的典型用法
type AnyString interface {
    ~string                        // 底层为 string 的所有类型
}
func Concat[T AnyString](parts []T) string {
    var b strings.Builder
    for _, p := range parts {
        b.WriteString(string(p))
    }
    return b.String()
}

type MyStr string

fmt.Println(Concat([]MyStr{"foo", "bar"}))   // 实测输出："foobar"

注意：嵌了 comparable 的接口（如上面的 ComparableHasher）只能当类型约束用，不能当普通变量类型——var ch ComparableHasher 会报编译错误 cannot use type ComparableHasher outside a type constraint: interface is (or embeds) comparable（实测）。

常用约束速查

约束	说明	可用版本
`any`	任意类型（`interface{}` 别名）	Go 1.18+
`comparable`	可使用 `==` `!=` 比较的类型（map/slice/函数不可）	Go 1.18+
`cmp.Ordered`	全部整数/浮点 + string（支持 `<` `>`）	Go 1.21+（此前用 `x/exp/constraints.Ordered`）
`~int \| ~int64 \| ~float64`	自定义类型集（`~` = 含底层为这些类型的自定义类型）	Go 1.18+

用 go doc 查看约束的真实定义

约束就是类型集合，与其背文档不如直接看：

$ go doc cmp.Ordered
package cmp // import "cmp"

type Ordered interface {
        ~int | ~int8 | ~int16 | ~int32 | ~int64 |
                ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
                ~float32 | ~float64 |
                ~string
}
    Ordered is a constraint that permits any ordered type: any type that
    supports the operators < <= >= >. If future releases of Go add new ordered
    types, this constraint will be modified to include them.

（实测输出节选，完整文档注释还包含浮点 NaN 比较的说明；1.27 起 go doc pkg@version 还能直接查其他版本的文档。）

类型推断（Go 1.27 起大幅放宽）

基础用法自古有之——参数类型能推就推：

y := Max(3.14, 2.71)      // 从实参推断 T = float64

Go 1.27 的新变化（官方 release notes 称 “generalized function type inference”，实测）：泛型函数被赋值或转换为具体函数类型时，也能在全上下文推断类型参数了。1.26 及以前，这类位置必须显式实例化 Max[int]：

var f func(int, int) int = Max                    // 从目标类型推断 T = int
var g func(float64, float64) float64 = Max

fmt.Println(f(4, 7))                              // 实测输出：7
fmt.Println(g(2.5, 1.0))                          // 实测输出：2.5

func apply[T cmp.Ordered](fn func(T, T) T, a, b T) T { return fn(a, b) }

fmt.Println(apply(Max, 8, 2))                     // 作为实参传递也可推断，实测输出：8

这让泛型函数能直接塞进回调、排序比较器等"函数类型槽位"，不必再写 Max[int] 这种样板。

泛型与接口的区别

维度	接口	泛型
多态时间	运行时（动态分发）	编译期（静态单态化）
性能	有虚调用开销（itab 查表）+ 装箱	接近零开销
共同行为	可以放同一容器（`[]Reader`）	不同类型实例不能放同一容器
代码膨胀	无	每种类型生成一份代码
适用场景	行为抽象，多态容器	算法复用，数据结构复用

当你需要"不同类型有共同行为"用接口；需要"同一个算法/数据结构适用于多种类型"用泛型。不要为了泛型而泛型。

泛型使用建议

// 适合：数据结构
type Set[T comparable] map[T]struct{}

// 适合：算法函数
func Map[T, U any](slice []T, fn func(T) U) []U
func Filter[T any](slice []T, pred func(T) bool) []T
func Reduce[T, U any](slice []T, initial U, fn func(U, T) U) U

// 不适合：只有一两个调用方的简单函数——直接写具体类型更清晰
func Add[T int | float64](a, b T) T { return a + b }   // 过度工程

// 不适合：需要"不同类型不同实现"的场景——那是接口的主场

完整取舍清单见 12-地道代码风格.md。

6. 泛型与类型系统的逐版本增强

Go 1.23：range 迭代器（正式版）

import "iter"

// iter.Seq[V]：单值迭代器 func(func(V) bool)
// iter.Seq2[K, V]：双值迭代器 func(func(K, V) bool)

func Backward[E any](s []E) iter.Seq2[int, E] {
    return func(yield func(int, E) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(i, s[i]) {
                return
            }
        }
    }
}

for i, v := range Backward([]int{1, 2, 3}) {
    fmt.Println("backward:", i, v)
}
// 实测输出：
// backward: 2 3
// backward: 1 2
// backward: 0 1

// slices / maps 包提供大量现成迭代器，可互相组合
m := map[string]int{"a": 1, "b": 2}
fmt.Println(slices.Collect(maps.Keys(m)))   // 实测输出：[a b]

Go 1.24：泛型类型别名

// 类型别名可以带类型参数（issue #46477，1.24 正式版默认开启）
type Vector[T any] []T

type VectorAlias[T any] = Vector[T]     // 泛型类型别名

v := VectorAlias[int]{1, 2}
fmt.Println("alias:", v)                // 实测输出：alias: [1 2]

用途：给复杂泛型签名起短名，减少重复书写。

Go 1.25：规范移除"核心类型"概念

1.25 release notes 原文：“in the language specification the notion of core types has been removed in favor of dedicated prose”。语言行为不变，是规范层面的简化——泛型操作（索引、切片、算术等）现在直接在类型集合层面逐成员定义合法性：

type SliceOrString interface {
    ~[]byte | ~string
}

func First[T SliceOrString](s T) byte { return s[0] }   // 两个成员类型都支持 s[0] → byte

fmt.Println(First("go"), First([]byte{9, 8}))
// 实测输出：103 9（'g' 的字节值；[]byte{9,8} 的首元素）

Go 1.26：自引用泛型类型

1.26 解除了"类型参数不能在自己的约束里被引用"的限制，CRTP 式递归约束终于可写：

// Go 1.26+：A 的约束可以引用 A 自身
type Adder[A Adder[A]] interface {
    Add(A) A
}

type Vec struct{ x, y int }

func (v Vec) Add(o Vec) Vec { return Vec{v.x + o.x, v.y + o.y} }

func Sum[A Adder[A]](x, y A) A { return x.Add(y) }

fmt.Printf("adder-sum: %+v\n", Sum(Vec{1, 2}, Vec{10, 20}))
// 实测输出：adder-sum: {x:11 y:22}

这让树节点、图节点、多维向量等"操作返回自己类型"的递归数据结构能被泛型函数统一描述。

Go 1.27：泛型方法解禁（方法可以声明类型参数）

这是本文件曾经记载过的过时结论的修正：Go 1.27 之前，“方法不能带自己的类型参数"确实是铁律（当时只能用包级泛型函数绕行）；1.27 起这条限制作废，普通类型和泛型类型的方法都可以声明自己的类型参数，泛型类型的方法还能在类型参数的基础上再引入新的。

例 1：普通类型上声明泛型方法（实测编译+运行通过）：

type Number interface{ ~int | ~int64 | ~float64 }

type Stats struct {
    sum   float64
    count int
}

// 类型参数 [T Number] 属于方法本身，与接收者无关
func (s *Stats) Add[T Number](vals ...T) {
    for _, v := range vals {
        s.sum += float64(v)
        s.count++
    }
}

stats := &Stats{}
stats.Add(1, 2, 3)        // T 推断为 int
stats.Add(10.0)           // T 推断为 float64
fmt.Printf("stats sum: %v count: %d\n", stats.sum, stats.count)
// 实测输出：stats sum: 16 count: 4

例 2：泛型类型的方法再引入新类型参数——1.27 前最典型的痛点（跨元素类型转换容器）现在有解了：

type Stack[T any] struct{ items []T }

func (s *Stack[T]) Push(item T) { s.items = append(s.items, item) }
func (s *Stack[T]) String() string { return fmt.Sprintf("%v", s.items) }

// 接收者带着 T，方法再带 U：*Stack[int] 直接变 *Stack[Pair]
func (s *Stack[T]) MapTo[U any](fn func(T) U) *Stack[U] {
    out := &Stack[U]{}
    for _, v := range s.items {
        out.Push(fn(v))
    }
    return out
}

type Pair struct{ n int }
func (p Pair) String() string { return fmt.Sprintf("n=%d", p.n) }

base := &Stack[int]{}
base.Push(1)
base.Push(2)
mapped := base.MapTo(func(i int) Pair { return Pair{n: i * 2} })   // T=int, U=Pair
fmt.Println("mapped:", mapped)
// 实测输出：mapped: [n=2 n=4]

1.26 及以前只能写成包级函数 func MapStack[T, U any](s *Stack[T], fn func(T) U) *Stack[U]，调用时类型参数散落两处、可读性差；现在链式方法 s.MapTo(...).MapTo(...) 成为可能。

标准库官方示例（1.27 release notes）：math/rand/v2 的 Rand 新增方法 (*Rand) N[Int intType](n Int) Int——此前泛型 N 只有包级函数 rand.N，Rand 实例上根本没有对应方法，1.27 把它补成了方法：

rng := rand.New(rand.NewPCG(1, 2))
fmt.Println(rng.N[int](100), rng.N(50))   // 前者显式指定；后者类型参数可推断（int）
// 实测输出（固定种子 1,2）：76 30

边界没有变：接口方法依然禁止类型参数，泛型方法也不能用来满足接口——详见 §7.5，那是这个新特性最容易被误用的地方。

注意（版本门控）：泛型方法由 go.mod 的 go 指令门控，要求 go ≥ 1.27。在 go 1.26 的模块里写 func (s *Stats) Add[T Number](vals ...T)，编译报错（实测）： generic method requires go1.27 or later (-lang was set to go1.26; check go.mod) 库作者尤其注意：发布含泛型方法的包，意味着把最低 go 版本要求抬到 1.27。

7. 常见陷阱

7.1 nil interface 不等于 nil

见 §4 黄金法则：返回 error 时，直接 return nil，不要 var err *MyError = nil; return err。接口值是 (类型, 数据) 两个字，typed-nil 装进接口后 == nil 为 false（实测 getError()==nil: false）。

7.2 类型断言失败 panic

var x any = "hello"
// _ = x.(int)     // 单返回值形式，运行时 panic（实测）：
// panic: interface conversion: interface {} is string, not int

总是用双返回值 v, ok := x.(string) 或 type switch。

7.3 指针接收者与接口实现

type Greeter interface{ Greet() string }

type Person struct{ Name string }

func (p *Person) Greet() string { return "Hi " + p.Name }

var g Greeter
// g = Person{Name: "Bob"}   // 编译错误：Person 没实现 Greeter（只有 *Person 实现了）
g = &Person{Name: "Bob"}     // OK

方法集规则：指针接收者的方法只属于 *T，值类型 T 不满足接口。接收者该用值还是指针的选择指南见 05-函数与方法.md。

7.4 接口值里放不可比较类型，== 比较时 panic

var x any = map[string]int{"a": 1}
_ = x == x        // 编译通过（接口类型间允许比较），运行时 panic（实测）：
// panic: runtime error: comparing uncomparable type map[string]int

比较发生在运行时的动态类型上：编译器只看接口静态类型，runtime 检查实际装的是不是 map/slice/func。comparable 约束（§5）挡不住 []any 里的元素两两比较，做集合/去重逻辑时要警惕。

7.5 接口方法仍然禁止类型参数；泛型方法无法满足接口

先纠正旧结论：本节在旧版手册里写的是"Go 不支持泛型方法”——该说法已在 Go 1.27 作废，方法可以声明自己的类型参数，正例与实测输出见 §6。但接口的边界没有松，1.27 release notes 在同一段落里特意补了一句：“Note that methods of interfaces may not declare type parameters nor can interface methods be implemented by generic methods.”

其一，接口方法不能带类型参数（1.27 实测仍是编译错误）：

type I interface {
    Do[T any](v T)     // 编译错误（实测）：interface method must have no type parameters
}

其二，类型上的泛型方法不算实现了同名接口方法（实测）：

type Greeter interface{ Greet(name string) }

type Bot struct{}

// 这是合法的泛型方法（1.27），但……
func (b Bot) Greet[T ~string](name T) { _ = name }

var _ Greeter = Bot{}
// 编译错误（实测）：
// cannot use Bot{} (value of struct type Bot) as Greeter value in variable declaration:
//         Bot does not implement Greeter (wrong type for method Greet)
//                 have Greet[T ~string](T)
//                 want Greet(string)

为什么这条边界留着：接口调用是运行时动态分发——编译器生成调用时只认识接口的 itab 方法表，表里每一项必须是固定签名。若 Do[T any] 可以放进接口，调用点写 i.Do(v) 时 T 要等运行时才知道，而泛型的单态化必须在编译期落定实例，两者根本对不上。泛型解决"编译期知道类型"的问题，接口解决"运行时才知道类型"的问题；泛型方法进接口等于要求编译器对无限多个实例都备好方法表。

替代方案（1.26 及以前处理这类需求的办法依然有效）：

调用方显式实例化后当普通方法/函数用：s.Do[int](v) 满足不了 Do(string)，那就老老实实定义 Do(string)，泛型逻辑放包级函数里
用包级泛型函数承接跨类型操作：func MapStack[T, U any](s *Stack[T], fn func(T) U) *Stack[U]
类型确实要进方法签名集合，用 any + 类型断言回到接口老路

8. 实战建议

接口优先小而稳：消费方定义 1–3 个方法的接口，配 var _ Itf = (*Impl)(nil) 编译断言；大接口重构时才抽。
error 返回永远 return nil：typed-nil 是本项目最高频事故点（§4/§7.1），代码评审盯紧"声明了具体指针类型的 err 变量再原样返回"。
泛型用在有第二、第三个具体类型调用方时：只有一个实现的 Add[T int|float64] 是负资产；容器（Set/Stack/Cache）和纯算法（Map/Filter/Reduce）最适合泛型。
新项目基线放心用 1.27 泛型方法：写库前确认 go.mod go ≥ 1.27，并在 README 注明；给老项目（go < 1.27）贡献代码时记住泛型方法会被版本门控拒掉（§6 末尾错误串）。
两条红线别碰（§7.5）：接口方法不能带类型参数、泛型方法满足不了接口。设计 API 时如果"接口里的方法想要类型参数"，通常意味着这个抽象本身该拆——把变化点挪到包级泛型函数，或换成 any+断言。
比较含 map/slice 的接口值前先探类型：== 的 panic 发生在运行时（§7.4），去重/集合逻辑改用具体类型，或显式语义比较（slices.Equal、bytes.Equal 等）。
更多跨主题陷阱与最佳实践汇总见 11-最佳实践与陷阱.md，风格取舍见 12-地道代码风格.md，各版本语言变更时间线见 10-版本变迁.md。

Go 函数与方法 Go 错误处理