Mantener actualizada la documentación de los microservicios todavía requiere la máxima disciplina en el desarrollo y grandes costos laborales. Por ejemplo, GraphQL ofrece un enfoque muy razonable para crear documentación, donde la documentación está indisolublemente vinculada con el código del programa y esto garantiza el 100% de cumplimiento de la documentación y los servicios documentados. Sin embargo, el enfoque inusual de GraphQL para desarrolladores que están acostumbrados a REST-API, aún dificulta la promoción de esta tecnología en el desarrollo práctico de aplicaciones. Aquí puede recordar SOAP, que durante mucho tiempo resolvió el problema de la conformidad de la documentación y los servicios, pero debido a la excesiva complejidad, no se arraigó entre las grandes masas de desarrolladores.
Me gustaría encontrar una pila de tecnologías para desarrollar microservicios que proporcionaran la misma auto documentabilidad del código del programa al desarrollar microservicios REST-API "tradicionales". Y él, como resultó, ya existe.
Definimos los actores e intérpretes que participarán en nuestro pequeño ejemplo.
ArangoDB es una base de datos híbrida orientada a documentos y gráficos.
UPD Un conocimiento más detallado de esta base de datos fue el motivo de otra decepción. Resultó que, después de que la base de datos excede un límite no limitado, que está limitado por la RAM libre, la base de datos comienza a disminuir, simplemente se detiene junto con el servidor. Al mismo tiempo, se expresaron suposiciones tímidas de que la transición a nuevos motores de almacenamiento funcionará mejor, lo que aún no se ha confirmado.
Foxx es un marco de microservicio integrado en la base de datos ArangoDB. Se ejecuta en un motor de JavaScript, que (a diferencia de nodejs) se puede ejecutar simultáneamente en un número ilimitado de subprocesos paralelos (sin bloquearse entre sí), como resultado de lo cual no hay necesidad de promesas / que / canch y async / esperar construcciones. A diferencia de mongodb, en el que no se recomienda abusar de los procedimientos del servidor, y las bases de datos relacionales en las que los procedimientos almacenados también se usan con cuidado y ciertamente no interactúan con los clientes (navegadores, aplicaciones móviles, etc.) a través de REST-API, es un marco de microservicio Foxx fue diseñado específicamente para el desarrollo de microservicios que se comunican directamente con el protocolo http con los clientes.
Swagger es un entorno de software de código abierto respaldado por un gran ecosistema de herramientas que ayuda a los desarrolladores a desarrollar, crear, documentar y consumir servicios web RESTful. Aunque la mayoría de los usuarios identifican Swagger con la interfaz de usuario de Swagger, el kit de herramientas Swagger incluye soporte para documentación automática, generación de código y generación de casos de prueba.
El hecho de que Swagger incluya soporte para la generación de código es una situación opuesta a la que nos gustaría obtener, cuando el código admite la generación de documentación. Lo que nos ofrece ArangoDB + Foxx solo incluye la opción opuesta. Cuando un código de microservicio genera un circuito para Swagger. Sin embargo, ahora puede verificar esto usted mismo después de haber realizado un mínimo de trabajo.
Debe tener instalado ArangoDB para realizar más acciones.
- Entramos en el panel de administración y seleccionamos el elemento para crear un nuevo microservicio Servicios-> Agregar servicio-> Nuevo.
- Rellenamos el formulario requerido en el formulario abierto. En el campo "Colecciones de documentos", agregue el nombre de la colección de documentos que se creará cuando se implemente el microservicio. Por ejemplo, gatos.
- Hacemos clic en el botón de instalación, ingresamos en el campo de URL en el que se montará el microservicio.
Al instalar un microservicio, para cada colección del campo "Colecciones de documentos" (ver cláusula 2), se crearán rutas que implementarán operaciones CRUD utilizando los métodos POST, GET, PUT y DELETE. Sin embargo, este es solo un borrador de métodos que puede cambiar, eliminar y agregar nuevos. Elegimos una colección al crear un microservicio (gatos), aunque es posible que no lo hayamos hecho, pero agregamos todo manualmente más tarde.
Ahora, nuestra colección de gatos tiene rutas para operaciones CRUD, y podemos comenzar a llamar estas rutas desde el panel de administración de la base de datos seleccionando la pestaña API (Servicios -> [Nombre del microservicio] -> API). Esta pestaña contiene la interfaz familiar de Swagger. También es posible publicar la interfaz Swagger en una ruta externa, accesible no solo a través del panel de administración, sino como una URL normal.
Si intentamos agregar el documento a la colección de gatos utilizando el método POST {"nombre": "Tom"}, obtendremos el estado con un error. Porque el campo de nombre que aún no hemos definido. Por lo tanto, continuaremos trabajando con el panel de administración de ArangoDB.
4. Para un desarrollo más conveniente, ArangoDB proporciona el modo Desarrollo, que está habilitado en la pestaña Configuración (Servicios -> [Nombre del microservicio] -> Configuración-Desarrollo del conjunto)
Ahora puede cambiar el código del servicio mundial y observar de inmediato el resultado (sin implementación adicional). El directorio donde se encuentra el código del programa de microservicios se puede encontrar en el panel de administración en la pestaña Información (Servicios -> [Nombre del microservicio] -> Información).
Veamos cómo se ve la definición de una ruta 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. `);
Tanto la validación como la documentación se basan en el uso de un esquema de objeto. Haremos pequeños cambios agregando el campo de nombre:
'use strict'; const _ = require('lodash'); const joi = require('joi'); module.exports = { schema: {
Al ir al marcador API, puede asegurarse de que el esquema ha cambiado y ahora el objeto con el campo de nombre se puede agregar a la colección de gatos.
apapacy@gmail.com
12 de noviembre de 2018.