¶ [Gov.Doc-API] Implementar middleware personalizado.
| Data de elaboração | 13/01/2023 |
| Responsável pelo estudo | Nara Carolina Galvão Feitosa, Raissa de Sousa Stodulski, Taillon Miguel Gonçalves, Ádelle Camarão Monteiro |
| Equipe do estudo | Tambakiss |
| Alvo | Gov.Doc API |
| Origem | Implementação, para facilitar novas integrações pois estará padronizando os retornos esperados dos endpoints, facilitando o entendimento e tratamento dos mesmos. |
| Objetivo | Com o middleware personalizado, facilitar novas integrações pois estará padronizando e simplificando os retornos esperados (tanto bem sucedidos quanto de validações e/ou erros). |
| Documentação correlata (opcional) | |
| Observações |
¶ A. Introdução
Para facilitar novas integrações com o Gov.Doc-API, propõem-se implementar middleware personalizado na mesma, pois é um padrão utilizado em todo o mundo nas aplicações independentemente das tecnologias utilizadas. Assim sendo, objetivo desse estudo é analisar as possibilidades de implementação, identificar as possíveis alterações e levantar as demandas necessárias.
¶ 1. O que é middleware
«[É o componente que] podemos usar para interceptar a solicitação, e assim, modificá-la enquanto ela passa pelo sistema. Os componentes de middleware, organizados em uma cadeia, formam o pipeline de solicitação. Esses componentes são escritos (ou registrados) no método “Configure” da classe “StartUp”. Neste caso, existem basicamente dois tipos de componentes de middleware. Componentes de middleware padrão (integrados) e personalizados.» (Jesus, Daniel)
«Em termos práticos, middleware seria um trecho de código que pode ser executado no fluxo de execução da aplicação. [São] organizados em um pipeline e são executados conforme uma solicitação é recebida e uma resposta enviada. A imagem abaixo ilustra este pipeline:» (Nascimento, Wladimilson)
![[gov.doc-api]_implementar_middleware_personalizado.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado.png)
É possível definir middleware de diversas funcionalidades, por exemplo, no trecho de código abaixo, temos oito middlewares:
| 1. Exception/error handling | 2. HTTP Strict Transport Security Protocol | 3. HTTPS redirection | 4. Static file server |
| 5. Cookie policy enforcement | 6. Authentication | 7. Session | 8.MVC |
¶ 2. Exemplos de implementação
Se é uma API que possui várias integrações ou se tem grande impacto nos sistemas que integram com ela, é de grande valia implementar o versionamento. O mesmo, permite que ao longo das alterações que a API sofre, você possa gradualmente descontinuando funcionalidades e permitindo que novas implementações não impactem integrações existentes com a API. O melhor momento para implementação é na criação da API.
| Descrição | Código |
| 1. Configura na Startup | ![[gov.doc-api]_implementar_middleware_personalizado2.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado2.png) |
| 2. Criando a classe Middleware | ![[gov.doc-api]_implementar_middleware_personalizado3.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado3.png) |
| 3. A chamada pode ser usando .UseMiddleware | ![[gov.doc-api]_implementar_middleware_personalizado4.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado4.png) |
| 4. Mas o recomendado é criar um método de extensão e utiliza-lo no Configure() | ![[gov.doc-api]_implementar_middleware_personalizado5.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado5.png)
|
| Cria endpoint configurado para gerar exceção. | ![[gov.doc-api]_implementar_middleware_personalizado7.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado7.png) |
| Cria um DTO para estruturar o retorno de exceções. | ![[gov.doc-api]_implementar_middleware_personalizado8.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado8.png)
|
| Cria a classe middleware para tratar/padronizar o tratamento/retorno de erros. | ![[gov.doc-api]_implementar_middleware_personalizado10.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado10.png) |
| Configura na Startup o middleware criado. | ![[gov.doc-api]_implementar_middleware_personalizado11.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado11.png) |
![[gov.doc-api]_implementar_middleware_personalizado6.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado6.png)
![[gov.doc-api]_implementar_middleware_personalizado9.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc-api%5D_implementar_middleware_personalizado9.png)
¶ 3. Alterações necessárias
A sugestão é utilizar o middleware para tratar e padronizar os erros.
Status HTTP: 500 - Internal Server Error
Retorno:
Mas seria necessário fazer um protótipo para tentar padronizar o retorno de validações.
Status HTTP: 400 - Bad Request
Retorno:
E padronizar o retorno de bem-sucedido tanto de criação (201 - Created) quanto qualquer outro (200 - OK).
Status HTTP: 200 - OK
Retorno: { mensagem: «mensagem de bem-sucedido» }
ou { mensagem: «mensagem de bem-sucedido», objeto: { } }
Status HTTP: 201 - Created
Retorno: { mensagem: «mensagem de bem-sucedido», objeto: { } }
Uma ideia seria criar um BaseService onde elaboraremos uma estrutura que permita adicionar mensagens de validação e antes de realizar a ação, verifica se caiu em alguma validação e retorna o BadRequest. Ou pode criar uma classe de exceção para BadRequest onde quando for gerado essa BadRequestException, usa um middleware para padronizar/formatar o retorno.
Para a questão do bem-sucedido, pode apenas ser criado um dto { mensagem: string, objeto: object } que o Service retornará para controller que retornará return Ok(dto);
¶ B. Conclusão
Concluímos que essas são alterações necessárias para implementar o middleware personalizado e que irá agregar grande valor para as APIs que aplicarem. Facilitará novas integrações, tanto no tratamento quanto no entendimento dos retornos.
¶ Fontes
- Aprendendo os componentes de Middleware do Asp .Net Core -Parte, Daniel Jesus.
- Compreendendo os middlewares no ASP.NET Core", Wladimilson M. Nascimento.
- Criando um middleware customizado para ASP.NET Core", Wladimilson M. Nascimento.
- Padrões de Web API – Parte 02: Middleware, Kenerry Serain.