Como escrever código Go
Introdução
Este documento demonstra o desenvolvimento de um pacote Go simples dentro de um módulo e apresenta a ferramenta go, a forma padrão de baixar, compilar e instalar módulos, pacotes e comandos Go.
Organização do código
Programas Go são organizados em pacotes. Um pacote é um conjunto de arquivos-fonte no mesmo diretório que são compilados juntos. Funções, tipos, variáveis e constantes definidos em um arquivo-fonte são visíveis para todos os outros arquivos-fonte dentro do mesmo pacote.
Um repositório contém um ou mais módulos. Um módulo é um conjunto de
pacotes Go relacionados que são lançados juntos. Um repositório Go geralmente
contém apenas um módulo, localizado na raiz do repositório. Um arquivo chamado
go.mod ali declara o caminho do módulo: o prefixo do
import path de todos os pacotes dentro do módulo. O módulo contém os pacotes
do diretório que contém seu arquivo go.mod, assim como os subdiretórios
desse diretório, até o próximo subdiretório que contenha outro
arquivo go.mod (se houver).
Observe que você não precisa publicar seu código em um repositório remoto antes de poder compilá-lo. Um módulo pode ser definido localmente, sem pertencer a um repositório. No entanto, é um bom hábito organizar seu código como se você fosse publicá-lo um dia.
O caminho de cada módulo não serve apenas como prefixo de import path para seus pacotes,
mas também indica onde o comando go deve procurar para baixá-lo.
Por exemplo, para baixar o módulo golang.org/x/tools,
o comando go consultaria o repositório indicado por
https://golang.org/x/tools (descrito com mais detalhes aqui).
Um import path é uma string usada para importar um pacote. O import path de um pacote
é o caminho do módulo concatenado com seu subdiretório dentro do módulo.
Por exemplo, o módulo github.com/google/go-cmp contém um pacote
no diretório cmp/. O import path desse pacote é
github.com/google/go-cmp/cmp. Os pacotes da biblioteca padrão
não têm prefixo de caminho de módulo.
Seu primeiro programa
Para compilar e executar um programa simples, primeiro escolha um caminho de módulo (vamos usar
example/user/hello) e crie um arquivo go.mod que
o declare:
$ mkdir hello # Alternatively, clone it if it already exists in version control. $ cd hello $ go mod init example/user/hello go: creating new go.mod: module example/user/hello $ cat go.mod module example/user/hello go 1.16 $
A primeira instrução em um arquivo-fonte Go deve ser
package nome. Comandos executáveis devem sempre usar
package main.
Em seguida, crie um arquivo chamado hello.go dentro desse diretório contendo
o seguinte código Go:
package main
import "fmt"
func main() {
fmt.Println("Hello, world.")
}
Agora você pode compilar e instalar esse programa com a ferramenta go:
$ go install example/user/hello $
Esse comando compila o comando hello, gerando um binário
executável. Em seguida, instala esse binário como $HOME/go/bin/hello (ou,
no Windows, %USERPROFILE%\go\bin\hello.exe).
O diretório de instalação é controlado pelas variáveis
de ambiente GOPATH e GOBIN. Se GOBIN estiver definida, os binários são instalados nesse
diretório. Se GOPATH estiver definida, os binários são instalados no
subdiretório bin do primeiro diretório da lista
GOPATH. Caso contrário, os binários são instalados no
subdiretório bin do GOPATH padrão
($HOME/go ou %USERPROFILE%\go).
Você pode usar o comando go env para definir de forma portável o valor padrão
de uma variável de ambiente para os próximos comandos go:
$ go env -w GOBIN=/somewhere/else/bin $
Para remover uma variável definida anteriormente com go env -w, use go env -u:
$ go env -u GOBIN $
Comandos como go install se aplicam no contexto do módulo
que contém o diretório de trabalho atual. Se o diretório de trabalho não estiver dentro
do módulo example/user/hello, o go install pode falhar.
Por conveniência, os comandos go aceitam caminhos relativos
ao diretório de trabalho e, se nenhum outro caminho for informado, usam por padrão o pacote do
diretório de trabalho atual.
Assim, no nosso diretório de trabalho, os comandos a seguir são todos equivalentes:
$ go install example/user/hello
$ go install .
$ go install
Em seguida, vamos executar o programa para garantir que ele funciona. Para facilitar ainda mais,
vamos adicionar o diretório de instalação ao nosso PATH para tornar a execução
dos binários simples:
# Windows users should consult /wiki/SettingGOPATH
# for setting %PATH%.
$ export PATH=$PATH:$(dirname $(go list -f '{{.Target}}' .))
$ hello
Hello, world.
$
Se você usa um sistema de controle de versão, agora é um bom momento para inicializar um repositório, adicionar os arquivos e fazer o commit da sua primeira mudança. Novamente, esta etapa é opcional: você não precisa usar controle de versão para escrever código Go.
$ git init Initialized empty Git repository in /home/user/hello/.git/ $ git add go.mod hello.go $ git commit -m "initial commit" [master (root-commit) 0b4507d] initial commit 1 file changed, 7 insertion(+) create mode 100644 go.mod hello.go $
O comando go localiza o repositório que contém um determinado caminho de módulo
fazendo uma requisição à URL HTTPS correspondente e lendo os metadados embutidos na
resposta HTML (veja
go help importpath).
Muitos serviços de hospedagem já fornecem esses metadados para repositórios que contêm
código Go, então a forma mais fácil de disponibilizar seu módulo para outros o usarem costuma ser
fazer com que o caminho do módulo coincida com a URL do repositório.
Importando pacotes do seu módulo
Vamos escrever um pacote morestrings e usá-lo a partir do programa hello.
Primeiro, crie um diretório para o pacote chamado
$HOME/hello/morestrings e, depois, um arquivo chamado
reverse.go nesse diretório com o seguinte conteúdo:
// Package morestrings implements additional functions to manipulate UTF-8
// encoded strings, beyond what is provided in the standard "strings" package.
package morestrings
// ReverseRunes returns its argument string reversed rune-wise left to right.
func ReverseRunes(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
r[i], r[j] = r[j], r[i]
}
return string(r)
}
Como nossa função ReverseRunes começa com uma letra maiúscula, ela é exportada
e pode ser usada em outros pacotes que importem nosso pacote morestrings.
Vamos verificar se o pacote compila com go build:
$ cd $HOME/hello/morestrings $ go build $
Isso não vai produzir um arquivo de saída. Em vez disso, ele salva o pacote compilado no cache de build local.
Depois de confirmar que o pacote morestrings compila, vamos usá-lo
no programa hello. Para isso, modifique seu $HOME/hello/hello.go original
para usar o pacote morestrings:
package main
import (
"fmt"
"example/user/hello/morestrings"
)
func main() {
fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
}
Instale o programa hello:
$ go install example/user/hello
Ao executar a nova versão do programa, você deve ver uma nova mensagem, invertida:
$ hello Hello, Go!
Importando pacotes de módulos remotos
Um import path pode descrever como obter o código-fonte do pacote usando um
sistema de controle de revisões, como Git ou Mercurial. A ferramenta go usa
essa propriedade para baixar pacotes automaticamente de repositórios remotos.
Por exemplo, para usar github.com/google/go-cmp/cmp no seu programa:
package main
import (
"fmt"
"example/user/hello/morestrings"
"github.com/google/go-cmp/cmp"
)
func main() {
fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
fmt.Println(cmp.Diff("Hello World", "Hello Go"))
}
Agora que você tem uma dependência de um módulo externo, precisa baixar esse
módulo e registrar sua versão no seu arquivo go.mod. O comando go
mod tidy adiciona os requisitos de módulo que faltam para os pacotes importados
e remove os requisitos de módulos que não são mais usados.
$ go mod tidy go: finding module for package github.com/google/go-cmp/cmp go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.5.4 $ go install example/user/hello $ hello Hello, Go! string( - "Hello World", + "Hello Go", ) $ cat go.mod module example/user/hello go 1.16 require github.com/google/go-cmp v0.5.4 $
As dependências dos módulos são baixadas automaticamente para o subdiretório pkg/mod
do diretório indicado pela variável de ambiente GOPATH. O conteúdo baixado de uma
versão específica de um módulo é compartilhado entre todos os outros módulos que fazem require dessa
versão, por isso o comando go marca esses arquivos e diretórios como somente leitura. Para
remover todos os módulos baixados, você pode passar a flag -modcache
para o go clean:
$ go clean -modcache $
Testes
Go tem um framework de testes leve, composto pelo comando go test
e pelo pacote testing.
Você escreve um teste criando um arquivo cujo nome termina em _test.go
e que contém funções com nomes TestXXX com a assinatura
func (t *testing.T).
O framework de testes executa cada uma dessas funções;
se a função chamar uma função de falha, como t.Error ou
t.Fail, o teste é considerado como tendo falhado.
Adicione um teste ao pacote morestrings criando o arquivo
$HOME/hello/morestrings/reverse_test.go contendo
o seguinte código Go.
package morestrings
import "testing"
func TestReverseRunes(t *testing.T) {
cases := []struct {
in, want string
}{
{"Hello, world", "dlrow ,olleH"},
{"Hello, 世界", "界世 ,olleH"},
{"", ""},
}
for _, c := range cases {
got := ReverseRunes(c.in)
if got != c.want {
t.Errorf("ReverseRunes(%q) == %q, want %q", c.in, got, c.want)
}
}
}
Em seguida, execute o teste com go test:
$ cd $HOME/hello/morestrings $ go test PASS ok example/user/hello/morestrings 0.165s $
Execute go help test e veja a
documentação do pacote testing para mais detalhes.
Próximos passos
Assine a lista de e-mails golang-announce para ser notificado quando uma nova versão estável do Go for lançada.
Veja Effective Go para dicas sobre como escrever código Go claro e idiomático.
Faça o Tour por Go para aprender a linguagem em si.
Visite a página de documentação para ver um conjunto de artigos aprofundados sobre a linguagem Go e suas bibliotecas e ferramentas.
Como obter ajuda
Para ajuda em tempo real, pergunte aos gophers prestativos no servidor gophers Slack, mantido pela comunidade (peça um convite aqui).
A lista de discussão oficial sobre a linguagem Go é a Go Nuts.
Reporte bugs usando o rastreador de issues do Go.