¶ Estudo sobre integração entre Portal do Servidor e Consignação.
| Data de elaboração | 11/06/2025 |
| Responsável pelo estudo | André Henrique Cortez |
| Equipe do estudo | Caveiras |
| Alvo | Portal do Servidor e Consignação |
| Origem | Análise técnica para melhoria de integração e robustez na comunicação com a API do consignação |
| Objetivo | Avaliar tecnicamente a integração com API do consignação e identificar falhas potenciais e propor melhorias com foco em segurança, manutenibilidade, testabilidade e modernização da arquitetura. |
¶ 1. Objetivo
O objetivo deste estudo técnico é realizar uma análise aprofundada da implementação do consumo da api do consignação, responsável por realizar a comunicação com o sistema de consignações 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.
¶ 2. Introdução
A integração com a api de consignação é utilizada no service de consignação para retonar a controller de consignação se o servidor possui consignações para contratar. A classe ApiConsignacao é responsável por integrar a aplicação ao sistema externo de consignações, realizando chamadas HTTP para consulta de dados de servidores e suas averbações. Com o tempo, foram identificados pontos que comprometem a segurança, a clareza e a facilidade de manutenção da implementação atual.
Este estudo tem como objetivo revisar a estrutura da classe, apontar melhorias técnicas e propor ações práticas para torná-la mais segura, robusta e alinhada com padrões modernos de desenvolvimento. Entre as melhorias sugeridas, está a adoção do Refit como alternativa ao RestSharp, centralização de headers, tratamento adequado de erros e maior cobertura de testes.
¶ 3. Desenvolvimento
¶ 3.1. Pontos Positivos
- Uso adequado de injeção de dependência.
- Separação entre autenticação e chamadas de serviço.
- Uso de DTOs para tipagem segura.
- Classe bem organizada em termos de coesão funcional.
¶ 3.2. Falhas Detectadas
| Problema | Impacto | Severidade |
|---|---|---|
| Acesso inseguro com credenciais via URL | Risco de vazamento de senhas | Alta |
Acesso a índice [0] sem validação |
Pode gerar IndexOutOfRangeException |
Alta |
| Falta de validação de resposta em chamadas críticas | Pode causar erro silencioso | Alta |
Uso de Console.WriteLine |
Inadequado para produção | Média |
| Duplicação de lógica para headers | Código redundante e difícil de manter | Média |
Ausência de JsonSerializerOptions |
Risco de falha na deserialização | Média |
| Strings mágicas (rotas e headers) | Reduz legibilidade e manutenibilidade | Média |
| Falta de testes unitários | Código pouco confiável em mudanças futuras | Alta |
| Uso de RestSharp acoplado | Dificulta testes e reaproveitamento | Média |
| Arquitetura desnecessaria para consumo da api | Deixa o código mais complexo | Baixa |
¶ 3.3. Plano de ação
| Código | Ação | Descrição |
|---|---|---|
| 1 | Refatorar autenticação | Enviar login e senha no corpo da requisição (x-www-form-urlencoded) em vez de parâmetros na URL. |
| 2 | Validar lista de retorno | Substituir funcionario[0] por FirstOrDefault() e verificar se a lista está vazia antes de acessar. |
| 3 | Verificar resposta da autenticação | Validar IsSuccessful, StatusCode e Content da resposta, além de tratar possíveis exceções. |
| 4 | Implementar logging estruturado | Substituir Console.WriteLine por ILogger<ApiConsignacao> para registrar logs de erro e operação. |
| 5 | Centralizar headers | Unificar a lógica de construção de headers comuns e de autenticação para evitar duplicação. |
| 6 | Configurar deserialização | Utilizar JsonSerializerOptions com PropertyNameCaseInsensitive = true nas deserializações. |
| 7 | Substituir strings mágicas | Criar constantes nomeadas para rotas e headers, melhorando a legibilidade e manutenção do código. |
| 8 | Criar testes unitários | Implementar testes com mocks para autenticação e chamadas HTTP principais, garantindo cobertura. |
| 9 | Avaliar uso do Refit | Analisar a viabilidade técnica de substituir RestSharp por Refit para consumo de APIs REST. |
| 10 | Implementar POC com Refit | Criar uma prova de conceito com a interface IApiConsignacao usando Refit e rotas declarativas. |
| 11 | Remover repositorio de consignação e centralizar tudo no service | Centralizar métodos da consignação no service. |
¶ 3.4. Refit - Justificativa e Benéficios
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.
¶ 4. Conclusão
A integração com a Api de consignação está funcional, mas a análise evidencia a importância de revisar periodicamente componentes críticos que realizam integrações com serviços externos. Embora a implementação atual atenda aos requisitos funcionais básicos, foram identificadas diversas oportunidades de melhoria que impactam diretamente a segurança, a confiabilidade e a manutenibilidade do código.
As ações propostas neste plano visam modernizar a arquitetura do serviço, reduzir riscos operacionais, padronizar práticas de desenvolvimento e preparar o código para crescer de forma sustentável. A substituição do RestSharp por Refit, por exemplo, representa uma mudança estratégica relevante, pois promove uma abordagem mais enxuta, declarativa e alinhada com o uso de interfaces e injeção de dependência — fatores essenciais em projetos que exigem alta testabilidade e coesão.
Além disso, o reforço no tratamento de erros, a centralização da lógica de headers e a adoção de logs estruturados tornam o sistema mais resiliente e facilitam a identificação de falhas em ambiente produtivo. A inclusão de testes automatizados também contribui significativamente para a confiabilidade da aplicação, especialmente em cenários de mudança contínua ou integração com múltiplos serviços.
Ao aplicar este plano de ação, a equipe técnica não apenas corrige fragilidades existentes, mas também estabelece uma base sólida para evoluções futuras, com menor acoplamento, maior previsibilidade e aderência a boas práticas amplamente reconhecidas no desenvolvimento de APIs em .NET.