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;
}
}
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:
| Estrategia | Enruta por | Uso típico |
|---|---|---|
| Ruta | /users/*, /orders/* | Un servicio por dominio de recursos |
| Host | api.example.com, admin.example.com | Separar APIs públicas y de administración |
| Encabezado | X-API-Version, Accept | APIs versionadas, negociación de contenido |
| Método | GET vs POST | Réplicas de lectura vs primarios de escritura |
| Ponderado | Reparto porcentual | Lanzamientos 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
| Variante | Caso de uso | Compromiso |
|---|---|---|
| API Gateway | Exponer APIs públicas a clientes externos | Centralizado pero puede ser cuello de botella |
| Backend for Frontend | Adaptar APIs a clientes web, móvil o socios | Añade un servicio por tipo de cliente |
| Edge Gateway | Gestionar TLS, DDoS y caché en el borde de red | Simplifica orígenes pero añade dependencia del proveedor |
| Gateway Interno | Enrutar tráfico dentro de un clúster con mTLS | Mantiene 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
/apise 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
- Código complementario: el repo companion de gateway-routing-pattern - gateway Express ejecutable, configuración NGINX y demo con Docker Compose con upstreams echo
- Guía de diseño de API Gateway - patrones de resiliencia, seguridad y escalado para gateways en producción
- Patrón Strangler Fig - el enrutamiento de gateway es como se despegan rutas de un monolito
- Patrón Anti-Corruption Layer - cuando el gateway también debe traducir entre modelos de dominio
- Microsoft: patrón Gateway Routing - la entrada del catálogo en la que se basa este patrón
- Documentación del módulo proxy de NGINX -
proxy_passy configuración de upstreams - http-proxy-middleware - el middleware de Express usado en los ejemplos
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.
Recursos Relacionados
Diseño de API Gateway: Resiliencia, Enrutamiento y Seguridad
Guía práctica para diseñar API gateways: enrutamiento, autenticación, rate limiting, circuit breakers, caché y patrones de despliegue para APIs resilientes.
PatternPatrón Backend for Frontend (BFF)
Dale a cada tipo de cliente su propio backend, que agrega los servicios de dominio y adapta la forma de los datos a cada plataforma.
PatternAnti-Corruption Layer: aísla el legacy con adaptadores
Cómo aislar sistemas legacy con adaptadores de traducción. Cubre la facade ACL, traducción de dominio, mapeo bidireccional y reemplazo gradual del legacy.
PatternPatrón Strangler Fig
Cómo reemplazar gradualmente un legacy system interceptando routes y routeando traffic a new services. Cubre strangler fig, incremental migration, y cutover.
GuideGuía Completa de Kubernetes Ingress
Configura y soluciona problemas de Kubernetes Ingress. Cubre controladores, TLS con cert-manager, enrutamiento por path, anotaciones y Gateway API.
PatternPatrón Health Check: Sondeos de Liveness y Readiness
Implementa sondeos de liveness y readiness para orquestadores. Cubre probes en Kubernetes, chequeos de dependencias y degradación elegante.