api-gateway

1. OBJETIVO

Gateway HTTP em Go que aplica autenticação externa, rate limiting, cache, balanceamento de carga e observabilidade. Atua como ponto de entrada único para todos os microserviços do ecossistema Aster/UVA, implementando Clean Architecture com funcionalidades essenciais de proxy reverso, circuit breaker, rate limiting, cache em memória e extração automática de claims JWT para multi-tenancy.

2. ÚLTIMA REVISÃO

• 15/09/2025 - Revisão e atualização da documentação (Equipe)

3. TECNOLOGIAS UTILIZADAS

Backend

Go 1.20, Gin v1.10.0 (HTTP), Viper v1.19.0 (config), Zap v1.27.0 (logging)

Prometheus v1.20.5 (métricas), Sony/gobreaker v0.4.1 (circuit breaker)

go-cache v2.1.0 (memória), JWT v5.2.1 (claims), validator/v10 v10.20.0

yaml.v3 v3.0.1 (config), Redis v9.7.0 (preparado), Repositórios: Local/GitHub

Frontend

Não aplicável (gateway puro)

Banco de Dados

Não aplicável (sem persistência própria)

Ferramentas de Conexão e Infraestrutura

Docker Compose (multi-stage), PostgreSQL 13 (Auth Service), SSL/TLS (Let's Encrypt)

Mock Service (testes), Rede compartilhada (astor_shared_network)

4. FUNCIONALIDADES E DOMÍNIOS

• Proxy Reverso: Roteamento dinâmico baseado em YAML, suporte a subpaths (/*subpath), preservação de headers e query parameters, timeout 15s
• Balanceamento de Carga: Round-robin thread-safe entre múltiplos endpoints, seleção atômica
• Circuit Breaker: Proteção contra falhas em cascata, configuração por rota (timeout 5s, max failures 3, reset 10s)
• Rate Limiting: Limitação global (100 req/s, burst 20) com token bucket, resposta 429
• Cache: Cache em memória com TTL 30s, chave SHA256, interceptação transparente, limpeza automática
• Autenticação: Extração automática JWT (Bearer token), headers x-tenant-id/user-id/user-name, suporte super admin (bypass tenant isolation)
• Observabilidade: Logs estruturados Zap, métricas Prometheus (api_gateway_requests_total), health check (/healthz), métricas (/metrics)
• SSL/TLS: Let's Encrypt autocert, certificados manuais, redirecionamento HTTP→HTTPS, cache de certificados

5. ARQUITETURA FRONTEND

Não aplicável - Gateway puro sem interface frontend

6. ARQUITETURA BACKEND

Controllers/Handlers

ProxyRequest (roteamento), HealthCheckHandler (/healthz), Métricas Prometheus (/metrics)

Features

Proxy reverso round-robin thread-safe, Circuit breaker (timeout 5s, max failures 3), Rate limiting (100 req/s, burst 20)

Cache opcional (TTL 30s), Extração automática JWT (tenant-id, user-id, user-name, isSuperAdmin), SSL/TLS com Let's Encrypt

Middlewares

CORS, Cache (chave SHA256), Rate Limit (golang.org/x/time/rate), External Auth (preparado), Request Validation (validator/v10), SSL

Repositories

Não aplicável (gateway stateless)

Entities/DTOs

ServerConfig, RouteConfig, BackendConfig, AuthServiceConfig, RateLimitConfig, CircuitBreakerConfig, CacheConfig

Helper/Utilities

Logger (Zap estruturado), Metrics (Prometheus RequestCounter), Cache (go-cache com limpeza), Balancer (round-robin atômico), Circuit Breaker (sony/gobreaker)

7. ROTAS E ENDPOINTS

Endpoints internos: /healthz (health check), /metrics (Prometheus)

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Não aplicável - Gateway stateless sem persistência própria

9. CONFIGURAÇÃO E VARIÁVEIS

Arquivo principal

configs/config.yaml

Sobrescrita via ENV

Prefixo API_GATEWAY_ (ex: API_GATEWAY_SERVER_PORT, API_GATEWAY_ENDPOINTS_[ROTA], API_GATEWAY_RATE_LIMIT_ENABLED)

Configurações principais

Porta: 8080 (HTTP), 443 (HTTPS); Rate Limit: 100 req/s, burst 20 (habilitado por padrão)

Circuit Breaker: timeout 5s, max failures 3, reset 10s (habilitado por padrão); Cache: TTL 30s (desabilitado por padrão)

SSL: Suporte a Let's Encrypt autocert e certificados manuais; Auth Service: https://auth.prod.aster.app.br, timeout 5s

Load Balancer: round_robin para todas as rotas

10. TREEVIEW DA ARQUITETURA

api-gateway/
├── cmd/
│   └── main.go                    # Ponto de entrada, inicialização
├── configs/
│   └── config.yaml               # Configuração principal
├── internal/
│   └── gateway/
│       ├── adapters/
│       │   ├── balancer/
│       │   │   └── roundrobin.go  # Balanceamento round-robin
│       │   └── circuitbreaker/
│       │       └── gobreaker_adapter.go # Circuit breaker
│       ├── config/
│       │   └── loader.go          # Carregamento de configuração
│       ├── handlers/
│       │   ├── health_check.go    # Health check endpoint
│       │   └── proxy_handler.go   # Handler principal de proxy
│       ├── middlewares/
│       │   ├── cache_middleware.go      # Cache de respostas
│       │   ├── cors_middleware.go       # Headers CORS
│       │   ├── external_auth_middleware.go # Auth externa
│       │   ├── rate_limit_middleware.go    # Rate limiting
│       │   ├── request_validation_middleware.go # Validação
│       │   └── ssl_middleware.go         # SSL/TLS
│       ├── router/
│       │   └── router.go          # Configuração de rotas
│       └── usecases/
│           └── proxy_usecase.go  # Lógica de proxy e JWT
├── pkg/
│   ├── cache/
│   │   └── cache.go              # Wrapper go-cache
│   ├── logger/
│   │   └── zap_logger.go         # Configuração Zap
│   └── metrics/
│       └── prometheus.go         # Métricas Prometheus
├── docker-compose.yml            # Orquestração de serviços
├── Dockerfile                    # Build multi-stage
├── go.mod                        # Dependências Go
├── go.sum                        # Checksums dependências
└── README.md                     # Documentação do projeto

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos

Auth Service (JWT - https://auth.prod.aster.app.br), Microserviços backend (11 configurados), Prometheus (opcional, preparado), Redis (preparado, comentado), PostgreSQL (Auth Service via Docker Compose)

Dependências principais

gin-gonic/gin v1.10.0, spf13/viper v1.19.0, go.uber.org/zap v1.27.0, prometheus/client_golang v1.20.5

sony/gobreaker v0.4.1, patrickmn/go-cache v2.1.0, golang.org/x/time v0.8.0, golang.org/x/crypto v0.24.0

github.com/golang-jwt/jwt/v5 v5.2.1, github.com/go-playground/validator/v10 v10.20.0, gopkg.in/yaml.v3 v3.0.1

12. INTEGRAÇÕES EXTERNAS

Auth Service

Integração com microserviço de autenticação para validação JWT

Microserviços Backend

Roteamento para todos os microserviços do ecossistema Aster/UVA

Prometheus

Coleta de métricas de performance e monitoramento

Let's Encrypt

Certificados SSL/TLS automáticos

13. CONTROLE DE VERSÃO

• Repositório: Local/GitHub
• Versionamento semântico recomendado
• Docker multi-stage build para otimização
• Docker Compose para desenvolvimento

14. SEGURANÇA E ACESSO

• Autenticação via JWT com extração automática de claims
• Headers de segurança (x-tenant-id, x-user-id, x-user-name)
• Suporte a SSL/TLS com Let's Encrypt
• Rate limiting para proteção contra DDoS
• Circuit breaker para resiliência
• CORS configurado, validação de requests preparada

15. CONSIDERAÇÕES FINAIS

API Gateway robusto e extensível em Go, seguindo Clean Architecture, com funcionalidades essenciais de proxy reverso, balanceamento de carga, circuit breaker, rate limiting, cache e observabilidade. Preparado para produção com suporte a SSL, multi-tenancy via JWT e integração com ecossistema de microserviços Aster/UVA. Arquitetura modular permite fácil extensão e manutenção. O gateway implementa extração automática de claims JWT para multi-tenancy, com suporte especial para super admin, e está configurado para rotear 11 microserviços diferentes. A implementação inclui Docker Compose para desenvolvimento local com Auth Service e PostgreSQL, e está preparada para integração com Redis e Prometheus em ambientes de produção.