Mapa de límites de servicio: evita el acoplamiento accidental en tu código

Por qué el acoplamiento accidental sigue apareciendo

El acoplamiento accidental ocurre cuando partes de tu app dependen unas de otras sin intención. En la práctica, se convierte en pequeños cambios que terminan en cortes sorpresa, informes de errores confusos y jornadas de lanzamiento largas.

Lo ves cuando alguien toca una función y tres cosas más tambalean. Un ajuste en precios bloquea inscripciones. Un cambio en las plantillas de correo rompe los restablecimientos de contraseña. Actualizar una regla de compra hace que el panel de administración se caiga. Nada en el código deja esas conexiones evidentes, así que la gente solo las aprende por las malas.

Una causa común es el código compartido que sigue creciendo porque resulta cómodo. Un módulo helper, una tabla de base de datos o un servicio “común” se convierten en el lugar donde todos añaden “solo una cosa más”. Con el tiempo, ese punto compartido se transforma en un nudo apretado. No es que el equipo sea descuidado: la base de código enseña silenciosamente a acoplar cosas.

Suele empeorar a medida que más personas tocan el código. Los contribuyentes nuevos no conocen las reglas ocultas, así que copian patrones existentes. Bajo presión, toman el camino más corto: reutilizar una función, coger datos de una tabla que ya existe, llamar a un endpoint interno porque funciona. Cada arreglo rápido añade otro hilo invisible entre partes del sistema.

La propiedad poco clara multiplica el problema. Cuando nadie puede decir “este servicio posee los correos de cliente” o “este módulo posee las reglas de precios”, las revisiones se vuelven conjeturas. La gente o aprueba cambios que no entiende del todo, o bloquea releases por si acaso. En cualquier caso, el despliegue se vuelve arriesgado.

Algunas señales de que vives con acoplamiento accidental:

• Los bugs aparecen lejos del cambio que los causó
• Los lanzamientos requieren muchas pruebas manuales “para estar seguros”
• Los equipos discuten sobre dónde debería vivir una pieza de lógica
• Evitas refactorizaciones porque todo se siente frágil
• Las correcciones necesitan múltiples revisores porque la propiedad no está clara

Qué es un mapa de límites de servicio (en términos sencillos)

Un mapa de límites de servicio es una imagen simple de tu sistema que responde tres preguntas: cuáles son los dominios (las grandes áreas de responsabilidad), quién posee cada dato y quién llama a qué. Piensa en él como un boceto etiquetado de la base de código, no un muro de diagramas.

Un buen mapa suele incluir los dominios principales (por ejemplo Accounts, Billing, Projects), qué datos posee cada dominio (tablas, documentos, entidades clave), las dependencias entre dominios (llamadas API, eventos, librerías compartidas) y los puntos de integración con el exterior (pagos, correo, almacenamiento).

Lo que no es: una reescritura arquitectónica completa o un plan perfecto de microservicios. Puedes hacer un mapa de límites de servicio para un monolito, un conjunto de funciones serverless o un prototipo a medio hacer. El objetivo es claridad, no “arquitectura ideal”.

El valor real son las decisiones que desbloquea. Con un mapa puedes responder preguntas como:

• ¿Dónde debe vivir esta nueva función?
• ¿Quién posee estos datos?
• Si cambiamos esto, ¿qué más se rompe?
• ¿Qué deberíamos aislar primero para reducir riesgo?

Así es como detienes el acoplamiento accidental: evitas que el trabajo nuevo atraviese límites sin que nadie lo note.

Un ejemplo concreto: alguien pide “añadir invitaciones de equipo”. Sin un mapa, un solo pull request podría tocar autenticación, perfiles de usuario, envío de correos y comprobaciones de facturación, con escrituras compartidas por todas partes. Con un mapa de límites de servicio, puedes mantenerlo contenido: las invitaciones pertenecen a Accounts, los correos pasan por un punto de integración único y las reglas de facturación siguen siendo propiedad de Billing.

Esto no es solo para ingenieros. Fundadores lo usan para entender por qué los “cambios pequeños” tardan más de lo esperado. Agencias que heredan una base de código desordenada lo usan para planear trabajo sin empeorar el lío.

Qué recopilar antes de empezar

Un mapa de límites de servicio vale lo que valen sus entradas. Antes de dibujar cajas y flechas, recoge los hechos básicos para mapear la realidad, no opiniones.

1) Decide el alcance (para que el mapa siga siendo útil)

Elige un límite que coincida con las decisiones que necesitas tomar a continuación. Si la meta es evitar que las nuevas funciones creen nuevo acoplamiento, no siempre necesitas el sistema entero el primer día.

Alcances comunes:

• Un repositorio
• Un área de producto
• Todo el sistema
• Un flujo de alto riesgo (auth, facturación, onboarding)

Escribe el alcance en una frase. Mantiene cortas las discusiones.

2) Reúne las entradas que muestran cómo corre realmente el sistema

Buscas todas las formas en que se activa el código y cada lugar donde los datos cruzan un límite. Junta:

• Puntos de entrada: rutas, endpoints, webhooks
• Trabajo no basado en requests: jobs en background, colas, tareas cron, programadores
• Integraciones de terceros: pagos, correo, analytics, almacenamiento, proveedores de auth
• Almacenamientos de datos: bases de datos, caches, buckets de archivos (tablas y entidades a alto nivel)
• El “pegamento” actual: librerías compartidas, config compartida, scripts administrativos compartidos

Manténlo a alto nivel. No necesitas cada columna de cada tabla. Necesitas lo suficiente para ver la propiedad y las colisiones.

Formato y límite de tiempo

Elige un formato que tu equipo realmente vaya a actualizar: foto de una pizarra, un doc con encabezados o una herramienta de diagramas simple.

Ponle límite de tiempo para que no se alargue. Un buen punto de partida es 60 a 90 minutos para recopilar entradas y luego una sesión de seguimiento para cubrir huecos.

Encuentra los dominios y los límites reales

Empieza por lo que los usuarios pueden hacer, no por cómo está organizado el repo. Un buen mapa suele comenzar con capacidades que alguien describiría en lenguaje llano: registrarse, iniciar sesión, gestionar facturación, buscar, enviar mensajes, trabajo de administración. Esas son pistas de tus dominios reales.

Una prueba simple: si puedes describir una parte del sistema en una frase sin palabras técnicas, probablemente sea un dominio. Si necesitas tres frases y un diagrama, podría ser que sean dos dominios pegados.

Agrupa por significado, no por carpetas

Los nombres de carpetas a menudo reflejan la historia, no la intención. En su lugar, busca sustantivos y verbos de negocio en código, tickets y etiquetas de UI. Luego agrupa componentes, rutas, jobs y tablas por su significado.

Escribe un propósito estricto de una frase para cada dominio:

• “Accounts maneja el registro, el inicio de sesión y la configuración de identidad.”
• “Billing gestiona planes, facturas, pagos y el estado de suscripción.”
• “Messaging maneja conversaciones, entrega y estado de lectura.”

Si te descubres añadiendo “y además,” has encontrado un problema de límites.

Separa utilidades compartidas de la lógica de negocio compartida

Compartir un formateador de fechas está bien. Compartir “reglas de suscripción” entre tres áreas es cómo se propaga el acoplamiento.

Una comprobación rápida cuando veas código compartido:

• Helpers puros (formateo, logging, cliente HTTP) pueden ser compartidos.
• Reglas (quién puede reembolsar, qué cuenta como activo) deben pertenecer a un dominio.
• Si dos dominios necesitan la misma regla, expónla vía API o evento, no con un archivo compartido.

También marca los puntos calientes: partes que cambian cada semana, rompen tests o generan PRs “pequeños” que tocan muchos archivos. Los puntos calientes suelen significar responsabilidades mezcladas.

Documenta la propiedad de datos para que los cambios dejen de chocar

La mayoría de los problemas de acoplamiento empiezan con un error simple: dos partes del sistema escriben en los mismos datos. Al principio parece más rápido, pero convierte cada cambio en una negociación.

Empieza escogiendo un dominio (Accounts, Billing, Content) y nombra los datos que posee. Sé específico. “Datos de usuario” es vago. “tabla users, tabla password_reset_tokens y archivos profile_images” es lo suficientemente claro para que la gente lo siga.

Luego escribe una regla y síguela: el propietario escribe, todos los demás leen a través de un límite. Ese límite puede ser una llamada API, un mensaje/evento o una vista de solo lectura que controla el propietario. La tecnología importa menos que la disciplina.

Una plantilla simple para cada dominio:

• Datos propiedad (tablas, colecciones, archivos/buckets)
• Regla de escritura (quién puede escribir y cómo)
• Ruta de lectura (API, evento, vista de reporting, job de exportación)
• Campos sensibles (PII, tokens de auth, detalles de pago, secretos)
• Propietario claro (nombre del equipo o un rol nombrado)

Las tablas compartidas son el punto caliente del acoplamiento. Si encuentras una tabla que “todos usan” (a menudo users, subscriptions, permissions, audit_logs), no lo aceptes como normal. Márcala como compartida, nombra quién se convierte en el verdadero propietario y acuerda un plan de transición. A veces el plan es “mover escrituras detrás de una API primero, dividir la tabla después.” Eso ya evita que nuevo acoplamiento se acumule.

Los datos sensibles merecen atención extra. Si tokens de auth, hashes de contraseña o detalles de pago se almacenan en múltiples lugares, tendrás bugs de seguridad y correcciones desordenadas. Un solo propietario debe controlar el almacenamiento y el acceso; otros dominios deben solicitar lo que necesiten sin copiar secretos.

Mapea dependencias y puntos de integración

Una vez que conoces los dominios, el siguiente problema de acoplamiento suele estar oculto en las conexiones entre ellos. Un mapa solo ayuda si muestra cómo el código realmente habla con otro código.

Empieza por llamadas directas: rutas HTTP, importaciones de módulos internos que atraviesan un límite, clientes SDK usados para pagos o correo, y librerías compartidas que se vuelven un “god package”.

Luego captura llamadas indirectas también. Un flujo de registro puede encolar un job, disparar un webhook y ejecutar una tarea programada más tarde que actualiza facturación. Nada se rompe de inmediato, pero la dependencia sigue siendo real.

Para cada punto de integración, anota:

• Dirección: quién depende de quién
• Contrato: esquema de la API, nombre del evento, payload del webhook, tabla/vista límite
• Atajos: lecturas directas de BD, vars de entorno compartidas, middleware de auth compartido
• Tipo de disparador: request síncrona, job asíncrono, webhook, tarea programada
• Propietario: quién lo arregla cuando se rompe

Los contratos son acoplamiento sano. Los atajos son acoplamiento accidental. “Simplemente importa el modelo user” o “simplemente lee esa tabla” funciona hasta que llega un refactor y todo falla.

Finalmente, marca cadenas riesgosas. Busca llamadas en abanico donde una acción golpea muchos servicios o módulos y las fallas se propagan. Ejemplo: una sola petición “Create Project” llama a auth, escribe en dos bases, publica en Slack, inicia un job de onboarding y pingea analytics. Eso es difícil de probar y fácil de romper.

Cómo crear el mapa paso a paso

Un mapa de límites de servicio solo ayuda si se mantiene simple. Dibuja la imagen más pequeña que impida que la gente haga cambios que unan partes del sistema sin darse cuenta.

Paso 1: Dibuja los dominios como cajas

Empieza con una página en blanco y dibuja 4 a 8 cajas. Nombra cada caja como la gente habla del negocio, no como está organizado el repo.

Debajo de cada caja, escribe una frase que describa el resultado que posee. Por ejemplo: “Billing crea facturas y registra pagos.” Si no puedes decirlo en una frase, la caja probablemente es demasiado grande.

Paso 2: Adjunta los datos que cada caja posee

Para cada caja, lista los datos que posee en palabras simples, cortas y concretas: “Facturas”, “Métodos de pago”, “Perfiles de usuario”, “Proyectos”, “API keys”.

Datos propiedad significa que ese dominio es el único permitido para escribirlos. Otros leen solo a través de una ruta acordada (una llamada, una vista o un evento exportado).

Paso 3: Añade flechas para llamadas y eventos

Dibuja flechas entre cajas por cada interacción que conozcas: llamadas API, eventos de mensajes, jobs en background, tareas programadas, cualquier cosa que mueva datos.

Si trabajas sobre un prototipo generado por IA, no confíes en la estructura de carpetas. Encuentra interacciones reales buscando llamadas HTTP internas, acceso directo a la base de datos desde un módulo incorrecto, jobs programados y handlers de webhooks.

Paso 4: Etiqueta cada flecha con lo que se intercambia

En cada flecha escribe qué se intercambia, no cómo está escrito. Buenas etiquetas: “Crear factura”, “Obtener perfil de usuario”, “Evento pago completado”, “Sincronizar estado del proyecto”. El significado debe permanecer estable aunque el código cambie.

Paso 5: Marca señales de alerta en el mapa

Marca patrones que crean acoplamiento accidental:

• Escrituras compartidas (dos dominios actualizando los mismos datos)
• Llamadas circulares (A llama a B y B llama a A)
• Jobs cron ocultos que actualizan datos “por el costado”
• Una caja que lo sabe todo (un servicio dios)
• Datos copiados en varios sitios sin una fuente de verdad

Paso 6: Escribe 3 a 5 reglas de frontera que seguirás

Añade una nota junto al mapa con reglas que la gente pueda recordar:

• Solo el dominio propietario escribe sus datos.
• Las lecturas entre dominios ocurren mediante una API definida o una vista exportada, no por acceso directo a la BD.
• Los eventos describen hechos (“Payment succeeded”), no comandos (“Actualizar facturación”).
• No hay dependencias circulares.
• Las tareas programadas viven en el dominio que afectan y aparecen en el mapa.

Ejemplo: convertir un prototipo enmarañado en dominios claros

Imagina un prototipo común: registro e inicio de sesión, página de perfil de usuario, pantalla de facturación y panel de administración. Funciona en demos, pero cada cambio rompe otra cosa.

Un problema raíz común es una sola tabla users sobrecargada que toca cada función. El código de login escribe en ella. El panel de administración la edita directamente. Facturación guarda el estado del plan ahí. La configuración del perfil vive ahí también. Una petición rápida de “añadir una columna” se vuelve una migración riesgosa que afecta cuatro partes de la app, además de un revoltijo de helpers compartidos.

Un mapa de límites de servicio hace visible el acoplamiento oculto y lo reemplaza por propiedad clara.

Qué cambia el mapa de límites

Puedes mantener la misma base de datos al principio, pero deja de tratarla como un cubo compartido. Define algunos dominios y haz que cada uno sea responsable de sus propios datos:

• Auth posee credenciales y sesiones (hashes de contraseña, enlaces OAuth, tokens de refresco).
• Profiles posee configuraciones visibles por el usuario (nombre para mostrar, preferencias, opciones de notificación).
• Billing posee dinero y derechos (clientes, facturas, historial de planes, estado de pago).
• Admin posee moderación y herramientas internas (flags, audit_logs, asignaciones de roles).

Luego haz la regla explícita: otros dominios no escriben en tablas que no poseen. Si Billing necesita saber “¿está activo este usuario?”, pregunta a Auth o lea una vista de derechos explícita controlada por Billing.

Reemplazar escrituras directas en DB por un límite API básico

En el prototipo enmarañado, la página de facturación podría actualizar directamente users.plan = 'pro'. Tras mapear límites, Billing llama algo como Billing.createSubscription(userId, planId) y actualiza sus propios registros. Si Auth necesita aplicar acceso, consulta el derecho actual de Billing mediante un punto de integración pequeño y definido.

Para evitar que el trabajo nuevo reintroduzca acoplamiento, establece expectativas para las solicitudes de funciones:

• Añade campos solo en el dominio propietario.
• Si necesitas datos de otro dominio, crea una API de lectura en lugar de una escritura compartida.
• Evita “solo una columna más en users” a menos que Auth realmente la posea.

Errores comunes que mantienen vivo el acoplamiento

El acoplamiento accidental no suele ocurrir porque la gente sea descuidada. Ocurre porque los equipos eligen un límite que parece ordenado en la superficie y siguen deployando sin comprobar si los límites reflejan la realidad.

Una trampa común es tratar el árbol de carpetas como modelo de dominio. Muchas bases de código (especialmente las generadas por IA) agrupan archivos por convenciones del framework, no por significado de negocio. Si tu mapa refleja las carpetas actuales, puedes terminar documentando el desorden en vez de encontrar costuras limpias.

Otra trampa es fragmentar demasiado pronto. Dividir en muchos servicios pequeños puede parecer progreso, pero si no has acordado la propiedad de datos, creas más llamadas, más modos de fallo y más debates. Aclara los límites de datos primero, luego decide qué merece despliegue independiente.

Errores recurrentes:

• Usar nombres de paquetes como frontera, aun cuando una función toca tres “dominios” en la práctica
• Dividir en muchos servicios antes de acordar quién posee qué datos y reglas
• Permitir que múltiples dominios sigan escribiendo en la misma tabla indefinidamente
• Mapear solo APIs request–response y olvidar jobs, cron, colas y webhooks
• Tratar el mapa como un artefacto de taller de una sola vez en vez de un documento vivo

El mapeo de dependencias también falla cuando ignora rutas silenciosas. Ejemplo: una página de Billing llama a una API de pagos, pero un job nocturno actualiza facturas y un webhook marca pagos como liquidados. Si esos no están en el mapa, la gente hace cambios que parecen seguros en la UI pero rompen la contabilidad a la mañana siguiente.

Lista rápida de verificación y siguientes pasos

Usa esto como control después de haber borrador tu mapa. Si no puedes responder una de estas en una frase, ahí suele esconderse el acoplamiento accidental.

Lista rápida

• Cada conjunto de datos tiene un propietario claro, y los demás lo leen mediante una interfaz acordada
• No hay dependencias circulares entre servicios o módulos
• Los contratos están escritos (aunque sea como una nota corta): qué espera una llamada, qué devuelve, qué significan los errores
• Los puntos de integración son visibles: colas, webhooks, cron jobs, librerías compartidas, accesos directos a DB
• El impacto del cambio es predecible: puedes nombrar qué debe cambiar cuando un campo o una regla cambian

Una forma simple de mantener útil el mapa: trátalo como código. Cuando alguien añade una dependencia nueva, una tabla nueva o una integración nueva, actualiza el mapa en el mismo pull request. Si eso se siente pesado, mantenlo ligero: una captura de pantalla o un párrafo corto suele ser suficiente.

Siguientes pasos que realmente reducen el acoplamiento

Elige un objetivo de refactor basado en riesgo, no en conveniencia. El mejor primer objetivo suele ser el punto donde un cambio pequeño causa caídas, problemas de seguridad o retrabajo repetido.

• Elige el punto de acoplamiento de mayor riesgo (tablas compartidas, lógica de auth usada en todas partes o un servicio dios)
• Escribe una regla de frontera que aplicarás la próxima semana (por ejemplo: “ningún servicio escribe en las tablas de otro servicio”)
• Añade una comprobación pequeña de fronteras para que las roturas aparezcan pronto (una prueba de contrato, validación de esquema o un guard simple)

Si tu base de código fue generada por herramientas de IA y se desordenó rápido, los límites en papel a menudo no coinciden con el comportamiento real en el código. Si quieres una segunda opinión, FixMyMess (fixmymess.ai) ofrece una auditoría de código gratuita y puede ayudar a identificar dependencias ocultas, conflictos de propiedad de datos y problemas de seguridad antes de que te comprometas a una gran reconstrucción.