¿Qué hace Diseño de Codebase?
Diseña módulos profundos: mucho comportamiento detrás de una interfaz pequeña, colocada en un seam limpio, testeable a través de esa interfaz. Usa este lenguaje y estos principios dondequiera que se diseñe o reestructure código. El objetivo es apalancamiento para los llamadores, localidad para los mantenedores y testabilidad para todos.
Glosario
Usa estos términos exactamente — no sustituyas "componente", "servicio", "API" o "límite". El lenguaje consistente es el punto central.
Módulo — cualquier cosa con una interfaz y una implementación. Deliberadamente independiente de escala: una función, clase, paquete o slice que cruza capas. Evita: unidad, componente, servicio.
Interfaz — todo lo que un llamador debe saber para usar el módulo correctamente: la firma de tipos, pero también invariantes, restricciones de orden, modos de error, configuración requerida y características de rendimiento. Evita: API, firma (demasiado estrechos — se refieren solo a la superficie de tipos).
Implementación — lo que está dentro de un módulo, su cuerpo de código. Distinto de Adaptador: una cosa puede ser un adaptador pequeño con una implementación grande (un repositorio Postgres) o un adaptador grande con una implementación pequeña (un fake en memoria). Recurre a "adaptador" cuando el seam sea el tema; "implementación" en caso contrario.
Profundidad — apalancamiento en la interfaz: la cantidad de comportamiento que un llamador (o una prueba) puede ejercer por unidad de interfaz que tiene que aprender. Un módulo es profundo cuando una gran cantidad de comportamiento se encuentra detrás de una interfaz pequeña, y superficial cuando la interfaz es casi tan compleja como la implementación.
Seam (Michael Feathers) — un lugar donde puedes alterar el comportamiento sin editar en ese lugar; la ubicación donde vive la interfaz de un módulo. Dónde poner el seam es una decisión de diseño en sí misma, distinta de lo que hay detrás. Evita: límite (sobrecargado por el contexto delimitado de DDD).
Adaptador — una cosa concreta que satisface una interfaz en un seam. Describe el rol (qué hueco llena), no la sustancia (lo que hay dentro).
Apalancamiento — lo que los llamadores obtienen de la profundidad: más capacidad por unidad de interfaz que aprenden. Una implementación se amortiza a través de N sitios de llamada y M pruebas.
Localidad — lo que los mantenedores obtienen de la profundidad: el cambio, los bugs, el conocimiento y la verificación se concentran en un lugar en lugar de extenderse entre los llamadores. Arreglado una vez, arreglado en todas partes.
Profundo vs superficial
Módulo profundo = interfaz pequeña + mucha implementación:
┌─────────────────────┐
│ Interfaz Pequeña │ ← Pocos métodos, parámetros simples
├─────────────────────┤
│ │
│ Implementación │ ← Lógica compleja oculta
│ Profunda │
│ │
└─────────────────────┘
Módulo superficial = interfaz grande + poca implementación (evitar):
┌─────────────────────────────────┐
│ Interfaz Grande │ ← Muchos métodos, parámetros complejos
├─────────────────────────────────┤
│ Implementación Fina │ ← Solo pasa a través
└─────────────────────────────────┘
Al diseñar una interfaz, pregúntate:
- ¿Puedo reducir el número de métodos?
- ¿Puedo simplificar los parámetros?
- ¿Puedo ocultar más complejidad en el interior?
Principios
- La profundidad es una propiedad de la interfaz, no de la implementación. Un módulo profundo puede estar compuesto internamente por partes pequeñas, simulables e intercambiables — simplemente no forman parte de la interfaz. Un módulo puede tener seams internos (privados a su implementación, usados por sus propias pruebas) así como el seam externo en su interfaz.
- La prueba de eliminación. Imagina eliminar el módulo. Si la complejidad desaparece, era un paso a través. Si la complejidad reaparece en N llamadores, estaba ganando su lugar.
- La interfaz es la superficie de prueba. Los llamadores y las pruebas cruzan el mismo seam. Si quieres probar más allá de la interfaz, probablemente el módulo tenga la forma incorrecta.
- Un adaptador significa un seam hipotético. Dos adaptadores significan uno real. No introduzcas un seam a menos que algo realmente varíe a través de él.
Diseñando para la testabilidad
Las buenas interfaces hacen que las pruebas sean naturales:
-
Acepta dependencias, no las crees.
// Testeable function procesarPedido(pedido, pasarelaPago) {} // Difícil de testear function procesarPedido(pedido) { const pasarela = new PasarelaStripe(); } -
Devuelve resultados, no produzcas efectos secundarios.
// Testeable function calcularDescuento(carrito): Descuento {} // Difícil de testear function aplicarDescuento(carrito): void { carrito.total -= descuento; } -
Área de superficie pequeña. Menos métodos = menos pruebas necesarias. Menos parámetros = configuración de prueba más simple.
Relaciones
- Un Módulo tiene exactamente una Interfaz (la superficie que presenta a los llamadores y las pruebas).
- La Profundidad es una propiedad de un Módulo, medida contra su Interfaz.
- Un Seam es donde vive la Interfaz de un Módulo.
- Un Adaptador se sienta en un Seam y satisface la Interfaz.
- La Profundidad produce Apalancamiento para los llamadores y Localidad para los mantenedores.
Enfoques rechazados
- Profundidad como ratio de líneas de implementación a líneas de interfaz (Ousterhout): recompensa inflar la implementación. Usamos profundidad-como-apalancamiento en su lugar.
- "Interfaz" como la palabra clave
interfacede TypeScript o los métodos públicos de una clase: demasiado estrecho — la interfaz aquí incluye todos los hechos que un llamador debe conocer. - "Límite": sobrecargado con el contexto delimitado de DDD. Di seam o interfaz.
Profundizando más
- Profundizar un clúster dadas sus dependencias — consulta DEEPENING.md: categorías de dependencia, disciplina de seam y pruebas de reemplazar-no-apilar.
- Explorando interfaces alternativas — consulta DESIGN-IT-TWICE.md: inicia subagentes paralelos para diseñar la interfaz de varias formas radicalmente diferentes, luego compara en profundidad, localidad y colocación del seam.