Como pacotes e módulos organizam código em Go?

Question

Accepted Answer

Go organiza código com **packages** (coleções de arquivos de código-fonte em um diretório) e **modules** (coleções de packages com dependências versionadas). Juntos, eles estruturam projetos e gerenciam dependências.

## Packages — um diretório de código relacionado

```go
// every .go file starts by declaring its package
package main         // "main" is special — produces an executable

// or a library package (named after its directory, conventionally)
package mathutil

func Add(a, b int) int { return a + b }   // Exported (capitalized) — usable outside
func helper() {}                           // unexported (lowercase) — package-private
```

Todos os arquivos em um diretório pertencem a um package. **A capitalização controla visibilidade**: nomes capitalizados são exportados (públicos entre packages), minúsculos são privados do package.

## Importando e usando packages

```go
import (
    "fmt"                          // standard library
    "strings"
    "github.com/user/repo/mathutil" // a third-party or local module package
)

fmt.Println(strings.ToUpper("hi"))
mathutil.Add(2, 3)                  // use Exported names via package.Name
```

## Modules — gerenciamento de dependências versionado

```bash
go mod init github.com/user/myapp   # create a module → makes go.mod
go get github.com/gin-gonic/gin     # add a dependency (records it in go.mod)
go mod tidy                          # add missing & remove unused dependencies
go build                             # build using the module's dependencies
```

```text
go.mod  — declares the module path, Go version, and direct dependencies (+ versions)
go.sum  — cryptographic checksums of dependencies (integrity/security)
```

Um **module** (introduzido no Go 1.11) é a unidade de gerenciamento de dependências — `go.mod` lista versões exatas de dependências, tornando as compilações reproduzíveis. `go.sum` verifica a integridade das dependências.

## A função init e main

```go
package main

func init() {    // runs automatically when the package loads (before main)
    // setup
}
func main() {    // entry point of an executable (package main only)
}
```

## Convenções de estrutura de projeto

```text
myapp/
  go.mod
  main.go              package main
  internal/            packages here are PRIVATE to this module (can't be imported externally)
  pkg/ or other dirs/  reusable packages
```

O diretório `internal/` é especial — seus packages podem ser importados apenas dentro do mesmo module, aplicando encapsulamento no nível do module.

## Por que isso importa

Packages e modules são como projetos Go são estruturados e como dependências são gerenciadas — essencial para qualquer projeto real.

Entender packages (um diretório de arquivos, visibilidade baseada em capitalização de exportado/não exportado, o package especial `main`) é fundamental para organizar código e controlar sua API pública.

Modules (`go mod`, `go.mod`/`go.sum`) fornecem gerenciamento de dependências reproduzível, versionado e verificado quanto à integridade — o padrão moderno que substituiu a abordagem antiga do GOPATH.

Conhecer o sistema de import, a convenção `internal/` para código privado de modules e as ferramentas (`go mod init/tidy`, `go get`) é necessário para construir, compartilhar e manter projetos Go, e reflete fluência prática com o ecossistema Go.