No mundo dinámico dos microservizos, calquera cousa pode cambiar: calquera compoñente pode reescribirse nunha linguaxe diferente, utilizando marcos e arquitecturas diferentes. Só os contratos deben permanecer inalterados para poder interactuar co microservizo desde o exterior de forma permanente, independentemente das metamorfoses internas. E hoxe falaremos do noso problema de escoller un formato para describir contratos e compartir os artefactos que atopamos.
Publicación preparada и
Microservizos. Ao desenvolver Acronis Cyber Cloud, decatámonos de que non podíamos escapar deles. E deseñar un microservizo é imposible sen formalizar o contrato, que representa a interface do microservizo.
Pero cando un produto contén máis dun compoñente e o desenvolvemento do contrato convértese nunha actividade habitual, non podes deixar de comezar a pensar na optimización do proceso. Faise obvio que a interface (contrato) e a implementación (microservizo) deben coincidir entre si, que os diferentes compoñentes deben facer as mesmas cousas do mesmo xeito, e que sen unha toma de decisións centralizada de todas estas decisións, cada equipo estará obrigado a pasar tempo unha e outra vez para conseguilos.
Diagrama de microservizos de Amazon Werner Vogelis, CTO Amazon
Cal é o dilema? De feito, hai dúas formas de interactuar cos microservizos: HTTP Rest e gRPC de Google. Non queremos quedar atrapados na pila tecnolóxica de Google, escollemos HTTP Rest. As anotacións de contratos HTTP REST descríbense con máis frecuencia nun dos dous formatos: RAML e OAS, antes coñecidos como Swagger. Polo tanto, cada equipo de desenvolvemento enfróntase á necesidade de escoller un dos estándares. Pero como se ve, facer esta elección pode ser moi difícil.
Por que son necesarias as anotacións?
A anotación é necesaria para que un usuario externo poida descubrir facilmente o que se pode facer co seu servizo a través da súa interface HTTP. É dicir, a nivel básico, a anotación debe conter polo menos unha lista de recursos dispoñibles, os seus métodos HTTP, os corpos de solicitude, unha lista de parámetros, unha indicación das cabeceiras requiridas e admitidas, así como códigos de retorno e formatos de resposta. Un elemento extremadamente importante da anotación do contrato é a súa descrición verbal ("que ocorrerá se engade este parámetro de consulta á solicitude?", "En que caso se devolverá o código 400?").
Non obstante, cando se trata de desenvolver un gran número de microservizos, quere extraer valor adicional das anotacións escritas. Por exemplo, baseado en RAML/Swagger, pode xerar código de cliente e servidor nunha gran cantidade de linguaxes de programación. Tamén pode recibir automaticamente documentación para o microservizo e cargala no seu portal de desenvolvedores :).
Exemplo de descrición dun contrato estruturado
Menos común é a práctica de probar microservizos baseados nas descricións dos contratos. Se escribiu tanto unha anotación como un compoñente, pode crear unha proba automática que verifique a adecuación do servizo con varios tipos de datos de entrada. O servizo devolve un código de resposta que non se describe na anotación? Será capaz de procesar correctamente datos obviamente incorrectos?
Ademais, a implementación de alta calidade non só dos propios contratos, senón tamén das ferramentas para visualizar anotacións permite simplificar o traballo co microservizo. É dicir, se o arquitecto describe cualitativamente o contrato, baseándose nel, os deseñadores e desenvolvedores implementarán o servizo noutros produtos sen custos de tempo adicionais.
Para habilitar ferramentas adicionais, tanto RAML como OAS teñen a capacidade de engadir metadatos non proporcionados polo estándar ().
En xeral, o alcance da creatividade no uso de contratos para microservizos é enorme... polo menos en teoría.
Comparación dun ourizo cunha serpe
Actualmente, a área de desenvolvemento prioritaria en Acronis é o desenvolvemento da plataforma cibernética Acronis. Acronis Cyber Platform é novos puntos de integración de servizos de terceiros con Acronis Cyber Cloud e a parte do axente. Aínda que estabamos satisfeitos coas nosas API internas descritas en RAML, a necesidade de publicar a API volveu plantexar a cuestión da elección: que estándar de anotación é mellor usar para o noso traballo?
Inicialmente, parecía que había dúas solucións: os desenvolvementos máis comúns eran RAML e Swagger (ou OAS). Pero de feito resultou que non hai polo menos 2 alternativas, senón 3 ou máis.
Por unha banda está RAML, unha linguaxe potente e eficiente. Implementa ben a xerarquía e a herdanza, polo que este formato é máis axeitado para grandes empresas que necesitan moitas descricións, é dicir, non un produto, senón moitos microservizos que teñen partes comúns de contratos, esquemas de autenticación, os mesmos tipos de datos, corpos de erro. .
Pero o desenvolvedor de RAML, Mulesoft, uniuse ao consorcio Open API, que está a desenvolver . Polo tanto, RAML suspendeu o seu desenvolvemento. Para imaxinar o formato do evento, imaxina que os mantedores dos principais compoñentes de Linux saíron a traballar para Microsoft. Esta situación crea os requisitos previos para o uso de Swagger, que se está a desenvolver de forma dinámica e na última -terceira versión- practicamente alcanza RAML en canto a flexibilidade e funcionalidade.
Se non por unha cousa...
Como resultado, non todas as utilidades de código aberto se actualizaron a OAS 3.0. Para os microservizos en Go, o máis crítico será a falta de adaptación para a última versión do estándar. Non obstante, a diferenza entre Swagger 2 e Swagger 3 é . Por exemplo, na terceira versión os desenvolvedores:
- descrición mellorada dos esquemas de autenticación
- Soporte de esquemas JSON
- mellorou a capacidade de engadir exemplos
A situación é divertida: ao elixir un estándar, cómpre considerar RAML, Swagger 2 e Swagger 3 como alternativas separadas. Non obstante, só Swagger 2 ten un bo soporte para ferramentas OpenSource. RAML é moi flexible... e complexo, e Swagger 3 está pouco soportado pola comunidade, polo que terás que usar ferramentas propietarias ou solucións comerciais, que adoitan ser bastante caras.
Ademais, se hai moitas funcións agradables en Swagger, como un portal preparado , na que podes cargar unha anotación e obter a súa visualización cunha descrición detallada, ligazóns e conexións, entón para o RAML máis fundamental e menos amigable non existe esa oportunidade. Si, podes buscar algo entre os proxectos en GitHub, atopar alí un análogo e implementalo por ti mesmo. Non obstante, en calquera caso, alguén terá que manter o portal, que non resulta tan conveniente para o uso básico ou as necesidades de proba. Ademais, o swagger é máis "sen principios" ou máis liberal: pódese xerar a partir de comentarios no código, que, por suposto, vai en contra do primeiro principio da API e non é compatible con ningunha das utilidades RAML.
No seu momento comezamos a traballar con RAML como unha linguaxe máis flexible e, como resultado, tivemos que facer moitas cousas nós. Por exemplo, un dos proxectos usa a utilidade en probas unitarias, que só admite RAML 0.8. Entón tivemos que engadir muletas para que a utilidade puidese "comer" a versión 1.0 de RAML.
Necesitas escoller?
Despois de traballar para completar o ecosistema de solucións para RAML, chegamos á conclusión de que necesitamos converter RAML en Swagger 2 e levar a cabo toda a automatización, verificación, proba e optimización posterior nel. Esta é unha boa forma de aproveitar tanto a flexibilidade de RAML como o soporte de ferramentas comunitarias de Swagger.
Para resolver este problema, hai dúas ferramentas OpenSource que deberían proporcionar conversión de contratos:
- é unha utilidade actualmente non compatible. Mentres traballamos con el, descubrimos que ten unha serie de problemas con RAML complexos que están "espandidos" por un gran número de ficheiros. Este programa está escrito en JavaScript e realiza un percorrido recursivo dunha árbore de sintaxe. Debido á escritura dinámica, faise difícil entender este código, polo que decidimos non perder o tempo escribindo parches para unha utilidade moribunda.
- - unha ferramenta da mesma empresa que di estar preparada para converter calquera cousa e todo, e en calquera dirección. Ata a data, anunciouse soporte para RAML 0.8, RAML 1.0 e Swagger 2.0. Non obstante, no momento da nosa investigación, a utilidade aínda estaba húmido e inservible. Os desenvolvedores crean unha especie de , o que lles permite engadir novos estándares rapidamente no futuro. Pero ata agora simplemente non funciona.
E non son todas as dificultades coas que nos atopamos. Un dos pasos do noso pipeline é verificar que a RAML do repositorio é correcta en relación coa especificación. Probamos varias utilidades. Sorprendentemente, todos xuraron as nosas anotacións en diferentes lugares e con malas palabras completamente diferentes. E non sempre ao grano :).
Ao final, asentámonos nun proxecto xa desactualizado, que tamén ten unha serie de problemas (ás veces falla por sorpresa, ten problemas ao traballar con expresións regulares). Así, non atopamos a forma de resolver os problemas de validación e conversión baseados en ferramentas libres, e decidimos utilizar unha utilidade comercial. No futuro, a medida que as ferramentas OpenSource maduran, este problema pode ser máis fácil de resolver. Mentres tanto, os custos laborais e de tempo para “acabar” pareceunos máis importantes que o custo dun servizo comercial.
Conclusión
Despois de todo isto, queriamos compartir a nosa experiencia e sinalar que antes de elixir unha ferramenta para describir contratos, cómpre definir claramente que quere dela e que orzamento está disposto a investir. Se nos esquecemos de OpenSource, xa hai un gran número de servizos e produtos que che axudarán a comprobar, converter e validar. Pero son caros, e ás veces moi caros. Para unha gran empresa, estes custos son tolerables, pero para unha startup poden converterse nunha gran carga.
Determine o conxunto de ferramentas que utilizará máis tarde. Por exemplo, se só precisa mostrar un contrato, será máis fácil usar Swagger 2, que ten unha fermosa API, porque en RAML terás que construír e manter o servizo ti mesmo.
Cantas máis tarefas teñas, máis ampla será a necesidade de ferramentas, e son diferentes para as diferentes plataformas, e é mellor familiarizarte inmediatamente coas versións dispoñibles para facer unha elección que minimice os teus custos no futuro.
Pero vale a pena recoñecer que todos os ecosistemas que existen hoxe en día son imperfectos. Por iso, se na empresa hai afeccionados aos que lles gusta traballar en RAML porque "permite expresar pensamentos de forma máis flexible" ou, pola contra, prefiren Swagger porque "está máis claro", o mellor é deixalos traballar. en que están Están afeitos e queren, porque as ferramentas de calquera dos formatos requiren modificación cun ficheiro.
En canto á nosa experiencia, nas seguintes publicacións falaremos de que comprobacións estáticas e dinámicas realizamos en función da nosa arquitectura RAML-Swagger, así como que documentación xeramos a partir dos contratos e como funciona todo.
Só os usuarios rexistrados poden participar na enquisa. , por favor.
Que lingua usas para anotar contratos de microservizos?
-
RAML 0.8
-
RAML 1.0
-
Trampa 2
-
OAS3 (tamén coñecido como)
-
Plano de traballo
-
Outro
-
Non usar
Votaron 100 usuarios. 24 usuarios abstivéronse.
Fonte: www.habr.com