Este projeto demonstra como criar um servidor HTTP completo com Domain-Driven Design (DDD), usando Gin e implementando um graceful shutdown.
.
├── cmd
│ └── main.go
├── go.mod
├── go.sum
├── internal
│ ├── domain
│ │ └── product
│ │ ├── entity
│ │ │ └── product.go
│ │ ├── events
│ │ │ └── product_created_event.go
│ │ └── repository
│ │ └── product_repository.go
│ ├── infra
│ │ └── http
│ │ ├── handlers
│ │ │ └── product_handler.go
│ │ └── router
│ │ └── product_router.go
│ └── shared
│ └── domain
│ └── events
│ └── events_handler.go
└── README.md
- Domínio puro e desacoplado: Entidades de domínio com validação integrada
- Repositório thread-safe: Usando
sync.RWMutexpara acesso concorrente seguro - Dispatcher de eventos de domínio: Sistema de eventos para extensibilidade
- Graceful shutdown: Encerramento controlado respeitando requisições em andamento
- Arquitetura limpa: Separação clara entre camadas de domínio, aplicação e infraestrutura
- Flyway Migrations: Versionamento automático e rastreável do schema do banco
- Go 1.23 ou superior
- Clone o repositório
- Instale as dependências:
go mod download- Configurar banco de dados:
# Copiar arquivo de configuração
cp config.env.example config.env
# Editar se necessário (valores padrão já funcionam)
# vim config.env
# Iniciar PostgreSQL
make db-up
# Aguardar ~10 segundos para migrations rodarem automaticamente- Execute a API:
Opção 1: Com Makefile (recomendado):
make runOpção 2: Diretamente:
go run cmd/main.goO servidor estará disponível em http://localhost:8080
make help # Ver todos os comandos disponíveis
make swagger # Gerar documentação Swagger
make build # Compilar binário
make run # Executar com auto-geração de docs
make dev # Executar sem regenerar docs
make clean # Limpar binários
make test # Executar testes
# Banco de dados
make db-up # Iniciar PostgreSQL
make db-down # Parar PostgreSQL
make db-connect # Conectar ao banco
make db-seed # Popular com dados
make db-clean # Limpar dados
make db-reset # Resetar banco
# Plataforma completa
make platform-up # Inicia tudo (DB + API + Monitoring)
make platform-down # Para tudo
make platform-logs # Ver logs de tudo
make platform-status # Status dos serviçosAcesse a documentação interativa da API em:
http://localhost:8080/swagger/index.html
Você pode testar todos os endpoints diretamente pelo navegador! 🎯
curl -X POST http://localhost:8080/api/v1/products \
-H "Content-Type: application/json" \
-d '{
"name": "Notebook",
"sku": 12345,
"categories": ["Eletrônicos", "Computadores"],
"price": 3500
}'curl http://localhost:8080/api/v1/productscurl http://localhost:8080/api/v1/products/Notebook- Entidade Product: Representa um produto com validações de negócio
- ProductCreatedEvent: Evento disparado quando um produto é criado
- ProductRepository: Interface e implementação para persistência de produtos
- ProductHandler: Handlers HTTP para operações com produtos
- Router: Configuração de rotas da API
- EventDispatcher: Sistema de eventos para comunicação entre componentes
O servidor implementa um shutdown controlado que:
- Captura sinais de terminação (SIGINT, SIGTERM)
- Aguarda até 5 segundos para finalizar requisições em andamento
- Encerra o servidor de forma limpa
Para testar, execute o servidor e pressione Ctrl+C. Você verá:
Received termination signal. Shutting down server...
Server shut down gracefully.
- ✅ Arquitetura Limpa - Separação clara entre camadas
- ✅ DDD - Domain-Driven Design com entidades ricas
- ✅ Persistência PostgreSQL - Dados persistidos em banco relacional
- ✅ Migrations - Controle de versão do schema do banco
- ✅ Thread-Safe - Repositório com proteção para concorrência
- ✅ Event Dispatcher - Sistema de eventos de domínio
- ✅ Graceful Shutdown - Encerramento controlado com fechamento do banco
- ✅ RESTful API - Endpoints bem definidos com Gin
- ✅ Swagger/OpenAPI - Documentação interativa automática
- ✅ Prometheus Monitoring - Golden Signals + métricas de negócio
Golden Signals (Google SRE):
- 🕐 Latency: Tempo de resposta das requisições
- 📈 Traffic: Taxa de requisições por segundo
- ❌ Errors: Taxa de erros (4xx, 5xx)
- 📊 Saturation: Requisições simultâneas
Métricas de Negócio:
- Produtos criados (total e taxa)
- Total de produtos em estoque
- Produtos por categoria
- Valor total do inventário
- Preço médio dos produtos
http://localhost:8080/metrics # Endpoint Prometheus
# Inicia PostgreSQL + API + Prometheus + Grafana
docker-compose up -d
# Ou use o Makefile
make platform-upAcesse:
- API:
http://localhost:8080 - Swagger:
http://localhost:8080/swagger/index.html - Prometheus:
http://localhost:9090 - Grafana:
http://localhost:3000(admin/admin) - PostgreSQL:
localhost:5432
📖 Guia completo de monitoramento →
- Go 1.24: Linguagem de programação
- Gin: Framework web de alta performance
- PostgreSQL: Banco de dados relacional
- Prometheus: Sistema de monitoramento e métricas
- Swagger/OpenAPI: Documentação interativa da API
- Flyway: Migrations de banco de dados versionadas
- DDD: Domain-Driven Design para arquitetura limpa
- Docker: Containerização com multi-stage build (~110MB)
Para entender os conceitos e padrões utilizados neste projeto, consulte a documentação técnica:
- Domain-Driven Design (DDD) - Entenda como organizamos o domínio
- Arquitetura Limpa - Conheça a estrutura de camadas
- Event Dispatcher - Aprenda sobre eventos de domínio
- Graceful Shutdown - Veja como implementamos shutdown controlado
- RESTful API com Gin - Domine o framework Gin
- Swagger / OpenAPI - Documentação interativa da API
- Prometheus Monitoring - Golden Signals e métricas de negócio
- Docker & Deployment - Multi-stage build e containerização
- Flyway Migrations - Gerenciamento profissional de migrations
- Prometheus Queries (PromQL) - Guia completo de queries para métricas
- Database PostgreSQL - Schema SQL, migrations e persistência
Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.
Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
Baseado no artigo de William Koller
