Múltiplos retornos em Golang: (valor, error) e resultados nomeados

Devolvendo mais de um valor

Liste os tipos dos resultados entre parênteses. Devolva os valores separados por vírgula e receba-os do mesmo jeito.

package main

import "fmt"

func minMax(xs []int) (int, int) {
	lo, hi := xs[0], xs[0]
	for _, x := range xs[1:] {
		lo = min(lo, x)
		hi = max(hi, x)
	}
	return lo, hi
}

func main() {
	lo, hi := minMax([]int{4, 9, 1, 7})
	fmt.Println("min:", lo, "max:", hi)
}

As funções embutidas min e max existem desde o Go 1.21. Quem chama precisa receber todos os resultados: x := minMax(nums) não compila e dá assignment mismatch: 1 variable but minMax returns 2 values.

A convenção (valor, error)

O motivo mais comum para devolver dois valores é reportar uma falha. Por convenção o erro vem por último, e quando ele não é nil os outros resultados devem ser tratados como sem significado.

package main

import (
	"errors"
	"fmt"
	"strconv"
)

func parsePort(s string) (int, error) {
	n, err := strconv.Atoi(s)
	if err != nil {
		return 0, fmt.Errorf("port %q: %w", s, err)
	}
	if n < 1 || n > 65535 {
		return 0, errors.New("port out of range")
	}
	return n, nil
}

func main() {
	for _, in := range []string{"8080", "http", "70000"} {
		port, err := parsePort(in)
		if err != nil {
			fmt.Println("error:", err)
			continue
		}
		fmt.Println("port:", port)
	}
}

Saída:

port: 8080
error: port "http": strconv.Atoi: parsing "http": invalid syntax
error: port out of range

Em caso de falha, devolva o valor zero em todos os outros resultados (0, "", nil). O padrão completo, incluindo empacotamento e verificação, está na página de tratamento de erros.

O idioma vírgula-ok

Várias operações embutidas devolvem um segundo valor opcional, um bool, que diz se o primeiro valor é real. Por convenção a variável se chama ok.

package main

import "fmt"

func main() {
	ages := map[string]int{"ana": 31}

	age, ok := ages["bob"]
	fmt.Println(age, ok) // 0 false: missing key, not a zero age

	var v any = "hello"
	s, ok := v.(string)
	fmt.Println(s, ok)

	ch := make(chan int, 1)
	ch <- 5
	close(ch)
	x, ok := <-ch
	fmt.Println(x, ok) // 5 true: a buffered value is still delivered
	x, ok = <-ch
	fmt.Println(x, ok) // 0 false: closed and drained
}

Essas três formas (busca em map, type assertion, recebimento de channel) são especiais: elas devolvem um ou dois valores dependendo de quantas variáveis você atribui. Suas próprias funções não podem fazer isso. Uma função declarada com dois resultados sempre devolve dois.

O identificador em branco

_ recebe um valor e o joga fora. Use-o para resultados de que você não precisa:

_, err := fmt.Sscan(input, &n)
key, _ := parseLine(line)

Ignorar um erro com _ compila, então faça isso só quando souber que a chamada não pode falhar ou que a falha não importa. strings.Builder.WriteString sempre devolve um erro nil, por exemplo; fechar um arquivo depois de escrever nele, não.

Resultados nomeados

Parâmetros de resultado podem ter nome. Eles são declarados no início da função, inicializados com seus valores zero, e um return sem valores devolve o que eles guardam.

package main

import "fmt"

func split(total int) (quotient, remainder int) {
	quotient = total / 7
	remainder = total % 7
	return
}

func main() {
	weeks, days := split(45)
	fmt.Println(weeks, "weeks and", days, "days")
}

Os nomes aparecem na saída do go doc, o que ajuda quando dois resultados têm o mesmo tipo: (quotient, remainder int) diz mais que (int, int).

Um return sem valores em uma função longa é difícil de ler, porque o leitor precisa voltar para ver o que os resultados guardam. O conselho de sempre: nomeie os resultados quando os nomes documentam algo, e ainda assim escreva return quotient, remainder explicitamente, a menos que a função tenha poucas linhas.

Resultados nomeados e defer

Uma função adiada executa depois de a instrução return definir os resultados e antes de quem chama recebê-los. Com resultados nomeados, a função adiada pode lê-los e alterá-los. É assim que você acrescenta contexto a qualquer erro que uma função devolve, ou transforma um panic em erro.

package main

import (
	"errors"
	"fmt"
)

func load(name string) (err error) {
	defer func() {
		if err != nil {
			err = fmt.Errorf("load %s: %w", name, err)
		}
	}()
	if name == "" {
		return errors.New("empty name")
	}
	return nil
}

func main() {
	fmt.Println(load(""))
	fmt.Println(load("config.json"))
}

Isto imprime load : empty name e depois <nil>. return errors.New(...) primeiro atribui a err, e depois a função adiada o empacota. Mais sobre isso em defer.

Shadowing de um resultado nomeado

Resultados nomeados vivem no escopo mais externo da função. Um := dentro de um bloco aninhado cria uma variável nova com o mesmo nome, e um return sem valores devolve então a de fora.

func find() (n int, err error) {
	if true {
		n, err := compute() // new n and err, shadowing the results
		_ = n
		_ = err
	}
	return // returns 0, nil
}

O compilador pega o pior caso: um return sem valores dentro do bloco em que um resultado está sombreado falha com result parameter err not in scope at return. Ele não pega a versão acima, em que o return fica fora do bloco. Use = em vez de := quando você se refere às variáveis de resultado.

Erros comuns

• Usar o valor quando err não é nil. Verifique err primeiro. Uma função pode devolver lixo junto com um erro.
• Devolver um ponteiro nil tipado como erro. var e *MyErr; return e devolve um error que não é nil. Devolva um nil literal em caso de sucesso.
• Resultados demais. Três ou mais resultados com significados misturados são difíceis de usar. Devolva uma struct.