Múltiplos Retornos, Retornos Nomeados e Retornos Nus

Funções Go podem retornar múltiplos valores - geralmente um resultado e um error - e opcionalmente nomear esses resultados na assinatura.

Retornos nomeados habilitam instruções return nuas e integram-se com defer, mas o uso excessivo esconde o fluxo de dados e frustra os leitores.

Resumo

Múltiplos valores de retorno são o principal mecanismo de Go para sinalizar falha sem exceções.

Chamadores recebem tuplas (T, error) e tratam erros explicitamente em cada etapa.

Parâmetros de resultado nomeados declaram variáveis com escopo para todo o corpo da função, inicializadas com valores zero na entrada.

Um return nu (sem operandos) retorna os valores atuais desses resultados nomeados.

Use retornos nomeados com moderação: eles brilham em funções curtas com defer que ajustam um erro, e prejudicam a legibilidade em funções longas com muitos branches.

Prefira retornos não nomeados quando a lógica for mais fácil de seguir com instruções explícitas de return valor, err.

Receita

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

func ReadConfig(path string) ([]byte, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("ler configuração %s: %w", path, err)
    }
    return data, nil
}
 
// Retornos nomeados + defer: ajusta o err na saída (padrão idiomático).
func WriteAtomic(path string, data []byte) (err error) {
    f, err := os.CreateTemp(filepath.Dir(path), "tmp-*")
    if err != nil {
        return err
    }
    defer func() {
        closeErr := f.Close()
        if err == nil {
            err = closeErr
        }
    }()
    if _, err = io.Copy(f, bytes.NewReader(data)); err != nil {
        return err
    }
    return os.Rename(f.Name(), path)
}

Quando usar isso:

• Qualquer função que possa falhar deve retornar error como último valor.
• Blocos defer precisam atualizar o erro de saída após a limpeza (defer + err nomeado).
• Ferramentas de documentação devem mostrar nomes de resultados em godoc para APIs pequenas.
• Você quer evitar repetir tipos de tuplas longas em muitas instruções return.

Exemplo de Trabalho

package config
 
import (
    "encoding/json"
    "fmt"
    "os"
)
 
type Settings struct {
    Port int    `json:"port"`
    Host string `json:"host"`
}
 
func Load(path string) (s Settings, err error) {
    raw, err := os.ReadFile(path)
    if err != nil {
        return s, fmt.Errorf("config: read: %w", err)
    }
    if err = json.Unmarshal(raw, &s); err != nil {
        return s, fmt.Errorf("config: decode: %w", err)
    }
    if s.Port == 0 {
        return s, fmt.Errorf("config: porta obrigatória")
    }
    return s, nil
}

O que isso demonstra:

• Retorno final explícito com valores, mesmo quando os resultados são nomeados - os leitores veem o que sai da função.
• Erros encapsulados preservam causas com %w para errors.Is / errors.As.
• Validação retorna o Settings zero junto com um erro - os chamadores devem verificar err antes de usar s.
• err nomeado poderia ser combinado com defer em carregadores mais complexos; aqui, retornos explícitos permanecem mais claros.

Mergulho Profundo

Como Funciona

• O compilador trata parâmetros de resultado como variáveis locais declaradas na entrada da função.
• Resultados nomeados são inicializados com valores zero (0, "", nil) antes da execução da primeira instrução.
• return sem argumentos não atribui nada novo - ele sai com os valores nomeados atuais.
• Resultados não nomeados exigem que cada return liste os valores explicitamente; o compilador impõe a aridade.

Retornos Nomeados vs. Não Nomeados

Defer e o Padrão err Nomeado

func do() (err error) {
    defer func() {
        if err != nil {
            err = fmt.Errorf("do: %w", err)
        }
    }()
    // ...
    return nil
}

A closure adiada observa a variável de resultado nomeada por referência (endereçável), então atribuições em defer afetam o valor retornado aos chamadores.

Ofuscar err com := em um bloco interno quebra este padrão - use = no resultado nomeado em vez disso.

Notas Go

// Anti-padrão: retorno nu longe da declaração.
func parseAll(input string) (tokens []string, err error) {
    for _, part := range strings.Split(input, ",") {
        if part == "" {
            return // quais valores? o leitor precisa rolar para cima
        }
        tokens = append(tokens, part)
    }
    return
}

Prefira return tokens, nil na parte inferior e após os erros para facilitar a leitura.

Armadilhas

• Ofuscar err nomeado com := - foo, err := interno cria um novo err que o defer não atualizará. Correção: use = no resultado nomeado existente ou evite := em err.
• Retorno nu em funções longas - Leitores não conseguem ver os valores retornados no ponto de saída. Correção: use return x, y explícito, exceto em helpers defer curtos.
• Retornar valor zero em caso de erro - Chamadores podem ignorar err e usar s mesmo assim. Correção: documente "indefinido em caso de erro" ou retorne ponteiros (*Settings, error).
• Misturar retornos nus e explícitos - Estilo inconsistente em uma função confunde a revisão. Correção: escolha um estilo por função.
• Resultados nomeados em API pública sem benefício - Adiciona carga cognitiva para vitórias marginais no godoc. Correção: nomeie apenas quando o padrão defer/erro exigir.
• Múltiplos erros - Go não tem agregação de erros em retornos. Correção: retorne o primeiro erro ou defina um tipo error personalizado coletando falhas.
• Alterar nomes de resultados é uma quebra de compatibilidade - Nomes de resultados aparecem no godoc e podem afetar wrappers gerados. Correção: trate assinaturas exportadas como API estável.

Alternativas

FAQs

Relacionados

• Noções Básicas de Funções e Métodos - exemplos introdutórios para retornos e métodos
• Funções e Interfaces: O Modelo de Composição de Go - como erros se compõem através de camadas
• Funções Variádicas e Tipos de Função - funções como valores retornando tuplas
• Interface Nil vs Ponteiro Nil - retornando nil, nil através de interfaces
• Melhores Práticas de Funções, Métodos e Interfaces - convenções de erro e API

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

WTI5a1pXZDFhV1JsY3k1cGIzeGpaMmx2TkRjM2ZESXdNall3Tnc9PQ==