Métodos: Receptores de Valor vs. Puntero

Los métodos adjuntan comportamiento a los tipos a través de receptores: una copia (T) o un puntero (*T).

La elección afecta la mutabilidad, las asignaciones, la satisfacción de interfaces y la consistencia de la API en tu paquete.

Resumen

Un receptor de valor copia la estructura para la llamada al método.

Las mutaciones dentro del método no afectan la copia del llamador.

Un receptor de puntero comparte el valor subyacente.

Las mutaciones persisten y evitan copiar estructuras grandes.

Los conjuntos de métodos determinan la satisfacción de la interfaz: el tipo de valor T solo incluye métodos con receptores de valor; el tipo de puntero *T incluye métodos con receptores de valor y puntero.

Elige un estilo de receptor por tipo a menos que tengas una excepción documentada.

Usa receptores de puntero cuando los métodos mutan el estado o cuando el tamaño de la estructura hace que la copia sea costosa.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

type Buffer struct {
    b []byte
}
 
// Receptor de puntero: muta y coincide con APIs estilo io.Writer.
func (buf *Buffer) Write(p []byte) (int, error) {
    buf.b = append(buf.b, p...)
    return len(p), nil
}
 
// Receptor de valor: instantánea de solo lectura.
func (buf Buffer) Bytes() []byte {
    return append([]byte(nil), buf.b...)
}
 
// Consistencia: si algún método necesita *T, prefiere *T para todos los métodos.
func (buf *Buffer) Reset() { buf.b = buf.b[:0] }

Cuándo usar esto:

• Los métodos de estructura mutan campos (Inc, Write, SetState).
• Los tipos implementan interfaces que requieren métodos de puntero (fmt.Stringer en estructuras grandes está bien de cualquier manera; sync.Mutex no debe copiarse).
• Los tipos de valor son identificadores inmutables pequeños (time.Time usa métodos de valor).
• Necesitas satisfacción de interfaz estable tanto para asignaciones de T como de *T.

Ejemplo de Trabajo

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
}

Lo que esto demuestra:

• Receptor de puntero en Credit muta el saldo.
• Receptor de valor en Balance devuelve una instantánea sin exponer estado mutable.
• Interfaz Creditor requiere Credit; satisfecha por *Account, no por el valor Account.
• Constructor devuelve *Account para que los llamadores lleguen al conjunto de métodos de puntero.

Profundización

Cómo Funciona

• Los métodos se descompilan en funciones: a.Credit(x) se convierte en Credit(a, x) con el receptor como primer argumento.
• El compilador pasa la dirección automáticamente para los receptores de puntero cuando la variable es direccionable.
• Conjuntos de métodos:
  • Para el tipo T: métodos con receptor T
  • Para el tipo *T: métodos con receptor T y *T
• Las comprobaciones de asignación de interfaz utilizan el conjunto de métodos del tipo dinámico que se mantiene.

Guía de Selección de Receptor

Tabla de Satisfacción de Interfaz

Notas de 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{}   // error de compilación: S le falta P
i = &S{}     // OK

Documenta los constructores que devuelven *T cuando existen métodos de puntero.

Trampas

• Receptor de valor en método mutante - Los cambios desaparecen después de la llamada. Solución: cambiar a *T o devolver explícitamente una copia actualizada.
• Copiar estructuras con mutexes - Los receptores de valor duplican sync.Mutex y provocan pánico. Solución: solo receptores de puntero; a veces, hacer la estructura no exportable.
• Receptores inconsistentes - func (T) Foo y func (*T) Bar rompen las asignaciones de interfaz T. Solución: unificar en *T cuando exista cualquier método de puntero.
• Llamadas a receptores de puntero nulos - Go permite var p *T; p.Method() si el método maneja nulos (ver guardas nil en la biblioteca estándar). Solución: documentar o provocar un pánico temprano para nulos inválidos.
• La interfaz contiene un valor con métodos de puntero - Asignar un valor Account a Creditor falla. Solución: almacenar *Account o agregar envolturas de receptor de valor solo cuando sea semánticamente sólido.
• Incrustar tipos de puntero - Los métodos promovidos pueden requerir una estructura externa direccionable. Solución: comprender los conjuntos de métodos promovidos al incrustar *bytes.Buffer.
• Tipos generados por JSON / protobuf - A menudo usan punteros para campos opcionales; no mezcles receptores de valor personalizados que copien el estado generado inesperadamente.

Alternativas

Preguntas Frecuentes

Relacionados

• Conceptos Básicos de Funciones y Métodos - primeros ejemplos de métodos de valor y puntero
• Definición e Implementación de Interfaces - conjuntos de métodos y comprobaciones de interfaz
• Interfaz Nula vs. Puntero Nulo - métodos de puntero en receptores nulos
• Funciones e Interfaces: El Modelo de Composición de Go - composición sin herencia
• Mejores Prácticas para Funciones, Métodos e Interfaces - reglas de consistencia de receptores

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).