
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.modestá 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.mdexplicando 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:
- Comece simples: evite criar estruturas complexas prematuramente. Adicione diretórios conforme surgir a necessidade real.
- Use
internal/generosamente: exponha apenas o que será suportado publicamente. Mantenha implementações internas privadas. - Nomes são importantes: invista tempo escolhendo bons nomes de pacotes. Nomes claros tornam o código auto-explicativo.
- Refatore quando necessário: a estrutura deve evoluir com o projeto. Reorganize quando a estrutura atual não atender mais as necessidades.
- 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
- Package names - The Go Blog - Artigo oficial sobre convenções de nomenclatura de pacotes
- Organizing a Go module - Go Documentation - Guia oficial sobre estruturação de módulos Go
- Effective Go - Documento fundamental sobre estilo e convenções Go
- How to Write Go Code - Tutorial sobre organização básica de código Go
Recursos da Comunidade
- Go Code Review Comments - Guia de revisão de código da equipe Go
- Organizing Go Code (2012) - Visão histórica da organização de código
- Go Modules Reference - Referência completa sobre módulos
- Internal Packages - Explicação detalhada do diretório
internal/
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.