| Data de elaboração | 30/06/2025 |
| Responsável pelo estudo | André Henrique Cortez |
| Equipe do estudo | Caveiras |
| Alvo | Portal do Servidor e assentamentos |
| Origem | Análise técnica para melhoria de integração e robustez na comunicação com a API de assentamentos |
| Objetivo | Avaliar tecnicamente a integração com API de assentamentos e identificar falhas potenciais e propor melhorias com foco em segurança, manutenibilidade, testabilidade e modernização da arquitetura. |
O objetivo deste estudo técnico é realizar uma análise aprofundada da implementação do consumo da api de assentamentos, responsável por buscar os assentamentos dos servidores através de requisições HTTP. A proposta visa identificar pontos críticos e falhas potenciais que possam comprometer a segurança, estabilidade e manutenibilidade do sistema, além de propor melhorias técnicas que aumentem a eficiência, a legibilidade do código e a facilidade de testes automatizados.
As classes ApiAssentamentoEEstado, AssentamentoRepositorio e AssentamentoAppService compõem o fluxo de consulta de assentamentos vinculados a um colaborador por meio do CPF, consumindo uma API externa e transformando os dados para uso na aplicação.
Embora a estrutura geral esteja funcional e organizada por camadas, foram identificados pontos de melhoria relacionados à segurança, validação de dados, clareza do código e oportunidades de modernização da arquitetura de comunicação com APIs REST. Este estudo técnico propõe melhorias práticas para elevar a qualidade do código, aumentar a previsibilidade e torná-lo mais fácil de testar e manter.
Boa separação por camadas (AppService, Repositório, Serviço externo)
Uso consistente de interfaces para abstração e injeção de dependência
Injeção de dependências via construtor (boas práticas de DI)
Código legível e de fácil manutenção
Uso eficiente de Task.WhenAll para chamadas paralelas
Utilização de DTOs e ViewModels para garantir segurança de tipo
| Falha | Impacto | Severidade |
|---|---|---|
| Ausência de validação da resposta da API externa | Pode causar exceções ou dados incorretos sendo processados pela aplicação | Alta |
| Falta de tratamento de exceções nas chamadas HTTP | Erros de comunicação podem passar despercebidos, dificultando suporte e diagnóstico | Alta |
| Ausência de logging estruturado | Dificulta o monitoramento e rastreamento de falhas em produção | Média |
Deserialização sem configuração (JsonSerializerOptions) |
Pode causar falhas sutis se a estrutura da resposta mudar | Média |
| Uso de strings mágicas para rotas e parâmetros | Aumenta o risco de erro humano e dificulta a manutenção do código | Média |
| Falta de testes automatizados | Reduz a confiabilidade das integrações e aumenta o risco de regressões | Alta |
| Nenhuma validação prévia do CPF | Pode gerar chamadas desnecessárias à API e mascarar erros de entrada | Média |
Lógica paralela embutida no AppService (Task.WhenAll) |
Reduz a legibilidade e dificulta testes unitários | Baixa |
Acoplamento ao consumo manual de API (IHttpHelperServico) |
Aumenta o esforço para manutenção e testes, reduz flexibilidade | Média |
| Falta de controle de chamadas concorrentes ou cache | Pode causar sobrecarga desnecessária em chamadas paralelas por matrícula | Baixa a Média (dependendo do volume de dados) |
| Código | Ação | Descrição |
|---|---|---|
| 1 | Validar retorno da API | Verificar se a deserialização do conteúdo retornado é válida e se a lista não está nula antes de retornar. |
| 2 | Adicionar tratamento de exceções | Incluir try-catch na chamada HTTP para capturar falhas de comunicação e retornar logs apropriados. |
| 3 | Injetar e utilizar ILogger | Substituir possíveis falhas silenciosas por logs estruturados usando ILogger<ApiAssentamentoEEstado>. |
| 4 | Usar JsonSerializerOptions | Adotar PropertyNameCaseInsensitive = true para garantir deserialização correta mesmo com variação de nomes. |
| 5 | Remover dependência de strings mágicas | Criar constantes ou enums para representar rotas e parâmetros fixos da URL. |
| 6 | Avaliar e migrar para Refit | Criar uma interface IAssentamentoApi com rotas declaradas e injetá-la no lugar de chamadas manuais. |
| 7 | Criar testes unitários | Garantir cobertura para os fluxos de integração com mocks de API e validação dos dados retornados. |
| 8 | Aplicar validação de CPF | Verificar se o CPF recebido como parâmetro é válido antes de chamar os serviços (evitar chamadas desnecessárias). |
| 9 | Melhorar a legibilidade do AppService | Reduzir a complexidade do Select em Task.WhenAll extraindo a lógica para um método auxiliar privado. |
| 10 | Avaliar cache ou paralelismo controlado | Dependendo do volume de chamadas simultâneas no Task.WhenAll, avaliar uso de throttling ou cache por matrícula. |
Adoção de Refit, uma biblioteca que transforma interfaces REST em implementações automáticas:
Benefícios:
Redução de código repetitivo: elimina a necessidade de construir rotas, headers e serialização manualmente.
Integração com DI: facilita a injeção e o teste de serviços REST.
Melhor organização: cada API fica definida como interface clara, tipada e autodocumentada.
Facilidade de teste: interfaces são naturalmente mockáveis.
As camadas responsáveis pela busca de assentamentos estão estruturadas de forma coerente, com responsabilidades bem definidas entre API externa, repositório e aplicação. No entanto, pequenos pontos de fragilidade, como ausência de validação, tratamento de erro e uso de string literals, podem comprometer a estabilidade do sistema em ambientes de produção.
A adoção de práticas modernas, como o uso do ILogger, validações robustas, testes automatizados e a substituição por Refit, contribuirá para tornar o código mais seguro, limpo e sustentável a longo prazo. O uso de Refit, em especial, elimina a necessidade de manipulação manual de rotas e deserialização, permitindo um consumo de API mais claro e orientado a interfaces, com maior facilidade de teste e evolução.
Implementar o plano de ação proposto permitirá à equipe técnica obter maior previsibilidade nas integrações e melhor capacidade de diagnóstico, além de preparar o sistema para demandas maiores e mais complexas no futuro.