Contratos públicos, cómo garantizar su coherencia.

• ¿Su sistema consta de muchos servicios interconectados?
• ¿Todavía actualiza manualmente el código de servicio al cambiar la API pública?
• los cambios en sus servicios a menudo socavan el trabajo de otros, y otros desarrolladores lo odian por esto?

Condiciones

Sobre qué es el artículo

¿Cómo se ve el problema?

Cómo resolver este problema

El equipo de servicio del proveedor arreglará todo

Actualice el código de su servicio al equipo de consumidores.

Piense qué hacer para evitar que aparezca el problema

Cómo prevenir la manifestación de un problema.

1. en la etapa de diseño, defina declarativamente contratos;
2. durante la implementación, generamos código de servidor y cliente bajo contratos;
3. Al realizar las pruebas, verificamos los contratos e intentamos tener en cuenta las necesidades del cliente (CDC).

Cómo se ve el problema con nosotros

Del problema a la tarea

• lado del servidor: los controladores ya están escritos;
• el navegador es un cliente del servicio;
• Los servicios se comunican a través de HTTP.
• La generación debe estar sintonizada. Por ejemplo, para admitir JWT.

Preguntas

• qué herramienta elegir;
• cómo obtener contratos;
• dónde colocar los contratos;
• dónde colocar el código del cliente;
• en que punto hacer la generacion.

Qué herramienta elegir

Herramientas

Herramientas para trabajar con OpenAPI

Dónde concertar contratos. Cómo acceder a servicios a contratos

• La carpeta del proyecto del servicio del proveedor es la opción más fácil. Si necesita ejecutar el enfoque, elíjalo.
• Una carpeta compartida es una opción válida si los proyectos deseados están en el mismo repositorio. A la larga, será difícil mantener la integridad de los contratos en la carpeta. Esto puede requerir una herramienta adicional para dar cuenta de diferentes versiones de contratos, etc.
• repositorio separado para especificaciones: si los proyectos están en repositorios diferentes, entonces los contratos deben colocarse en un lugar público. Las desventajas son las mismas que la carpeta compartida.
• a través del servicio API (swagger.ui, swaggerhub), un servicio separado que se ocupa de la gestión de especificaciones.

¿En qué punto generas

Dónde colocar el código del cliente

• el código del cliente está cerca de su servicio y está constantemente actualizado;
• los consumidores pueden usar el enlace al proyecto dentro de un repositorio.

• no funcionará si necesita generar un cliente en otra parte del sistema, por ejemplo, un repositorio diferente. Se resuelve utilizando al menos una carpeta compartida para contratos;
• Los consumidores deben estar escritos en el mismo idioma. Si necesita un cliente en otro idioma, debe usar OpenApiTools.

Sujetamos NSwag

Atributos del controlador

[Microsoft.AspNetCore.Mvc.Routing.Route("[controller]")]  //  url
[Microsoft.AspNetCore.Mvc.ApiController] //     
public class DescriptionController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("GetDescription")] //    
[Microsoft.AspNetCore.Mvc.ProducesResponseType(typeof(ConversionDescription), 200)] //    200  
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)] //    401
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)] //    403
[Microsoft.AspNetCore.Mvc.HttpGet("{pluginName}/{binaryDataId}")] //  url
public ActionResult<ConversionDescription> GetDescription(string pluginName, Guid binaryDataId) { 
 // ... 
}

[Microsoft.AspNetCore.Mvc.Route("[controller]")]
[Microsoft.AspNetCore.Mvc.ApiController]
public class FileController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("SaveFile")]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)]
[Microsoft.AspNetCore.Mvc.HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[OurNamespace.FileUploadOperation] //  
public async Task SaveFile() { // ... }

Procesador para generar especificaciones para operaciones de archivo

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

Configuración de NSwag para la generación de especificaciones y código

• tiempo de ejecución: especifica el tiempo de ejecución de .net. Por ejemplo, NetCore22;
• documentGenerator: describe cómo generar una especificación;
• codeGenerators: define cómo generar código de acuerdo con la especificación.

Generamos la especificación y el código del cliente al ensamblar el proyecto del proveedor de servicios.

1. Creamos un proyecto WebApi para el cliente.
2. Escribimos una configuración para Nswag CLI - Nswag.json (descrito en la sección anterior).
3. Escribimos un PostBuild Target dentro del proyecto del proveedor de servicios csproj.

• $ (NSwagExe_Core22) ejecutar nswag.json - ejecuta la utilidad NSwag bajo .bet runtine netCore 2.2 con la configuración nswag.json

1. NSwag genera una especificación a partir de un conjunto de servicios de proveedor.
2. NSwag genera código de cliente según la especificación.

Cómo agregar soporte para JWT

protected Task<HttpRequestMessage> CreateHttpRequestMessageAsync(CancellationToken cancellationToken) {
      var message = new HttpRequestMessage();

      if (!string.IsNullOrWhiteSpace(this.AuthorizationToken)) {
        message.Headers.Authorization =
          new System.Net.Http.Headers.AuthenticationHeaderValue(BearerScheme, this.AuthorizationToken);
      }

      return Task.FromResult(message);
    }

Conclusión

• la especificación es detallada;
• , ;
• ;
• .

• , URL, HTTP ..;
• OpenAPI;
• ;
• ;
• HTTP/2.

Versiones de contratos públicos

¿Por qué versionar contratos públicos?

Opciones de solucion

Sin versionar contratos públicos

Usar versiones de contratos públicos

• qué herramienta usar;
• cuándo presentar una nueva versión;
• cuánto tiempo mantener versiones antiguas.

Qué herramienta usar

Cuando presentar una nueva versión

• para OpenAPI hay una herramienta Azure opeanapi-diff para verificar la compatibilidad entre 2 especificaciones github.com/Azure/openapi-diff;
• no se encontró ninguna herramienta automática para gRPC, solo hay políticas de versiones;
• general github.com/grpc/grpc/blob/master/doc/versioning.md;
• en .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

Cuánto tiempo mantener versiones

• notifique a los clientes que la versión anterior ya no será compatible. En este caso, podemos perder los ingresos del cliente;
• admite todo el conjunto de versiones. El costo del soporte de software está creciendo;
• Para responder a esta pregunta, debe preguntarle a la empresa: ¿los ingresos de los antiguos clientes exceden el costo de soportar versiones anteriores de software? ¿Podría ser más rentable pedirles a los clientes que actualicen?

Conclusión

Prueba de contratos y CDC

Contratos impulsados ​​por el consumidor (CDC)

1. El consumidor describe el contrato.
2. El proveedor implementa este contrato en casa.
3. Este contrato se utiliza en el proceso de CI en el consumidor y el proveedor. Si se viola el proceso, alguien ha dejado de cumplir con el contrato.

Pacto

1. El consumidor escribe pruebas usando la biblioteca PACT.
2. Estas pruebas se convierten en un artefacto - archivo de pacto. Contiene información sobre los contratos.
3. El proveedor y el consumidor usan el archivo del pacto para ejecutar las pruebas.

Enlaces útiles sobre Pact

• Pact broker: solución de gestión de archivos de pacto docs.pact.io/pact_broker
• Pact aún no es compatible con GRPC. Lea más sobre la hoja de ruta Pact pact.canny.io .
• Más información sobre el PACT docs.pact.io .
• ¿Por qué debería usar PACT docs.pact.io/faq/convinceme?

Cómo se pueden incrustar CDC en CI

• desplegando usted mismo Pact + Pact broker;
• compre una solución SaaS Pact Flow preparada.

Conclusión