Die Aktualisierung der Dokumentation für Microservices erfordert nach wie vor äußerste Disziplin in der Entwicklung und hohe Arbeitskosten. Zum Beispiel bietet GraphQL einen sehr vernünftigen Ansatz zum Erstellen von Dokumentation, bei dem die Dokumentation untrennbar mit dem Programmcode verbunden ist und dies eine 100% ige Übereinstimmung der Dokumentation und der dokumentierten Dienste garantiert. Der ungewöhnliche Ansatz von GraphQL für Entwickler, die an die REST-API gewöhnt sind, macht es jedoch immer noch schwierig, diese Technologie in der praktischen Anwendungsentwicklung zu fördern. Hier können Sie sich an SOAP erinnern, das das Problem der Konformität von Dokumentation und Diensten seit langem gelöst hat, aber aufgrund der Überkomplexität bei der breiten Masse der Entwickler keine Wurzeln schlug.
Ich würde gerne einen solchen Stapel von Technologien für die Entwicklung von Mikrodiensten finden, die die gleiche Selbstdokumentierbarkeit des Programmcodes bei der Entwicklung "traditioneller" REST-API-Mikrodienste bieten. Und wie sich herausstellte, existiert er bereits.
Wir definieren die Schauspieler und Darsteller, die an unserem kleinen Beispiel beteiligt sein werden.
ArangoDB ist eine hybride, dokument + graphorientierte Datenbank.
UPD Eine detailliertere Bekanntschaft mit dieser Datenbank war der Grund für eine weitere Enttäuschung. Wie sich herausstellte, verlangsamt sich die Datenbank, nachdem die Datenbank ein nicht begrenztes Limit überschritten hat, das durch den freien Arbeitsspeicher begrenzt ist. Sie stoppt nur zusammen mit dem Server. Gleichzeitig wurden schüchterne Annahmen geäußert, dass der Übergang zu neuen Speicher-Engines besser funktionieren wird, was noch nicht bestätigt wurde.
Foxx ist ein in die ArangoDB-Datenbank integriertes Microservice-Framework. Es läuft auf einer JavaScript-Engine, die (im Gegensatz zu nodejs) gleichzeitig in einer unbegrenzten Anzahl paralleler Threads ausgeführt werden kann (ohne sich gegenseitig zu blockieren), wodurch keine Konstrukte versprechen / than / canch und async / await erforderlich sind. Im Gegensatz zu Mongodb, bei dem es nicht empfohlen wird, Serverprozeduren zu missbrauchen, und relationalen Datenbanken, bei denen gespeicherte Prozeduren ebenfalls sorgfältig verwendet werden und über die REST-API nicht mit Clients (Browsern, mobilen Anwendungen usw.) interagieren, handelt es sich um ein Microservice-Framework Foxx wurde speziell für die Entwicklung von Microservices entwickelt, die direkt mit dem http-Protokoll mit Clients kommunizieren.
Swagger ist eine Open-Source-Softwareumgebung, die von einem großen Ökosystem von Tools unterstützt wird, mit denen Entwickler RESTful-Webdienste entwickeln, erstellen, dokumentieren und nutzen können. Obwohl die meisten Benutzer Swagger mit der Swagger-Benutzeroberfläche identifizieren, unterstützt das Swagger-Toolkit die automatische Dokumentation, Codegenerierung und Testfallgenerierung.
Die Tatsache, dass Swagger Unterstützung für die Codegenerierung enthält, ist eine Situation, die der Situation entgegengesetzt ist, die wir uns wünschen - wenn der Code die Dokumentationsgenerierung unterstützt. Was ArangoDB + Foxx uns bietet, beinhaltet nur die entgegengesetzte Option. Wenn ein Microservice-Code eine Schaltung für Swagger generiert. Jetzt können Sie dies jedoch selbst überprüfen, nachdem Sie ein Minimum an Arbeit geleistet haben.
Sie müssen ArangoDB installiert haben, um weitere Aktionen ausführen zu können.
- Wir gehen in das Admin-Panel und wählen das Element zum Erstellen eines neuen Microservice aus. Services-> Service hinzufügen-> Neu.
- Wir füllen das gewünschte Formular im geöffneten Formular aus. Fügen Sie im Feld "Dokumentensammlungen" den Namen der Dokumentensammlung hinzu, die bei der Bereitstellung des Microservices erstellt wird. Zum Beispiel Katzen.
- Wir klicken auf die Schaltfläche Installieren und geben in das URL-Feld ein, an dem der Microservice bereitgestellt werden soll.
Bei der Installation eines Mikrodienstes werden für jede Sammlung aus dem Feld "Dokumentensammlungen" (siehe Abschnitt 2) Routen erstellt, die CRUD-Operationen mit den Methoden POST, GET, PUT und DELETE implementieren. Dies ist jedoch nur ein Entwurf von Methoden, die Sie ändern, löschen und neue hinzufügen können. Wir haben beim Erstellen eines Microservices (Katzen) eine Sammlung ausgewählt, obwohl wir dies möglicherweise nicht getan haben, sondern später alles manuell hinzugefügt haben.
Jetzt verfügt unsere Katzensammlung über Routen für CRUD-Vorgänge. Sie können diese Routen über das Datenbankadministrationsfenster aufrufen, indem Sie die Registerkarte API (Dienste -> [Microservice-Name] -> API) auswählen. Diese Registerkarte enthält die bekannte Swagger-Oberfläche. Es ist auch möglich, die Swagger-Oberfläche auf einer externen Route zu veröffentlichen, auf die nicht nur über das Admin-Panel, sondern auch als reguläre URL zugegriffen werden kann.
Wenn wir versuchen, das Dokument mit der POST-Methode {"name": "Tom"} zur Katzensammlung hinzuzufügen, wird der Status mit einem Fehler angezeigt. Weil Das Namensfeld haben wir noch nicht definiert. Daher werden wir weiterhin mit dem ArangoDB-Admin-Panel arbeiten.
4. Für eine bequemere Entwicklung bietet ArangoDB den Entwicklungsmodus, der auf der Registerkarte Einstellungen aktiviert ist (Dienste -> [Microservice Name] -> Entwicklung der Einstellungssätze).
Jetzt können Sie den Code des World Service ändern und das Ergebnis sofort beobachten (ohne zusätzliche Bereitstellung). Das Verzeichnis, in dem sich der Microservice-Programmcode befindet, befindet sich im Admin-Bereich auf der Registerkarte Info (Dienste -> [Microservice-Name] -> Info).
Mal sehen, wie die Definition einer POST-Route aussieht.
'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. `);
Sowohl die Validierung als auch die Dokumentation basieren auf der Verwendung eines Objektschemas. Wir werden kleine Änderungen daran vornehmen, indem wir das Namensfeld hinzufügen:
'use strict'; const _ = require('lodash'); const joi = require('joi'); module.exports = { schema: {
Wenn Sie zum API-Lesezeichen gehen, können Sie sicherstellen, dass sich das Schema geändert hat, und jetzt kann das Objekt mit dem Namensfeld zur Katzensammlung hinzugefügt werden.
apapacy@gmail.com
12. November 2018.