Métodos em Golang: receiver de valor ou de ponteiro, explicado

Declarando um método

Um método é uma função com um receiver: um parâmetro extra escrito antes do nome do método. O receiver liga o método a um tipo.

package main

import (
	"fmt"
	"math"
)

type Circle struct {
	Radius float64
}

func (c Circle) Area() float64 {
	return math.Pi * c.Radius * c.Radius
}

func (c Circle) String() string {
	return fmt.Sprintf("Circle(r=%.1f)", c.Radius)
}

func main() {
	c := Circle{Radius: 2}
	fmt.Printf("%.2f\n", c.Area())
	fmt.Println(c) // uses the String method
}

O nome do receiver costuma ter uma ou duas letras tiradas do tipo (c para Circle). Go não usa this nem self, e os guias de estilo desencorajam esses nomes.

Como Circle tem um método String() string, ele satisfaz fmt.Stringer, e o fmt.Println imprime o resultado em vez de {2}.

Receivers de valor e receivers de ponteiro

Um receiver de valor (c Circle) recebe uma cópia. Um receiver ponteiro (c *Circle) recebe o endereço, então as mudanças nos campos permanecem.

package main

import "fmt"

type Counter struct {
	n int
}

func (c Counter) IncByValue() {
	c.n++ // changes the copy only
}

func (c *Counter) Inc() {
	c.n++
}

func (c Counter) Value() int {
	return c.n
}

func main() {
	var c Counter
	c.IncByValue()
	fmt.Println(c.Value()) // 0

	c.Inc() // Go takes &c automatically
	c.Inc()
	fmt.Println(c.Value()) // 2

	p := &c
	fmt.Println(p.Value()) // Go dereferences p automatically
}

IncByValue compila e não faz nada visível, um bug clássico. Se um método deve modificar o seu receiver, ele precisa de receiver ponteiro.

As chamadas também mostram as duas conveniências que o Go oferece. c.Inc() em uma variável endereçável é reescrito como (&c).Inc(), e p.Value() em um ponteiro é reescrito como (*p).Value(). Você raramente escreve & ou * só para chamar um método.

O & automático precisa de algo endereçável. Um elemento de map ou um literal composto não é:

m := map[string]Counter{"a": {}}
m["a"].Inc()    // compile error: cannot call pointer method Inc on Counter
Counter{}.Inc() // same error: a composite literal is not addressable

Guarde ponteiros no map (map[string]*Counter) ou copie o valor para fora, altere e grave de volta.

Qual receiver escolher

O FAQ do Go e a biblioteca padrão seguem uma regra prática: seja consistente. Se algum método precisa de receiver ponteiro, dê receiver ponteiro a todos os métodos, para que o conjunto de métodos seja previsível. O go vet aponta uma struct com um sync.Mutex que é copiada por meio de um receiver de valor (passes lock by value).

Conjuntos de métodos e interfaces

A diferença importa mais nas interfaces. O conjunto de métodos de T contém os métodos com receiver de valor. O conjunto de métodos de *T contém os métodos com receiver de valor e os com receiver ponteiro.

package main

import "fmt"

type Shape interface {
	Area() float64
}

type Square struct{ Side float64 }

func (s *Square) Area() float64 { return s.Side * s.Side }

type Rect struct{ W, H float64 }

func (r Rect) Area() float64 { return r.W * r.H }

func main() {
	shapes := []Shape{
		&Square{Side: 3},  // *Square has Area
		Rect{W: 2, H: 5},  // Rect has Area
		&Rect{W: 1, H: 1}, // *Rect has it too
	}
	for _, s := range shapes {
		fmt.Printf("%T %.0f\n", s, s.Area())
	}
}

Escrever Square{Side: 3} sem o & naquele slice não compila:

cannot use Square{…} (value of struct type Square) as Shape value in array or slice literal: Square does not implement Shape (method Area has pointer receiver)

O motivo: uma interface pode guardar uma cópia de um Square que não é endereçável, então o Go não consegue pegar o endereço dela para chamar um método de ponteiro. Veja interfaces para o resto dessa história.

Métodos em tipos que não são structs

Qualquer tipo nomeado declarado no seu pacote pode ter métodos, não só structs.

package main

import (
	"fmt"
	"strings"
)

type Celsius float64

func (c Celsius) Fahrenheit() float64 {
	return float64(c)*9/5 + 32
}

type Tags []string

func (t Tags) String() string {
	return "#" + strings.Join(t, " #")
}

type Status int

func (s Status) String() string {
	switch s {
	case 0:
		return "pending"
	case 1:
		return "done"
	}
	return fmt.Sprintf("Status(%d)", int(s))
}

func main() {
	fmt.Println(Celsius(100).Fahrenheit())
	fmt.Println(Tags{"go", "backend"})
	fmt.Println(Status(1), Status(7))
}

Os limites: o tipo precisa ser definido no mesmo pacote que o método, e o seu tipo subjacente não pode ser um ponteiro ou uma interface. Você não pode acrescentar métodos a int, string ou time.Time a partir do seu pacote. Envolver em um novo tipo nomeado é o jeito Go. String() em um tipo inteiro também é como enums ganham uma saída legível; veja enums com iota.

Method values e method expressions

Um método ligado a um receiver específico é um valor de função:

package main

import "fmt"

type Greeter struct{ Name string }

func (g Greeter) Hello(to string) string {
	return g.Name + " says hi to " + to
}

func main() {
	g := Greeter{Name: "Ana"}

	f := g.Hello // method value: receiver bound now
	g.Name = "Bob"
	fmt.Println(f("Cy")) // still Ana: the receiver was copied

	h := Greeter.Hello // method expression: receiver becomes the first parameter
	fmt.Println(h(g, "Dee"))
}

Um method value com receiver de valor copia o receiver no momento em que é criado, e é por isso que f ainda diz Ana. Com receiver ponteiro, ele guardaria o ponteiro e veria as mudanças posteriores. Method values são práticos para callbacks: http.HandleFunc("/", srv.handleIndex).

Erros comuns

• Receiver de valor em um método que altera o estado. Compila e altera uma cópia em silêncio.
• Misturar tipos de receiver. Deixa pouco claro se é T ou *T que satisfaz uma interface. Escolha um por tipo.
• Chamar um método de ponteiro em um ponteiro nil. É permitido, e o método executa com um receiver nil. Ele só causa panic quando acessa um campo. Alguns tipos (como uma lista ligada segura para nil) usam isso de propósito; a maioria não espera por isso.