Manter a documentação atualizada dos microsserviços ainda requer muita disciplina no desenvolvimento e grandes custos de mão-de-obra. Por exemplo, o GraphQL oferece uma abordagem bastante razoável para a criação de documentação, onde a documentação está inextricavelmente vinculada ao código do programa e isso garante 100% de conformidade da documentação e dos serviços documentados. No entanto, a abordagem incomum do GraphQL para desenvolvedores acostumados à API REST, ainda dificulta a promoção dessa tecnologia no desenvolvimento prático de aplicativos. Aqui você pode se lembrar do SOAP, que há muito tempo resolveu o problema da conformidade da documentação e dos serviços, mas, devido à complexidade excessiva, não criou raízes entre as grandes massas de desenvolvedores.
Gostaria de encontrar uma pilha de tecnologias para o desenvolvimento de microsserviços que forneçam a mesma auto-documentação do código do programa ao desenvolver microsserviços "tradicionais" da API REST. E ele, como se viu, já existe.
Definimos os atores e artistas que estarão envolvidos em nosso pequeno exemplo.
O ArangoDB é um banco de dados híbrido, orientado a documentos e gráficos.
UPD O conhecimento mais detalhado desse banco de dados foi o motivo de outra decepção. Como se viu, depois que o banco de dados excede um limite não limitado, limitado pela RAM livre, o banco de dados começa a ficar lento - ele apenas para junto com o servidor. Ao mesmo tempo, foram expressas suposições tímidas de que a transição para novos mecanismos de armazenamento funcionará melhor, o que ainda não foi confirmado.
Foxx é uma estrutura de microsserviço incorporada ao banco de dados ArangoDB. Ele é executado em um mecanismo JavaScript, que (diferente dos nodejs) pode ser executado simultaneamente em um número ilimitado de encadeamentos paralelos (sem bloquear um ao outro), como resultado dos quais não há necessidade de construções de promessa / que / canch e async / waitit. Ao contrário do mongodb, no qual não é recomendável abusar dos procedimentos do servidor e dos bancos de dados relacionais nos quais os procedimentos armazenados também são usados com cuidado e certamente não interagem com os clientes (navegadores, aplicativos móveis etc.) via REST-API, é uma estrutura de microsserviço O Foxx foi projetado especificamente para o desenvolvimento de microsserviços que se comunicam diretamente com o protocolo http com os clientes.
O Swagger é um ambiente de software de código aberto suportado por um grande ecossistema de ferramentas que ajuda os desenvolvedores a desenvolver, criar, documentar e consumir serviços da Web RESTful. Embora a maioria dos usuários identifique o Swagger com a interface do usuário do Swagger, o kit de ferramentas Swagger inclui suporte para documentação automática, geração de código e geração de casos de teste.
O fato de o Swagger incluir suporte para geração de código é uma situação oposta à que gostaríamos de obter - quando o código suporta a geração de documentação. O que o ArangoDB + Foxx nos oferece inclui apenas a opção oposta. Quando um código de microsserviço gera um circuito para o Swagger. No entanto, agora você pode verificar isso fazendo um mínimo de trabalho.
Você deve ter o ArangoDB instalado para executar outras ações.
- Entramos no painel de administração e selecionamos o item para criar um novo microsserviço Serviços-> Adicionar serviço-> Novo.
- Nós preenchemos o formulário necessário no formulário aberto. No campo "Coleções de documentos", adicione o nome da coleção de documentos que será criada quando o microsserviço for implantado. Por exemplo, gatos.
- Clicamos no botão de instalação, entramos no campo de URL no qual o microsserviço será montado.
Ao instalar um microsserviço, para cada coleção do campo "Document Collections" (consulte a seção 2), serão criadas rotas que implementam operações CRUD usando os métodos POST, GET, PUT e DELETE. No entanto, este é apenas um rascunho de métodos que você pode alterar, excluir e adicionar novos. Escolhemos uma coleção ao criar um microsserviço (gatos), embora não o tenhamos feito, mas adicionamos tudo manualmente mais tarde.
Agora, nossa coleção de gatos possui rotas para operações CRUD, e podemos começar a chamá-las no painel de administração do banco de dados, selecionando a guia API (Serviços -> [Nome do microsserviço] -> API). Essa guia contém a interface familiar do Swagger. Também é possível publicar a interface do Swagger em uma rota externa, acessível não apenas pelo painel de administração, mas como uma URL comum.
Se tentarmos adicionar o documento à coleção de gatos usando o método POST {"name": "Tom"}, obteremos o status com um erro. Porque o campo de nome que ainda não definimos. Portanto, continuaremos trabalhando com o painel de administração do ArangoDB.
4. Para um desenvolvimento mais conveniente, o ArangoDB fornece o modo Desenvolvimento, que é ativado na guia Configurações (Serviços -> [Nome do microsserviço] -> Desenvolvimento do conjunto de configurações)
Agora você pode alterar o código do serviço mundial e observar imediatamente o resultado (sem implantação adicional). O diretório em que o código do programa de microsserviço está localizado pode ser encontrado no painel de administração na guia Informações (Serviços -> [Nome do microsserviço] -> Informações).
Vamos ver como é a definição de uma rota POST.
'use strict'; const dd = require('dedent'); const joi = require('joi'); const httpError = require('http-errors'); const status = require('statuses'); const errors = require('@arangodb').errors; const createRouter = require('@arangodb/foxx/router'); const Cat = require('../models/cat'); const cats = module.context.collection('cats'); const keySchema = joi.string().required() .description('The key of the cat'); const ARANGO_NOT_FOUND = errors.ERROR_ARANGO_DOCUMENT_NOT_FOUND.code; const ARANGO_DUPLICATE = errors.ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED.code; const ARANGO_CONFLICT = errors.ERROR_ARANGO_CONFLICT.code; const HTTP_NOT_FOUND = status('not found'); const HTTP_CONFLICT = status('conflict'); const router = createRouter(); module.exports = router; router.tag('cat'); router.post(function (req, res) { const cat = req.body; let meta; try { meta = cats.save(cat); } catch (e) { if (e.isArangoError && e.errorNum === ARANGO_DUPLICATE) { throw httpError(HTTP_CONFLICT, e.message); } throw e; } Object.assign(cat, meta); res.status(201); res.set('location', req.makeAbsolute( req.reverse('detail', {key: cat._key}) )); res.send(cat); }, 'create') .body(Cat, 'The cat to create.') .response(201, Cat, 'The created cat.') .error(HTTP_CONFLICT, 'The cat already exists.') .summary('Create a new cat') .description(dd` Creates a new cat from the request body and returns the saved document. `);
A validação e a documentação são baseadas no uso de um esquema de objeto. Faremos pequenas alterações adicionando o campo de nome:
'use strict'; const _ = require('lodash'); const joi = require('joi'); module.exports = { schema: {
Acessando o marcador da API, você pode garantir que o esquema tenha sido alterado e agora o objeto com o campo de nome possa ser adicionado à coleção de gatos.
apapacy@gmail.com
12 de novembro de 2018.