Arquitetura de Sistemas · Insper · Lab 1

Lab 1 — Primeiro serviço: catalog

Um serviço web de eventos e locais: Spring Boot, PostgreSQL, Flyway, um container — e a sua latência sem carga

A história até aqui

lab 0 · o tetoNginx de fábrica: dezenas de milhares de req/s
→
capítulo 2 · lab 1catalog: um serviço, um banco
→
depois · lab 2o joelho, medido

Às 10:00 a demanda é de ~33.000 holds/s; um PostgreSQL faz ~1.100. Antes: quão rápido um serviço de verdade responde a um usuário?

  • O tempo de serviço medido hoje é a referência de todo lab seguinte.

Por que o catalog primeiro?

Durante a venda relâmpago, quantas leituras da página do evento acontecem para cada alteração de um administrador?

  • Milhões de fãs recarregam; um punhado de administradores edita → muita leitura.
  • Ele será a cobaia do balanceamento de carga (lab 3), do cache (lab 5), dos índices (lab 6).
  • Hoje: a versão mais simples que funciona — monolith-first.

O que você vai construir

fãGET /catalog/events?city=Recife
→
catalog :8082Spring Boot · 1 CPU, 768 MB
→
db :5432PostgreSQL 17, schema catalog
consulta 1events JOIN venues · ORDER BY starts_at · LIMIT 20
consulta 2count(*) para os links de página: 20.000
200{items, page: 0, totalItems: 20000}
  • 50 locais em 10 cidades, 200.000 eventos, criados por uma migration: um volume realista de propósito.
  • Evento 1: BoxOffice Fest — Stadium Night, num estádio de 60.000 lugares — o show da venda relâmpago do curso.

O contrato

Método Caminho Resposta
GET /catalog/events?city=&page=&size= página de próximos eventos
GET /catalog/events/{id} evento + local, ou 404
POST /catalog/events 201 + Location
PUT · DELETE /catalog/events/{id} 200 · 204
GET · POST /catalog/venues locais

Tudo sob /catalog: o edge e o gateway roteiam sem reescrever caminhos.

Decisões de projeto

  • Coleções são paginadas, size ≤ 50 — toda lista é limitada.
  • Dinheiro é BigDecimal / NUMERIC(10,2); tempo é TIMESTAMPTZ, ISO-8601.
  • Erros seguem o pedido de comentários (RFC, Request for Comments) 9457: problem+json.
  • 201 Created + Location para recursos novos.

Na entrevista: recursos + verbos, estratégia de paginação, modelo de erros.

Três camadas, uma regra

  • Controller: HTTP, validação, códigos de status.
  • Service: regras de negócio, @Transactional.
  • Repository: consultas (JPA, Jakarta Persistence).

A interface de programação (API, application programming interface) nunca devolve entidades: só records, os objetos de transferência de dados (EventOut, VenueOut). Uma coluna nova não pode vazar; uma associação lazy não pode explodir.

Qual código de status?

POST /catalog/events
→
@Valid EventIn, @Min / @Maxconferidos antes de o método rodar
→
CatalogServiceo local existe?
→
201 Created+ Location
400 problem+jsonsem título, preço −1, ?size=500
400 / 404local desconhecido / id desconhecido
@RequestParam(defaultValue = "20") @Min(1) @Max(50) int size
  • ?size=500 → 400 problem+json, não uma consulta de 500 linhas.

JPA: cuidado com o N+1

Listar 20 eventos, cada um com o seu local. Quantas consultas na linguagem de consulta estruturada (SQL, Structured Query Language)?

  • Sem join fetch: 1 + 20 = 21 idas e voltas.
  • Com select e from Event e join fetch e.venue: 1.
  • Cada ida e volta segura uma das 10 conexões do pool por mais tempo.

Flyway: o schema é código

  • V1__create_catalog.sql, V2__seed_catalog.sql — aplicadas uma vez, em ordem.
  • Nunca edite uma migration aplicada: acrescente V3__....
  • ddl-auto: validate: o Hibernate confere, o Flyway é o dono.
  • Carga com generate_series: 200.000 eventos, idênticos em todo notebook.

Volume realista de propósito: uma consulta instantânea com 10 linhas pode levar dezenas de ms com 200.000.

O container: dois estágios

build · maven:3.9-eclipse-temurin-21
pom.xml + src/
mvn package~/.m2 num cache mount
target/app.jar
COPY --from=build →
runtime · eclipse-temurin:21-jre
app.jarrodado pelo usuário app, não root
sem kit de desenvolvimento Java (JDK, Java Development Kit), sem Maven, sem código-fonte
  • java -XX:MaxRAMPercentage=75: o heap segue o limite de memória do container.
  • A imagem leva só um ambiente de execução Java (JRE, Java Runtime Environment) e o jar.

Compose: o que o up espera

db inicia
→
pg_isreadya cada 5 s → healthy
→
catalog iniciadepends_on: service_healthy
→
Flyway V1, V2depois o Hibernate valida
→
/actuator/health/readinessUP → healthy
  • Volume db-data: os dados sobrevivem ao down; down -v zera.
  • 1 CPU, 768 MB por catalog: uma unidade fixa de capacidade.

Dentro de um container, o banco é db, não localhost.

Meça: o tempo de serviço

k6 run load/smoke.js        # 1 VU, 30 s, think time 0.5 s
Endpoint p50 p95 p99
GET /catalog/events/{id} ~5 ms ~11 ms ~40 ms
GET /catalog/events?city= ~30 ms ~42 ms ~71 ms

Números de um notebook — registre os seus em results/lab1.md.

Lendo a referência

  • Listagem ≈ 2–6× o detalhe: join + ordenação + count(*) sobre 20.000 linhas; o detalhe é uma busca pela chave primária.
  • p99 ≫ p50 mesmo com um usuário: compilação just-in-time (JIT), coleta de lixo, pool frio, páginas frias.
  • Sempre aqueça antes de medir; nunca compare frio com aquecido.

Qual endpoint vai quebrar primeiro sob carga? Anote a hipótese para o lab 2.

O que quebra em seguida

lab 1 · tempo de serviçoum usuário: detalhe ~11 ms, listagem ~42 ms no p95
→
quantas req/s?a prévia desenha ~530; as 10:00 pedem ~33.000
→
lab 2 · meça primeirocarga aberta até a latência explodir: o joelho
  • Escreva a sua hipótese agora: qual recurso enche primeiro?

Pontos-chave

  1. Desenhe o contrato primeiro: recursos, coleções limitadas, códigos de status, problem+json.
  2. Records desacoplam a API das tabelas.
  3. join fetch evita o N+1; toda consulta pega emprestada uma conexão do pool.
  4. O Flyway é dono do schema; migrations aplicadas nunca mudam.
  5. Um comando para rodar tudo: docker compose up --build.
  6. Registre a latência sem carga: é a referência para todos os labs seguintes.

Capítulo 2 da história. Roteiro: (1) por que o catalog primeiro; (2) o que você vai construir; (3) o contrato da API; (4) camadas, DTOs e códigos de status; (5) JPA, N+1, o pool; (6) Flyway; (7) Dockerfile e Compose; (8) smoke test e tempo de serviço.

A história da disciplina (visão geral de 2027.1, "A história da disciplina"): todo capítulo abre com o número que o anterior deixou. O lab 1 abre o capítulo 2: o serviço único e o banco único que a aula 2 confere no papel.