StackPractices
intermediate Por Mathias Paulenko

Patrón de Enrutamiento de Gateway

Enruta solicitudes a múltiples servicios backend a través de un único punto de entrada que gestiona preocupaciones transversales.

Visión General

El Patrón de Enrutamiento de Gateway coloca un único punto de entrada frente a múltiples servicios backend. En lugar de dejar que cada servicio mire de cara a los clientes, el gateway toma cada solicitud y la envía al upstream que coincida, por ruta, método, encabezado o cualquier regla que configures. También centraliza preocupaciones transversales como la terminación TLS, la autenticación, el rate limiting y el registro, para que los servicios individuales no tengan que hacerlo.

El patrón proviene del catálogo de diseño para la nube publicado por Microsoft, donde convive con Gateway Offloading y Gateway Aggregation. Los tres comparten la misma idea: los clientes deben hablar con una sola dirección estable, y todo lo que hay detrás de esa dirección debe poder cambiar libremente. Pueden aparecer servicios nuevos, moverse o dividirse los existentes, y los clientes ni se enteran porque la tabla de enrutamiento absorbe el cambio.

Esto importa sobre todo en arquitecturas de microservicios, donde una sola acción del usuario suele desplegarse en una docena de servicios. También rinde durante las migraciones: despega endpoints del monolito ruta a ruta mientras la API pública no se mueve.

Cuándo Usar

Usa este patrón cuando:

  • Tengas múltiples servicios backend que los clientes deben alcanzar a través de una sola dirección
  • Necesites aplicar TLS, autenticación o rate limiting en un solo lugar
  • Quieras enrutar tráfico por ruta URL, host o versión de API sin cambiar clientes
  • Estés migrando de un monolito a microservicios y necesites ocultar cambios internos
  • Necesites componer respuestas de varios servicios o traducir entre protocolos

Sáltalo cuando un único backend atienda todo el tráfico (un proxy inverso basta), o cuando los servicios ya vivan detrás de un service mesh completo que gestione el enrutamiento interno; añadir una segunda capa de enrutado solo duplica los saltos. El gateway tampoco es el lugar para reglas de negocio; si las decisiones de enrutado necesitan conocimiento del dominio, esa lógica pertenece a los servicios o a una capa de Backend for Frontend.

Hay otro límite que conviene marcar pronto: el gateway enruta solicitudes, no las orquesta. Si un cliente necesita datos de cinco servicios unidos en una sola respuesta, eso es agregación, un patrón distinto con modos de fallo distintos.

Solución

En su forma más simple, un gateway es una tabla de enrutamiento más un proxy. Esta configuración de Express reenvía cada prefijo de ruta a un servicio upstream distinto:

// Configuración mínima de gateway (Express + http-proxy-middleware)
import express from 'express';
import { createProxyMiddleware } from 'http-proxy-middleware';

const app = express();

app.use('/users', createProxyMiddleware({
  target: 'http://users-service:3001',
  changeOrigin: true,
}));

app.use('/orders', createProxyMiddleware({
  target: 'http://orders-service:3002',
  changeOrigin: true,
}));

app.use('/inventory', createProxyMiddleware({
  target: 'http://inventory-service:3003',
  changeOrigin: true,
}));

app.listen(3000, () => console.log('Gateway escuchando en el puerto 3000'));

El mismo enrutado se traduce directamente a NGINX, que es lo que usan la mayoría de los gateways en producción:

# Enrutamiento por ubicación en NGINX
server {
  listen 443 ssl;
  server_name api.example.com;

  location /users {
    proxy_pass http://users-service;
  }

  location /orders {
    proxy_pass http://orders-service;
  }

  location /inventory {
    proxy_pass http://inventory-service;
  }
}
flowchart diagram: Clientes

Los clientes solo ven la dirección del gateway. Todo lo que hay a su derecha puede escalar, moverse o reemplazarse sin cambiar nada en el cliente.

Explicación

Cuando llega una solicitud, el gateway la pasa por un pipeline de coincidencia: extrae los atributos de la solicitud (ruta, host, método, encabezados), encuentra la primera regla que coincide, aplica la cadena de middleware de esa ruta y reenvía la solicitud al upstream seleccionado. La respuesta vuelve por el mismo gateway, que puede reescribir encabezados, envolver el payload o cachear el resultado antes de devolverlo.

Las reglas de coincidencia son el corazón del patrón. Estrategias habituales:

EstrategiaEnruta porUso típico
Ruta/users/*, /orders/*Un servicio por dominio de recursos
Hostapi.example.com, admin.example.comSeparar APIs públicas y de administración
EncabezadoX-API-Version, AcceptAPIs versionadas, negociación de contenido
MétodoGET vs POSTRéplicas de lectura vs primarios de escritura
PonderadoReparto porcentualLanzamientos canary, rollouts A/B

Las reglas se evalúan en orden, así que pon primero las rutas más específicas. Un bug habitual: declarar /api antes que /api/admin manda el tráfico de administración al servicio de la API general.

Cuatro responsabilidades suelen acompañar al enrutado:

  • Balanceo de carga: distribuir solicitudes entre instancias upstream saludables, sacando de la rotación las caídas
  • Seguridad: terminar TLS, validar tokens y aplicar rate limits antes de que el tráfico llegue a los servicios
  • Observabilidad: asignar un ID de correlación en el borde para que cada log y traza upstream lo comparta; mira Health Check Pattern para la parte de health checks
  • Resiliencia: timeouts, reintentos acotados y circuit breakers para evitar que un servicio lento arrastre a todo el gateway

Algunos casos límite muerden en producción. Las barras finales importan: /users y /users/ pueden coincidir con reglas distintas según el proxy, así que normalízalas en el borde. El caso de los encabezados es inconsistente entre clientes: Node los pasa a minúsculas, algunos stacks de Java no. Las subidas grandes y los streams SSE/WebSocket necesitan el proxy configurado para reenviar cuerpos y hacer upgrade de conexiones en lugar de buferear la solicitud entera. Y los redirects que emiten los upstreams deben reescribir sus encabezados Location, o los clientes rebotan a un hostname interno que no pueden resolver.

La contrapartida es que el propio gateway se convierte en infraestructura crítica. Toda solicitud pasa por él, así que una caída del gateway es una caída total. Ejecuta al menos dos instancias detrás de un balanceador, mantén el gateway sin estado para que cualquier instancia sirva cualquier solicitud, y vigila su presupuesto de latencia: cada middleware de la cadena añade milisegundos que paga cada solicitud.

Variantes

VarianteCaso de usoCompromiso
API GatewayExponer APIs públicas a clientes externosCentralizado pero puede ser cuello de botella
Backend for FrontendAdaptar APIs a clientes web, móvil o sociosAñade un servicio por tipo de cliente
Edge GatewayGestionar TLS, DDoS y caché en el borde de redSimplifica orígenes pero añade dependencia del proveedor
Gateway InternoEnrutar tráfico dentro de un clúster con mTLSMantiene el tráfico privado pero se solapa con el mesh

El enrutamiento de gateway también se solapa con dos vecinos. Un service mesh enruta entre servicios dentro del clúster: es tráfico este-oeste, mientras el gateway es dueño del tráfico norte-sur que viene de fuera. Muchos sistemas ejecutan ambos. Un Backend for Frontend va más allá del enrutado: compone y remodela respuestas para un tipo de cliente, a costa de un gateway por cliente. Si tus reglas de enrutado empiezan a acumular lógica de composición de respuestas, esa es la señal para extraer un BFF en lugar de engordar el gateway.

Elegir implementación se reduce a quién debe ser dueño de la capa de enrutado. Los archivos de configuración de NGINX o HAProxy funcionan cuando la tabla de rutas cambia poco y el equipo de ops ya los gestiona. Un gateway gestionado (AWS ALB, Azure Application Gateway, Cloudflare) cambia flexibilidad por uptime y protección DDoS de terceros. Los gateways a nivel de aplicación como el ejemplo de Express encajan en equipos que quieren la lógica de enrutado en el mismo lenguaje y pipeline de despliegue que sus servicios. En Kubernetes, el mismo patrón aparece como controladores Ingress y la Gateway API, cubierto en profundidad en la guía de Kubernetes Ingress.

Lo que Funciona

  • Mantén el gateway sin estado para que escale horizontalmente y sobreviva a la pérdida de instancias
  • Guarda las reglas de enrutado en configuración (YAML, un plano de control, descubrimiento de servicios), no en código
  • Usa health checks para que el tráfico solo fluya a instancias que responden
  • Descarga TLS en el gateway para sacar la gestión de certificados de los servicios
  • Limita la lógica del gateway a preocupaciones transversales; en cuanto una ruta necesite reglas de dominio, muévela
  • Asigna un ID de correlación en el borde y propágalo a cada llamada upstream

Errores Comunes

  • Meter lógica de negocio en el gateway, donde es difícil de probar y versionar
  • Enrutar cada microservicio por un único gateway infradimensionado; ese es el problema del SPOF. Ejecuta dos o más instancias con health checks
  • Ignorar la configuración de timeout y reintentos, que convierte un upstream lento en fallos en cascada
  • Sobrecargar el gateway con transformaciones pesadas; el remodelado complejo pertenece a un BFF
  • Olvidar validar los certificados TLS en las conexiones upstream, lo que desactiva en silencio la autenticación entre saltos
  • Ordenar mal las reglas, de modo que un patrón amplio como /api se traga el tráfico destinado a una ruta específica

Patrones Avanzados

Los ejemplos estáticos de arriba cubren el caso común. Cuando el tráfico crece, cuatro extensiones aparecen una y otra vez: resolución dinámica de upstreams, circuit breaking por servicio, transformación y repartos ponderados.

Enrutamiento dinámico con descubrimiento de servicios

Las tablas de rutas estáticas quedan obsoletas en cuanto los servicios autoescalan o se redespliegan. Conectar el gateway a un registro de servicios mantiene los upstreams al día: cuando las instancias se registran o dan de baja, el router las resuelve de nuevo por solicitud.

import express from 'express';
import { randomUUID } from 'node:crypto';
import { createProxyMiddleware } from 'http-proxy-middleware';
import { ServiceRegistry } from './service-registry';

class DynamicGateway {
  private registry: ServiceRegistry;
  private app: express.Application;

  constructor(registry: ServiceRegistry) {
    this.registry = registry;
    this.app = express();
  }

  async setupRoutes() {
    // El middleware de ID de correlación debe ejecutarse antes que cualquier ruta proxy.
    this.app.use((req, _res, next) => {
      req.headers['x-request-id'] ??= randomUUID();
      next();
    });

    const services = await this.registry.getAllServices();

    services.forEach(service => {
      this.app.use(service.path, createProxyMiddleware({
        target: `http://${service.instances[0].host}:${service.instances[0].port}`,
        changeOrigin: true,
        router: () => {
          // Sustituto del round-robin: elige una instancia saludable por solicitud.
          const healthy = service.instances.filter(i => i.healthy);
          const pick = healthy[Math.floor(Math.random() * healthy.length)];
          return `http://${pick.host}:${pick.port}`;
        },
        onProxyReq: (proxyReq, req) => {
          proxyReq.setHeader('X-Request-ID', req.headers['x-request-id']);
        },
        onError: (_err, _req, res) => {
          (res as express.Response).status(502).json({ error: 'Bad Gateway' });
        },
      }));
    });
  }

  listen(port: number) {
    this.app.listen(port, () => console.log(`Gateway escuchando en ${port}`));
  }
}

Circuit breaker por upstream

Envolver cada llamada upstream en un circuit breaker evita que un servicio que falla agote el pool de conexiones del gateway. El estado vive por servicio, así que un upstream muerto no dispara los demás:

import CircuitBreaker from 'opossum';

const breakerOptions = {
  timeout: 3000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000,
};

class CircuitBreakerGateway {
  private breakers = new Map<string, CircuitBreaker>();

  getBreaker(serviceName: string) {
    if (!this.breakers.has(serviceName)) {
      const breaker = new CircuitBreaker(
        async (url: string, init: RequestInit) => {
          const response = await fetch(url, init);
          if (!response.ok) throw new Error(`HTTP ${response.status}`);
          return response.json();
        },
        breakerOptions,
      );

      breaker.on('open', () => console.log(`Circuito abierto para ${serviceName}`));
      breaker.on('halfOpen', () => console.log(`Circuito medio-abierto para ${serviceName}`));
      breaker.on('close', () => console.log(`Circuito cerrado para ${serviceName}`));

      this.breakers.set(serviceName, breaker);
    }
    return this.breakers.get(serviceName)!;
  }

  async proxyRequest(serviceName: string, path: string, method: string, body?: string) {
    const breaker = this.getBreaker(serviceName);
    return breaker.fire(`http://${serviceName}:3001${path}`, {
      method,
      headers: { 'content-type': 'application/json' },
      body,
    });
  }
}

Transformación de solicitudes y respuestas

La inyección de encabezados y el envoltorio de respuestas son transformaciones seguras a nivel de gateway. La traducción de protocolos es más pesada. El bloque gRPC de abajo es un boceto, no código ejecutable, porque necesita un cliente generado:

import express from 'express';

class TransformGateway {
  private app = express();

  setupTransforms() {
    // Inyectar encabezados antes del enrutado.
    this.app.use('/api/v1', (req, _res, next) => {
      req.headers['x-api-version'] = 'v1';
      req.headers['x-request-time'] = new Date().toISOString();
      next();
    });

    // Envolver las respuestas v2 en un sobre meta.
    this.app.use('/api/v2', (_req, res, next) => {
      const originalJson = res.json.bind(res);
      res.json = (data: unknown) => originalJson({
        meta: { version: 'v2', timestamp: new Date().toISOString() },
        data,
      });
      next();
    });

    // Boceto: traducción REST a gRPC. Conecta aquí un cliente generado;
    // loadGrpcClient y los mappers vienen de tu toolchain de proto.
    this.app.post('/grpc-proxy', async (req, res) => {
      try {
        // const client = loadGrpcClient('users-service');
        // const grpcRes = await client.getUser(mapRestToGrpc(req.body));
        // res.json(mapGrpcToRest(grpcRes));
        res.status(501).json({ error: 'Traducción gRPC no configurada' });
      } catch {
        res.status(500).json({ error: 'Fallo de traducción gRPC' });
      }
    });
  }
}

Enrutamiento ponderado para lanzamientos canary

Un reparto porcentual envía una pequeña parte del tráfico a la versión nueva mientras el resto sigue en la estable. Adelanta el peso mientras las métricas sigan en verde:

# Enrutamiento ponderado: 10% del tráfico al canary
routes:
  - path: /api/users
    upstreams:
      - service: users-service-v1
        weight: 90
      - service: users-service-v2   # canary
        weight: 10

Acompáñalo de rate limiting por cliente (contadores en Redis para gateways distribuidos) y rollback automático cuando suben las tasas de error; el canary solo es seguro si algo lo está vigilando.

Véase También

Preguntas frecuentes

¿Cuál es la diferencia entre Gateway Routing y un API Gateway?

El enrutamiento es la pieza que empareja solicitudes con upstreams. Un API Gateway es el producto construido alrededor, así que normalmente trae autenticación, rate limiting, transformación y un portal de desarrolladores incluidos.

¿Debería el gateway gestionar reintentos?

Puede reintentar solicitudes seguras e idempotentes (GET, PUT con claves de idempotencia), pero ten cuidado con POST y otras operaciones que cambian estado; un cobro o un pedido reintentado puede duplicar trabajo. Acota siempre los reintentos y añade jitter.

¿Puedo usar este patrón con funciones serverless?

Funcionan sin problema. Cada función se registra como destino upstream y se enruta por ruta o método, igual que un servicio en contenedor. La pega es el arranque en frío: una función dormida puede añadir segundos, así que dimensiona tu presupuesto de timeout para ello.

¿Cómo gestiono la autenticación en el gateway?

Valida JWTs o claves de API en el borde y luego entrega la identidad a los servicios como encabezados firmados tipo X-User-Id y X-Scopes. Los servicios comprueban la firma, que es más barato y seguro que reprocesar tokens en cada salto.

¿Debería el gateway cachear respuestas?

Cachear respuestas GET de datos calientes rinde rápido, pero respeta el Cache-Control de los upstreams y planifica la invalidación; un dato obsoleto servido rápido sigue siendo obsoleto.

¿Cómo monitorizo el rendimiento del gateway?

Empieza por latencia p50/p99, tasa de errores y throughput por ruta, más la salud de los upstreams. El tracing distribuido con el ID de correlación es lo que une un span del gateway con los spans de los servicios detrás.