a. Visão geral

Todo site de ingressos começa pela mesma página: o que tem, onde e quando? No BoxOffice esse é o trabalho do catalog. Ele é o serviço com mais leitura do sistema — durante uma venda relâmpago, milhões de fãs recarregam a página do evento enquanto só um punhado de administradores a altera — e por isso será a cobaia do balanceamento de carga (lab 3), do cache (lab 5) e dos índices (lab 6). Hoje você constrói a versão mais simples que funciona, o passo monolith-first da jornada de escala.

Antes de começar

Confira as ferramentas:

docker compose version        # Docker Compose v2.x (or newer)
java -version                 # 21 or newer
mvn -v                        # Apache Maven 3.9+
k6 version                    # k6 v1.0+
uv --version                  # uv (runs the Python helper scripts)

Estado inicial — o fim do lab 0:

📁 boxoffice/
├──  .gitignore
├── 📁 load/
│   └──  hello.js
├── 📁 results/
│   └──  lab0.md
└── 📁 scripts/
    └──  check-env.sh

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

O que você vai construir

sequenceDiagram
    autonumber
    actor Fan as Fã
    participant C as catalog :8082<br/>(Spring Boot)
    participant DB as db :5432<br/>(PostgreSQL, schema catalog)
    Fan->>C: GET /catalog/events?city=Recife
    C->>DB: SELECT events JOIN venues WHERE city = ? ORDER BY starts_at LIMIT 20
    DB-->>C: 20 linhas
    C->>DB: SELECT count(*) ... (total para os links de página)
    DB-->>C: 20000
    C-->>Fan: 200 {items: [...], page: 0, totalItems: 20000}

O serviço segue a estrutura clássica de três camadas — controller (HTTP, validação, DTOs) → service (regras de negócio, transações) → repository (SQL via JPA) — com uma regra que importa para tudo que vem depois: a API nunca expõe as entidades do banco, só records (EventOut, VenueOut) que você controla.

O banco começa com 50 locais em 10 cidades e 200.000 eventos (um por hora a partir de março de 2027), gerados por uma migration do Flyway¹. O evento 1 é o show de venda relâmpago da disciplina: BoxOffice Fest — Stadium Night, em um estádio de 60.000 lugares. Um volume realista de dados é proposital: uma consulta instantânea com 10 linhas pode levar dezenas de milissegundos com 200.000, e é exatamente isso que você vai medir.

Passos

Ao fim dos três passos, o seu repositório fica assim:

📁 boxoffice/
├──  docker-compose.yaml
├── 📁 load/
│   ├──  hello.js
│   └──  smoke.js
├── 📁 results/
│   ├──  lab0.md
│   └──  lab1.md
└── 📁 services/
    └── 📁 catalog/
        ├──  Dockerfile
        ├──  .dockerignore
        ├──  pom.xml
        ├── 📁 src/main/java/boxoffice/catalog/
        │   ├──  CatalogApplication.java
        │   ├──  Category.java
        │   ├──  Event.java              Venue.java
        │   ├──  EventRepository.java    VenueRepository.java
        │   ├──  CatalogService.java
        │   ├──  EventController.java    VenueController.java
        │   └──  EventIn.java  EventOut.java  VenueIn.java  VenueOut.java  PageOut.java
        └── 📁 src/main/resources/
            ├──  application.yaml
            └── 📁 db/migration/
                ├──  V1__create_catalog.sql
                └──  V2__seed_catalog.sql

Meça: a referência sem carga

Antes de perguntar "quanta carga ele aguenta?" (lab 2), registre a velocidade de cada endpoint com um único usuário. Esse é o tempo de serviço: a melhor latência que você verá, e a referência para toda comparação posterior.

Salve o smoke test como load/smoke.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// Lab 1: smoke test. One user, 30 seconds: does every endpoint answer, and how fast
// when the service is NOT under load?   k6 run load/smoke.js
import http from 'k6/http';
import { check, sleep } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'http://localhost:8082';
const CITIES = ['São Paulo', 'Rio de Janeiro', 'Belo Horizonte', 'Porto Alegre', 'Curitiba',
  'Salvador', 'Recife', 'Fortaleza', 'Brasília', 'Manaus'];

export const options = {
  vus: 1,
  duration: '30s',
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
  thresholds: {
    http_req_failed: ['rate==0'],
    // one threshold per endpoint makes k6 print one latency line per endpoint
    'http_req_duration{name:GET /catalog/events/{id}}': ['p(95)<200'],
    'http_req_duration{name:GET /catalog/events?city}': ['p(95)<500'],
  },
};

export default function () {
  const id = 1 + Math.floor(Math.random() * 200000);
  const detail = http.get(`${BASE_URL}/catalog/events/${id}`,
    { tags: { name: 'GET /catalog/events/{id}' } });
  check(detail, { 'detail is 200': (r) => r.status === 200 });

  const city = CITIES[Math.floor(Math.random() * CITIES.length)];
  const list = http.get(`${BASE_URL}/catalog/events?city=${encodeURIComponent(city)}&page=0&size=20`,
    { tags: { name: 'GET /catalog/events?city' } });
  check(list, {
    'list is 200': (r) => r.status === 200,
    'list has 20 items': (r) => r.json('items').length === 20,
  });

  sleep(0.5);   // think time: a real user does not click non-stop
}

Com a stack rodando (passo 3):

Os números acima vêm de uma execução em um notebook; os seus serão diferentes. Duas coisas devem chamar a atenção mesmo assim: a listagem é claramente mais lenta que o detalhe, umas 2 a 6 vezes (ela junta duas tabelas, ordena e conta milhares de linhas; o detalhe é uma busca por chave primária), e o p99 fica longe da mediana mesmo com um único usuário (compilação JIT, coleta de lixo, as primeiras conexões do pool).

Registre os resultados em results/lab1.md:

# Lab 1 — catalog, unloaded (1 VU, 30 s)

| Endpoint                     | p50 (ms) | p95 (ms) | p99 (ms) | max (ms) |
|------------------------------|---------:|---------:|---------:|---------:|
| GET /catalog/events/{id}     |          |          |          |          |
| GET /catalog/events?city=... |          |          |          |          |

- Startup time ("Started CatalogApplication in ... seconds"): ____ s
- Image size (`docker image ls boxoffice-catalog`): ____ MB
- Seed time (Flyway "Successfully applied 2 migrations ... execution time"): ____ s
- Why is the listing slower than the detail? ____

Solução de problemas

Limpeza

docker compose down          # stop and remove the containers, keep the database volume
# docker compose down -v     # ...and also erase the database (Flyway seeds it again next time)

Mantenha o repositório como está: o lab 2 mede este mesmo serviço.

Entrega

• services/catalog compila e roda com docker compose up --build; o Flyway aplica V1 e V2.
• Todo endpoint da tabela responde como descrito (teste também os casos 400 e 404 — o corpo deve ser application/problem+json²).
• O documento OpenAPI é servido em http://localhost:8082/catalog/openapi.
• load/smoke.js passa em todos os thresholds; results/lab1.md está preenchido.
• Repositório com a tag lab1; quiz respondido.

Estado final

📁 boxoffice/
├──  docker-compose.yaml                      # new: db + catalog
├──  load/smoke.js                            # new
├──  results/lab1.md                          # your measurements
└── 📁 services/catalog/                        # new: the whole service
    ├──  Dockerfile  .dockerignore  pom.xml
    ├──  src/main/java/boxoffice/catalog/*.java   (14 classes)
    ├──  src/main/resources/application.yaml
    └──  src/main/resources/db/migration/V1__create_catalog.sql, V2__seed_catalog.sql

Rodando: db (PostgreSQL 17, schema catalog com 50 locais e 200.000 eventos) e catalog na porta 8082.

Próximo: Lab 2 — Meça primeiro.