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.