Métodos: Receivers de Valor vs. Ponteiro

Métodos anexam comportamento a tipos através de receivers - uma cópia (T) ou um ponteiro (*T).

A escolha afeta a mutabilidade, alocações, satisfação de interface e consistência da API em seu pacote.

Resumo

Um receiver de valor copia a struct para a chamada do método.

Mutações dentro do método não afetam a cópia do chamador.

Um receiver de ponteiro compartilha o valor subjacente.

Mutações persistem e evitam a cópia de structs grandes.

Conjuntos de métodos determinam a satisfação de interface: o tipo de valor T inclui apenas métodos com receivers de valor; o tipo de ponteiro *T inclui métodos com receivers de valor e ponteiro.

Escolha um estilo de receiver por tipo, a menos que haja uma exceção documentada.

Use receivers de ponteiro quando os métodos modificam o estado ou quando o tamanho da struct torna a cópia custosa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

type Buffer struct {
    b []byte
}
 
// Receiver de ponteiro: muta e corresponde a APIs no estilo io.Writer.
func (buf *Buffer) Write(p []byte) (int, error) {
    buf.b = append(buf.b, p...)
    return len(p), nil
}
 
// Receiver de valor: snapshot somente leitura.
func (buf Buffer) Bytes() []byte {
    return append([]byte(nil), buf.b...)
}
 
// Consistência: se algum método precisar de *T, prefira *T para todos os métodos.
func (buf *Buffer) Reset() { buf.b = buf.b[:0] }

Quando usar isso:

• Métodos de struct modificam campos (Inc, Write, SetState).
• Tipos implementam interfaces que exigem métodos de ponteiro (fmt.Stringer em structs grandes está bom de qualquer forma; sync.Mutex não deve ser copiado).
• Tipos de valor são pequenos identificadores imutáveis (time.Time usa métodos de valor).
• Você precisa de satisfação de interface estável para atribuições de T e *T.

Exemplo de Trabalho

package ledger
 
import "fmt"
 
type Account struct {
    id      string
    balance int64
}
 
func NewAccount(id string) *Account {
    return &Account{id: id}
}
 
func (a *Account) Credit(cents int64) error {
    if cents < 0 {
        return fmt.Errorf("ledger: negative credit %d", cents)
    }
    a.balance += cents
    return nil
}
 
func (a Account) Balance() int64 {
    return a.balance
}
 
type Creditor interface {
    Credit(cents int64) error
}
 
func Process(c Creditor, amount int64) error {
    return c.Credit(amount)
}
 
func Example() error {
    acct := NewAccount("user-1")
    if err := Process(acct, 500); err != nil {
        return err
    }
    return nil
}

O que isso demonstra:

• Receiver de ponteiro em Credit modifica o saldo.
• Receiver de valor em Balance retorna um snapshot sem expor estado mutável.
• Interface Creditor exige Credit; satisfeita por *Account, não por valor Account.
• Construtor retorna *Account para que os chamadores cheguem ao conjunto de métodos de ponteiro.

Mergulho Profundo

Como Funciona

• Métodos são descompilados em funções: a.Credit(x) se torna Credit(a, x) com o receiver como primeiro argumento.
• O compilador passa o endereço automaticamente para receivers de ponteiro quando a variável é endereçável.
• Conjuntos de métodos:
  • Para o tipo T: métodos com receiver T
  • Para o tipo *T: métodos com receiver T e *T
• Verificações de atribuição de interface usam o conjunto de métodos do tipo dinâmico mantido.

Guia de Seleção de Receiver

Tabela de Satisfação de Interface

Notas do Go

type S struct{ n int }
func (s S) V() int    { return s.n }
func (s *S) P() int   { s.n++; return s.n }
 
var i interface {
    V() int
    P() int
}
// i = S{}   // erro de compilação: S não tem P
i = &S{}     // OK

Documente construtores que retornam *T quando métodos de ponteiro existem.

Armadilhas

• Receiver de valor em método mutável - As alterações desaparecem após a chamada. Correção: mudar para *T ou retornar explicitamente uma cópia atualizada.
• Copiar structs com mutexes - Receivers de valor duplicam sync.Mutex e causam pânico. Correção: apenas receivers de ponteiro; às vezes, exportar a struct.
• Receivers inconsistentes - func (T) Foo e func (*T) Bar quebram atribuições de interface T. Correção: unificar em *T quando qualquer método de ponteiro existir.
• Chamadas de receiver de ponteiro nulo - Go permite var p *T; p.Method() se o método lidar com nulo (veja guardas nil na biblioteca padrão). Correção: documentar ou entrar em pânico cedo para nulos inválidos.
• Interface contém valor com métodos de ponteiro - Atribuir um valor Account a Creditor falha. Correção: armazenar *Account ou adicionar wrappers de receiver de valor apenas quando semanticamente correto.
• Embutir tipos de ponteiro - Métodos promovidos podem exigir uma struct externa endereçável. Correção: entender conjuntos de métodos promovidos ao embutir *bytes.Buffer.
• Tipos gerados por JSON / protobuf - Frequentemente usam ponteiros para campos opcionais; não misture receivers de valor personalizados que copiam o estado gerado inesperadamente.

Alternativas

FAQs

Relacionados

• Noções Básicas de Funções e Métodos - primeiros exemplos de métodos de valor e ponteiro
• Definindo e Implementando Interfaces - conjuntos de métodos e verificações de interface
• Interface Nula vs. Ponteiro Nulo - métodos de ponteiro em receivers nulos
• Funções e Interfaces: Modelo de Composição do Go - composição sem herança
• Melhores Práticas de Funções, Métodos e Interfaces - regras de consistência de receiver

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).