Documentação de Go
Referência concisa e baseada em exemplos de Go. Leia o conceito, veja o código e pratique em uma jornada da Coddy.
Inicie uma jornada guiada de GoPrimeiros passos
- O que é Go?Go (muitas vezes chamada de Golang) é uma linguagem compilada e de tipagem estática criada no Google para construir servidores e ferramentas rápidos e confiáveis. Aqui você vê o que ela é, para que serve e onde ela deixa a desejar.
- Instalar o GoComo baixar e instalar o Go no Windows, macOS e Linux, conferir a instalação com go version, entender o GOPATH e corrigir o erro "go: command not found".
- Hello WorldO hello world em Go linha por linha: package main, o bloco de import, func main e fmt.Println, além de como executar o programa e os erros de compilação que todo iniciante encontra primeiro.
- go run e go buildO que go run, go build e go install fazem, como o Go dá nome ao binário, como fazer compilação cruzada com GOOS e GOARCH e as verificações go fmt e go vet para rodar antes do commit.
- Módulos GoComo os módulos Go funcionam: criar um com go mod init, escolher o caminho do módulo, adicionar dependências com go get, arrumar com go mod tidy, para que serve o go.sum e replace para desenvolvimento local.
- Pacotes e importsComo os pacotes do Go funcionam: a cláusula package, importar pacotes da biblioteca padrão e de módulos, nomes exportados e não exportados, dividir um pacote em vários arquivos, pacotes internal, aliases de import, imports em branco e o erro "undefined" do go run main.go.
Fundamentos
- VariáveisComo declarar variáveis em Go com var e com a forma curta :=, o que são valores zero, atribuição múltipla e os erros de sombreamento e de variável sem uso que pegam quem está começando em Go.
- ConstantesComo const funciona em Go: declarar constantes, a diferença entre constantes tipadas e não tipadas, expressões constantes com precisão arbitrária e por que Go não tem slices, maps ou structs constantes.
- Enums e iotaGo não tem a palavra-chave enum. Esta página mostra o substituto idiomático, um tipo nomeado mais um bloco const com iota, e como acrescentar String(), validação, parsing, bit flags e suporte a JSON.
- Tipos de dadosOs tipos embutidos do Go: tamanhos e faixas dos inteiros, float32 e float64, bool, string, byte e rune, números complexos, valores zero e como imprimir o tipo de um valor com %T.
- Conversão de tiposComo converter entre tipos em Go: int para string e string para int com strconv, float para int, conversões numéricas com T(v), bytes e runes, a armadilha do string(65) e o tratamento de erros de conversão.
- StringsTrabalhando com strings em Go: o pacote strings (Split, Join, Contains, Replace, Fields, TrimSpace, ToUpper), montar strings com eficiência usando strings.Builder, raw strings de várias linhas, imutabilidade e por que len conta bytes.
- Runes e bytesO que rune e byte significam em Go, como strings guardam UTF-8, por que len conta bytes, como range decodifica runes, como converter entre string, []byte e []rune e como usar o pacote bytes.
- fmt.Printf e SprintfComo o pacote fmt do Go imprime e formata valores: Println, Printf, Sprintf e Errorf, a tabela completa de verbos de formato (%v, %+v, %d, %s, %q, %f, %T, %w e mais), largura, precisão e preenchimento.
Controle de fluxo
- if / elseComo if, else if e else funcionam em Go: sem parênteses, chaves obrigatórias, o if com cláusula de inicialização e o seu escopo, o idioma if err != nil e retornos antecipados em vez de aninhamento profundo.
- laço forGo tem uma única palavra-chave de laço, for, e ela cobre tudo: o laço contador de três cláusulas, o laço só com condição (o while), o laço infinito e o range sobre slices, maps, strings, channels, inteiros e funções. Mais break e continue com label e a mudança nas variáveis de laço do Go 1.22.
- laço whileGo não tem a palavra-chave while. Um for só com condição é o while do Go, um for sem condição é um laço infinito, e um do-while é um laço infinito com a verificação no final.
- Laços com rangeO que o for range entrega para slices, arrays, strings, maps, channels, inteiros e funções iteradoras, por que a variável de valor é uma cópia, o que acontece ao alterar um slice ou map durante o range e o range sobre funções do Go 1.23.
- Instrução switchComo o switch funciona em Go: os cases não caem no próximo por padrão, um case pode listar vários valores, switch sem condição substitui cadeias de if/else, switch com instrução de inicialização, a palavra-chave fallthrough e uma visão rápida do type switch.
- Operador ternárioGo não tem operador ternário (cond ? a : b). Esta página explica o porquê, mostra o substituto idiomático com if/else, o cmp.Or para valores padrão e uma função genérica auxiliar, junto com a armadilha que a diferencia de um ternário de verdade.
Funções
- FunçõesComo declarar e chamar funções em Go: parâmetros, parâmetros que compartilham o tipo, valores de retorno, passagem por valor e funções como valores que você guarda e repassa.
- Múltiplos retornosFunções em Go podem devolver vários valores. Esta página cobre a sintaxe, a convenção (valor, error), o idioma vírgula-ok, resultados nomeados, return sem valores e o identificador em branco.
- Funções variádicasUma função variádica em Go aceita qualquer quantidade de argumentos finais de um mesmo tipo. Veja a sintaxe ...T, como passar um slice com s..., a armadilha do slice compartilhado e como o fmt.Println usa ...any.
- ClosuresFunções anônimas em Go podem capturar variáveis do escopo ao redor. Isso gera closures: contadores, geradores, middlewares e callbacks que guardam o próprio estado.
- Instrução deferdefer agenda uma chamada para executar quando a função que a contém retorna. Veja a ordem LIFO, quando os argumentos são avaliados, como fechar arquivos e liberar mutexes, defer em laços e como alterar resultados nomeados.
- MétodosUm método é uma função com um receiver. Veja como declarar métodos, quando usar receiver de valor ou de ponteiro, conjuntos de métodos e interfaces, e métodos em tipos que não são structs.
Coleções
- ArraysUm array em Go tem tamanho fixo, que faz parte do seu tipo, e é copiado na atribuição. Veja como declarar, percorrer, comparar e passar arrays, e por que a maior parte do código Go usa slices no lugar.
- SlicesSlices são o tipo de lista do dia a dia em Go. Veja make, append e o crescimento, len e cap, como o fatiamento compartilha o array subjacente (e o bug que isso causa), copy, o pacote slices, slices 2D e nil ou vazio.
- MapsMaps em Go guardam pares chave-valor com busca rápida. Veja como criá-los, verificar se uma chave existe com vírgula-ok, apagar, percorrer (em ordem aleatória), ordenar as chaves, guardar structs e evitar o panic do map nil e das escritas concorrentes.
- SetsGo não tem um tipo set embutido. O idioma padrão é um map com valores de struct vazia. Veja como adicionar, verificar e remover, união, interseção e diferença, e como escrever um pequeno Set genérico.
- OrdenaçãoOrdene slices em Go com slices.Sort e slices.SortFunc, ordene structs por um ou vários campos com cmp.Compare, mantenha elementos iguais na ordem com uma ordenação estável e entenda código mais antigo com sort.Slice.
Structs, interfaces e genéricos
- StructsStructs agrupam campos nomeados em um único tipo. Veja como defini-las e inicializá-las, valores zero, ponteiros para structs, structs anônimas, comparação, struct tags e a convenção de construtor NewX.
- PonteirosUm ponteiro guarda o endereço de um valor. Veja & e *, new, ponteiros para structs, por que é seguro devolver um ponteiro para uma variável local, quando usar ponteiros e o panic de desreferência de ponteiro nil.
- InterfacesInterfaces em Go são satisfeitas de forma implícita: qualquer tipo com os métodos certos as implementa. Veja interfaces pequenas como io.Reader e fmt.Stringer, a interface vazia any, a armadilha da interface nil e a regra aceite interfaces, devolva structs.
- Embedding de structsEmbedding coloca um tipo dentro de outro sem nome de campo, e os campos e métodos dele são promovidos para o tipo externo. Veja como a promoção funciona, embedding de interfaces, conflitos de nome e por que embedding não é herança.
- Type assertionsUma type assertion tira o valor concreto de dentro de uma interface. Veja x.(T), a forma vírgula-ok que nunca causa panic, a assertion para outra interface, type switches e errors.As para erros empacotados.
- GenericsGenerics (Go 1.18+) permitem que uma função ou um tipo funcione com muitos tipos sem perder a segurança de tipos. Veja parâmetros de tipo, as restrições any, comparable e cmp.Ordered, restrições personalizadas com ~, tipos genéricos e quando não usá-los.
Erros
- Tratamento de errosGo trata erros como valores comuns devolvidos por funções. Veja a interface error, if err != nil, errors.New e fmt.Errorf, como devolver erros com contexto, como verificá-los com errors.Is e errors.As e como tratar cada erro uma única vez.
- Erros personalizadosDefina erros sentinela e tipos de erro próprios, empacote erros com %w, verifique-os com errors.Is e errors.As, combine vários com errors.Join e escreva métodos Unwrap e Is quando precisar.
- panic e recoverUm panic interrompe a execução normal e desenrola a pilha, executando as chamadas adiadas. Veja o que causa panics, como o recover em uma função adiada interrompe um, as mensagens de erro de runtime que você vai ver e quando causar panic é a decisão certa.
Concorrência
- GoroutinesComo executar funções de forma concorrente com a palavra-chave go, esperar que terminem, receber os resultados e evitar as data races, os vazamentos e os crashes que as goroutines facilitam.
- ChannelsComo os channels do Go passam valores entre goroutines: channels sem buffer e com buffer, fechar e percorrer com range, tipos com direção, o erro de deadlock e um pipeline montado com eles.
- Instrução selectComo o select espera por várias operações de channel ao mesmo tempo: escolha entre cases prontos, envios e recebimentos sem bloqueio com default, timeouts com time.After e como parar laços com um channel de parada ou um context.
- WaitGroupComo o sync.WaitGroup espera um conjunto de goroutines terminar: as regras de Add, Done e Wait, por que ele precisa ser passado por ponteiro, como coletar resultados e erros e um worker pool construído com ele.
- MutexComo proteger estado compartilhado entre goroutines com sync.Mutex e sync.RWMutex, quando sync/atomic é suficiente, como o sync.Once executa uma inicialização exatamente uma vez e os erros de lock que causam deadlocks.
- Pacote contextComo o context.Context leva cancelamento, prazos e valores da requisição por um programa Go: Background, WithCancel, WithTimeout, WithValue, ctx.Done no select e context em servidores e clientes HTTP.
Biblioteca padrão
- Pacote timeComo trabalhar com datas e horas em Go: time.Now e time.Sleep, aritmética com Duration, o layout de referência 2006-01-02 15:04:05 para Format e Parse, fusos horários, timestamps Unix, timers e tickers.
- JSONComo codificar e decodificar JSON em Go com encoding/json: Marshal e Unmarshal, struct tags como omitempty e omitzero, saída formatada, decodificar em map[string]any, rejeitar campos desconhecidos e streaming com Decoder.
- Ler e escrever arquivosComo ler e escrever arquivos em Go: os.ReadFile e os.WriteFile, ler linha por linha com bufio.Scanner, acrescentar com os.OpenFile, verificar se um arquivo existe e trabalhar com diretórios.
- Servidor HTTPComo construir um servidor web com o pacote padrão net/http do Go: handlers, rotas do ServeMux com métodos e wildcards no caminho (Go 1.22), respostas JSON, códigos de status, middleware, timeouts e desligamento gracioso.
- Cliente HTTPComo fazer requisições HTTP em Go com net/http: http.Get, ler e fechar o corpo, verificar códigos de status, timeouts do http.Client, requisições com context e headers, parâmetros de query e POST com JSON.
- Argumentos de linha de comandoComo um programa Go lê a sua linha de comando: os.Args, o pacote flag para opções tipadas, subcomandos com FlagSet, variáveis de ambiente com os.Getenv e os.LookupEnv e códigos de saída com os.Exit.
- Expressões regularesComo usar expressões regulares em Go com o pacote regexp: MustCompile, MatchString, FindString e FindAllString, grupos de captura e grupos nomeados, ReplaceAllString e os limites da sintaxe RE2, como a falta de lookbehind.
- LogsComo fazer logs em Go: o pacote clássico log, com as suas flags e o log.Fatal, e o log/slog (Go 1.21) para logs estruturados com níveis, atributos chave-valor, handlers de texto e JSON e loggers que carregam contexto com With.
Testes e estrutura de projetos
- TestesComo testar código Go com o pacote padrão testing e o go test: arquivos _test.go, funções TestXxx, t.Errorf ou t.Fatalf, testes orientados a tabela com t.Run, helpers e diretórios temporários, cobertura, benchmarks com b.Loop e testes de exemplo.
- Estrutura de projetoComo organizar um projeto Go: comece plano, divida em pacotes quando houver motivo, use cmd/ para vários binários e internal/ para código que ninguém mais pode importar, dê bons nomes aos pacotes e mantenha os testes ao lado do código.
