En el mundo dinámico de los microservicios, cualquier cosa puede cambiar: cualquier componente se puede reescribir en un lenguaje diferente, utilizando marcos y arquitecturas diferentes. Sólo los contratos deben permanecer sin cambios para que se pueda interactuar con el microservicio desde el exterior de forma permanente, independientemente de las metamorfosis internas. Y hoy hablaremos sobre nuestro problema de elegir un formato para describir contratos y compartir los artefactos que encontramos.
Publicación preparada и
Microservicios. Al desarrollar Acronis Cyber Cloud, nos dimos cuenta de que no podíamos escapar de ellos. Y diseñar un microservicio es imposible sin formalizar el contrato, que representa la interfaz del microservicio.
Pero cuando un producto contiene más de un componente y el desarrollo de contratos se convierte en una actividad habitual, no se puede evitar empezar a pensar en la optimización del proceso. Resulta obvio que la interfaz (contrato) y la implementación (microservicio) deben coincidir entre sí, que diferentes componentes deben hacer las mismas cosas de la misma manera y que sin una toma de decisiones centralizada de todas estas decisiones, cada equipo se verá obligado a dedica tiempo una y otra vez para conseguirlos.
Diagrama de microservicios de Amazon de Werner Vogelis, director tecnológico de Amazon
¿Cuál es el dilema? De facto, hay dos formas de interactuar con los microservicios: HTTP Rest y gRPC de Google. Como no queremos quedar atrapados en la tecnología de Google, elegimos HTTP Rest. Las anotaciones de contratos HTTP REST se describen con mayor frecuencia en uno de dos formatos: RAML y OAS, anteriormente conocido como Swagger, por lo que cada equipo de desarrollo se enfrenta a la necesidad de elegir uno de los estándares. Pero resulta que tomar esta decisión puede resultar muy difícil.
¿Por qué se necesitan anotaciones?
La anotación es necesaria para que un usuario externo pueda descubrir fácilmente qué se puede hacer con su servicio a través de su interfaz HTTP. Es decir, en un nivel básico, la anotación debe contener al menos una lista de recursos disponibles, sus métodos HTTP, cuerpos de solicitud, una lista de parámetros, una indicación de los encabezados requeridos y admitidos, así como códigos de retorno y formatos de respuesta. Un elemento extremadamente importante de la anotación del contrato es su descripción verbal (“¿qué pasará si agrega este parámetro de consulta a la solicitud?”, “¿En qué caso se devolverá el código 400?”)
Sin embargo, cuando se trata de desarrollar una gran cantidad de microservicios, conviene extraer valor adicional de las anotaciones escritas. Por ejemplo, basándose en RAML/Swagger, puede generar código de cliente y de servidor en una gran cantidad de lenguajes de programación. También puede recibir automáticamente documentación para el microservicio y cargarla en su portal de desarrollador :).
Ejemplo de descripción de contrato estructurado
Menos común es la práctica de probar microservicios basándose en descripciones de contratos. Si ha escrito tanto una anotación como un componente, puede crear una prueba automática que verifique la idoneidad del servicio con varios tipos de datos de entrada. ¿El servicio devuelve un código de respuesta que no se describe en la anotación? ¿Podrá procesar correctamente datos obviamente incorrectos?
Además, la implementación de alta calidad no solo de los contratos en sí, sino también de las herramientas para visualizar anotaciones permite simplificar el trabajo con el microservicio. Es decir, si el arquitecto describió cualitativamente el contrato, en base a él, los diseñadores y desarrolladores implementarán el servicio en otros productos sin costos de tiempo adicionales.
Para habilitar herramientas adicionales, tanto RAML como OAS tienen la capacidad de agregar metadatos no previstos por el estándar ().
En general, el margen para la creatividad en el uso de contratos de microservicios es enorme... al menos en teoría.
Comparación de un erizo con una serpiente.
Actualmente, el área de desarrollo prioritaria en Acronis es el desarrollo de Acronis Cyber Platform. Acronis Cyber Platform son nuevos puntos de integración de servicios de terceros con Acronis Cyber Cloud y la parte del agente. Aunque estábamos contentos con nuestras API internas descritas en RAML, la necesidad de publicar la API nuevamente planteó la cuestión de elegir: ¿qué estándar de anotación es mejor usar para nuestro trabajo?
Al principio parecía que había dos soluciones: los desarrollos más comunes eran RAML y Swagger (u OAS). Pero, de hecho, resultó que al menos no hay 2 alternativas, sino 3 o más.
Por un lado está RAML, un lenguaje potente y eficaz. Implementa bien la jerarquía y la herencia, por lo que este formato es más adecuado para grandes empresas que necesitan muchas descripciones, es decir, no un producto, sino muchos microservicios que tienen partes comunes en los contratos: esquemas de autenticación, los mismos tipos de datos, cuerpos de error. .
Pero el desarrollador de RAML, Mulesoft, se ha unido al consorcio Open API, que está desarrollando . Por tanto, RAML suspendió su desarrollo. Para imaginar el formato del evento, imaginemos que los mantenedores de los principales componentes de Linux se fueron a trabajar a Microsoft. Esta situación crea los requisitos previos para el uso de Swagger, que se está desarrollando dinámicamente y en la última versión, la tercera, prácticamente alcanza a RAML en términos de flexibilidad y funcionalidad.
Si no fuera por una cosa pero ...
Resulta que no todas las utilidades de código abierto se han actualizado a OAS 3.0. Para los microservicios en Go, lo más crítico será la falta de adaptación para la última versión del estándar. Sin embargo, la diferencia entre Swagger 2 y Swagger 3 es . Por ejemplo, en la tercera versión los desarrolladores:
- descripción mejorada de los esquemas de autenticación
- Soporte de esquema JSON
- Se actualizó la capacidad de agregar ejemplos.
La situación es divertida: al elegir un estándar, es necesario considerar RAML, Swagger 2 y Swagger 3 como alternativas separadas. Sin embargo, sólo Swagger 2 tiene un buen soporte para herramientas OpenSource. RAML es muy flexible... y complejo, y Swagger 3 no cuenta con el apoyo adecuado de la comunidad, por lo que tendrás que usar herramientas propietarias o soluciones comerciales, que tienden a ser bastante costosas.
Además, si hay muchas características interesantes en Swagger, como un portal listo para usar , en el que puede cargar una anotación y obtener su visualización con una descripción detallada, enlaces y conexiones, entonces para el RAML más fundamental y menos amigable no existe tal oportunidad. Sí, puedes buscar algo entre los proyectos en GitHub, encontrar un análogo allí e implementarlo tú mismo. Sin embargo, en cualquier caso, alguien tendrá que mantener el portal, lo que no es tan conveniente para el uso básico o las necesidades de prueba. Además, la arrogancia es menos "sin principios" o más liberal: puede generarse a partir de comentarios en el código, lo que, por supuesto, va en contra del primer principio de la API y no es compatible con ninguna de las utilidades RAML.
Hubo un tiempo en que empezamos a trabajar con RAML como un lenguaje más flexible y, como resultado, teníamos que hacer muchas cosas nosotros mismos. Por ejemplo, uno de los proyectos utiliza la utilidad. en pruebas unitarias, que solo admite RAML 0.8. Así que tuvimos que agregar muletas para que la utilidad pudiera "comerse" la versión 1.0 de RAML.
¿Necesitas elegir?
Habiendo trabajado para completar el ecosistema de soluciones para RAML, llegamos a la conclusión de que necesitamos convertir RAML en Swagger 2 y realizar en él toda la automatización, verificación, pruebas y posterior optimización. Esta es una buena manera de aprovechar tanto la flexibilidad de RAML como el soporte de herramientas comunitarias de Swagger.
Para resolver este problema, existen dos herramientas OpenSource que deberían proporcionar conversión de contratos:
- es una utilidad actualmente no compatible. Mientras trabajábamos con él, descubrimos que tiene una serie de problemas con RAML complejas que están "repartidas" en una gran cantidad de archivos. Este programa está escrito en JavaScript y realiza un recorrido recursivo de un árbol de sintaxis. Debido a la escritura dinámica, resulta difícil entender este código, por lo que decidimos no perder el tiempo escribiendo parches para una utilidad moribunda.
- - una herramienta de la misma empresa que afirma estar lista para convertir cualquier cosa y en cualquier dirección. Hasta la fecha, se ha anunciado soporte para RAML 0.8, RAML 1.0 y Swagger 2.0. Sin embargo, en el momento de nuestra investigación, la utilidad todavía era húmedo e inutilizable. Los desarrolladores crean una especie de , lo que les permitirá agregar rápidamente nuevos estándares en el futuro. Pero hasta ahora simplemente no funciona.
Y esas no son todas las dificultades que encontramos. Uno de los pasos de nuestro proceso es verificar que la RAML del repositorio sea correcta en relación con la especificación. Probamos varias utilidades. Sorprendentemente, todos insultaron nuestras anotaciones en diferentes lugares y con malas palabras completamente diferentes. Y no siempre al grano :).
Al final, nos decidimos por un proyecto ahora desactualizado, que también tiene una serie de problemas (a veces falla repentinamente, tiene problemas al trabajar con expresiones regulares). Por tanto, no encontramos la manera de solucionar los problemas de validación y conversión basándonos en herramientas gratuitas, y decidimos utilizar una utilidad comercial. En el futuro, a medida que las herramientas OpenSource maduren, este problema puede resultar más fácil de resolver. Mientras tanto, los costes de mano de obra y tiempo para el “acabado” nos parecían más importantes que el coste de un servicio comercial.
Conclusión
Después de todo esto, queríamos compartir nuestra experiencia y señalar que antes de elegir una herramienta para describir contratos, debes definir claramente qué quieres de ella y qué presupuesto estás dispuesto a invertir. Si nos olvidamos del OpenSource, ya existen una gran cantidad de servicios y productos que te ayudarán a comprobar, convertir y validar. Pero son caros y, a veces, muy caros. Para una gran empresa, estos costes son tolerables, pero para una startup pueden convertirse en una gran carga.
Determine el conjunto de herramientas que utilizará más adelante. Por ejemplo, si solo necesita mostrar un contrato, será más fácil usar Swagger 2, que tiene una hermosa API, porque en RAML tendrá que crear y mantener el servicio usted mismo.
Cuantas más tareas tenga, mayor será la necesidad de herramientas, y son diferentes para diferentes plataformas, y es mejor familiarizarse inmediatamente con las versiones disponibles para poder elegir lo que minimice sus costos en el futuro.
Pero vale la pena reconocer que todos los ecosistemas que existen hoy son imperfectos. Por tanto, si hay fans en la empresa a los que les gusta trabajar en RAML porque “permite expresar pensamientos de forma más flexible”, o, por el contrario, prefieren Swagger porque “es más claro”, lo mejor es dejarles trabajar. en lo que están Están acostumbrados y lo quieren, porque las herramientas de cualquiera de los formatos requieren modificación con un archivo.
En cuanto a nuestra experiencia, en las siguientes publicaciones hablaremos sobre qué comprobaciones estáticas y dinámicas realizamos en función de nuestra arquitectura RAML-Swagger, así como qué documentación generamos a partir de los contratos y cómo funciona todo.
Solo los usuarios registrados pueden participar en la encuesta. por favor
¿Qué idioma utiliza para anotar contratos de microservicios?
-
RAML 0.8
-
RAML 1.0
-
arrogancia 2
-
OEA3 (también conocido como)
-
Planos
-
Otro
-
No usando
100 usuarios votaron. 24 usuarios se abstuvieron.
Fuente: habr.com