Em um mundo dinâmico de microsserviços, tudo pode mudar — qualquer componente pode ser reescrito em outra linguagem, utilizando diferentes frameworks e arquiteturas. Apenas os contratos devem permanecer imutáveis, para que a interação com o microsserviço possa ocorrer de forma consistente do exterior, independentemente das metamorfoses internas. Hoje, iremos falar sobre nosso dilema na escolha do formato de descrição dos contratos e compartilhar os artefatos encontrados.
Post elaborado por e
Microsserviços. Durante o desenvolvimento do Acronis Cyber Cloud, percebemos que não poderíamos evitar isso. E o design de 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 do contrato se torna uma atividade regular, você começa a pensar na otimização do processo. Torna-se evidente que a interface (contrato) e a implementação (microsserviço) devem corresponder uma à outra, que diferentes componentes devem realizar as mesmas funções de maneira uniforme, e que sem uma entrega centralizada de todas essas decisões, cada equipe precisará, repetidamente, reinvestir tempo para obtê-las.
Esquema de microsserviços da Amazon de de Werner Vogels, CTO da Amazon
Qual é, então, o dilema? De fato, existem duas maneiras de os microsserviços interagirem - HTTP Rest e gRPC da Google. Não desejando ser envolvido na stack de tecnologias da Google, escolhemos HTTP Rest. Anotações de contratos HTTP REST geralmente são descritas em um dos dois formatos: RAML e OAS, anteriormente conhecido como Swagger. Portanto, cada equipe de desenvolvimento enfrenta a necessidade de escolher um dos padrões. Mas, como se revelou, fazer essa escolha pode ser bastante desafiador.
Por que são necessárias anotações?
A anotação é necessária para que um usuário externo consiga entender facilmente o que pode ser feito com seu serviço através da 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ções, enumeração de parâmetros, indicação de 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 descrição verbal deles (“o que acontecerá se esse query-parâmetro for adicionado à solicitação?”, “em qual caso retornará o código 400?”)
No entanto, quando se trata de desenvolver um grande número de microsserviços, é desejável extrair mais benefícios das anotações escritas. Por exemplo, com base no RAML/Swagger, é possível gerar tanto código cliente quanto servidor em uma enorme variedade de linguagens de programação. Além disso, é possível obter automaticamente a documentação do microsserviço e publicá-la em seu portal de desenvolvedores :).
Exemplo de descrição estruturada de contrato
É menos comum a prática de testar microsserviços com base nas descrições dos contratos. Se você escreveu tanto a anotação quanto o componente, pode criar um autoteste que verifique a adequação do funcionamento do serviço com diferentes tipos de dados de entrada. O serviço retorna algum código de resposta que não está descrito na anotação? Ele consegue processar corretamente dados deliberadamente inválidos?
Além disso, uma implementação de qualidade não apenas dos próprios contratos, mas também de ferramentas para visualização de anotações pode simplificar o trabalho com o microsserviço. Ou seja, se o arquiteto descreveu o contrato com qualidade, com base nele, os designers e desenvolvedores poderão integrar o serviço em outros produtos sem custos de tempo adicionais.
Para o funcionamento de ferramentas adicionais, tanto o RAML quanto o OAS têm a capacidade de adicionar metadados não previstos pelo padrão ().
Em geral, há um grande espaço para criatividade na aplicação de contratos para microsserviços… pelo menos teoricamente
Comparação de um ouriço com uma cobra
Atualmente, a principal linha de desenvolvimento na Acronis é a evolução da Acronis Cyber Platform. A Acronis Cyber Platform é uma nova interface de integração de serviços de terceiros com a Acronis Cyber Cloud e com a parte de agência. Embora nossas APIs internas, descritas em RAML, estivessem funcionando bem para nós, a necessidade de publicar a API levantou novamente a questão da escolha: qual padrão de anotações é melhor para o nosso trabalho?
Inicialmente, parecia que havia duas soluções — as mais comuns, RAML e Swagger (ou OAS). Mas, na prática, não se tratava de apenas duas alternativas, mas sim de três ou mais.
De um lado, temos o RAML — uma linguagem poderosa e eficiente. Ele implementa bem hierarquias e heranças, tornando esse formato mais adequado para grandes empresas que precisam de muitas descrições — ou seja, não um produto, mas muitos microserviços que possuem partes comuns nos contratos — esquemas de autenticação, tipos de dados idênticos, corpos de erro.
Mas o desenvolvedor do RAML, a empresa Mulesoft, se juntou ao consórcio Open API, que está focado no desenvolvimento do . Portanto, o desenvolvimento do RAML foi suspenso. Para imaginar a situação do formato, considere que os mantenedores dos componentes principais do Linux foram trabalhar na Microsoft. Essa situação gera condições para o uso do Swagger, que está em desenvolvimento dinâmico e, na sua última — terceira versão — está praticamente alcançando o RAML em flexibilidade e funcionalidade.
Se não fosse por um pequeno detalhe...
Como se viu, nem todas as utilidades de código aberto foram atualizadas para a versão OAS 3.0. Para microserviços em Go, a falta de adaptação do para a nova versão do padrão será extremamente crítica. No entanto, a diferença entre o Swagger 2 e o Swagger 3 é Por exemplo, na terceira versão, os desenvolvedores:
- melhoraram a descrição dos esquemas de autenticação,
- o suporte ao JSON Schema,
- melhoraram a capacidade de adicionar exemplos.
A situação é curiosa: ao escolher um padrão, devemos considerar o RAML, o Swagger 2 e o Swagger 3 como alternativas distintas. E somente o Swagger 2 possui um bom suporte de ferramentas OpenSource. O RAML é muito flexível… e complexo, enquanto o Swagger 3 é pouco apoiado pela comunidade, então você terá que usar ferramentas de desenvolvimento próprio ou soluções comerciais, que geralmente têm um custo bastante elevado.
Ao mesmo tempo, se no Swagger existem muitas possibilidades agradáveis, como um portal pronto, , onde você pode fazer upload de uma anotação e obter sua visualização com uma descrição detalhada, links e relações, enquanto para o RAML, que é mais fundamental e menos amigável, essa possibilidade não existe. Sim, pode-se procurar algum projeto no GitHub, encontrar um análogo e implantá-lo manualmente. No entanto, de qualquer forma, alguém precisará 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 liberal — pode ser gerado de comentários no código, o que, claro, vai contra o princípio do API first e não é suportado por nenhuma das utilidades RAML.
No nosso tempo, começamos a trabalhar com RAML, por ser uma linguagem mais flexível, e acabamos fazendo muitas coisas manualmente. Por exemplo, em um dos projetos, usamos uma ferramenta em testes de unidade, que suporta apenas RAML 0.8. Portanto, tivemos que adicionar gambiarras para que a ferramenta pudesse "processar" RAML na versão 1.0.
E precisamos escolher?
Após nos familiarizarmos com a adição de uma ecossistema de soluções para RAML, chegamos à conclusão de que precisávamos converter RAML para Swagger 2 e realizar toda a automação, verificação, testes e posterior otimização nele. Essa é uma boa forma de usar tanto a flexibilidade do RAML quanto o suporte da comunidade para as ferramentas do Swagger.
Para resolver essa tarefa, existem duas ferramentas OpenSource que devem garantir a conversão de contratos:
- — uma ferramenta atualmente não suportada. Ao trabalhar com ela, descobrimos que surgem uma série de problemas com RAMLs complexos que estão "distribuídos" por muitos arquivos. Este programa é escrito em JavaScript e realiza uma travessia recursiva da árvore de sintaxe. Devido à tipagem dinâmica, torna-se complicado entender esse código, então decidimos não perder tempo escrevendo patches para uma ferramenta em declínio.
- — uma ferramenta da mesma empresa, que se propõe a converter tudo e qualquer coisa, em qualquer direção. Até o momento, o suporte declarado é para RAML 0.8, RAML 1.0 e Swagger 2.0. No entanto, no momento da nossa pesquisa, a ferramenta ainda estava crua e imprópria para uso. Os desenvolvedores estão criando uma espécie de , o que permitirá que eles adicionem rapidamente novos padrões no futuro. Mas por enquanto, tudo isso simplesmente não funciona.
E isso não são todas as dificuldades que enfrentamos. Um dos passos do nosso pipeline é verificar se o RAML do repositório é válido em relação à especificação. Experimentamos várias ferramentas. Curiosamente, todas reclamaram das nossas anotações em diferentes lugares e com palavras bastante negativas. E, surpreendentemente, nem sempre era pertinente :).
No final, optamos por um projeto atualmente desatualizado, que também apresenta uma série de problemas (às vezes ele falha sem motivos claros, tem dificuldades ao trabalhar com expressões regulares). Assim, não encontramos uma maneira de resolver os problemas de validação e conversão usando ferramentas gratuitas, e decidimos utilizar uma ferramenta comercial. No futuro, quando os recursos OpenSource se tornarem mais desenvolvidos, a solução para essa tarefa pode se tornar mais fácil. Mas, por enquanto, o custo em tempo e esforço para 'ajustar' parecia ser mais significativo do que o preço do serviço comercial.
Conclusão
Depois de tudo isso, sentimos a necessidade de compartilhar a experiência e observar que, antes de escolher uma ferramenta para descrever contratos, é preciso definir claramente o que você espera dela e qual orçamento está disposto a investir. Se ignorar o OpenSource, já existem muitos serviços e produtos que podem ajudar a realizar a verificação, 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.
Defina um conjunto de ferramentas que você usará posteriormente. Por exemplo, se você apenas precisa exibir um contrato, será mais fácil usar o Swagger 2, que possui uma API bonita, enquanto no RAML você terá que configurar e manter o serviço por conta própria.
Quanto mais tarefas você tiver, maior será a necessidade de ferramentas, e eles são diferentes para diferentes plataformas. É melhor se familiarizar desde já com as versões disponíveis, para fazer uma escolha que minimize seus custos no futuro.
Mas é preciso reconhecer que todos os ecossistemas existentes hoje são imperfeitos. Portanto, se houver fãs na empresa que adoram trabalhar com RAML, porque "ele permite expressar ideias de forma mais flexível", ou, ao contrário, preferem Swagger porque "é mais compreensível" — é melhor deixá-los trabalhar com aquilo que estão acostumados e querem, pois as ferramentas de qualquer um dos formatos precisam de ajustes.
Quanto à nossa experiência, em posts futuros falaremos sobre quais — verificações estáticas e dinâmicas realizamos com base na nossa arquitetura RAML-Swagger, assim como sobre a documentação que geramos a partir dos contratos e como tudo isso funciona.
Apenas usuários registrados podem participar da pesquisa. , por favor.
E qual linguagem você usa para anotações de contratos de microsserviços?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (também conhecido como )
Blueprint
Outro
Não utilizo
Votaram 100 usuários. 24 usuários se abstiveram.
Fonte: habr.com
