Forem: Thiago Matos

🎯 Guia de Conhecimentos em Golang por Nível

Thiago Matos — Fri, 23 Jan 2026 17:48:06 +0000

Este documento serve como referência para entrevistas técnicas de desenvolvedores Go, organizando os conhecimentos esperados por nível de senioridade.

👶 Desenvolvedor Júnior

Fundamentos da Linguagem

Sintaxe básica: Variáveis, constantes, tipos de dados primitivos
Estruturas de controle: if/else, switch, for loops
Funções: Declaração, parâmetros, retorno múltiplo
Arrays e Slices: Diferenças e uso básico
Maps: Criação, inserção, leitura e deleção
Structs: Definição e uso básico
Ponteiros: Conceito básico e quando usar & e *
Packages: Importação e uso de pacotes da stdlib
Error handling: Tratamento básico de erros com if err != nil

Conceitos Básicos

Exported vs Unexported: Entender maiúsculas/minúsculas em identificadores
Zero values: Valores padrão dos tipos
Type conversion: Conversão entre tipos
String manipulation: Operações básicas com strings
fmt package: Printf, Sprintf, Println

Ferramentas Essenciais

go run: Executar programas Go
go build: Compilar programas
go fmt: Formatar código automaticamente
go mod init: Inicializar módulo Go
go get: Baixar dependências

Bibliotecas Standard Library (Básicas)

fmt - Formatação de I/O
strings - Manipulação de strings
strconv - Conversões string/números
os - Interação com sistema operacional
io - Interfaces básicas de I/O

Perguntas Sugeridas para Júnior

1. Explique a diferença entre array e slice

Resposta esperada:

Array tem tamanho fixo definido em tempo de compilação [5]int
Slice é dinâmico, referência para um array subjacente []int
Slice pode crescer com append()
Arrays são valores, slices são referências

2. O que são zero values? Dê exemplos

Resposta esperada:

Valor padrão quando variável é declarada sem inicialização
int/float: 0
string: "" (vazia)
bool: false
pointer/slice/map/channel: nil

3. Como você declara uma variável em Go? Quais as diferentes formas?

Resposta esperada:

var x int = 10          // declaração completa
var x = 10              // tipo inferido
x := 10                 // declaração curta (apenas em funções)
var x int               // declarada com zero value

4. O que acontece se você não tratar um erro retornado por uma função?

Resposta esperada:

O compilador não força tratamento de erro
Variável err fica ignorada (usar _ para explícito)
Pode causar bugs silenciosos em runtime
Boa prática: sempre verificar if err != nil

5. Qual a diferença entre make e new?

Resposta esperada:

new(T): aloca memória zerada, retorna *T (ponteiro)
make(T): inicializa slice/map/channel, retorna T (não ponteiro)
new para qualquer tipo, make apenas para slice, map, channel
make pode especificar capacidade: make([]int, 0, 10)

6. Como funciona o retorno múltiplo de funções?

Resposta esperada:

func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, errors.New("divisão por zero")
    }
    return a / b, nil
}

result, err := divide(10, 2)

Go permite retornar múltiplos valores
Comum retornar (resultado, error)
Pode usar retornos nomeados

🧑‍💻 Desenvolvedor Pleno

Conhecimentos Avançados da Linguagem

Interfaces: Definição, implementação implícita, type assertion
Goroutines: Criação e conceitos de concorrência
Channels: Comunicação entre goroutines, buffered vs unbuffered
Select statement: Multiplexing de channels
Defer: Uso e ordem de execução
Panic e Recover: Quando e como usar
Methods: Receivers (value vs pointer)
Embedding: Composição de structs
Type assertions e Type switches
Generics (Go 1.18+): Sintaxe básica e uso

Padrões e Boas Práticas

Error handling: Padrões idiomáticos, custom errors
Context package: Cancelamento e timeouts
Dependency injection: Injeção de dependências
Clean Architecture: Separação de camadas
SOLID principles aplicados em Go
Table-driven tests: Padrão de testes em Go
Naming conventions: Convenções de nomenclatura

Ferramentas e Ecosystem

go test: Testes unitários e de integração
go mod: Gerenciamento completo de dependências
go vet: Análise estática de código
golangci-lint: Linting avançado
go generate: Geração de código
Delve: Debugger para Go
pprof: Profiling de performance

Bibliotecas Standard Library (Intermediárias)

net/http - Servidor HTTP e cliente
encoding/json - Serialização JSON
database/sql - Interface de banco de dados
context - Controle de contexto e cancelamento
sync - Primitivas de sincronização (Mutex, WaitGroup, Once)
time - Manipulação de tempo
log - Logging básico
testing - Framework de testes

Frameworks e Bibliotecas Populares

Web Frameworks: Gin, Echo, Fiber, Chi
ORMs: GORM, sqlx, ent
Validation: go-playground/validator
Configuration: Viper, envconfig
Testing: testify, gomock

Banco de Dados

Uso de database/sql com drivers (postgres, mysql)
Preparação de statements
Transações
Connection pooling
Migrations (golang-migrate, goose)

Perguntas Sugeridas para Pleno

1. Explique como funcionam as goroutines e o scheduler do Go

Resposta esperada:

Goroutines são threads leves gerenciadas pela runtime do Go
Scheduler usa modelo M:N (M goroutines em N threads OS)
Componentes: G (goroutine), M (thread OS), P (processador lógico)
Work stealing: P rouba goroutines de outras filas quando ociosas
Preemptivo desde Go 1.14

2. Qual a diferença entre buffered e unbuffered channels?

Resposta esperada:

Unbuffered make(chan int): send bloqueia até receive
Buffered make(chan int, 10): send só bloqueia se buffer cheio
Unbuffered garante sincronização
Buffered permite assincronia limitada

3. Quando você usaria um pointer receiver vs value receiver?

Resposta esperada:

Pointer receiver: modificar estado, grandes structs, consistência
Value receiver: imutabilidade, pequenas structs, tipos primitivos
Regra: se algum método usa pointer, todos devem usar

func (p *Person) SetName(n string) { p.name = n } // pointer
func (p Person) GetName() string { return p.name } // value ok

4. Como você implementaria um rate limiter usando channels?

Resposta esperada:

limiter := time.Tick(100 * time.Millisecond)
for req := range requests {
    <-limiter  // bloqueia até próximo tick
    go handle(req)
}

Ou usar golang.org/x/time/rate com token bucket

5. Explique o padrão de erro idiomático em Go e como criar custom errors

Resposta esperada:

// Padrão idiomático
result, err := doSomething()
if err != nil {
    return fmt.Errorf("failed to do something: %w", err)
}

// Custom error
type ValidationError struct {
    Field string
    Message string
}
func (e *ValidationError) Error() string {
    return fmt.Sprintf("%s: %s", e.Field, e.Message)
}

Usar %w para wrapping (Go 1.13+)
errors.Is() e errors.As() para verificação

6. Como funciona o Context e quando você deve usá-lo?

Resposta esperada:

Propaga cancelamento, timeouts e valores entre goroutines
Primeiro parâmetro de funções por convenção

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

Usar para: requests HTTP, queries DB, operações longas
Não usar para: passar dependências opcionais

7. Qual a diferença entre sync.Mutex e sync.RWMutex?

Resposta esperada:

Mutex: lock exclusivo (escrita ou leitura)
RWMutex: múltiplos readers ou um writer
RWMutex otimiza cenários read-heavy

mu.RLock()   // múltiplas goroutines podem ler
mu.RUnlock()
mu.Lock()    // exclusivo para escrita
mu.Unlock()

8. Como você estruturaria uma aplicação web em Go?

Resposta esperada:

/cmd/api       - entry point
/internal
  /handlers    - HTTP handlers
  /services    - business logic
  /repository  - data access
  /models      - domain models
/pkg           - código reutilizável
/migrations    - DB migrations

Dependency injection
Interface-based design
Separação de camadas

9. Explique o que é race condition e como detectar em Go

Resposta esperada:

Múltiplas goroutines acessando mesma memória, pelo menos uma escrevendo
Comportamento não-determinístico
Detectar: go run -race main.go ou go test -race
Prevenir: channels, sync.Mutex, sync/atomic

🎓 Desenvolvedor Sênior

Expertise Técnica Profunda

Runtime internals: Garbage collector, scheduler, memory model
Performance optimization: Benchmarking, profiling, otimizações
Concurrency patterns: Worker pools, pipeline, fan-out/fan-in
Memory management: Stack vs heap allocation, escape analysis
Reflection: Package reflect, quando usar e trade-offs
Unsafe package: Quando é apropriado e riscos
Assembly: Leitura básica de assembly output
Build tags e conditional compilation
CGo: Integração com C, trade-offs de performance

Arquitetura e Design

Microservices: Design, comunicação, patterns
Domain-Driven Design em Go
Hexagonal Architecture / Ports & Adapters
Event-driven architecture
CQRS e Event Sourcing
API Design: REST, gRPC, GraphQL
Distributed systems: CAP theorem, eventual consistency
Message queues: RabbitMQ, Kafka, NATS

Observabilidade e Reliability

Structured logging: zap, zerolog
Metrics: Prometheus, OpenTelemetry
Tracing: Jaeger, OpenTelemetry
Monitoring: Grafana, alerting
Circuit breakers e retry policies
Rate limiting e backpressure
Load balancing
Health checks e readiness probes

DevOps e Deployment

Docker: Criação de imagens otimizadas multi-stage
Kubernetes: Deployment, Services, ConfigMaps, Secrets
CI/CD: GitLab CI, GitHub Actions, Jenkins
Infrastructure as Code: Terraform, CloudFormation
Cloud platforms: AWS, GCP, Azure com Go SDKs
Service mesh: Istio, Linkerd

Segurança

Authentication/Authorization: JWT, OAuth2, OIDC
Cryptography: TLS, encryption at rest
Input validation e sanitization
SQL injection prevention
Secrets management: Vault, AWS Secrets Manager
Security best practices: OWASP Top 10

Testing Avançado

Test coverage: Estratégias para cobertura efetiva
Mocking: gomock, testify/mock
Integration tests: testcontainers-go
E2E tests: Estratégias de teste end-to-end
Contract testing: Pact
Load testing: k6, vegeta
Chaos engineering: Princípios e ferramentas

Performance

Profiling: CPU, memory, goroutine, mutex profiling
Benchmarking: Microbenchmarks, análise de resultados
Optimization: Hot path optimization, algoritmos eficientes
Memory leaks: Detecção e prevenção
Caching strategies: Redis, in-memory caching
Database optimization: Indexing, query optimization

Ferramentas Avançadas

go:generate: Templates, protobuf, mocks
Wire: Dependency injection automática
Buf: Gerenciamento de Protocol Buffers
Task/Make: Build automation
govulncheck: Verificação de vulnerabilidades
staticcheck: Análise estática avançada

Liderança Técnica

Code review: Habilidade de revisar código efetivamente
Mentoria: Capacidade de ensinar e guiar júniores/plenos
Architectural decisions: Trade-offs e decisões de arquitetura
Technical debt: Identificação e gerenciamento
RFC/ADR: Documentação de decisões técnicas
Performance budgets: Definição e monitoramento
Migration strategies: Estratégias de migração de sistemas legados

Comunidade e Ecosystem

Go Proverbs: Conhecimento dos princípios da linguagem
Go proposals: Acompanhamento de novas features
Open source: Contribuição em projetos Go
Tendências: Conhecimento das últimas tendências em Go
Go conferences: Acompanhamento de talks e keynotes

Bibliotecas e Frameworks Avançados

gRPC: Implementação completa de serviços
Protocol Buffers: Definição de schemas
GraphQL: go-graphql, gqlgen
Temporal/Cadence: Workflow orchestration
NATS: Messaging system
etcd: Service discovery e configuration
Consul: Service mesh e discovery

Perguntas Sugeridas para Sênior

1. Explique como funciona o garbage collector do Go e suas otimizações

Resposta esperada:

GC concurrent tri-color mark-and-sweep
STW (Stop-The-World) minimizado (<1ms em Go 1.5+)
Write barriers durante marking phase
Tuneable com GOGC (padrão 100 = 100% overhead)
Otimizações: escape analysis move alocações para stack

2. Como você identificaria e resolveria um memory leak em produção?

Resposta esperada:

pprof para heap profile: go tool pprof http://localhost:6060/debug/pprof/heap
Comparar snapshots: base vs current
Monitorar goroutine leaks: /debug/pprof/goroutine
Procurar: maps sem cleanup, goroutines sem término, channels não fechados
Solução: defer cleanup, context cancelation, timeouts

3. Descreva a implementação de um worker pool otimizado usando goroutines

Resposta esperada:

func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- process(job)
            }
        }()
    }
    wg.Wait()
    close(results)
}

Número de workers = runtime.NumCPU() ou baseado em I/O
Buffered channels para evitar blocking

4. Quando você usaria reflection e quais são os trade-offs?

Resposta esperada:

Casos: serialização (JSON), ORMs, dependency injection, testes
Trade-offs: performance (-10x a -100x), type safety perdida, complexidade
Evitar em hot paths
Alternativas: code generation, generics (Go 1.18+)

5. Como funciona escape analysis e como isso afeta performance?

Resposta esperada:

Determina se variável vai para stack ou heap
Stack: rápido, sem GC overhead
Heap: escapa se: retornada, armazenada em estrutura global, muito grande
Ver decisões: go build -gcflags='-m'
Otimizar: retornar values em vez de pointers quando possível

6. Explique diferentes estratégias de graceful shutdown em serviços Go

Resposta esperada:

quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
    log.Fatal(err)
}

Drain connection pools, finalizar goroutines, flush buffers
Health check retorna unhealthy imediatamente

7. Como você implementaria um sistema distribuído de rate limiting?

Resposta esperada:

Sliding window com Redis: INCR key, EXPIRE key ttl
Token bucket distribuído: Redis sorted sets
Algoritmos: leaky bucket, sliding window counter
Considerar: latência rede, consistência eventual, fallback local

8. Descreva sua abordagem para migrar um monolito para microservices em Go

Resposta esperada:

Estratégia strangler fig pattern
Identificar bounded contexts (DDD)
Extrair serviços por domínio, não por camada
API Gateway para roteamento
Event-driven communication (NATS/Kafka)
Database per service gradualmente
Feature flags para rollback

9. Como você garantiria zero-downtime deployment?

Resposta esperada:

Blue-green deployment ou rolling update
Health checks (readiness/liveness probes)
Graceful shutdown
Database migrations backward compatible
Feature toggles
Load balancer draining
Monitoring e rollback automático

10. Explique o memory model do Go e como prevenir race conditions sutis

Resposta esperada:

Happens-before relationship
Channel operations garantem sincronização
sync/atomic para operações atômicas
Evitar: unsynchronized shared memory
Usar -race detector sempre
Patterns: channels, mutexes, sync.Once

11. Como você otimizaria uma aplicação Go que está com alto uso de CPU?

Resposta esperada:

CPU profiling: go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
Identificar hot paths (top functions)
Otimizações: algoritmos (O(n²) → O(n log n)), pools (sync.Pool), reduce allocations
Benchmarks antes/depois: go test -bench=. -benchmem
Considerar: caching, lazy evaluation, concurrency

12. Descreve como implementaria observabilidade completa em um sistema distribuído

Resposta esperada:

Logging: structured logs (zap/zerolog), correlation IDs
Metrics: Prometheus (RED/USE method), custom business metrics
Tracing: OpenTelemetry, propagação de trace context
Dashboards: Grafana com SLI/SLO
Alerting: baseado em SLOs, runbooks
Instrumentação automática vs manual

13. Quais são os trade-offs entre diferentes patterns de error handling em Go?

Resposta esperada:

if err != nil: verboso mas explícito
panic/recover: apenas para erros irrecuperáveis
Sentinel errors vs error types vs wrapped errors
errors.Is/As vs type assertion
Error wrapping: contexto vs stack trace
Considerações: performance, debugabilidade, API clarity

14. Como você faria profiling de uma aplicação em produção sem impactar performance?

Resposta esperada:

Ativar pprof endpoints com autenticação
Sample rate baixo (30s, não continuous)
Apenas em subset de instâncias
Off-peak hours se possível
Usar -seconds=30 para limitar duração
Continuous profiling tools: Google Cloud Profiler, Datadog
Overhead < 5% aceitável

15. Explique sua estratégia para testing em uma arquitetura de microservices

Resposta esperada:

Unit tests: lógica de negócio isolada, mocks
Integration tests: testcontainers-go para dependencies
Contract tests: Pact entre consumers/providers
E2E tests: cenários críticos, ambiente staging
Chaos testing: simular falhas (latency, network partition)
Test pyramid: muito unit, médio integration, pouco E2E
CI/CD com coverage mínimo (80%+)

🎯 Guia de Nivelamento Interativo

Esta seção ajuda você a identificar o nível do desenvolvedor quando você não tem certeza. Use o fluxograma abaixo para fazer perguntas progressivas e deduzir o nível baseado nas respostas.

Como Usar

Comece com a Pergunta Inicial (P1)
Avalie a resposta do candidato
Siga o fluxo baseado na qualidade da resposta
Faça perguntas de confirmação
Chegue a uma conclusão sobre o nível

Fluxograma de Nivelamento

P1: Explique a diferença entre slice e array em Go

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não sabe, confunde conceitos, diz que são iguais	Abaixo de Júnior
✓ Básica	"Array fixo, slice dinâmico", menciona `append()`	Júnior potencial → P2
✓✓ Completa	Implementação interna, slice como referência, capacity vs length, performance	Pleno+ → P3

P2: Como você trataria erros em Go?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Apenas `if err != nil` sem contexto adicional	Júnior confirmado
✓ Intermediária	Wrap errors com `%w`, contexto nas mensagens	Pleno potencial → P4
✓✓ Avançada	Custom errors, `errors.Is/As`, patterns idiomáticos	Pleno+ → P5

P3: Explique como funcionam as goroutines e o scheduler do Go

Nível Resposta	Indicadores	Dedução
❌ Inadequada	"São threads leves" sem mais detalhes	Pleno potencial → P4
✓ Intermediária	M:N threading, G-M-P model, conceitos corretos	Pleno+ → P5
✓✓ Avançada	Work stealing, preemption, detalhes de implementação	Sênior potencial → P6

P4: Quando você usaria um pointer receiver vs value receiver?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não sabe quando usar	Júnior confirmado
✓ Intermediária	Mutação vs imutabilidade, performance básica	Pleno potencial → P7
✓✓ Avançada	Escape analysis, consistency rules, trade-offs	Pleno+ → P8

P5: Como você implementaria um rate limiter usando channels?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não consegue ou implementação errada	Pleno confirmado
✓ Intermediária	`time.Tick` ou buffered channel básico	Pleno+ → P8
✓✓ Avançada	Token bucket, bibliotecas `x/time/rate`, distribuído	Sênior potencial → P9

P6: Como você identificaria e resolveria um memory leak em produção?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não sabe ferramentas ou processo	Pleno confirmado
✓ Intermediária	Menciona pprof, processo básico de investigação	Sênior potencial → P9
✓✓ Avançada	pprof detalhado, goroutine leaks, continuous profiling	Sênior potencial → P10

P7: O que é race condition e como detectar em Go?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Conceito vago ou incorreto	Júnior confirmado
✓ Boa	Explica bem, menciona `-race`, sync primitives	Pleno confirmado

P8: Como você estruturaria uma aplicação web em Go?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Tudo em um arquivo ou sem separação clara	Pleno confirmado
✓ Intermediária	Handler/Service/Repository básico	Pleno confirmado
✓✓ Avançada	Hexagonal/Clean arch, DI, interfaces bem definidas	Sênior potencial → P11

P9: Descreva sua abordagem para migrar um monolito para microservices em Go

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Sem experiência ou estratégia	Pleno confirmado
✓ Intermediária	Strangler pattern, bounded contexts	Sênior potencial → P12
✓✓ Avançada	DDD completo, event-driven, database per service	Sênior potencial → P13

P10: Como você faria profiling de uma aplicação em produção sem impactar performance?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não considerou impacto	Pleno confirmado
✓ Intermediária	Sample rate, subset de instâncias	Sênior confirmado
✓✓ Avançada	Continuous profiling, overhead budget, ferramentas enterprise	Sênior confirmado

P11: Quais são os trade-offs entre diferentes patterns de error handling em Go?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Conhece apenas if err != nil	Pleno confirmado
✓ Intermediária	Sentinel vs wrapped, trade-offs básicos	Sênior confirmado
✓✓ Avançada	Performance, debugabilidade, API design	Sênior confirmado

P12: Como você garantiria zero-downtime deployment?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Não sabe estratégias	Pleno confirmado
✓ Intermediária	Blue-green ou rolling, health checks	Sênior confirmado
✓✓ Avançada	Graceful shutdown completo, migrations compatíveis	Sênior confirmado

P13: Como você implementaria observabilidade completa em um sistema distribuído?

Nível Resposta	Indicadores	Dedução
❌ Inadequada	Apenas logging isolado	Pleno confirmado
✓ Intermediária	Logs + Metrics + Tracing, ferramentas	Sênior confirmado
✓✓ Avançada	OpenTelemetry, correlation IDs, SLI/SLO, runbooks	Sênior confirmado

💡 Dicas de Uso

Flexibilidade: Você não precisa seguir todas as perguntas se já tiver certeza do nível
Adaptação: Ajuste perguntas baseado no contexto da vaga
Observação: Preste atenção não só no que dizem, mas em COMO explicam
Profundidade: Faça follow-ups para confirmar entendimento real vs decorado
Prática: Candidatos podem saber teoria mas não ter prática (ou vice-versa)

⚠️ Sinais de Alerta

Red Flags para qualquer nível:
- Respostas decoradas sem entendimento
- Não admite quando não sabe
- Defensivo ao receber perguntas mais difíceis
- Não consegue explicar com exemplos práticos
Green Flags:
- Admite quando não sabe algo específico
- Relaciona conceitos entre si
- Dá exemplos de experiências reais
- Faz perguntas de volta para clarificar contexto

📊 Conhecimentos por Categoria

Categorização Visual

Júnior  ▓▓▓▓▓▓▓▓░░░░░░░░░░░░  Sintaxe e Fundamentos
Pleno   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  Padrões e Ferramentas
Sênior  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  Arquitetura e Liderança

💡 Dicas para Entrevistas

Para Avaliar Júnior

Foque em fundamentos: sintaxe, tipos de dados, estruturas básicas
Peça para resolver problemas simples de algoritmos
Avalie a capacidade de ler e entender código
Teste conhecimento de error handling básico

Para Avaliar Pleno

Apresente cenários reais de desenvolvimento
Peça para desenhar arquitetura de uma API REST
Avalie conhecimento de testes e boas práticas
Discuta trade-offs de diferentes abordagens
Código review de um snippet com problemas

Para Avaliar Sênior

Discussões de arquitetura em alto nível
Resolução de problemas de produção (debugging, performance)
Decisões técnicas com justificativas baseadas em trade-offs
Capacidade de mentoria e liderança técnica
Conhecimento de design distribuído e escalabilidade

🔗 Recursos Recomendados

Livros

Júnior: "The Go Programming Language" (Donovan & Kernighan)
Pleno: "Concurrency in Go" (Katherine Cox-Buday)
Sênior: "Distributed Services with Go" (Travis Jeffery)

Websites

Practice

Exercism Go Track
LeetCode com soluções em Go
Gophercises

🚀 Criar Endpoint POST /invoices

Thiago Matos — Mon, 29 Dec 2025 22:23:00 +0000

Para: Desenvolvedor Júnior Iniciante

Objetivo: Criar um endpoint REST para cadastrar faturas

Tempo estimado: 3-4 horas

Nível de dificuldade: ⭐⭐⭐ Intermediário

📋 Pré-requisitos

Antes de começar, certifique-se de que você completou:

✅ Projeto invoice-service criado e funcionando
✅ IntelliJ IDEA configurado corretamente
✅ Aplicação roda em http://localhost:8080
✅ Estrutura de pacotes criada (controller, service, model, repository)

Se algo estiver pendente, volte ao guia Como criar um novo projeto Spring Boot! 😊

🎯 O que vamos construir?

Hoje você vai criar sua primeira API REST funcional! Especificamente:

Modelo de dados Invoice - A estrutura que representa uma fatura
Endpoint POST /invoices - Para criar novas faturas
Validações - Garantir que os dados estão corretos
Testes - Verificar se tudo funciona usando Postman ou cURL

Resultado final:

# Enviar requisição
POST http://localhost:8080/invoices
{
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING"
}

# Receber resposta 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING",
  "createdAt": "2025-12-29T18:00:00"
}

Legal, né? Vamos lá! 🚀

📦 Parte 1: Criar o Modelo de Dados (Invoice)

O que é um modelo de dados?

É uma classe que representa um objeto do mundo real. No nosso caso, uma fatura (invoice).

Analogia: Pense em um formulário de papel. O modelo é como o template desse formulário, definindo quais campos existem (nome, CPF, valor, etc.).

Passo a Passo

1.1 Criar a Data Class Invoice

No IntelliJ, navegue até: src/main/kotlin/com/invoice/model/
Clique com botão direito na pasta model → New → Kotlin Class/File
Digite: Invoice
Selecione: Class

1.2 Implementar a Data Class

Abra o arquivo Invoice.kt e adicione o seguinte código:

package com.invoice.model

import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull
import jakarta.validation.constraints.Positive
import java.math.BigDecimal
import java.time.LocalDateTime
import java.util.UUID

data class Invoice(
    val id: String = UUID.randomUUID().toString(),

    @field:NotBlank(message = "Customer ID é obrigatório")
    val customerId: String,

    @field:NotNull(message = "Valor é obrigatório")
    @field:Positive(message = "Valor deve ser positivo")
    val amount: BigDecimal,

    @field:NotBlank(message = "Status é obrigatório")
    val status: String,

    val createdAt: LocalDateTime = LocalDateTime.now()
)

1.3 Entendendo o Código Linha por Linha

Vamos explicar cada parte:

1. Imports:

import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull
import jakarta.validation.constraints.Positive

Esses imports trazem as anotações de validação. São como "regras" que garantem dados válidos.

2. Data Class:

data class Invoice(...)

data class - Tipo especial do Kotlin que gera automaticamente:
- Método equals() - compara objetos
- Método hashCode() - útil para coleções
- Método toString() - mostra os valores
- Método copy() - cria cópias com alterações

Analogia: É como um atalho que escreve muito código por você!

3. Propriedades:

val id: String = UUID.randomUUID().toString()

val - Propriedade imutável (não pode ser alterada depois)
id: String - Nome e tipo da propriedade
UUID.randomUUID().toString() - Gera um ID único automaticamente
- Exemplo: "550e8400-e29b-41d4-a716-446655440000"

@field:NotBlank(message = "Customer ID é obrigatório")
val customerId: String

@field:NotBlank - Validação: não pode ser vazio ou só espaços
message = "..." - Mensagem de erro customizada
customerId: String - ID do cliente

@field:NotNull(message = "Valor é obrigatório")
@field:Positive(message = "Valor deve ser positivo")
val amount: BigDecimal

BigDecimal - Tipo para valores monetários (mais preciso que Double)
@NotNull - Não pode ser nulo
@Positive - Deve ser maior que zero

Por que BigDecimal? Números decimais como Double têm problemas de arredondamento. Para dinheiro, use sempre BigDecimal!

val createdAt: LocalDateTime = LocalDateTime.now()

LocalDateTime - Data e hora sem timezone
LocalDateTime.now() - Pega data/hora atual automaticamente

1.4 Adicionar Dependência de Validação

Para as validações funcionarem, precisamos adicionar a dependência no build.gradle.kts.

Abra o arquivo build.gradle.kts
Localize a seção dependencies
Adicione esta linha:

dependencies {
    // ... dependências existentes ...

    // Validação
    implementation("org.springframework.boot:spring-boot-starter-validation")
}

Clique no ícone 🐘 (elefante do Gradle) que aparece no canto superior direito
Selecione Reload Gradle Project

⏱️ Aguarde alguns segundos enquanto o Gradle baixa a dependência.

1.5 Testar a Data Class

Vamos verificar se a classe compila corretamente:

Clique com botão direito no arquivo Invoice.kt
Selecione Build Module 'invoice-service.main'

✅ Se não aparecer erro, perfeito! Sua data class está pronta.

🎮 Parte 2: Criar o Controller

O que é um Controller?

É a classe que recebe requisições HTTP e as processa. É a "porta de entrada" da sua API.

Analogia: É como o atendente de um restaurante que anota seu pedido e leva para a cozinha.

Passo a Passo

2.1 Criar a Classe InvoiceController

Navegue até: src/main/kotlin/com/invoice/controller/
Clique com botão direito → New → Kotlin Class/File
Digite: InvoiceController
Selecione: Class

2.2 Implementar o Controller Básico

Adicione o seguinte código:

package com.invoice.controller

import com.invoice.model.Invoice
import jakarta.validation.Valid
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/invoices")
class InvoiceController {

    // Lista temporária para armazenar faturas (in-memory)
    private val invoices = mutableListOf<Invoice>()

    @PostMapping
    fun createInvoice(@Valid @RequestBody invoice: Invoice): ResponseEntity<Invoice> {
        // Adiciona a fatura na lista
        invoices.add(invoice)

        // Retorna 201 Created com a fatura criada
        return ResponseEntity.status(HttpStatus.CREATED).body(invoice)
    }
}

2.3 Entendendo o Código Linha por Linha

1. Anotações da Classe:

@RestController
@RequestMapping("/invoices")
class InvoiceController

@RestController - Diz ao Spring: "Esta classe é um controller REST"
- Automaticamente converte objetos para JSON
- Processa requisições HTTP
@RequestMapping("/invoices") - Define o caminho base
- Todas as rotas deste controller começam com /invoices

2. Armazenamento Temporário:

private val invoices = mutableListOf<Invoice>()

mutableListOf<Invoice>() - Lista mutável (pode adicionar/remover)
Por enquanto, armazena só na memória (quando reiniciar a app, perde tudo)
Na quarta-feira vamos adicionar banco de dados real!

3. Método createInvoice:

@PostMapping
fun createInvoice(@Valid @RequestBody invoice: Invoice): ResponseEntity<Invoice>

Quebra completa:

@PostMapping - Esta função responde a requisições HTTP POST
- Caminho completo: POST /invoices (lembra do @RequestMapping?)
fun createInvoice - Nome do método (pode ser qualquer nome)
@Valid - Valida o objeto usando as anotações que definimos (@notblank, etc.)
- Se validação falhar, retorna 400 Bad Request automaticamente
@RequestBody - O Spring pega o JSON da requisição e converte para objeto Invoice
invoice: Invoice - Parâmetro que recebe os dados
: ResponseEntity<Invoice> - Tipo de retorno
- ResponseEntity permite controlar status HTTP (201, 200, 404, etc.)
- <Invoice> - O corpo da resposta será um objeto Invoice

4. Lógica do Método:

invoices.add(invoice)

Adiciona a fatura recebida na lista

return ResponseEntity.status(HttpStatus.CREATED).body(invoice)

ResponseEntity.status(HttpStatus.CREATED) - Define status 201 (Created)
.body(invoice) - Coloca a fatura no corpo da resposta
Spring automaticamente converte para JSON

Por que 201 e não 200?

200 OK: Requisição bem-sucedida (usado em GET, PUT)
201 Created: Recurso criado com sucesso (usado em POST)

É uma boa prática usar o status HTTP correto!

🧪 Parte 3: Testar o Endpoint

Opção A: Testar com cURL (Terminal)

O cURL é uma ferramenta de linha de comando para fazer requisições HTTP.

3.1 Iniciar a Aplicação

No IntelliJ, abra InvoiceServiceApplication.kt
Clique no ▶️ verde ao lado de fun main
Aguarde aparecer: Started InvoiceServiceApplication

3.2 Fazer a Requisição

Abra um novo terminal (fora do IntelliJ) e execute:

curl -X POST http://localhost:8080/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUST001",
    "amount": 150.50,
    "status": "PENDING"
  }'

Explicação do comando:

curl - Ferramenta para fazer requisições HTTP
-X POST - Método HTTP POST
http://localhost:8080/invoices - URL do endpoint
-H "Content-Type: application/json" - Header dizendo que enviamos JSON
-d '{...}' - Corpo da requisição (dados em JSON)

Resposta esperada:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING",
  "createdAt": "2025-12-29T18:00:00"
}

✅ Se você viu isso, PARABÉNS! Seu endpoint está funcionando! 🎉

Opção B: Testar com Postman (Recomendado)

Postman é uma ferramenta visual mais amigável para testar APIs.

3.3 Instalar Postman

Acesse: https://www.postman.com/downloads/
Baixe e instale
Crie uma conta gratuita (ou pule)

3.4 Criar a Requisição

Abra o Postman
Clique em New → HTTP Request
Configure:

Campo	Valor
Método	POST
URL	`http://localhost:8080/invoices`

Vá na aba Body
Selecione raw
No dropdown ao lado, selecione JSON
Cole este JSON:

{
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING"
}

Clique em Send

Resultado esperado:

Status: 201 Created (canto superior direito)
Body: JSON com a fatura criada, incluindo id e createdAt

3.5 Testar Validações

Vamos ver se as validações estão funcionando:

Teste 1: Enviar valor negativo

{
  "customerId": "CUST001",
  "amount": -50.00,
  "status": "PENDING"
}

Resultado esperado: 400 Bad Request com mensagem "Valor deve ser positivo"

Teste 2: Enviar customerId vazio

{
  "customerId": "",
  "amount": 100.00,
  "status": "PENDING"
}

Resultado esperado: 400 Bad Request com mensagem "Customer ID é obrigatório"

Teste 3: Não enviar amount

{
  "customerId": "CUST001",
  "status": "PENDING"
}

Resultado esperado: 400 Bad Request com mensagem "Valor é obrigatório"

✅ Se todos os testes passaram, suas validações estão funcionando!

📊 Parte 4: Adicionar Logs para Debug

Logs ajudam a entender o que está acontecendo na aplicação.

4.1 Adicionar Logger no Controller

Atualize seu InvoiceController.kt:

package com.invoice.controller

import com.invoice.model.Invoice
import jakarta.validation.Valid
import org.slf4j.LoggerFactory
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/invoices")
class InvoiceController {

    private val logger = LoggerFactory.getLogger(InvoiceController::class.java)
    private val invoices = mutableListOf<Invoice>()

    @PostMapping
    fun createInvoice(@Valid @RequestBody invoice: Invoice): ResponseEntity<Invoice> {
        logger.info("Recebida requisição para criar fatura: {}", invoice)

        invoices.add(invoice)
        logger.info("Fatura criada com sucesso. ID: {}", invoice.id)

        return ResponseEntity.status(HttpStatus.CREATED).body(invoice)
    }
}

O que mudou:

private val logger = ... - Cria um objeto logger
logger.info("...") - Escreve mensagens no console

4.2 Testar os Logs

Reinicie a aplicação
Faça uma requisição POST
Observe o console do IntelliJ

Você verá algo como:

INFO  c.i.controller.InvoiceController - Recebida requisição para criar fatura: Invoice(id=550e8400..., customerId=CUST001, amount=150.50, status=PENDING, createdAt=2025-12-29T18:00:00)
INFO  c.i.controller.InvoiceController - Fatura criada com sucesso. ID: 550e8400-e29b-41d4-a716-446655440000

🎨 Parte 5: Melhorias Opcionais (Bônus)

5.1 Criar um Enum para Status

Ao invés de aceitar qualquer texto no status, vamos limitar aos valores válidos.

Crie o arquivo: src/main/kotlin/com/invoice/model/InvoiceStatus.kt

package com.invoice.model

enum class InvoiceStatus {
    PENDING,
    PAID,
    CANCELLED,
    OVERDUE
}

Atualize a classe Invoice:

data class Invoice(
    val id: String = UUID.randomUUID().toString(),

    @field:NotBlank(message = "Customer ID é obrigatório")
    val customerId: String,

    @field:NotNull(message = "Valor é obrigatório")
    @field:Positive(message = "Valor deve ser positivo")
    val amount: BigDecimal,

    @field:NotNull(message = "Status é obrigatório")
    val status: InvoiceStatus,  // Mudou aqui!

    val createdAt: LocalDateTime = LocalDateTime.now()
)

Agora o JSON deve ser:

{
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING"
}

Se enviar status inválido (ex: "INVALID"), retorna erro automaticamente!

5.2 Adicionar Endpoint GET para Listar Faturas

Vamos adicionar um endpoint para ver todas as faturas criadas:

@GetMapping
fun getAllInvoices(): ResponseEntity<List<Invoice>> {
    logger.info("Recebida requisição para listar todas as faturas")
    return ResponseEntity.ok(invoices)
}

Testar:

curl http://localhost:8080/invoices

Ou no Postman: GET http://localhost:8080/invoices

✅ Critérios de Aceite - Checklist Final

Marque cada item que você completou:

Criar Modelo Invoice

[ ] Arquivo Invoice.kt criado em model/
[ ] Data class com 5 campos: id, customerId, amount, status, createdAt
[ ] Validações adicionadas: @notblank, @NotNull, @positive
[ ] Dependência spring-boot-starter-validation adicionada no build.gradle.kts
[ ] Classe compila sem erros

Criar InvoiceController

[ ] Arquivo InvoiceController.kt criado em controller/
[ ] Classe anotada com @RestController
[ ] @RequestMapping("/invoices") configurado
[ ] Lista in-memory criada (mutableListOf)
[ ] Método createInvoice implementado
[ ] Método anotado com @PostMapping
[ ] Parâmetro com @valid e @RequestBody
[ ] Retorna ResponseEntity com status 201

Testar Endpoint

[ ] Aplicação inicia sem erros
[ ] Requisição POST retorna 201 Created
[ ] Resposta contém id gerado automaticamente
[ ] Resposta contém createdAt gerado automaticamente
[ ] Validações funcionam (testes com dados inválidos retornam 400)
[ ] Logs aparecem no console

Bônus (Opcional)

[ ] Enum InvoiceStatus criado
[ ] Status aceita apenas valores do enum
[ ] Endpoint GET /invoices implementado
[ ] GET retorna lista de faturas criadas

🐛 Problemas Comuns e Soluções

Erro: "Unresolved reference: NotBlank"

Causa: Dependência de validação não foi adicionada

Solução:

Verifique se adicionou spring-boot-starter-validation no build.gradle.kts
Clique no ícone Gradle para recarregar as dependências
Aguarde o download completar

Erro: 404 Not Found ao fazer POST

Causa: Aplicação não está rodando ou URL incorreta

Solução:

Verifique se a aplicação está rodando (console deve mostrar "Started InvoiceServiceApplication")
Confirme a URL: http://localhost:8080/invoices (sem /api)
Verifique o método: deve ser POST, não GET

Erro: 400 Bad Request sem mensagem clara

Causa: JSON malformado

Solução:

Use um validador JSON online: jsonlint.com
Verifique vírgulas, aspas e chaves
Exemplo correto:

{
  "customerId": "CUST001",
  "amount": 150.50,
  "status": "PENDING"
}

Erro: "HttpMessageNotReadableException"

Causa: Tipo de dado incorreto no JSON

Solução:

amount deve ser número: 150.50 (sem aspas)
customerId e status devem ser texto: "CUST001" (com aspas)

Validações não funcionam (aceita dados inválidos)

Causa: Esqueceu @Valid no parâmetro

Solução:

Verifique se o método tem:

fun createInvoice(@Valid @RequestBody invoice: Invoice)
                  ^^^^^^

Resposta retorna 200 ao invés de 201

Causa: Esqueceu de definir o status HTTP

Solução:

Retorne com:

return ResponseEntity.status(HttpStatus.CREATED).body(invoice)

Não use apenas:

return ResponseEntity.ok(invoice) // Retorna 200

🎓 Conceitos Importantes para Entender

O que é REST?

REST (Representational State Transfer) é um estilo de arquitetura para APIs web.

Princípios básicos:

Recursos são identificados por URLs (/invoices)
Usam métodos HTTP padrão (GET, POST, PUT, DELETE)
São stateless (cada requisição é independente)
Respostas geralmente em JSON

Analogia: É como organizar uma biblioteca:

Cada livro tem uma identificação única (URL)
Ações padronizadas: pegar (GET), adicionar (POST), atualizar (PUT), remover (DELETE)

O que é JSON?

JSON (JavaScript Object Notation) é um formato de texto para trocar dados.

Exemplo:

{
  "nome": "João",
  "idade": 25,
  "ativo": true
}

Por que usamos JSON?

Fácil de ler para humanos
Fácil de processar para computadores
Padrão da indústria para APIs

HTTP Status Codes Importantes

Código	Nome	Quando usar
200	OK	Requisição bem-sucedida (GET, PUT)
201	Created	Recurso criado com sucesso (POST)
400	Bad Request	Dados inválidos enviados
404	Not Found	Recurso não encontrado
500	Internal Server Error	Erro no servidor

O que é Serialização/Desserialização?

Serialização: Converter objeto Java/Kotlin → JSON
Desserialização: Converter JSON → objeto Java/Kotlin

O Spring faz isso automaticamente usando a biblioteca Jackson!

// Objeto Kotlin
Invoice(id="123", customerId="CUST001", ...)

     ↓ Serialização (automática)

// JSON
{"id":"123","customerId":"CUST001",...}

O que é Validation?

Garantir que os dados recebidos estão corretos antes de processar.

Sem validação:

{
  "customerId": "",
  "amount": -100,
  "status": "XPTO"
}

Isso causaria problemas! Com validação, rejeitamos automaticamente.

🎯 Próximos Passos

Depois de completar esta atividade, você deve:

Commitar no Git - Salve seu progresso!

git add .
git commit -m "feat: adiciona endpoint POST /invoices e modelo Invoice"

Testar mais cenários - Experimente diferentes dados
Mostrar para o alguém - Demonstre funcionando!

💡 Dicas

Teste sempre que mudar algo!

Não acumule mudanças. Faça pequenas alterações e teste cada uma.

Leia as mensagens de erro com atenção

Elas geralmente dizem exatamente qual é o problema. Procure a última linha da stack trace.

Use logs para debug

Quando algo não funciona como esperado, adicione logger.info() para ver o que está acontecendo.

Não decore, entenda!

É melhor entender o conceito do que decorar código. Se entender, saberá adaptar para outros cenários.

Postman é seu amigo

Salve suas requisições no Postman. Você vai reutilizá-las muito!

🎉 Parabéns

Se você chegou até aqui e seu endpoint está funcionando, você acabou de:

✅ Criar seu primeiro modelo de dados com validações

✅ Implementar seu primeiro endpoint REST POST

✅ Entender serialização JSON

✅ Testar APIs usando Postman/cURL

✅ Adicionar logs para debug

Você está oficialmente criando APIs profissionais! 🚀

Isso é incrível para alguém que há pouco tempo era estagiário! Você já está produzindo código que roda em produção em muitas empresas.

Continue assim! Cada linha de código é um passo a mais na sua jornada. 💪

🚀 Como criar um novo projeto Spring Boot

Thiago Matos — Mon, 29 Dec 2025 18:40:40 +0000

Para: Desenvolvedor Júnior Iniciante

Objetivo: Criar o projeto Spring Boot + Kotlin do serviço de faturas

Tempo estimado: 2-3 horas

Nível de dificuldade: ⭐⭐ Iniciante-Intermediário

📋 Pré-requisitos

Antes de começar, verifique se você tem instalado:

Java 17 ou superior - Execute no terminal: java -version
IntelliJ IDEA (Community) - Download aqui
Git - Execute: git --version

Opcional: Instalar Gradle Localmente

O projeto Spring Boot vem com Gradle Wrapper (arquivos gradlew e gradlew.bat) que baixa automaticamente a versão correta do Gradle. Porém, em alguns ambientes corporativos, é preferível usar uma instalação local do Gradle.

Para instalar Gradle no Linux:

# Usando SDKMAN (recomendado)
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install gradle 8.5

# Verificar instalação
gradle --version

Para instalar no macOS:

brew install gradle

💡 Quando usar Gradle local vs Wrapper?

Wrapper (padrão): Garante que todos usem a mesma versão, recomendado para iniciantes

Gradle local: Útil em ambientes corporativos com restrições de rede ou quando você trabalha em múltiplos projetos

⚙️ Configurar IntelliJ IDEA (Importante!)

Antes de importar o projeto, vamos configurar corretamente o IntelliJ para evitar problemas.

Configuração 1: Verificar/Configurar JDK

O IntelliJ precisa saber qual versão do Java usar.

Passo a Passo

Abra o IntelliJ IDEA
Antes de abrir qualquer projeto, vá em:
- File → Project Structure (ou pressione Ctrl+Alt+Shift+S no Linux/Windows, ⌘+; no Mac)
Na janela que abrir, clique em Project (lado esquerdo)
Configure:

Campo	Valor
SDK	Java 17 (ou superior)
Language Level	SDK default

Se não aparecer Java 17 na lista:
- Clique no dropdown do SDK
- Selecione Add SDK → Download JDK...
- Escolha:
  - Vendor: Amazon Corretto, Eclipse Temurin ou Oracle OpenJDK
  - Version: 17
- Clique em Download
Clique em OK para salvar

Verificação:

# No terminal, verifique qual Java está configurado
java -version

# Deve mostrar algo como:
# openjdk version "17.0.x"

Configuração 2: Escolher entre Gradle Wrapper ou Gradle Local

Você pode escolher usar o Gradle que vem com o projeto (wrapper) ou uma instalação local.

Opção A: Usar Gradle Wrapper (Recomendado para Iniciantes)

Esta é a configuração padrão. O IntelliJ usa os arquivos gradlew e gradlew.bat do projeto.

No IntelliJ:

File → Settings (ou Ctrl+Alt+S)
Navegue até: Build, Execution, Deployment → Build Tools → Gradle
Configure:

Campo	Valor
Use Gradle from	`'wrapper' task in Gradle build script`
Gradle JVM	Project SDK (Java 17)
Build and run using	Gradle (Recomendado)
Run tests using	Gradle (Recomendado)

Vantagens:

✅ Garante que todos da equipe usam a mesma versão do Gradle
✅ Não precisa instalar nada manualmente
✅ Versão especificada no arquivo gradle/wrapper/gradle-wrapper.properties

Desvantagens:

❌ Precisa baixar o Gradle na primeira vez (pode demorar)
❌ Pode ter problemas se houver firewall/proxy bloqueando o download

Opção B: Usar Gradle Instalado Localmente

Se sua empresa tem restrições ou você já tem Gradle instalado.

No IntelliJ:

File → Settings (ou Ctrl+Alt+S)
Navegue até: Build, Execution, Deployment → Build Tools → Gradle
Configure:

Campo	Valor
Use Gradle from	`Specified location`
Gradle home	Caminho da instalação (ex: `/usr/local/gradle-8.5` ou `/home/usuario/.sdkman/candidates/gradle/8.5`)
Gradle JVM	Project SDK (Java 17)

Para descobrir o caminho do Gradle:

which gradle
# Mostra algo como: /usr/local/bin/gradle

# Para ver o diretório home do Gradle:
gradle --version
# Mostra Gradle home: /usr/local/gradle-8.5

No macOS (Homebrew):

# O caminho geralmente é:
/usr/local/Cellar/gradle/8.5/libexec

Com SDKMAN:

# O caminho geralmente é:
~/.sdkman/candidates/gradle/current

Vantagens:

✅ Mais rápido (não precisa baixar)
✅ Funciona offline
✅ Útil quando você trabalha em vários projetos

Desvantagens:

❌ Precisa manter o Gradle atualizado manualmente
❌ Pode ter incompatibilidade se a versão local for diferente da esperada pelo projeto

Configuração 3: Configurar Gradle JVM Corretamente

IMPORTANTE: O Gradle precisa rodar usando a JVM correta!

No IntelliJ → Settings → Build Tools → Gradle:

Gradle JVM: Selecione o Java 17 que você configurou anteriormente
- Opção comum: Project SDK (java version "17")...
- Evite: Usar JVMs antigas (Java 8, Java 11) ou muito novas se o projeto especifica Java 17

Se o Gradle JVM não aparecer:

Clique no dropdown Gradle JVM
Selecione Add JDK...
Navegue até a pasta onde o Java 17 está instalado:
- Linux (SDKMAN): ~/.sdkman/candidates/java/17.x.x-tem
- Linux (apt): /usr/lib/jvm/java-17-openjdk-amd64
- macOS (Homebrew): /usr/local/Cellar/openjdk@17/17.x.x
- Windows: C:\Program Files\Java\jdk-17

Verificar Configurações

Depois de configurar, verifique se está tudo certo:

Abra o Terminal do IntelliJ (aba na parte inferior)
Execute:

# Se usar Gradle Wrapper:
./gradlew --version

# Se usar Gradle local:
gradle --version

Resultado esperado:

------------------------------------------------------------
Gradle 8.5
------------------------------------------------------------

Build time:   2023-11-15 13:36:12 UTC
Revision:     1234567890

Kotlin:       1.9.10
Groovy:       3.0.17
Ant:          Apache Ant(TM) version 1.10.13
JVM:          17.0.9 (Amazon.com Inc. 17.0.9+8-LTS)
OS:           Linux 5.15.0-91-generic amd64

✅ Ótimo! O campo JVM: deve mostrar Java 17 (ou superior).

🎯 Parte 1: Configurar Spring Initializr

O que é Spring Initializr?

É uma ferramenta web que gera automaticamente a estrutura inicial de um projeto Spring Boot. Pense nele como um "criador de projetos automático" que já configura tudo para você começar a programar rapidamente.

Passo a Passo

1.1 Acessar o Spring Initializr

Abra seu navegador
Acesse: https://start.spring.io/
Você verá uma página com vários campos de configuração

1.2 Configurar o Projeto

Preencha os campos EXATAMENTE como descrito abaixo:

Campo	Valor	Por que?
Project	Gradle - Kotlin	Ferramenta para gerenciar dependências
Language	Kotlin	A linguagem que vamos usar
Spring Boot	3.2.x (mais recente)	Versão do framework
Group	`com.invoice`	Identificador da sua empresa/projeto
Artifact	`invoice-service`	Nome do seu projeto
Name	`invoice-service`	Nome da aplicação
Description	`Invoice Processing Service`	Descrição curta
Package name	`com.invoice`	Deixe o padrão
Packaging	Jar	Formato do pacote final
Java	17	Versão do Java

1.3 Adicionar Dependências

Na seção Dependencies (lado direito), clique em "ADD DEPENDENCIES" e adicione:

Spring Web
- O que faz: Permite criar APIs REST (endpoints HTTP)
- Por que precisa: Vamos criar endpoints para gerenciar faturas
Spring DevTools
- O que faz: Reinicia automaticamente a aplicação quando você salva o código
- Por que precisa: Agiliza o desenvolvimento, você não precisa parar e iniciar manualmente
Spring Boot Actuator (opcional, mas recomendado)
- O que faz: Fornece endpoints de monitoramento (/health, /metrics)
- Por que precisa: Útil para verificar se a aplicação está rodando

1.4 Gerar o Projeto

Clique no botão GENERATE (no final da página)
Um arquivo .zip será baixado automaticamente
Salve em uma pasta que você lembre (ex: ~/Documentos/projetos/)

1.5 Descompactar o Projeto

No Linux:

cd ~/Documentos/projetos/
unzip invoice-service.zip
cd invoice-service

Agora você tem a estrutura básica do projeto! 🎉

🏗️ Parte 2: Criar Estrutura de Pacotes

O que são pacotes?

Pacotes são pastas que organizam o código. É como organizar documentos em gavetas: cada tipo de arquivo vai em uma gaveta específica.

Passo a Passo

2.1 Importar no IntelliJ IDEA

Abra o IntelliJ IDEA
Clique em File → Open
Navegue até a pasta invoice-service e selecione-a
Clique em OK
Aguarde o IntelliJ baixar as dependências (veja a barra de progresso no canto inferior)

⏱️ Dica: Primeira vez pode demorar 5-10 minutos baixando bibliotecas. É normal!

2.2 Entender a Estrutura Atual

Depois de abrir, você verá algo assim:

invoice-service/
├── src/
│   ├── main/
│   │   ├── kotlin/
│   │   │   └── com/
│   │   │       └── invoice/
│   │   │           └── InvoiceServiceApplication.kt
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── build.gradle.kts
└── settings.gradle.kts

O que cada pasta significa:

src/main/kotlin/ - Onde fica seu código fonte
src/main/resources/ - Arquivos de configuração
src/test/ - Onde ficam os testes
build.gradle.kts - Configurações do projeto e dependências

2.3 Criar os Pacotes

Vamos criar 4 pacotes para organizar nosso código seguindo o padrão de "arquitetura em camadas":

No IntelliJ, navegue até: src/main/kotlin/com/invoice/
Clique com botão direito em invoice → New → Package
Digite: controller e pressione Enter
Repita os passos 2-3 para criar:
- service
- model
- repository

Resultado final:

src/main/kotlin/com/invoice/
├── controller/      (endpoints da API)
├── service/         (lógica de negócio)
├── model/           (classes de dados)
├── repository/      (acesso a dados)
└── InvoiceServiceApplication.kt

Por que essa estrutura?

Controller: Recebe as requisições HTTP (ex: POST /invoices)
Service: Contém as regras de negócio (ex: calcular juros)
Model: Define estruturas de dados (ex: classe Invoice)
Repository: Conversa com banco de dados

Essa separação é chamada de Separation of Concerns - cada camada tem uma responsabilidade específica!

🔐 Parte 3: Configurar Repositórios Privados (Artifactory)

Por que usar repositórios privados?

Em ambientes corporativos, muitas empresas usam repositórios privados (como Artifactory ou Nexus) para:

Armazenar bibliotecas internas - Código compartilhado entre equipes
Cache de dependências - Mais rápido que baixar direto da internet
Segurança - Controlar quais bibliotecas podem ser usadas
Trabalhar offline - Dependências já estão no repositório da empresa

Analogia: É como ter uma biblioteca da empresa ao invés de sempre ir à biblioteca pública.

Passo a Passo

3.1 Criar arquivo gradle.properties

Este arquivo guarda configurações globais do Gradle, incluindo URLs de repositórios.

Na raiz do projeto, crie o arquivo gradle.properties
Adicione as seguintes configurações:

# URL base do Artifactory da empresa
artifactoryUrl=https://artifactory.suaempresa.com/artifactory

# Repositórios específicos
artifactoryReleaseRepo=libs-release
artifactorySnapshotRepo=libs-snapshot
artifactoryPluginRepo=plugins-release

# Credenciais (NÃO commitar em produção!)
# Em produção, use variáveis de ambiente
artifactoryUser=seu.usuario
artifactoryPassword=sua.senha

⚠️ IMPORTANTE: Nunca commite senhas reais no Git! Em produção, use variáveis de ambiente ou ferramentas como Vault.

Explicação de cada propriedade:

artifactoryUrl - URL base do servidor Artifactory da empresa
artifactoryReleaseRepo - Nome do repositório de versões estáveis
artifactorySnapshotRepo - Nome do repositório de versões em desenvolvimento
artifactoryPluginRepo - Nome do repositório de plugins Gradle
artifactoryUser / artifactoryPassword - Suas credenciais de acesso

3.2 Usar Variáveis de Ambiente (Recomendado para Produção)

Para não expor senhas, use variáveis de ambiente:

No Linux/Mac, adicione no ~/.bashrc ou ~/.zshrc:

export ARTIFACTORY_USER="seu.usuario"
export ARTIFACTORY_PASSWORD="sua.senha"

No gradle.properties:

artifactoryUrl=https://artifactory.suaempresa.com/artifactory
artifactoryReleaseRepo=libs-release
artifactorySnapshotRepo=libs-snapshot
artifactoryPluginRepo=plugins-release

# Credenciais virão de variáveis de ambiente
artifactoryUser=${ARTIFACTORY_USER}
artifactoryPassword=${ARTIFACTORY_PASSWORD}

3.3 Configurar settings.gradle.kts

O arquivo settings.gradle.kts controla de onde o Gradle baixa plugins.

Abra o arquivo settings.gradle.kts e substitua o conteúdo por:

pluginManagement {
    repositories {
        // 1. MavenLocal - cache local da sua máquina
        mavenLocal()

        // 2. Artifactory privado - repositório da empresa
        maven {
            url = uri("${settings.extra["artifactoryUrl"]}/${settings.extra["artifactoryPluginRepo"]}")
            credentials {
                username = settings.extra["artifactoryUser"] as String?
                password = settings.extra["artifactoryPassword"] as String?
            }
        }

        // 3. Gradle Plugin Portal - repositório público oficial
        gradlePluginPortal()

        // 4. Maven Central - repositório público (fallback)
        mavenCentral()
    }
}

rootProject.name = "invoice-service"

Explicação linha por linha:

pluginManagement { } - Seção que configura onde buscar plugins do Gradle
mavenLocal() - Primeiro procura no cache local (~/.m2/repository)
maven { url = ... } - Configura repositório privado (Artifactory)
- ${settings.extra["artifactoryUrl"]} - Lê a URL do gradle.properties
- credentials { } - Adiciona usuário e senha para autenticação
gradlePluginPortal() - Repositório oficial de plugins do Gradle
mavenCentral() - Repositório público (caso não encontre nos anteriores)

Ordem de busca: mavenLocal → Artifactory → Gradle Plugin Portal → Maven Central

3.4 Configurar build.gradle.kts

O arquivo build.gradle.kts controla de onde o Gradle baixa dependências da aplicação.

Abra o arquivo build.gradle.kts e localize a seção repositories. Substitua por:

repositories {
    // 1. MavenLocal - cache local
    mavenLocal()

    // 2. Artifactory - releases (bibliotecas estáveis)
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactoryReleaseRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 3. Artifactory - snapshots (bibliotecas em desenvolvimento)
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactorySnapshotRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 4. Maven Central - repositório público (fallback)
    mavenCentral()
}

Explicação:

mavenLocal() - Busca primeiro no cache local
Primeiro maven { } - Repositório de releases (versões 1.0.0, 2.3.1, etc.)
Segundo maven { } - Repositório de snapshots (versões 1.0.0-SNAPSHOT)
mavenCentral() - Repositório público como fallback

Diferença entre Release e Snapshot:

Release	Snapshot
Versão estável (1.0.0)	Versão em desenvolvimento (1.0.0-SNAPSHOT)
Não muda depois de publicada	Pode ser atualizada a qualquer momento
Para produção	Para testes internos

Conceitos Importantes

MavenLocal: Um cache local de dependências no seu computador. O Gradle verifica aqui primeiro para evitar downloads repetidos.
Artifactory (ou Nexus): Repositórios privados usados por empresas para gerenciar suas próprias bibliotecas e fazer cache de dependências públicas.
Gradle Plugin Portal: O repositório oficial para plugins do Gradle.
Maven Central: O maior repositório público de bibliotecas Java/Kotlin. É o "fallback" caso a dependência não seja encontrada nos repositórios anteriores.
settings.gradle.kts vs build.gradle.kts:
- settings.gradle.kts: Configura de onde o Gradle baixa plugins.
- build.gradle.kts: Configura de onde o Gradle baixa dependências da aplicação.
--refresh-dependencies: Um comando Gradle que força o download de todas as dependências novamente, ignorando o cache local. Útil para garantir que você está usando as versões mais recentes.

3.5 Exemplo Completo do build.gradle.kts

Aqui está como deve ficar o arquivo completo:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "1.9.20"
    kotlin("plugin.spring") version "1.9.20"
}

group = "com.invoice"
version = "0.0.1-SNAPSHOT"

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    // 1. MavenLocal
    mavenLocal()

    // 2. Artifactory - releases
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactoryReleaseRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 3. Artifactory - snapshots
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactorySnapshotRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 4. Maven Central
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    developmentOnly("org.springframework.boot:spring-boot-devtools")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs += "-Xjsr305=strict"
        jvmTarget = "17"
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

3.6 Testar a Configuração

Agora vamos verificar se está tudo funcionando!

No terminal, execute:

./gradlew clean build --refresh-dependencies

O que esse comando faz:

clean - Remove arquivos compilados antigos
build - Compila o projeto
--refresh-dependencies - Força o download das dependências novamente

Resultado esperado:

BUILD SUCCESSFUL in 45s

Se aparecer erros, veja a seção de troubleshooting mais abaixo.

3.7 Verificar de Onde as Dependências Foram Baixadas

Para ver de qual repositório cada dependência veio:

./gradlew dependencies --configuration runtimeClasspath

Você verá algo assim:

com.fasterxml.jackson.module:jackson-module-kotlin:2.15.3
   -> Downloaded from: https://artifactory.suaempresa.com/artifactory/libs-release/...

⚙️ Parte 4: Configurar application.yml

Por que configurar?

O arquivo de configuração define como sua aplicação se comporta: em que porta roda, nome da aplicação, configurações de banco, etc.

Passo a Passo

3.1 Converter .properties para .yml

O Spring Initializr cria um arquivo application.properties, mas vamos usar .yml que é mais organizado.

Localize: src/main/resources/application.properties
Clique com botão direito → Refactor → Rename
Renomeie para: application.yml

3.2 Adicionar Configurações Básicas

Abra o arquivo application.yml e adicione:

server:
  port: 8080

spring:
  application:
    name: invoice-service

logging:
  level:
    com.invoice: DEBUG

O que cada configuração faz:

server.port: 8080 - A aplicação rodará em http://localhost:8080
spring.application.name - Nome da aplicação (útil em logs)
logging.level - Mostra logs detalhados do seu código (útil para debug)

🚀 Parte 5: Executar a Aplicação

Momento da Verdade

Vamos subir a aplicação pela primeira vez. 😊

Passo a Passo

4.1 Executar pelo IntelliJ

Abra o arquivo InvoiceServiceApplication.kt
Você verá um código assim:

package com.invoice

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class InvoiceServiceApplication

fun main(args: Array<String>) {
    runApplication<InvoiceServiceApplication>(*args)
}

Clique no ícone ▶️ verde ao lado de fun main
Selecione Run 'InvoiceServiceApplication'

4.2 Verificar se Funcionou

Observe o console (painel inferior do IntelliJ). Você deve ver:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.2.x)

...
Started InvoiceServiceApplication in 2.345 seconds

✅ Se você viu isso, PARABÉNS! Sua aplicação está rodando! 🎉

4.3 Testar no Navegador

Abra seu navegador
Acesse: http://localhost:8080
Você verá uma página de erro "Whitelabel Error Page"

Isso está CORRETO! 😎

A página de erro aparece porque ainda não criamos nenhum endpoint. O importante é que a aplicação está respondendo!

✅ Critérios de Aceite - Checklist Final

Marque cada item que você completou:

Configurar IntelliJ IDEA

[ ] IntelliJ IDEA instalado
[ ] JDK 17 configurado no IntelliJ (Project Structure → SDK)
[ ] Gradle configurado (Wrapper ou Local)
[ ] Gradle JVM configurado para usar Java 17
[ ] Comando ./gradlew --version ou gradle --version executado com sucesso

Configurar Spring Initializr

[ ] Projeto gerado com Java 17+
[ ] Linguagem: Kotlin
[ ] Dependências: Spring Web e Spring DevTools
[ ] Projeto baixado e descompactado

Criar Estrutura de Pacotes

[ ] Projeto importado no IntelliJ
[ ] Pacote controller criado
[ ] Pacote service criado
[ ] Pacote model criado
[ ] Pacote repository criado

Configurar Repositórios Privados (Artifactory)

[ ] Arquivo gradle.properties criado na raiz do projeto
[ ] URL do Artifactory configurada
[ ] Credenciais configuradas (ou variáveis de ambiente)
[ ] settings.gradle.kts atualizado com repositórios de plugins
[ ] build.gradle.kts atualizado com repositórios de dependências
[ ] Comando ./gradlew clean build executado com sucesso

Configurar application.yml

[ ] Arquivo .properties renomeado para .yml
[ ] Porta configurada: 8080
[ ] Nome da aplicação definido
[ ] Nível de log configurado

Executar Aplicação

[ ] Aplicação compila sem erros
[ ] Console mostra "Started InvoiceServiceApplication"
[ ] http://localhost:8080 retorna página de erro do Spring (esperado!)

🐛 Problemas Comuns e Soluções

Erro: "Java version mismatch"

Causa: Versão errada do Java configurada

Solução:

No IntelliJ: File → Project Structure → Project
Configure SDK para Java 17
Em Language Level, selecione 17 - Sealed types, always-strict floating-point...

Erro: "Port 8080 already in use"

Causa: Outra aplicação já está usando a porta 8080

Solução:

No terminal: lsof -i :8080 (veja qual processo está usando)
Mate o processo ou mude a porta no application.yml para 8081

Dependências não baixam

Causa: Problema de rede ou cache do Gradle

Solução:

No terminal, dentro da pasta do projeto:

./gradlew clean build --refresh-dependencies

IntelliJ não reconhece código Kotlin

Causa: Plugin Kotlin não instalado

Solução:

File → Settings → Plugins
Procure por "Kotlin"
Clique em Install
Reinicie o IntelliJ

Erro: "Unsupported class file major version XX"

Causa: Versão do Java incompatível (código compilado com Java mais novo que o configurado)

Solução:

Verifique qual Java o projeto precisa: abra build.gradle.kts e procure sourceCompatibility
No IntelliJ: File → Project Structure → Project
Configure SDK para a versão correta (Java 17+)
No IntelliJ: File → Settings → Build Tools → Gradle
Configure Gradle JVM para a mesma versão
Execute: ./gradlew clean build

Erro: "Could not determine Java version"

Causa: Gradle JVM não configurado ou apontando para local inválido

Solução:

File → Settings → Build Tools → Gradle
Em Gradle JVM, selecione um JDK válido (Java 17+)
Se não aparecer nenhum JDK:
- Clique em Add JDK...
- Navegue até a pasta de instalação do Java
- No Linux: /usr/lib/jvm/java-17-openjdk-amd64
Clique em Apply e depois OK

Erro: "Gradle version X.X is required. Current version is Y.Y"

Causa: Versão do Gradle instalada não é compatível com o projeto

Solução:

Se usando Gradle Local:

Instale a versão correta: sdk install gradle 8.5 (usando SDKMAN)
Atualize o caminho no IntelliJ: Settings → Gradle → Gradle home

Se usando Wrapper (recomendado):

Settings → Gradle → Use Gradle from
Selecione: 'wrapper' task in Gradle build script
O wrapper baixará automaticamente a versão correta

Erro: "Could not resolve all dependencies" (Artifactory)

Causa: Credenciais incorretas ou URL do Artifactory errada

Solução:

Verifique se a URL no gradle.properties está correta
Teste acessar a URL no navegador: https://artifactory.suaempresa.com/artifactory
Confirme usuário e senha
Se usar variáveis de ambiente, execute: echo $ARTIFACTORY_USER para verificar

Erro: "HTTP 401 Unauthorized" (Artifactory)

Causa: Senha expirada ou usuário sem permissão

Solução:

Verificar suas permissões no Artifactory
Tente resetar sua senha no portal do Artifactory
Verifique se não há espaços extras no gradle.properties

Erro: "UnknownHostException" (Artifactory)

Causa: Você está fora da rede da empresa ou VPN desconectada

Solução:

Conecte-se à VPN da empresa
Verifique conexão: ping artifactory.suaempresa.com
Se estiver offline, comente temporariamente os repositórios privados e use só mavenCentral()

🎓 Conceitos Importantes para Entender

O que é Spring Boot?

É um framework (conjunto de ferramentas) que facilita criar aplicações Java/Kotlin. Ele já vem com muita coisa pronta, então você foca na lógica do seu negócio.

Analogia: É como comprar um carro pronto ao invés de construir cada peça do zero.

O que é API REST?

É uma forma de aplicações conversarem entre si usando HTTP (mesmo protocolo do navegador). Você cria "endpoints" (URLs) que recebem e envolvam dados.

Exemplo:

POST /invoices - Cria uma nova fatura
GET /invoices/123 - Busca a fatura de ID 123

O que é Gradle?

É uma ferramenta que:

Baixa bibliotecas (dependências) que seu projeto precisa
Compila seu código
Empacota tudo em um arquivo .jar executável

Analogia: É como um assistente que busca todas as ferramentas que você precisa e organiza tudo.

O que é Artifactory?

É um gerenciador de repositórios de artefatos usado em empresas. Funciona como um "armazém central" que:

Guarda bibliotecas internas - Código criado pela sua empresa
Faz cache de bibliotecas públicas - Copia do Maven Central para a rede da empresa
Controla versões - Sabe exatamente qual versão de cada biblioteca está sendo usada

Analogia: É como um armazém da Amazon, mas só para código da sua empresa.

Outros nomes: Nexus, Azure Artifacts, GitHub Packages (fazem a mesma coisa)

O que é Maven Local?

É uma pasta no seu computador (~/.m2/repository) que funciona como cache local de bibliotecas já baixadas.

Por que usar:

Evita baixar a mesma biblioteca várias vezes
Funciona offline se a biblioteca já foi baixada antes
Acelera o build (compilar sem internet)

Analogia: É como ter uma cópia local de livros que você já pegou emprestado antes.

Diferença: Plugins vs Dependências

Plugins (`settings.gradle.kts`)	Dependências (`build.gradle.kts`)
Ferramentas que ajudam a construir	Bibliotecas que o código usa
Exemplos: plugin do Kotlin, Spring Boot	Exemplos: Jackson, Spring Web
Baixados durante configuração do Gradle	Baixados durante compilação
Configura como o projeto é compilado	Código que roda na aplicação

💡 Dicas

Não copie e cole código sem entender!

Leia cada linha, tente compreender. Se não entender algo, pergunte!

Erros são normais

Você vai ver MUITAS mensagens de erro. Aprenda a lê-las com calma. Geralmente a última linha diz o problema.

Documente suas dúvidas

Anote o que não entendeu para perguntar depois. Isso mostra proatividade!

Commits frequentes

Quando algo funcionar, salve no Git. É como criar pontos de restore de um jogo.

🎉 Parabéns

Se você chegou até aqui e sua aplicação está rodando, você acabou de:

✅ Criar seu primeiro projeto Spring Boot

✅ Entender estrutura de pacotes

✅ Configurar uma aplicação

✅ Executar um servidor web

Isso é MUITA coisa para um dia de trabalho! 🚀

Lembre-se: Todo desenvolvedor sênior já esteve no seu lugar. A diferença é que eles persistiram e continuaram aprendendo. Você está no caminho certo! 💪

Git: Update remote url in your local machine

Thiago Matos — Sat, 17 Aug 2024 19:36:20 +0000

Given
You've cloned a remote git repository, for example:

git@gitlab.com:project-name.git

When
That repository changes its remote url to, for example:

git@gitlab.com:another-project-name.git

Then
I must update the remote url in your local machine using this command:

git remote set-url origin git@gitlab.com:another-project-name.git

And then, confirm the change was applied:

git remote -v

If you are using IntelliJ Idea, then you can access:

Menu -> Git -> Manage Remotes...

And make the update in this window:

The Logging, The AOP and The Clean Code

Thiago Matos — Fri, 09 Aug 2024 22:31:16 +0000

Logging is an essential practice that helps developers understand the flow of their applications and diagnose issues.

Understand the flow: It shows you how your application is behaving over time, making it easier to understand and improve.
Diagnose issues: It keeps a record of what your application is doing.

It is like having a notebook where you write down every step to build a robot. After you build, if the robot makes a mistake, you can look back at your notes to see what went wrong and fix it.

One clean-code way to implement logging in a Spring Boot application is through Aspect-Oriented Programming (AOP).

What is Aspect-Oriented Programming (AOP)?

AOP is a programming paradigm that aims to increase modularity by allowing the separation of aspects of a program that affect multiple components (cross-cutting concerns). AOP allows you to encapsulate these concerns into reusable modules called "aspects".

Imagine you are responsible to log what the program is doing. Without AOP, you would have to write the same log pattern in many different places. This makes your code hard to manage. With AOP, you would create a special module called aspect to handle the logs and then you would tell your program to use the aspect.This makes your code clean and organized.

In this article, I will show a practical example of AOP, implementing a custom annotation to log method inputs and outputs at a class level. After that, you can use this annotation in many places of your code.

Learning AOP with an example

First, let's see a class without AOP.

import org.springframework.stereotype.Service

@Service
class ExampleWithoutAop {

    fun methodA(
        parameterA: String,
        parameterB: Int
    ): String {
        println("ExampleWithoutAop#methodA START - parameterA=$parameterA, parameterB=$parameterB")
        val result = "$parameterA $parameterB"
        println("ExampleWithoutAop#methodA END - result=$result")
        return result
    }

    fun methodB(
        throwsException: Boolean
    ) {
        println("ExampleWithoutAop#methodB START - throwsException=$throwsException")
        if (throwsException) {
            val message = "error message"
            println("ExampleWithoutAop#methodB ERROR - message=$message")
            throw RuntimeException(message)
        }
        println("ExampleWithoutAop#methodB END")
    }
}

Add this runner in the main class of Spring Boot:

import org.springframework.boot.ApplicationRunner
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.Bean

@SpringBootApplication
class DemoApplication {

    @Bean
    fun runner(exampleWithoutAop: ExampleWithoutAop): ApplicationRunner {
        return ApplicationRunner {
            exampleWithoutAop.methodA("Hello", 42)
            exampleWithoutAop.methodB(false)
            exampleWithoutAop.methodB(true)
        }
    }
}

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}

Here is the output:

ExampleWithoutAop#methodA START - parameterA=Hello, parameterB=42
ExampleWithoutAop#methodA END - result=Hello 42
ExampleWithoutAop#methodB START - throwsException=false
ExampleWithoutAop#methodB END
ExampleWithoutAop#methodB START - throwsException=true
ExampleWithoutAop#methodB ERROR - message=error message

Let's clean the code using AOP and Custom Annotation

Step 1: Define the custom annotation

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecution

Step 2: Add the following dependency in your build.gradle.kts:

implementation("org.springframework.boot:spring-boot-starter-aop")

Step 3: Enable the AOP for Spring Boot by adding this annotation in your DemoApplication class:

@EnableAspectJAutoProxy

Here is how your main class will look like:

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.context.annotation.EnableAspectJAutoProxy

@EnableAspectJAutoProxy
@SpringBootApplication
class DemoApplication

Step 4: Create the Aspect

import org.aspectj.lang.ProceedingJoinPoint
import org.aspectj.lang.annotation.Around
import org.aspectj.lang.annotation.Aspect
import org.aspectj.lang.annotation.Pointcut
import org.aspectj.lang.reflect.MethodSignature
import org.springframework.stereotype.Component

// Define this class as an Aspect
@Aspect
// Makes this class a Spring-managed bean,
// allowing Spring to discover and manage it
@Component
class LoggingAspect {

    // An expression that selects the join points
    // where additional code (advice) will be applied.
    // It selects all methods
    // within classes annotated with @LogExecution.
    @Pointcut("within(@com.example.demo.LogExecution *)")
    fun logExecutionMethods() {}

    // Define an "Around" Advice (additional code),
    // which surrounds (around) the execution of
    // the method selected by the Pointcut
    @Around("logExecutionMethods()")
    fun logMethodExecution(joinPoint: ProceedingJoinPoint): Any? {

        // Get the method signature from the join point
        val methodSignature = joinPoint.signature as MethodSignature

        // Get the name of the class where the method is located
        val className = methodSignature.declaringType.simpleName

        // Get the name of the method
        val methodName = methodSignature.name

        // Get the names of the method's parameters
        val inputNames = methodSignature.parameterNames

        // Get the values of the arguments passed to the method
        val inputValues = joinPoint.args

        // Combine the parameter names and values into a formatted string
        val inputs = inputNames.zip(inputValues)
            .joinToString(", ") {
                "${it.first}=${it.second}"
            }

        // Create a tag that combines the class name and method name
        val tag = "$className#$methodName"

        // Print a log message indicating
        // the starting of the method execution,
        // including the input parameters
        println("$tag START${log(inputs)}")

        // Try to execute the original method
        // and store the output value
        val output = try {
            joinPoint.proceed()
        } catch (ex: Throwable) {
            // If an exception occurs,
            // print an error message to the log
            // and rethrow the exception
            println("$tag ERROR - message=${ex.message}")
            throw ex
        }

        // Print a log message indicating
        // the ending of the method execution,
        // including the return value
        println("$tag END${log(output)}")

        // Return the output value of the original method
        return output
    }

    // Helper function to format
    // the input parameters for logging
    private fun log(inputs: String) =
      if (inputs.isEmpty()) ""
      else " - $inputs"

    // Helper function to format
    // the output value for logging
    private fun log(output: Any?) =
      output
        ?.let { " - result=$it" }
        ?: ""
}

Step 5: Replace ExampleWithoutAop by its new version using AOP with custom annotation:

import org.springframework.stereotype.Service

@LogExecution
@Service
class ExampleWithAop {

    fun methodA(
        parameterA: String,
        parameterB: Int
    ): String = "$parameterA $parameterB"

    fun methodB(
        throwsException: Boolean
    ) {
        if (throwsException) {
            throw RuntimeException("error message")
        }
    }
}

Execute the Spring Boot application and see the same output. But now, notice that the code of ExampleService is much more clean allowing you to focus on your business rules.

Conclusion

By creating a custom annotation and an aspect, we can easily log into any class of our application. This approach not only helps in debugging but also keeps our code clean and modular.

Benefits of Using AOP:

It allows separation of cross-cutting concerns, like logging, from the main business logic;
It allows reusing across different parts of your application, reducing code duplication;
Single Responsibility Principle: By separating logging and other cross-cutting concerns into aspects, each class has only one reason to change;
Open/Closed Principle: It allows you to add new behaviors (like logging) without modifying existing code, making your classes open for extension but closed for modification.

Running Tests in GitLab CI: From Zero to Pipeline

Thiago Matos — Thu, 11 Jul 2024 22:26:06 +0000

Continuous Integration (CI) is an essential practice in modern software development. It ensures that code changes are automatically tested, leading to faster and more reliable software releases. In this article, we'll walk through the process of setting up a Spring Boot project with Gradle, writing unit tests, and configuring GitLab CI to automate the testing.

Pre-requirements:

Linux (Ubuntu based) Operational System
GitLab Account
Tool to unzip a file

Step 1: Install SDKMAN and Java 21

First, we need to install SDKMAN, a tool for managing parallel versions of multiple Software Development Kits (SDKs), including Java.

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

You can close and open again your terminal to assure your installation is successful.

Second, use sdkman to install Java 21, the most stable version.
The command below shows the available versions:

sdk list java

You can choose one of your preferences. Use the Identifier column as reference to install the chosen version:

sdk install java 21.0.2-open

Third, confirm you've installed successfully

java --version

Step 2: Install Git

Next, install Git, a version control system that we'll use to manage code changes of our project.

sudo apt-get update
sudo apt-get install git

Step 3 Install IntelliJ IDEA

IntelliJ IDEA is a popular IDE(Integrated Development Environment) for Java development. Here is the command to install it:

sudo snap install intellij-idea-community --classic

Step 4: Create a Spring Boot Project

We'll use Spring Initializr to create a new project for the most recent version.
Access https://start.spring.io/ and configure the project as follows:

Project: Gradle - Kotlin
Language: Java
Spring Boot: 3.3.1
Packaging: jar
Java: 21
Dependencies: No dependency is necessary

Click on the button GENERATE to download the project as zip.

Step 5: Import the Project into IntelliJ

Unzip the downloaded file into a folder of your preference.
Open IntelliJ IDEA and import the unzipped project. IntelliJ will automatically detect the Gradle configuration and set up the project accordingly.

Step 6: Make a TDD

First, let's create a Test. Create a simple class and a corresponding unit test.

Create a new class named Calculator in the folder src/main/java/com/example/demo:

public class Calculator {
    public int add(int a, int b) {
        return 0;
    }
}

Use jUnit lib (it already comes with the Spring Boot) to create its unit test in the folder src/test/java/com/example/demo:

import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
class CalculatorTest {
    @Test
    void testAdd() {
        var calculator = new Calculator();
        var result = calculator.add(2, 3);
        assertThat(result).isEqualTo(5);
    }
}

Second, let the test fail.
Press one of the Green Buttons to run the test.

Check that the test fails.

Third, fix the test by writing the correct business rule:

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}

And, at last, run the test again and see that now it is passing.

Step 6: Create a Gitlab CI Configuration File

Create a .gitlab-ci.yml file in the root of your project. This file will define the pipeline.

stages:
  - build

Build:
  stage: build
  image: gradle:8.8.0-alpine
  script:
    - gradle --build-cache clean build
  artifacts:
    when: always
    expire_in: 1 days
    paths:
      - build/libs/*.jar
      - build/test-results/test/*.xml
    reports:
      junit:
        - build/test-results/test/*.xml
  only:
    - main

stages: define a sequence of steps that the pipeline will execute. The pipeline runs stages in the order they are defined, and all jobs within the same stage run in parallel. Only after all jobs in a stage complete successfully does the pipeline proceed to the next stage.
Build: name of the job to be executed for the stage.
Image: Docker Image that will be used to execute the job.
script: gradle command to generate the jar, run the tests and generate a report about the tests.
artifacts: Files that will survive when the job is done.
only: name of the git branch

Step 8: Create a Project on GitLab

Gitlab is a web-based DevOps lifecycle tool that provides a Git repository manager offering source code management, continuous integration, and continuous deployment capabilities.

Go to GitLab and create a new blank project and make it public or private based on your preference.
https://gitlab.com/projects/new#blank_project

Step 9: Configure Git in Project

Open the terminal, go to the directory where you unzipped your code and configure git on it.

git init --initial-branch=main
git remote add origin https://gitlab.com/your-username/spring-boot-unit-test-ci.git
git add .
git commit -m "Initial commit"
git push --set-upstream origin main

Step 10: Check the pipeline running

Go to https://gitlab.com/your-username/spring-boot-unit-test-ci/-/pipelines and click on the first (and only existent) pipeline running.

Here you can see the pipeline running:

After some time, the pipeline passes:

Here you can see the test report:

Conclusion

By following these steps, you've successfully set up a Spring Boot project with Gradle, written an unit test, and configured GitLab CI to automate the testing. You can now make a test fail intentionally and observe the pipeline breaking, then fix the test and see the pipeline pass again. This iterative process helps ensure that your code is always in a deployable state.

Here is the link to the project:
https://gitlab.com/thiagoematos/spring-boot-unit-test-ci

Introduction to Pact Flow

Thiago Matos — Thu, 04 Jul 2024 18:18:49 +0000

Introduction to Contract Testing

Definition and importance of contract testing: Imagine that you and your friends are planning a party and each one has a task: one will bring the snacks, another the sweets, and another the drinks. To ensure that everything goes well, you make a list of what everyone should bring. "Contract testing" is like this list, but for computer programs that need to talk to each other. It checks that each part of the program is doing exactly what it promised, just like you check that each friend brought what they agreed to for the party. This is important because if someone forgets or brings something wrong, the party might not be as fun. Likewise, if a program doesn't do what it promises, other programs may stop working correctly.

Differences between contract testing and other types of testing (unit, integration, end-to-end): Imagine you have a Lego. "Unit testing" is like testing each piece of Lego separately to see if they are perfect. "Integration testing" is when you put a few pieces together and check if they fit well and work together. "End-to-end testing" is when you assemble the entire toy and see if it works the way you want, like a walking car. "Contract testing" is as if you had a manual that tells you exactly how each piece should fit together with the others. It checks whether each part of the toy follows the rules in the manual, ensuring that everything will work correctly when you assemble it. Each type of test is important to ensure your toy is perfect and fun to play with!

Benefits of contract testing in microservices architecture: Imagine that you and your friends are building a Lego city, and each one is responsible for a part: one makes the houses, another the streets, and another the parks. For the city to function well, you need to ensure that the streets connect well with the houses and parks. "Contract testing" is like an agreement you make to ensure that each part of the city will fit perfectly with the others. This is super important because, if someone builds a street that doesn't connect to the houses, people won't be able to get home! In a microservices architecture, each part of the program is like one of those parts of the city, and contract testing helps ensure that they all work well together, even if they are done by different people or at different times. This makes the city, or the program, work properly and without problems.

Benefits of PactFlow

Improved Collaboration: Enhances communication between development teams.
Reduced Integration Issues: Minimizes problems when integrating different services.
Faster Development Cycles: Speeds up the development process by catching issues early.
Increased Confidence: Provides assurance that services will work together as expected.
PactFlow is like a helper that keeps an eye on these messages to ensure that everyone is complying with what was agreed.
When someone says they are going to bring snacks, Pact checks whether that person actually brought the snacks at the party.

Setting Up the Environment

pom.xml
create an account

Consumer-Driven Contracts

Writing consumer tests with Pact is like making a party wish list, saying exactly what you hope your friends will bring. Imagine that you are organizing the party and want to make sure you get the snacks, sweets and drinks you ordered. Consumer will generate a contract in json format. You write a little code that describes what the response should look like. If the test passes, it means that the other program is fulfilling what was agreed. If it doesn't pass, you know you need to adjust something.
Writing provider tests with Pact is like ensuring you actually bring what you promised to the party. Imagine that you said that you are going to take a chocolate cake with strawberry frosting. To make sure you don't forget or take something wrong, you do a check before leaving home: "Do I have the chocolate cake? Yes. Does it have strawberry frosting? Yes." So, on provider we need to write a code to provider the response for contract.