No mundo dinâmico dos microsserviços, tudo pode mudar: qualquer componente pode ser reescrito em uma linguagem diferente, usando estruturas e arquiteturas diferentes. Apenas os contratos devem permanecer inalterados para que o microsserviço possa interagir externamente de forma permanente, independentemente das metamorfoses internas. E hoje falaremos sobre nosso problema de escolha de um formato para descrever contratos e compartilharemos os artefatos que encontramos.
Postagem preparada и
Microsserviços. Ao desenvolver o Acronis Cyber Cloud, percebemos que não poderíamos escapar deles. E projetar um microsserviço é impossível sem a formalização do contrato, que representa a interface do microsserviço.
Mas quando um produto contém mais de um componente e o desenvolvimento de contratos se torna uma atividade regular, você não pode deixar de começar a pensar na otimização de processos. Torna-se óbvio que a interface (contrato) e a implementação (microserviço) devem corresponder entre si, que diferentes componentes devem fazer as mesmas coisas da mesma maneira e que sem uma tomada de decisão centralizada de todas essas decisões, cada equipe será forçada a gaste tempo repetidamente para obtê-los.
Diagrama de microsserviços da Amazon de Werner Vogelis, CTO da Amazon
Qual é o dilema? Na verdade, existem duas maneiras de interagir microsserviços: HTTP Rest e gRPC do Google. Não querendo nos deixar levar pela pilha de tecnologia do Google, escolhemos HTTP Rest. As anotações de contrato HTTP REST são mais frequentemente descritas em um dos dois formatos: RAML e OAS, anteriormente conhecido como Swagger. Portanto, toda equipe de desenvolvimento se depara com a necessidade de escolher um dos padrões. Mas acontece que fazer essa escolha pode ser muito difícil.
Por que as anotações são necessárias?
A anotação é necessária para que um usuário externo possa descobrir facilmente o que pode ser feito com seu serviço por meio de sua interface HTTP. Ou seja, em um nível básico, a anotação deve conter pelo menos uma lista de recursos disponíveis, seus métodos HTTP, corpos de solicitação, uma listagem de parâmetros, uma indicação dos cabeçalhos necessários e suportados, bem como códigos de retorno e formatos de resposta. Um elemento extremamente importante da anotação do contrato é a sua descrição verbal (“o que acontecerá se você adicionar este parâmetro de consulta à solicitação?”, “Em que caso o código 400 será retornado?”)
No entanto, quando se trata de desenvolver um grande número de microsserviços, você deseja extrair valor adicional das anotações escritas. Por exemplo, com base em RAML/Swagger, você pode gerar código de cliente e servidor em um grande número de linguagens de programação. Você também pode receber automaticamente a documentação do microsserviço e carregá-la no portal do desenvolvedor :).
Exemplo de descrição de contrato estruturado
Menos comum é a prática de testar microsserviços com base em descrições de contratos. Se você escreveu uma anotação e um componente, poderá criar um autoteste que verifica a adequação do serviço com vários tipos de dados de entrada. O serviço retorna um código de resposta que não está descrito na anotação? Será capaz de processar corretamente dados obviamente incorretos?
Além disso, a implementação de alta qualidade não só dos próprios contratos, mas também das ferramentas de visualização de anotações permite simplificar o trabalho com o microsserviço. Ou seja, se o arquiteto descreveu o contrato com qualidade, a partir dele os projetistas e desenvolvedores implementarão o serviço em outros produtos sem custos adicionais de tempo.
Para habilitar ferramentas adicionais, tanto RAML quanto OAS têm a capacidade de adicionar metadados não previstos pelo padrão ().
Em geral, o espaço para criatividade no uso de contratos para microsserviços é enorme... pelo menos em teoria.
Comparação de um ouriço com uma cobra
Atualmente, a área de desenvolvimento prioritária da Acronis é o desenvolvimento da Acronis Cyber Platform. Acronis Cyber Platform são novos pontos de integração de serviços de terceiros com o Acronis Cyber Cloud e a parte do agente. Embora estivéssemos satisfeitos com nossas APIs internas descritas em RAML, a necessidade de publicar a API levantou novamente a questão de escolha: qual padrão de anotação é melhor usar em nosso trabalho?
Inicialmente, parecia que havia duas soluções - os desenvolvimentos mais comuns eram RAML e Swagger (ou OAS). Mas, na verdade, descobriu-se que existem pelo menos não 2 alternativas, mas 3 ou mais.
Por um lado existe o RAML – uma linguagem poderosa e eficiente. Ele implementa bem hierarquia e herança, portanto esse formato é mais adequado para grandes empresas que precisam de muitas descrições - ou seja, não um produto, mas muitos microsserviços que possuem partes comuns de contratos - esquemas de autenticação, os mesmos tipos de dados, corpos de erro .
Mas o desenvolvedor do RAML, Mulesoft, juntou-se ao consórcio Open API, que está desenvolvendo . Portanto, RAML suspendeu o seu desenvolvimento. Para imaginar o formato do evento, imagine que os mantenedores dos principais componentes do Linux saíram para trabalhar na Microsoft. Esta situação cria os pré-requisitos para a utilização do Swagger, que se desenvolve de forma dinâmica e na última - terceira versão - praticamente alcança o RAML em termos de flexibilidade e funcionalidade.
Se não fosse por uma coisa, mas ...
Acontece que nem todos os utilitários de código aberto foram atualizados para o OAS 3.0. Para microsserviços em Go, o mais crítico será a falta de adaptação para a versão mais recente do padrão. No entanto, a diferença entre Swagger 2 e Swagger 3 é . Por exemplo, na terceira versão os desenvolvedores:
- descrição melhorada dos esquemas de autenticação
- Suporte ao esquema JSON
- atualizou a capacidade de adicionar exemplos
A situação é engraçada: ao escolher um padrão, você precisa considerar RAML, Swagger 2 e Swagger 3 como alternativas separadas. No entanto, apenas o Swagger 2 possui um bom suporte para ferramentas OpenSource. RAML é muito flexível...e complexo, e o Swagger 3 é mal suportado pela comunidade, então você terá que usar ferramentas proprietárias ou soluções comerciais, que tendem a ser bastante caras.
Além disso, se houver muitos recursos interessantes no Swagger, como um portal pronto , no qual você pode fazer upload de uma anotação e obter sua visualização com uma descrição detalhada, links e conexões, então para o RAML mais fundamental e menos amigável não existe essa oportunidade. Sim, você pode procurar algo entre os projetos no GitHub, encontrar um análogo lá e implantá-lo você mesmo. Porém, em qualquer caso, alguém terá que manter o portal, o que não é tão conveniente para uso básico ou necessidades de teste. Além disso, o swagger é mais “sem princípios”, ou mais liberal – pode ser gerado a partir de comentários no código, o que, claro, vai contra o primeiro princípio da API e não é suportado por nenhum dos utilitários RAML.
Certa vez, começamos a trabalhar com RAML como uma linguagem mais flexível e, como resultado, tivemos que fazer muitas coisas sozinhos. Por exemplo, um dos projetos utiliza o utilitário em testes unitários, que suporta apenas RAML 0.8. Então tivemos que adicionar muletas para que o utilitário pudesse “comer” o RAML versão 1.0.
Você precisa escolher?
Depois de trabalhar na conclusão do ecossistema de soluções para RAML, chegamos à conclusão de que precisamos converter o RAML em Swagger 2 e realizar toda a automação, verificação, testes e posterior otimização do mesmo. Esta é uma boa maneira de aproveitar a flexibilidade do RAML e o suporte de ferramentas da comunidade do Swagger.
Para resolver este problema, existem duas ferramentas OpenSource que devem fornecer a conversão de contratos:
- é um utilitário atualmente sem suporte. Ao trabalhar com ele, descobrimos que ele apresenta vários problemas com RAMLs complexos que estão “espalhados” por um grande número de arquivos. Este programa é escrito em JavaScript e realiza uma travessia recursiva de uma árvore sintática. Devido à digitação dinâmica, fica difícil entender esse código, então decidimos não perder tempo escrevendo patches para um utilitário que está morrendo.
- - uma ferramenta da mesma empresa que afirma estar pronta para converter tudo e qualquer coisa, e em qualquer direção. Até o momento, foi anunciado suporte para RAML 0.8, RAML 1.0 e Swagger 2.0. No entanto, no momento da nossa pesquisa, a utilidade ainda era úmido e inutilizável. Os desenvolvedores criam uma espécie de , permitindo-lhes adicionar rapidamente novos padrões no futuro. Mas até agora simplesmente não funciona.
E essas não são todas as dificuldades que encontramos. Uma das etapas do nosso pipeline é verificar se a RAML do repositório está correta em relação à especificação. Tentamos vários utilitários. Surpreendentemente, todos eles xingaram nossas anotações em lugares diferentes e com palavrões completamente diferentes. E nem sempre direto ao ponto :).
No final, optamos por um projeto já desatualizado, que também apresenta vários problemas (às vezes trava do nada, tem problemas ao trabalhar com expressões regulares). Assim, não encontramos uma forma de resolver os problemas de validação e conversão com base em ferramentas gratuitas, e decidimos utilizar um utilitário comercial. No futuro, à medida que as ferramentas OpenSource se tornarem mais maduras, este problema poderá tornar-se mais fácil de resolver. Entretanto, os custos de mão-de-obra e tempo de “acabamento” pareciam-nos mais significativos do que o custo de um serviço comercial.
Conclusão
Depois de tudo isso, gostaríamos de compartilhar nossa experiência e ressaltar que antes de escolher uma ferramenta de descrição de contratos, você precisa definir claramente o que deseja dela e qual orçamento está disposto a investir. Se esquecermos do OpenSource, já existe um grande número de serviços e produtos que irão ajudá-lo a verificar, converter e validar. Mas eles são caros e às vezes muito caros. Para uma grande empresa, esses custos são toleráveis, mas para uma startup podem se tornar um grande fardo.
Determine o conjunto de ferramentas que você usará mais tarde. Por exemplo, se você só precisa exibir um contrato, será mais fácil usar o Swagger 2, que possui uma API linda, pois no RAML você mesmo terá que construir e manter o serviço.
Quanto mais tarefas você tiver, maior será a necessidade de ferramentas, e elas são diferentes para diferentes plataformas, sendo melhor se familiarizar imediatamente com as versões disponíveis para fazer uma escolha que minimize seus custos no futuro.
Mas vale a pena reconhecer que todos os ecossistemas que existem hoje são imperfeitos. Portanto, se há fãs na empresa que gostam de trabalhar em RAML porque “permite expressar pensamentos com mais flexibilidade”, ou, pelo contrário, preferem Swagger porque “é mais claro”, o melhor é deixá-los trabalhar no que são Eles estão acostumados e querem, pois as ferramentas de qualquer um dos formatos requerem modificação com um arquivo.
Quanto à nossa experiência, nos próximos posts falaremos sobre quais verificações estáticas e dinâmicas realizamos com base em nossa arquitetura RAML-Swagger, bem como qual documentação geramos a partir de contratos e como tudo funciona.
Apenas usuários registrados podem participar da pesquisa. por favor
Que linguagem você usa para anotar contratos de microsserviços?
-
RAML 0.8
-
RAML 1.0
-
Arrogância 2
-
OAS3 (também conhecido como)
-
Diagrama
-
Outro
-
Não use
100 usuários votaram. 24 usuários se abstiveram.
Fonte: habr.com