# 方法

Source: https://codewiki.com/zh/go/methods/

> - **what**: 方法是带有接收者参数的函数，它把行为关联到当前包中定义的类型，并参与接口满足关系。
> - **trap**: `value.M()` 能编译，不代表值类型一定拥有 `M`；可寻址值调用指针接收者方法时，编译器可能隐式取地址。
> - **fix**: 先按复制、修改和标识语义选择接收者，再分别验证 `T` 与 `*T` 的方法集和接口赋值。

## 是什么，为什么存在

方法（method）是一种带有特殊接收者参数的函数。接收者（receiver）写在 `func` 与方法名之间，用来确定方法关联的类型；调用方则通过 `value.Method()` 选择它。Go 没有类，但命名类型可以拥有方法，因此数据表示与行为可以形成清楚的 API。

方法不只属于结构体。只要接收者的基类型是在当前包中定义的非指针、非接口类型，整数、字符串、切片等底层表示的命名类型也能声明方法。这个限制让定义类型的包控制其方法集合，其他包不能给它“补”方法。

普通函数把所有输入都列在参数表中，方法则把一个输入放在接收者位置。这个区别会影响名称查找、方法值、方法表达式以及接口实现，但不会自动带来继承、构造器或动态重写。把 Go 方法直接套进传统类体系，往往会误判嵌入和提升的语义。

方法让不同类型可以复用 `String`、`Read` 或 `ServeHTTP` 等短名称，而不必在包级命名空间中加入类型前缀。更重要的是，接口根据方法集隐式判断类型是否满足契约。你会在领域值、可变服务、标准库接口、嵌入组件和泛型类型上遇到方法。

## 工作原理

### 接收者决定复制边界

值接收者写作 `(v T)`。调用时，接收者按普通赋值规则复制到方法参数中；重新给字段赋值只改变副本。这个复制是逐字段复制而不是递归深拷贝，因此副本中的切片、映射、指针或接口仍可能访问共享的可变数据。

指针接收者写作 `(p *T)`。方法得到一个指向值的指针，所以可以修改该值，也能让多个调用共享同一标识。需要修改接收者、避免复制含锁的值，或类型本身代表具有身份的可变对象时，通常应使用指针接收者。

只读并不自动等于值接收者，结构体较大也不自动等于指针接收者。先判断复制后是否仍保持正确语义，再考虑一致性和经过测量的成本。一个类型的部分方法若必须使用指针接收者，其余方法通常也使用指针接收者，这样接口方法集与使用方预期更稳定。

| 声明 | 方法体接收的内容 | 能否直接替换调用方的字段 | 典型语义 |
|---|---|---|---|
| `func (v T) M()` | `T` 的一份浅复制 | 否 | 小型值、不可变式操作 |
| `func (p *T) M()` | 指向 `T` 的指针 | 是 | 修改、身份、不可复制状态 |

### 方法调用包含可寻址性便利规则

如果 `x` 可寻址，而且 `*T` 的方法集中有 `M`，那么 `x.M()` 可以作为 `(&x).M()` 的简写。局部变量通常可寻址，所以值变量经常能直接调用指针接收者方法。这个语法便利不会把 `M` 加进 `T` 的方法集。

映射元素通常不可寻址，因为映射实现可能移动条目。若 `users` 的元素类型是 `User`，而 `Rename` 只有 `*User` 接收者，`users[id].Rename(...)` 就不能依赖隐式取地址。应先取出、修改再写回，或者按所有权需求把映射元素改为 `*User`。

反方向也有选择器便利：`*T` 可以调用 `T` 的值接收者方法，调用时会取得指针所指值的副本。若指针为 `nil`，这一步无法产生 `T` 值，会在进入方法体前发生 panic。只有指针接收者方法才有机会把 `nil` 当作显式状态处理。

### 方法集决定接口满足关系

方法集（method set）是与某个类型关联、可用于接口判断的方法集合。对已定义的非指针、非接口类型 `T`，基础规则很短：`T` 的方法集只包含接收者为 `T` 的方法，`*T` 的方法集同时包含接收者为 `T` 与 `*T` 的方法。

| 静态类型 | 方法集中包含的声明 |
|---|---|
| `T` | `func (T) M(...)` |
| `*T` | `func (T) M(...)` 与 `func (*T) M(...)` |

因此，只有指针接收者方法时，通常是 `*T` 而不是 `T` 满足相应接口。接口赋值不会应用 `x.M()` 的隐式取地址规则，因为接口中保存的是值的副本，未必存在可取地址的原始变量。编译期断言 `var _ Interface = (*T)(nil)` 能把这个选择写进代码并防止后续签名漂移。

接收者名称不参与方法签名，可以使用简短且一致的名称。方法能否满足接口取决于方法名、参数和结果类型是否完全匹配；“看起来兼容”的参数类型不会发生协变或自动适配。接口契约的详细设计属于 `go/interfaces`，这里的方法集是两者之间的连接点。

### 方法值会保存接收者

表达式 `x.M` 是方法值（method value）。求值时会计算并保存接收者，结果是一个不再显式接收该参数的函数值。值接收者会保存当时的值副本；指针接收者会保存当时算出的指针，因此之后通过同一指针发生的修改仍然可见。

表达式 `T.M` 或 `(*T).M` 是方法表达式（method expression）。它不会绑定某个接收者，而是生成把接收者作为第一个普通参数的函数。方法表达式适合适配回调或把同一操作应用到多个值，方法值则适合把一个具体对象的操作交给其他代码。

方法值在创建时就求值接收者，这与 `defer` 和 `go` 语句中的方法调用尤其相关。若生成代码假设接收者会在稍后才查找，观察到的可能是旧副本；若保存的是指针，又可能观察到后续修改。审查时需要明确保存的是值还是指针。

### 嵌入可以提升方法

结构体嵌入字段后，路径唯一的方法可以通过外层值的短选择器访问，这称为提升（promotion）。提升不会复制方法，也不会把外层类型变成内层类型；完整路径仍然存在，例如 `service.Logger.SetPrefix(...)`。

外层类型声明同名方法时，短选择器会选择外层方法。多个相同最浅深度的嵌入路径都提供同名方法时，短选择器会产生歧义，必须写出完整路径。提升影响外层方法集，从而也可能让外层类型满足一个接口。

## 示例

### 值接收者与指针接收者

第一个示例把读取与修改放在同一类型上。`Rename` 修改值接收者的副本，所以名称保持不变；`Add` 通过指针修改调用方。

<!-- quick -->

```go
// file: receivers.go
package main

import "fmt"

type Counter struct {
	Name  string
	Total int
}

func (c Counter) Rename(name string) {
	c.Name = name
}

func (c *Counter) Add(delta int) {
	c.Total += delta
}

func (c Counter) Snapshot() string {
	return fmt.Sprintf("%s=%d", c.Name, c.Total)
}

func main() {
	counter := Counter{Name: "orders", Total: 10}
	counter.Rename("archived")
	counter.Add(5)
	fmt.Println(counter.Snapshot())

	copied := counter
	copied.Add(2)
	fmt.Println(counter.Snapshot())
	fmt.Println(copied.Snapshot())
}
```

```text
orders=15
orders=15
orders=17
```

<!-- /quick -->

`counter` 是可寻址的局部变量，因此 `counter.Add(5)` 会隐式取地址。把它赋给 `copied` 后，两者是两个独立的纯值；对 `copied` 取地址并修改，不会回到原来的 `counter`。

这个例子没有切片、映射或指针字段，所以结构体复制形成完整独立状态。若加入这些字段，仍要逐字段判断别名关系，不能从值接收者三个字推断深拷贝。

### 调用能力与接口能力

第二个示例把可寻址调用与方法集分开。`User` 和 `*User` 都拥有值接收者 `String`，但只有 `*User` 拥有指针接收者 `Rename`。

```go
// file: method_sets.go
package main

import "fmt"

type Renamer interface {
	Rename(string)
}

type User struct {
	Name string
}

func (u User) String() string {
	return u.Name
}

func (u *User) Rename(name string) {
	u.Name = name
}

var _ fmt.Stringer = User{}
var _ fmt.Stringer = (*User)(nil)
var _ Renamer = (*User)(nil)

func main() {
	user := User{Name: "Mina"}
	user.Rename("Lin")
	fmt.Println(user)

	var named fmt.Stringer = user
	var renamer Renamer = &user
	renamer.Rename("Ari")
	fmt.Println(named, user)
}
```

```text
Lin
Lin Ari
```

`user.Rename("Lin")` 能编译，因为 `user` 可寻址。相反，`var _ Renamer = User{}` 会编译失败，所以示例只对 `*User` 写出 `Renamer` 断言。

赋给 `named` 的接口值保存了当时 `user` 的一份副本，后面的重命名不会改变它。`renamer` 保存 `&user`，所以调用会修改原变量；最后一行同时显示旧副本 `Lin` 与当前值 `Ari`。

### 方法值与方法表达式

第三个示例把接收者求值时机变成可观察结果。`preview` 绑定值接收者，`deposit` 绑定指针接收者，而 `calculate` 要求调用方显式传入接收者。

```go
// file: method_values.go
package main

import "fmt"

type Account struct {
	Balance int
}

func (a Account) BalanceAfter(delta int) int {
	return a.Balance + delta
}

func (a *Account) Deposit(amount int) {
	a.Balance += amount
}

func main() {
	account := Account{Balance: 100}
	preview := account.BalanceAfter
	deposit := account.Deposit
	calculate := Account.BalanceAfter

	account.Balance = 200
	fmt.Println(preview(10))

	deposit(25)
	fmt.Println(calculate(account, 10))
	fmt.Println(account.Balance)
}
```

```text
110
235
225
```

`preview` 在余额还是 `100` 时保存了一份 `Account`，所以结果是 `110`。`deposit` 保存指向原账户的指针，把当前余额从 `200` 改为 `225`。

方法表达式 `Account.BalanceAfter` 没有保存账户。调用 `calculate(account, 10)` 时才显式传入当前值，因此得到 `235`，同时值接收者不会修改 `account.Balance`。

### 嵌入方法的提升与遮蔽

最后一个示例嵌入 `*Logger`。`SetPrefix` 被提升到 `Service`，而外层 `Label` 会遮蔽提升来的同名方法；显式路径仍可选择内层方法。

```go
// file: promotion.go
package main

import "fmt"

type Logger struct {
	Prefix string
}

func (l Logger) Label() string {
	return "logger:" + l.Prefix
}

func (l *Logger) SetPrefix(prefix string) {
	l.Prefix = prefix
}

type Service struct {
	*Logger
	Name string
}

func (s Service) Label() string {
	return "service:" + s.Name
}

type PrefixSetter interface {
	SetPrefix(string)
}

var _ PrefixSetter = Service{}

func main() {
	service := Service{Logger: &Logger{Prefix: "dev"}, Name: "api"}
	fmt.Println(service.Label())
	fmt.Println(service.Logger.Label())

	var setter PrefixSetter = service
	setter.SetPrefix("prod")
	fmt.Println(service.Logger.Label())
}
```

```text
service:api
logger:dev
logger:prod
```

嵌入 `*Logger` 时，它的值接收者与指针接收者方法都会提升到 `Service` 和 `*Service` 的方法集。因此示例中的 `Service{}` 编译期断言成立。

把 `service` 复制进接口也复制了嵌入指针，而不是复制 `Logger` 目标。接口中的副本与原变量仍指向同一个 `Logger`，所以通过 `setter` 修改前缀后，显式路径读到 `prod`。

## 陷阱

### 修改方法误用值接收者

> **陷阱:** 生成或重构代码时把修改方法写成值接收者，方法可以正常返回，却只改了副本。若字段包含切片或映射，部分修改又可能泄漏到底层共享数据，使行为更不一致。

**修复方法：** 对修改、身份或不可复制状态使用指针接收者，并用调用后的状态断言验证效果。对含引用语义字段的值接收者，逐字段记录别名与所有权；需要快照时显式克隆对应层级。

### 把可调用误认为满足接口

> **陷阱:** `x.M()` 编译通过后，代码就假定 `T` 满足要求 `M` 的接口。若 `M` 的接收者是 `*T`，可寻址性只是帮这次调用取了地址，`T` 的方法集并没有变化。

**修复方法：** 在契约附近分别写 `var _ I = T{}` 或 `var _ I = (*T)(nil)`，只保留真正需要成立的断言。还要编译映射元素、接口返回值和泛型调用等实际使用形态，因为它们不一定拥有局部变量的可寻址性。

### 复制含锁或内部指针的接收者

> **陷阱:** 含有 `sync.Mutex` 等首次使用后不可复制字段的类型若使用值接收者，每次调用都会复制锁。锁住副本不能保护原对象，`go vet` 通常会把这种接收者或按值传递报告为 `copylocks`。

**修复方法：** 让这类类型从构造后开始只通过指针使用，所有方法保持指针接收者，并运行 `go vet ./...` 与 `go test -race ./...`。即使方法当前只读，也不要用值接收者复制整份同步状态。

### 对 nil 接收者作错误假设

> **陷阱:** 指针接收者方法可以收到 `nil`，但这不意味着调用安全。方法体解引用字段就会 panic；通过 `nil` 的 `*T` 调用值接收者方法，则可能在进入方法体之前因隐式解引用而 panic。

**修复方法：** 只有 API 明确定义了 `nil` 语义时才在指针接收者方法开头处理它，并测试该路径。否则应在构造或调用边界拒绝 `nil`，不要添加看似防御性、实际掩盖无效状态的检查。

### 把提升当作继承

> **陷阱:** 嵌入类型的方法被提升后，生成代码可能假设外层类型是内层类型的子类，或者内层方法会动态调用外层的同名“重写”。Go 的提升只是选择器与方法集规则，不提供这种动态分派。

**修复方法：** 需要外层协调行为时，在外层方法中显式调用嵌入字段或把依赖写成接口。遇到同名成员时测试短选择器与完整路径；依赖外层类型满足接口时，再为 `T` 与 `*T` 写出编译期断言。

<!-- deep -->

## 方法声明的边界

方法接收者的基类型必须是当前包定义的类型，且不能是指针或接口类型。接收者声明本身可以写成 `T` 或 `*T`，但不能为另一个包的类型、类型别名所表示的外部类型，或已经定义好的指针类型增加方法。若需要扩展外部类型，应定义新的本地类型，或者写接收该类型的普通函数。

给新定义的本地类型添加方法时，它不会自动继承底层类型的方法。例如，一个以标准库类型为底层类型的新类型拥有新的方法集。若使用别名，别名与原类型保持同一身份，但别名声明不是绕过“当前包定义”限制的扩展机制。

同一基类型不能声明两个同名方法，即使接收者一个是 `T`、一个是 `*T`。方法名必须在该基类型的方法集合中唯一，因为两者都会出现在 `*T` 的方法集中。接收者参数的名称只是方法体内的局部名称，不影响唯一性或接口匹配。

泛型类型的方法接收者需要在接收者规格中声明与基类型参数对应的标识符，这些标识符会使用基类型声明中的约束。Go 1.27 还允许具体方法在方法名后声明自己的类型参数，使用前必须显式或隐式实例化。接口方法不能声明类型参数，泛型方法也不能用来实现接口方法。

## 提升方法的方法集矩阵

嵌入字段是 `T` 时，外层值 `S` 与指针 `*S` 都会得到 `T` 的值接收者方法；只有 `*S` 还会得到 `*T` 的指针接收者方法。这个不对称与普通字段的可寻址调用不同，因为这里讨论的是外层类型实际用于接口判断的方法集。

嵌入字段是 `*T` 时，`S` 与 `*S` 的方法集都会包含 `T` 和 `*T` 中被提升的方法。前面的 `Service` 因此能以值形式满足 `PrefixSetter`。不过，`Service` 的零值包含 `nil` 的 `*Logger`，满足接口不代表运行时调用一定安全。

| `S` 的嵌入字段 | `S` 得到的提升方法 | `*S` 得到的提升方法 |
|---|---|---|
| `T` | 接收者为 `T` 的方法 | 接收者为 `T` 或 `*T` 的方法 |
| `*T` | 接收者为 `T` 或 `*T` 的方法 | 接收者为 `T` 或 `*T` 的方法 |

方法提升只在选择器路径唯一时成立。两个嵌入字段若在同一最浅深度提供同名方法，`s.M` 会产生歧义；更深路径上的同名候选不会战胜较浅候选。显式写出 `s.Left.M()` 或 `s.Right.M()` 可以消除选择器歧义，但不会自动决定外层类型应公开哪个契约。

提升也不是虚方法分派。调用提升方法时，真正的接收者仍是嵌入字段；内层方法内部对其他方法的选择，仍依据内层接收者的静态类型。需要外层策略参与时，应由外层方法显式编排，或者把可替换行为作为接口字段注入。

## 方法值的求值细节

方法值表达式会立即求值并保存接收者。若选择值接收者方法，保存过程按赋值规则复制 `T`；其中的切片头、映射值和指针仍可能共享目标。若选择指针接收者方法，保存的是指针，即使原来使用的是可寻址值的短选择器，隐式取地址也在创建方法值时完成。

方法表达式不保存具体接收者，所以函数类型会多出第一个接收者参数。`T.M` 只对应 `T` 方法集中可选的方法；指针接收者方法要写 `(*T).M`。把方法表达式赋给回调前，应检查调用方需要的函数签名，并决定是否要暴露指针语义。

延迟方法调用会在执行 `defer` 语句时求值并保存接收者与普通实参，而不是在外围函数返回时才求值。启动 goroutine 的方法调用也会先在当前 goroutine 中求值函数值与参数。涉及状态快照、循环变量或临时指针时，明确写出局部变量能让保存时机更容易审查。

<!-- /deep -->

[检查点: go/methods](https://codewiki.com/zh/go/methods/#checkpoint)

## 延伸阅读

- [Go 语言规范：方法声明](https://go.dev/ref/spec#Method_declarations)
- [Go 语言规范：方法集](https://go.dev/ref/spec#Method_sets)
- [Effective Go：指针与值](https://go.dev/doc/effective_go#pointers_vs_values)
- [Go Wiki 代码审查建议：接收者类型](https://go.dev/wiki/CodeReviewComments#receiver-type)
- [Go 1.27 发布说明](https://go.dev/doc/go1.27)