samber/golang-project-layout

O que golang-project-layout faz?

Fornece um guia para configurar layouts e workspaces de projetos Golang. Use ao iniciar um novo projeto Go, organizar um código existente, configurar um monorepo com múltiplos pacotes, criar ferramentas CLI com múltiplos pacotes main, decidir entre convenções de diretório cmd/internal/pkg, ou discutir reestruturação, divisão de pacotes ou módulos.

Estrutura de Diretórios Recomendada

meu-projeto-go/
├── cmd/              # Aplicações principais do projeto
│   ├── app1/         # main package para app1
│   │   └── main.go
│   └── app2/         # main package para app2
│       └── main.go
├── internal/         # Pacotes privados, não exportados
│   └── db/
│       ├── migrator.go
│       └── store.go
├── pkg/              # Pacotes públicos que podem ser importados por outros projetos
│   ├── config/
│   └── utils/
├── api/              # Definições de API (OpenAPI, gRPC, etc.)
├── web/              # Ativos web (HTML, CSS, JS, etc.)
├── scripts/          # Scripts de build, deploy, etc.
├── test/             # Testes de integração ou dados de teste
├── go.mod
├── go.sum
├── Makefile
└── README.md

Workspaces de Módulos

Use workspaces (go.work) para projetos com múltiplos módulos, como monorepos:

go.work
├── meu-modulo/
│   └── go.mod
└── outro-modulo/
    └── go.mod

Convenções de Diretório

cmd/

• Cada subdiretório contém um main.go e é um pacote main.
• Nomeie os subdiretórios de acordo com o nome do binário gerado.

internal/

• Pacotes privados que só podem ser importados pelo módulo raiz.
• Ideal para lógica de negócios, acesso a dados, configurações.

pkg/

• Pacotes que podem ser reutilizados por outros projetos.
• Opcional; use apenas se houver intenção de exportar.

Decisões Comuns

• Reestruturação de pacotes: Mova código de pacotes grandes para subpacotes ou módulos menores.
• Divisão de pacotes: Separe funcionalidades distintas em pacotes independentes para melhor coesão.
• Divisão de módulos: Quando um projeto cresce demais, extraia módulos específicos em repositórios ou workspaces separados.

Links Úteis

• Documentação oficial de workspaces
• Guia de layout de projetos Go

---

Nota: Este guia segue as práticas recomendadas pela comunidade Go e pode ser adaptado conforme a necessidade do projeto.