API HTTP simples em Spring Boot, usada para responder a uma requisição de saudação e exercitar o encaminhamento e o balanceamento de tráfego com Nginx.
A aplicação expõe um endpoint:
| Método | Caminho | Resposta |
|---|---|---|
GET |
/api/v1/hello |
200 OK com o texto Hello World! |
Cada requisição é registrada no log da aplicação com a porta configurada e o
endereço remoto visto pela aplicação. A porta padrão é 8080; ela pode ser
alterada para executar mais de uma instância.
- Java 25
- Redis 7 ou superior para executar a aplicação localmente
- Nginx para o exemplo de proxy reverso
- Docker e Docker Compose, caso queira executar o teste de carga incluído
Inicie o Redis em outro terminal:
docker run --rm -p 6379:6379 redis:7-alpineNa raiz do projeto, inicie a aplicação com o Maven Wrapper:
./mvnw spring-boot:runEm outro terminal, faça uma requisição diretamente à aplicação:
curl -i http://localhost:8080/api/v1/helloO corpo da resposta será:
Hello World!
A resposta é armazenada no Redis por 10 minutos. O host e a porta padrão são
localhost:6379; configure SPRING_DATA_REDIS_HOST e
SPRING_DATA_REDIS_PORT para usar outro endereço.
Para compilar, empacotar e executar os testes:
./mvnw test
./mvnw packageDepois de empacotar, o JAR pode ser executado assim:
java -jar target/hello-word-0.0.2-SNAPSHOT.jarConstrua a imagem a partir da raiz do projeto:
docker build -f dockerfile -t hello-word .Para executar a aplicação em container junto com o Redis, use o Docker Compose descrito abaixo:
docker compose up --buildEm outro terminal, teste o endpoint:
curl http://localhost:8080/api/v1/helloA resposta esperada é Hello World!. Para parar o container, pressione
Ctrl+C no terminal em que ele está rodando.
O arquivo docker-compose.yml inicia o Redis e cinco instâncias da API. Cada
instância escuta na porta 8080 dentro do container e fica disponível no host pelas portas
8080 a 8084:
docker compose up --buildPara iniciar em segundo plano, use:
docker compose up --build -dConfira o estado das instâncias e acompanhe os logs de um serviço específico:
docker compose ps
docker compose logs -f app-8080Para ver os logs de outra instância, substitua app-8080 por app-8081,
app-8082, app-8083 ou app-8084.
Teste qualquer instância, por exemplo:
curl http://localhost:8080/api/v1/hello
curl http://localhost:8084/api/v1/helloPara parar e remover os containers:
docker compose downTodas as instâncias usam o mesmo serviço Redis do Compose, permitindo que
compartilhem a resposta em cache. A entrada greetings expira após 10 minutos.
Para execução fora do Compose, o padrão é conectar a localhost:6379; as
variáveis SPRING_DATA_REDIS_HOST e SPRING_DATA_REDIS_PORT podem substituir
essa configuração.
O Nginx recebe as conexões HTTP na porta 80 e encaminha as requisições do
endpoint para a aplicação. O exemplo abaixo configura duas instâncias locais
do serviço, nas portas 8080 e 8081; o balanceamento padrão do Nginx entre
servidores de um upstream é round-robin.
flowchart LR
C[Cliente / k6] -->|GET /api/v1/hello| N[Nginx<br/>Proxy reverso :80]
N -->|Round-robin| U1[API Spring Boot<br/>:8080]
N -->|Round-robin| U2[API Spring Boot<br/>:8081]
U1 -->|200 Hello World!| N
U2 -->|200 Hello World!| N
N -->|Resposta HTTP| C
Crie, por exemplo, /etc/nginx/conf.d/hello-word.conf:
upstream hello_word_backend {
server 127.0.0.1:8080;
server 127.0.0.1:8081;
}
server {
listen 80;
server_name localhost;
location /api/v1/hello {
proxy_pass http://hello_word_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Como proxy_pass não inclui uma URI após o nome do upstream, o caminho
original (/api/v1/hello) é encaminhado sem alteração.
Inicie a primeira instância na porta padrão e a segunda em 8081:
./mvnw spring-boot:run
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081Em instalações nas quais o comando spring-boot:run não repassa essa opção,
use dois processos do JAR empacotado:
java -jar target/hello-word-0.0.2-SNAPSHOT.jar --server.port=8080
java -jar target/hello-word-0.0.2-SNAPSHOT.jar --server.port=8081Valide a configuração e recarregue o Nginx:
sudo nginx -t
sudo systemctl reload nginxAgora a chamada passa pelo proxy:
curl -i http://localhost/api/v1/helloPara um proxy de instância única, mantenha apenas um servidor no upstream.
Em produção, configure também o nome de domínio e TLS conforme a infraestrutura
do ambiente.
O Nginx envia X-Real-IP e X-Forwarded-For, mas a implementação atual registra
HttpServletRequest.getRemoteAddr(). Esse valor é o endereço remoto da conexão
que chegou à aplicação — normalmente o próprio Nginx quando há proxy — e não
usa automaticamente os cabeçalhos encaminhados. Portanto, o log atual pode
mostrar o endereço do proxy em vez do IP original do cliente.
O script scripts/carga/teste-carga.js usa k6 para chamar
http://localhost/api/v1/hello pelo Nginx. O cenário sobe gradualmente até 100
usuários virtuais, mantém essa carga por 30 segundos e então reduz a carga. Cada
requisição verifica o status 200 e o corpo exato Hello World!. O teste falha
se algum check não passar, se 1% ou mais das requisições falharem ou se o
percentil 95 do tempo de resposta atingir 150 ms.
Com a aplicação e o Nginx em execução, rode o teste a partir do diretório do script:
cd scripts/carga
docker compose up --abort-on-container-exitPara remover containers órfãos e reiniciar os serviços com a configuração atual:
docker compose down --remove-orphans && docker compose upO Compose está configurado com network_mode: host, para que o container k6
acesse o Nginx pelo localhost da máquina. Esse modo é voltado a Linux e
compartilha a rede do host. O teste não inicia a aplicação nem o Nginx; eles
precisam estar disponíveis antes de executá-lo.
Para testar outra URL, informe TARGET_URL ao Compose:
TARGET_URL=http://localhost:8080/api/v1/hello docker compose up --abort-on-container-exitEsse exemplo acessa a aplicação diretamente, sem passar pelo Nginx.