Galduria Software – Microservice Core

gs-microservice-core es un paquete opinionated para la creación de microservicios basados en Node.js y Express, utilizado como núcleo común en la plataforma Factal y en otros productos de Galduria Software.

Su objetivo es estandarizar y acelerar la creación de microservicios proporcionando una configuración base común que incluye middlewares, logging, validación, manejo de errores y utilidades transversales.

Este paquete está pensado principalmente para uso interno, aunque se publica de forma abierta para facilitar su reutilización, pruebas y despliegue.
No contiene claves, secretos, certificados ni lógica de negocio sensible.

License

ISC

Funcionalidades

gs-microservice-core proporciona un conjunto de funcionalidades comunes para microservicios Node.js/Express, con el objetivo de reducir código repetido y garantizar comportamientos homogéneos entre servicios.

Incluye, entre otras, las siguientes características:

• Inicialización estandarizada de Express

  • Configuración base de la aplicación.
  • Preparado para ejecutarse detrás de proxies (Nginx, load balancers).

• Logging centralizado y estructurado

  • Integración con Morgan y Winston.
  • Logs en formato JSON, pensados para sistemas como CloudWatch.
  • Inclusión automática de información de contexto (requestId, navegador, sistema operativo, tipo de dispositivo, etc.).

• Identificador único de petición (requestId)

  • Asignación automática de un identificador único por request.
  • Permite trazar una petición a través de múltiples microservicios.

• Detección de User-Agent

  • Identificación del navegador, sistema operativo y tipo de dispositivo (desktop, mobile, tablet).
  • Información accesible desde el contexto de la petición y disponible en los logs.

• Validación de esquemas

  • Validación de payloads mediante esquemas JSON (AJV).
  • Respuestas de error homogéneas ante datos inválidos.

• Autenticación basada en JWT

  • Middleware opcional para validación de tokens JWT.
  • Pensado para escenarios de microservicios detrás de un API Gateway.

• Manejo centralizado de errores

  • Captura y normalización de errores no controlados.
  • Respuestas consistentes para el cliente.

• Configuración de seguridad básica

  • Integración con Helmet.
  • Configuración de CORS.

• Estructura común de respuestas

  • Respuestas HTTP homogéneas en todos los microservicios.
  • Facilita el consumo desde frontend y otros servicios.

Ejemplo de uso

A continuación se muestra un ejemplo básico de cómo inicializar un microservicio Express utilizando gs-microservice-core.

Ejemplo básico (sin autenticación)

import express from "express";
import { setupCoreMiddlewares, setupErrorHandler, standardResponse, logInfo } from "gs-microservice-core";

const app = express();

setupCoreMiddlewares(app, {
  gateway: false,
});

app.get("/health", (_req, res) => {
  standardResponse(res, 200, "Servicio operativo");
});

setupErrorHandler(app);

app.listen(3000, () => {
  logInfo("Servicio iniciado en el puerto 3000");
});

Ejemplo con autenticación

import express from "express";
import { setupCoreMiddlewares, setupErrorHandler, verifyToken, standardResponse } from "gs-microservice-core";

const app = express();

setupCoreMiddlewares(app, {
  jwtSecret: process.env.JWT_SECRET,
  gateway: false,
});

app.get("/secure", verifyToken, (req, res) => {
  standardResponse(res, 200, "Endpoint protegido", {
    userId: req.userId,
  });
});

setupErrorHandler(app);

app.listen(3000);

API

setupCoreMiddlewares(app, options)

Inicializa y configura los middlewares comunes del core en una aplicación Express.

Incluye, entre otros:

• logging y trazabilidad
• configuración de seguridad (Helmet)
• configuración de CORS
• parseo de JSON
• contexto de petición
• soporte para autenticación JWT

Firma

setupCoreMiddlewares(
  app: any,
  options?: {
    gateway?: boolean;
    jwtSecret?: string;
    helmetConfig?: HelmetOptions;
    corsOptions?: CorsOptions;
  }
): void

Parámetros

• app
  Instancia de Express sobre la que se aplicarán los middlewares.

• options.gateway (opcional, por defecto false)
  Indica si el microservicio actúa como API Gateway.

• options.jwtSecret (opcional)
  Clave secreta para la validación de tokens JWT.

• options.helmetConfig (opcional)
  Configuración personalizada para Helmet.

• options.corsOptions (opcional)
  Configuración personalizada para CORS.

setupErrorHandler(app)

Configura el manejador global de errores de la aplicación.

Captura errores no controlados y los transforma en respuestas homogéneas.

Firma

setupErrorHandler(app: any): void

Debe ejecutarse después de definir todas las rutas.

verifyToken

Middleware para validar tokens JWT en rutas protegidas. El middleware añade la información del usuario autenticado al objeto req.

Firma

verifyToken(req: any, res: any, next: any): void

verifyPublicToken

Middleware para validar tokens públicos.

Firma

verifyPublicToken(req: any, res: any, next: any): void

standardResponse(res, code, message, data?, time?, invalidatedAt?, schema?, count?)

Envía una respuesta HTTP estandarizada.

Firma

standardResponse(
  res: any,
  code: number,
  message: string,
  data?: any,
  time?: number,
  invalidatedAt?: Date,
  schema?: any,
  count?: number
): void

validateSchema(schema, data)

Valida datos contra un esquema definido.

Firma

validateSchema(schema: any, data: any): boolean

Logging

Funciones de logging integradas en el core.

logInfo

logInfo(message: string): void

logError

logError(error: any): void

logDebug

logDebug(message: string): void

logOperation

Registra información de una operación a partir del contexto de la petición.

logOperation(req: any): void

Errores comunes

Clases y catálogos de errores reutilizables.

AppError;
commonErrors;
commonHTTPErrors;