Sistema de Clima com gRPC e Spring Boot

Este projeto é um sistema distribuído composto por dois microsserviços (um Cliente REST e um Servidor gRPC) que se comunicam utilizando o protocolo gRPC para consultar, cadastrar e fornecer estatísticas sobre o clima de diversas cidades.

📂 Estrutura do Projeto

O repositório segue a estrutura padrão do ecossistema Java/Spring Boot com orquestração via Docker:

weather-grpc-system/
├── src/                  # Código-fonte Java e contrato (.proto)
│   └── main/
│       ├── java/         # Implementação do cliente REST e servidor gRPC
│       ├── proto/        # Arquivo weather.proto (contrato gRPC)
│       └── resources/    # Configurações do Spring Boot (application.yaml)
├── build.gradle          # Configuração de dependências e plugins
├── settings.gradle       # Configuração do projeto
├── docker-compose.yml    # Orquestrador dos containers
├── client.dockerfile     # Instruções de build da imagem do Cliente
├── server.dockerfile     # Instruções de build da imagem do Servidor

---

🚀 Como rodar o projeto

O projeto foi configurado com Docker e Docker Compose, o que torna a execução muito simples através de multi-stage builds. Você não precisa ter o Gradle ou o Java instalados na sua máquina, apenas o Docker.

1. Clone o repositório.
2. Na raiz do projeto, abra o terminal e execute:

   docker compose up --build
   

3. O Docker fará o download das dependências, compilará o código e iniciará os dois serviços.
4. A API REST estará disponível em http://localhost:8080.

Nota: Para parar a execução, utilize Ctrl + C no terminal e depois execute docker compose down para remover os containers.

---

🌐 Endpoints da API REST

O cliente REST expõe os seguintes endpoints na porta 8080 para comunicação com o usuário final. Estes endpoints repassam a requisição via gRPC para o servidor na porta 9090.

Método HTTP	Endpoint	Descrição	Exemplo de Uso
POST	/cidade	Cadastra uma nova cidade no mock do servidor.	Corpo (JSON): {"nome": "Ipameri"}
GET	/cidades	Lista os nomes de todas as cidades cadastradas.	http://localhost:8080/cidades
GET	/temperatura	Retorna a temperatura atual da cidade informada.	http://localhost:8080/temperatura?cidade=Ipameri
GET	/previsao	Retorna a previsão de temperatura para os próximos dias.	http://localhost:8080/previsao?cidade=Ipameri
GET	/estatisticas	Retorna os cálculos de média, mínima e máxima da cidade.	http://localhost:8080/estatisticas?cidade=Ipameri

---

📄 Explicação do Arquivo .proto

O arquivo weather.proto é o "contrato" do nosso sistema. Ele define exatamente como a comunicação entre o cliente e o servidor vai acontecer, sendo agnóstico de linguagem.

1. Definição do Serviço (service)

service WeatherService {
  rpc CadastrarCidade (CidadeRequest) returns (CidadeResponse);
  rpc ListarCidades (Empty) returns (ListaCidadesResponse);
  rpc ObterTemperaturaAtual (CidadeRequest) returns (TemperaturaResponse);
  rpc PrevisaoCincoDias (CidadeRequest) returns (PrevisaoResponse);
  rpc EstatisticasClimaticas (CidadeRequest) returns (EstatisticasResponse);
}

O bloco service agrupa todas as chamadas remotas (RPCs) que o nosso servidor gRPC expõe. Ele funciona como uma interface (interface) no Java. Cada método RPC define o que ele recebe como entrada e o que devolve como saída.

2. Definição das Mensagens (message)

message CidadeRequest {
  string nome = 1;
}

message TemperaturaResponse {
  string cidade = 1;
  double temperatura = 2;
}
// ... outras mensagens

As messages são as estruturas de dados transportadas na rede. Elas se transformam em classes Java (DTOs). Os números (= 1, = 2) são chamados de tags; eles são usados pelo Protobuf para codificar o campo em binário, garantindo que o transporte seja extremamente leve e rápido, em vez de enviar os nomes dos campos em texto plano (como no JSON).

3. RPCs Implementados

• CadastrarCidade: Recebe um CidadeRequest (com o nome da cidade) e retorna uma CidadeResponse confirmando o cadastro.
• ListarCidades: Recebe uma mensagem Empty (vazia) e devolve uma ListaCidadesResponse contendo um array (ou lista) de strings com todas as cidades cadastradas.
• ObterTemperaturaAtual: Recebe um CidadeRequest e retorna um TemperaturaResponse com a temperatura daquela cidade no momento atual (pegando o primeiro registro do mock).
• PrevisaoCincoDias: Recebe a cidade e devolve uma PrevisaoResponse, que internamente contém uma lista (repeated) da mensagem PrevisaoDia (com o nome do dia e a respectiva temperatura).
• EstatisticasClimaticas: Recebe a cidade e devolve uma EstatisticasResponse contendo cálculos como a média, a mínima e a máxima de temperatura daquela cidade.

4. Como o .proto gera código (Stubs)

Através do plugin protoc configurado no build.gradle, o compilador do Protobuf analisa o arquivo weather.proto toda vez que o comando de build é executado. Ele gera dois tipos de códigos (chamados de Stubs):

• Classes de Mensagens: Classes Java com Builders imutáveis correspondentes a cada message (ex: CidadeRequest).
• Classes de Serviço (Stubs):
  • Para o Servidor, ele gera uma classe abstrata (WeatherServiceImplBase) que nós estendemos (extends) na nossa classe WeatherServiceImpl para escrever a lógica real.
  • Para o Cliente, ele gera um BlockingStub (e outros), que age como um "representante" do servidor. O cliente apenas chama o método no Stub localmente, e esse Stub converte o objeto em bytes e lida com a rede.

---

🔄 Fluxo da Requisição: De HTTP para gRPC

1. Chamada do Usuário: O usuário envia uma requisição HTTP (ex: um POST via Postman para /cidade enviando os dados em formato JSON no Body).
2. Controller REST (Tomcat): O Spring Web intercepta a chamada HTTP no WeatherController. Ele converte o JSON da requisição em um objeto Java (CidadeDto).
3. Mapeamento para Protobuf: O Controller pega os dados do DTO e usa o padrão Builder gerado pelo Protobuf para criar um objeto CidadeRequest do gRPC.
4. O Stub entra em ação: O Controller chama o método cadastrarCidade(req) diretamente no stub (que foi injetado pelo Spring Boot via @GrpcClient).
5. Transporte gRPC (Netty): O Stub serializa o objeto Java para um array de bytes binário (Protocol Buffers) e envia esses bytes pela rede via HTTP/2 diretamente para o servidor gRPC (porta 9090).
6. Processamento no Servidor: O servidor gRPC recebe os bytes, os desserializa de volta para o objeto Java CidadeRequest e chama o método correspondente no WeatherServiceImpl.
7. Retorno: O servidor realiza a lógica (salva no mock), cria o objeto CidadeResponse, serializa para binário e devolve. O Stub no cliente recebe, desserializa e o Controller REST transforma isso novamente em JSON/Texto para a resposta HTTP do usuário.

---

📸 Telas do Sistema (Postman)

Abaixo estão as capturas de tela demonstrando o funcionamento de cada endpoint do sistema via Postman:

1. Cadastrando uma Cidade (POST /cidade)

Aqui demonstramos o cadastro de uma nova cidade no sistema, enviando um payload JSON no Body da requisição ({"nome": "Urutaí"}).

Recebemos status 200 OK, e mensagem de Cidade cadastrada!

2. Listando Cidades (GET /cidades)

Retorna a lista de todas as cidades que foram cadastradas no mock.

Recebemos status 200 OK, com a lista das cidades cadastradas [ "Urutaí", "Ipameri", "Goiania" ]

3. Obtendo Temperatura Atual (GET /temperatura)

Abaixo, consultamos a temperatura atual para as cidades cadastradas:

Temperatura em Ipameri:

---

Temperatura em Urutaí:

4. Previsão para os próximos 5 dias (GET /previsao)

Essas requisições retornam um mapa com a previsão do tempo para os próximos dias de uma cidade específica.

Previsão para Ipameri:

---

Previsão para Urutaí:

5. Estatísticas Climáticas (GET /estatisticas)

Por fim, os endpoints que retornam a média, mínima e máxima calculadas a partir das previsões.

Estatísticas de Ipameri:

---

Estatísticas de Urutaí: