Pular para o conteúdo principal

Organizando Pacotes e Módulos em Go

Organizando Pacotes e Módulos em Go

O que vai na raiz de um projeto Go? Quando faz sentido criar internal/, cmd/ ou pkg/? Essas decisões dependem do que você está construindo e de quem vai usar o código.

Quero partir dessas perguntas para discutir nomes e organização de pacotes. Vamos usar um gerenciador de tarefas como exemplo, começando com poucos arquivos e chegando a uma estrutura com API e CLI. As referências da documentação do Go estão no fim do post.

Por que a organização importa?

A organização aparece em tarefas do dia a dia:

  • Clareza: outros desenvolvedores (e você mesmo no futuro) entendem rapidamente onde encontrar cada funcionalidade
  • Manutenibilidade: mudanças e refatorações ficam mais seguras e previsíveis
  • Reutilização: código bem organizado é mais fácil de compartilhar entre projetos
  • Compilação: separar responsabilidades ajuda a evitar dependências desnecessárias, que podem deixar o build mais lento; ciclos entre pacotes impedem a compilação

Ao voltar ao projeto depois de um tempo, os nomes e a divisão dos pacotes também ajudam você a recuperar o contexto.

Fundamentos: Pacotes e Módulos

Primeiro, precisamos distinguir pacote de módulo.

Pacote (Package)

Um pacote é uma coleção de arquivos Go no mesmo diretório que declaram o mesmo nome de pacote. Representa a unidade básica de organização de código em Go.

package users

Módulo (Module)

Um módulo é uma coleção de pacotes relacionados versionados juntos. É definido por um arquivo go.mod na raiz do projeto.

module github.com/rafikmoreira/account-manager

go 1.26

Princípios de Nomenclatura

1. Nomes de pacotes devem ser curtos e claros

A recomendação do Go é usar nomes curtos, em minúsculas, sem underscores ou mixedCaps. Um substantivo que diga o que o pacote contém costuma funcionar bem.

Evite:

package taskServiceClient
package priority_queue
package util
package common

Prefira:

package task
package category
package auth
package notification

2. Evite repetição entre pacote e conteúdo

Como o código cliente sempre usa o nome do pacote como prefixo ao referenciar tipos e funções exportadas, não repita informações desnecessariamente.

Evite:

package task

type TaskManager struct {}
func NewTaskManager() *TaskManager {}

Prefira:

package task

type Manager struct {}
func NewManager() *Manager {}

Veja como a chamada fica no código que usa o pacote:

manager := task.NewManager()

Em task.Manager, o nome do pacote já informa o contexto do tipo.

3. Use abreviações com moderação

Abreviar faz sentido quando quem lê reconhece o nome. É o caso destes pacotes da biblioteca padrão:

Bons exemplos:

  • strconv (string conversion)
  • fmt (formatted I/O)
  • http (HyperText Transfer Protocol)
  • syscall (system call)

Evite abreviações obscuras:

  • usrmgmt (user management)
  • acctsvc (account service)

Se a abreviação tornar o nome ambíguo ou pouco claro, use o nome completo.

Estruturas Comuns de Projetos

A estrutura pode começar pequena e ganhar diretórios conforme o código precisar deles.

Pacote Básico

Para projetos simples, todo o código pode ficar na raiz:

taskman/
  go.mod
  task.go
  task_test.go
  filter.go
  filter_test.go
module github.com/rafikmoreira/taskman

Arquivo task.go:

package task

type Task struct {
    ID          string
    Title       string
    Description string
    Completed   bool
}

Usuários importam com:

import "github.com/rafikmoreira/taskman"

Projeto com Pacotes de Suporte

Quando o projeto cresce, use o diretório internal/ para pacotes auxiliares que você não quer expor publicamente:

taskman/
  go.mod
  task.go
  task_test.go
  internal/
    validation/
      validation.go
      validation_test.go
    storage/
      sqlite.go
      sqlite_test.go

O comando go restringe quem pode importar um pacote dentro de internal/: o caminho de importação de quem o usa precisa compartilhar o prefixo anterior a internal. No exemplo, esse prefixo é github.com/rafikmoreira/taskman. A regra permite mudar as implementações internas sem quebrar o código de usuários externos a esse limite. Os detalhes estão na documentação de pacotes internos.

Múltiplos Pacotes Exportáveis

Para bibliotecas que oferecem múltiplas funcionalidades relacionadas:

taskman/
  go.mod
  task.go
  task_test.go
  category/
    category.go
    category_test.go
  label/
    label.go
    label_test.go
  priority/
    priority.go
    priority_test.go
  internal/
    audit/
      audit.go

Usuários podem importar especificamente o que precisam:

import "github.com/rafikmoreira/taskman"
import "github.com/rafikmoreira/taskman/category"
import "github.com/rafikmoreira/taskman/label"
import "github.com/rafikmoreira/taskman/priority"

Exemplo Completo: Sistema de Gerenciamento de Tarefas

Agora vamos reunir essas escolhas em um gerenciador de tarefas com mais funcionalidades. O exemplo abaixo propõe a organização dos arquivos; a implementação de cada recurso fica fora do escopo deste post.

Requisitos do Sistema

  • Criar e gerenciar tarefas com título, descrição e status
  • Organizar tarefas por categorias e etiquetas
  • Definir prioridades e prazos
  • Filtrar e buscar tarefas
  • Enviar notificações de lembretes
  • Gerar relatórios de produtividade
  • API REST e CLI para acesso

Estrutura Proposta

taskman/
  go.mod
  README.md
  
  cmd/
    api-server/
      main.go
    cli/
      main.go
  
  internal/
    server/
      server.go
      routes.go
      middleware.go
    storage/
      sqlite.go
      migrations/
    config/
      config.go
  
  pkg/
    task/
      task.go
      task_test.go
      repository.go
    category/
      category.go
      category_test.go
      repository.go
    label/
      label.go
      label_test.go
    priority/
      priority.go
      priority_test.go
    notification/
      email.go
      notification.go
      notification_test.go
    report/
      report.go
      generator.go

Detalhamento dos Diretórios

Diretório cmd/

O diretório cmd/ contém os pontos de entrada da aplicação. Cada subdiretório representa um programa executável diferente.

Instalação pelo usuário:

go install github.com/rafikmoreira/taskman/cmd/api-server@latest
go install github.com/rafikmoreira/taskman/cmd/cli@latest

Diretório internal/

Reúne as implementações específicas do projeto, com a restrição de importação de internal/ que vimos acima.

Diretório pkg/ (Opcional)

Neste exemplo, reúne a lógica de negócio que outros projetos podem importar. O nome pkg/ é opcional e não cria uma regra de acesso especial no Go.

Segundo a documentação oficial, pacotes exportáveis podem estar diretamente na raiz do módulo ou em subdiretórios. O uso de pkg/ é uma convenção adotada por alguns projetos grandes (como Kubernetes) para tornar explícito que o código é público, diferenciando-o de cmd/ e internal/. Projetos menores geralmente não necessitam desta camada adicional.

Erros Comuns e Como Evitá-los

Pacotes "Utilitários" Genéricos

Ao encontrar um pacote chamado util, common ou misc, o que você espera que esteja dentro dele? Esses nomes dão pouca informação e dificultam decidir o que pertence ao pacote.

Agrupe as funcionalidades relacionadas e dê um nome a esse grupo. Um pacote utils pode dar lugar a pacotes como stringset, auth e validation.

Pacotes Monolíticos de API

Colocar todas as interfaces em um único pacote (geralmente chamado api, types ou interfaces) é outro erro comum. Esses pacotes sofrem dos mesmos problemas que util, crescendo sem limites e acumulando dependências desnecessárias.

Nesse caso, separe por contexto de domínio: task, category e label dizem mais sobre o conteúdo do que um único pacote api.

Dependências Circulares

Dependências circulares entre pacotes são proibidas em Go e resultam em erros de compilação.

task/ → category/ → task/  (não compila)

Para desfazer o ciclo, reorganize a direção das dependências ou extraia as interfaces necessárias para um pacote que não dependa dos dois lados.

Lógica Concentrada no Pacote Main

Concentrar toda a lógica da aplicação no pacote main dificulta testes e reutilização.

Conforme essa lógica cresce, extraia-a para outros pacotes e deixe main responsável por iniciar a aplicação e conectar as chamadas entre eles.

Diretrizes de Layout por Tipo de Projeto

Biblioteca Pura

Código para ser importado por outros projetos. Use a raiz para o pacote principal:

mylib/
  go.mod
  mylib.go
  mylib_test.go
  feature1/
    feature1.go
    feature1_test.go
  feature2/
    feature2.go
  internal/
    helpers/

Quem usa essa biblioteca importa o pacote principal pela raiz e escolhe os demais conforme precisar.

Aplicação CLI

Em uma ferramenta de linha de comando com pacotes de apoio, você pode colocar a lógica em internal/ e o executável em cmd/:

mytool/
  go.mod
  cmd/
    mytool/
      main.go
  internal/
    cli/
      commands.go
      flags.go
    processor/
      processor.go

Aqui, o que será distribuído é o executável. Para um comando pequeno, também é possível começar com main na raiz, sem criar essa divisão de imediato.

Servidor/API

Para projetos com servidor e lógica de negócio:

myserver/
  go.mod
  cmd/
    server/
      main.go
  internal/
    server/
      server.go
      routes.go
    database/
      postgres.go
  pkg/
    domain1/
      domain1.go
    domain2/
      domain2.go

Use essa divisão quando houver lógica de domínio a compartilhar com outros projetos. Se o código só atende ao servidor, mantenha-o em internal/. Quando o compartilhamento crescer, o guia oficial recomenda separar os pacotes reutilizáveis em outros módulos.

Projeto Misto

Para bibliotecas que também fornecem ferramentas auxiliares:

myproject/
  go.mod
  core.go
  core_test.go
  feature/
    feature.go
  cmd/
    tool1/
      main.go
    tool2/
      main.go
  internal/
    shared/

Os usuários podem importar a biblioteca e instalar as ferramentas de cmd/ separadamente.

Quando Migrar Entre Estruturas

A estrutura inicial pode deixar de atender ao projeto. Estas são algumas situações em que vale mudá-la:

De Raiz para internal/

Quando o código cresce mas não há intenção de expor pacotes publicamente, mova-os para internal/.

Antes:
project/
  go.mod
  handler.go
  database.go

Depois:
project/
  go.mod
  internal/
    handler/
    database/

De internal/ para Pacotes Exportáveis

Quando outros projetos precisam reutilizar código que está em internal/, mova-o para a raiz do módulo ou para um subdiretório apropriado.

Antes:
internal/
  auth/

Depois:
pkg/
  auth/

Adicionar cmd/

Use cmd/ quando precisar organizar vários executáveis ou separar as ferramentas CLI dos pacotes da biblioteca.

Antes:
project/
  main.go
  pkg/

Depois:
project/
  cmd/
    server/
      main.go
    cli/
      main.go
  pkg/

Checklist de Boas Práticas

Na revisão de um projeto Go, estas perguntas ajudam a conferir as escolhas:

Nomenclatura

  • Os nomes dos pacotes são substantivos simples e descritivos?
  • Evitei nomes genéricos como util, common, helpers?
  • O nome do pacote não se repete nos tipos/funções exportados?
  • Abreviações usadas são amplamente conhecidas?

Estrutura

  • Código privado está em internal/?
  • Cada pacote tem uma responsabilidade clara e única?
  • Se há vários executáveis ou uma mistura de biblioteca e comandos, faz sentido reuni-los em cmd/?
  • O go.mod está na raiz do projeto?
  • Não há dependências circulares?

Testabilidade

  • A estrutura facilita testes?
  • Testes estão junto aos arquivos (*_test.go)?
  • Interfaces permitem mocking de dependências?

Documentação

  • Há um README.md explicando o projeto?
  • Pacotes principais têm comentários de documentação?
  • Exemplos de uso estão claros?

Conclusão

A árvore do gerenciador de tarefas reúne várias possibilidades. Você pode começar com menos diretórios e voltar a estas decisões conforme o projeto crescer:

  1. Comece simples: evite criar estruturas complexas prematuramente. Adicione diretórios conforme surgir a necessidade real.
  2. Use internal/ generosamente: exponha apenas o que será suportado publicamente. Mantenha implementações internas privadas.
  3. Nomes são importantes: invista tempo escolhendo bons nomes de pacotes. Nomes claros tornam o código auto-explicativo.
  4. Refatore quando necessário: a estrutura deve evoluir com o projeto. Reorganize quando a estrutura atual não atender mais as necessidades.
  5. Aprenda com a comunidade: observe projetos Go estabelecidos e a biblioteca padrão para absorver padrões comprovados.

Para experimentar essas escolhas em código:

  • Estude o código-fonte da biblioteca padrão do Go
  • Analise projetos open source estabelecidos em Go no GitHub
  • Refatore projetos existentes aplicando essas diretrizes
  • Participe de revisões de código com foco em estrutura e organização

Referências e Leituras Complementares

Documentação Oficial

Recursos da Comunidade

Ao consultar pkg.go.dev/std, observe os nomes e as dependências entre pacotes. Isso ajuda a comparar as recomendações com código em uso.

Voltar