La mise à jour de la documentation des microservices nécessite toujours une discipline de développement extrême et des coûts de main-d'œuvre élevés. Par exemple, GraphQL offre une approche très raisonnable de la création de documentation, où la documentation est inextricablement liée au code du programme et cela garantit une conformité à 100% de la documentation et des services documentés. Cependant, l'approche inhabituelle de GraphQL pour les développeurs habitués à l'API REST, rend encore difficile la promotion de cette technologie dans le développement d'applications pratiques. Ici, vous vous souvenez de SOAP, qui a depuis longtemps résolu le problème de conformité de la documentation et des services, mais en raison de sa complexité excessive, il n'a pas pris racine parmi les larges masses de développeurs.
Je voudrais trouver une telle pile de technologies pour développer des microservices qui fournissent la même auto-documentabilité du code de programme lors du développement de microservices "traditionnels" REST-API. Et il s'est avéré qu'il existe déjà.
Nous définissons les acteurs et interprètes qui seront impliqués dans notre petit exemple.
ArangoDB est une base de données hybride, orientée document + graphique.
UPD Une connaissance plus détaillée de cette base de données était la raison d'une autre déception. Il s'est avéré que, après que la base de données a dépassé une limite non limitée, qui est limitée par la RAM libre, la base de données commence à ralentir - elle s'arrête juste avec le serveur. Dans le même temps, des hypothèses timides ont été exprimées selon lesquelles la transition vers de nouveaux moteurs de stockage fonctionnerait mieux, ce qui n'a pas encore été confirmé.
Foxx est un cadre de microservices intégré à la base de données ArangoDB. Il s'exécute sur un moteur JavaScript, qui (contrairement à nodejs) peut être exécuté simultanément dans un nombre illimité de threads parallèles (ne se bloquant pas les uns les autres), ce qui ne nécessite pas de constructions promise / than / canch et async / wait. Contrairement à mongodb, dans lequel il n'est pas recommandé d'abuser des procédures serveur, et des bases de données relationnelles, dans lesquelles les procédures stockées sont également utilisées avec prudence et n'interagissent certainement pas avec les clients (navigateurs, applications mobiles, etc.) via l'API REST, il s'agit d'un cadre de microservice Foxx a été conçu spécifiquement pour le développement de microservices qui communiquent directement avec le protocole http avec les clients.
Swagger est un environnement logiciel open source soutenu par un large écosystème d'outils qui aide les développeurs à développer, créer, documenter et consommer des services Web RESTful. Bien que la plupart des utilisateurs identifient Swagger avec l'interface utilisateur Swagger, la boîte à outils Swagger prend en charge la documentation automatique, la génération de code et la génération de cas de test.
Le fait que Swagger inclut la prise en charge de la génération de code est une situation opposée à celle que nous aimerions obtenir - lorsque le code prend en charge la génération de documentation. Ce que nous propose ArangoDB + Foxx inclut simplement l'option opposée. Lorsqu'un code de microservice génère un circuit pour Swagger. Cependant, vous pouvez maintenant le vérifier vous-même après avoir effectué un minimum de travail.
Vous devez avoir installé ArangoDB pour effectuer d'autres actions.
- Nous allons dans le panneau d'administration et sélectionnons l'élément pour créer un nouveau microservice Services-> Ajouter un service-> Nouveau.
- Nous remplissons le formulaire requis dans le formulaire ouvert. Dans le champ «Collections de documents», ajoutez le nom de la collection de documents qui sera créée lors du déploiement du microservice. Par exemple, les chats.
- Nous cliquons sur le bouton d'installation, entrons dans le champ url sur lequel le microservice sera monté.
Lors de l'installation d'un microservice, pour chaque collection du champ «Collections de documents» (voir section 2), des itinéraires seront créés qui implémenteront les opérations CRUD en utilisant les méthodes POST, GET, PUT et DELETE. Cependant, ce n'est qu'un projet de méthodes que vous pouvez modifier, supprimer, ajouter de nouvelles. Nous avons choisi une collection lors de la création d'un microservice (chats), bien que nous ne l'ayons peut-être pas fait, mais nous avons tout ajouté manuellement plus tard.
Maintenant, notre collection de chats a des routes pour les opérations CRUD, et nous pouvons commencer à appeler ces routes depuis le panneau d'administration de la base de données en sélectionnant l'onglet API (Services -> [Nom du microservice] -> API). Cet onglet contient l'interface Swagger familière. Il est également possible de publier l'interface Swagger sur une route externe, accessible non seulement via le panneau d'administration, mais en tant qu'URL régulière.
Si nous essayons d'ajouter le document à la collection de chats en utilisant la méthode POST {"name": "Tom"}, nous obtenons le statut avec une erreur. Parce que le champ de nom que nous n'avons pas encore défini. Par conséquent, nous continuerons à travailler avec le panneau d'administration ArangoDB.
4. Pour un développement plus pratique, ArangoDB fournit le mode de développement, qui est activé sur l'onglet Paramètres (Services -> [Nom du microservice] -> Développement de l'ensemble de paramètres)
Vous pouvez maintenant modifier le code du service mondial et observer immédiatement le résultat (sans déploiement supplémentaire). Le répertoire où se trouve le code du programme de microservice se trouve dans le panneau d'administration sur l'onglet Info (Services -> [Nom du microservice] -> Info).
Voyons à quoi ressemble la définition d'une route 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. `);
La validation et la documentation sont basées sur l'utilisation d'un schéma d'objet. Nous y apporterons de petites modifications en ajoutant le champ de nom:
'use strict'; const _ = require('lodash'); const joi = require('joi'); module.exports = { schema: {
En accédant au signet de l'API, vous pouvez vous assurer que le schéma a changé et maintenant l'objet avec le champ de nom peut être ajouté à la collection cats.
apapacy@gmail.com
12 novembre 2018.