Nombre el rol, no al proveedor: la nomenclatura de interfaces como decisión arquitectónica
La mayoría de los debates sobre nombres son cuestión de gusto y merecen unos cinco minutos. Un número reducido son decisiones arquitectónicas disfrazadas, y valen considerablemente más, porque un nombre que se filtra en una interfaz se convierte en una restricción que sobrevive a aquello que le dio nombre.
La distinción es simple. Los nombres dentro de un sistema pueden ser cambiados por quien sea dueño del sistema. Los nombres en una interfaz (un encabezado, una variable de entorno, un nombre de servicio, una clave de configuración) son contratos. Otros sistemas dependen de ellos. Cambiar uno es una migración.
Un caso concreto
Necesitábamos un encabezado de solicitud que transportara un secreto compartido entre un sistema de gestión de contenidos y el frontend que lo consume. El nombre obvio tomaba prestado el prefijo del marco del frontend: X-<Framework>-Revalidate-Secret. Era descriptivo y encajaba con el ecosistema circundante.
También era incorrecto, y la razón merece enunciarse con precisión: el encabezado no es una propiedad del frontend. Es el contrato entre los dos sistemas. Nombrarlo según uno de los participantes afirma que ese participante es permanente.
La alternativa que primero se sugiere, un prefijo de organización, X-<Company>-Revalidate-Secret, es incorrecta de la misma manera, un eje más allá. Dice que el contrato pertenece a un solo inquilino. Para cualquier cosa destinada a desplegarse para más de un cliente, ese es el error más costoso, porque fija la interfaz al primer cliente y no meramente al primer marco.
Lo que se publicó fue X-Revalidate-Secret. Nombra lo que hace el encabezado. Sobrevive al reemplazo del frontend, al reemplazo del CMS y al despliegue para una organización distinta, porque nunca afirmó nada sobre ninguno de ellos.
Los cuatro ejes
Los nombres se filtran a lo largo de cuatro ejes, y cada uno se convierte en una migración más adelante:
- Proveedor o marco: fija la interfaz a una elección tecnológica. Reemplazar la tecnología ahora significa una migración o un nombre que miente.
- Inquilino o cliente: la fija al primer cliente. Cada despliegue posterior hereda un nombre que se refiere a otro.
- Host o máquina: la fija a una sola caja. El sistema no puede moverse sin un cambio de nombre o una documentación que es discretamente falsa.
- Entorno: la fija a una etapa. Los nombres que contienen "staging" o "prod" tienden a terminar en el otro.
En cada caso el nombre era exacto cuando se escribió. La exactitud no es la propiedad que importa; la durabilidad sí.
Lo que no debe renombrarse
La regla tiene un límite, e ignorarlo causa daño real.
Algunos nombres específicos de un marco son estructurales. Una herramienta de construcción que solo expone variables de entorno con un prefijo determinado no está siguiendo una convención que usted pueda mejorar: ese prefijo es un requisito funcional. Renómbrelo y el valor dejará de llegar en silencio al código que lo necesita, sin ningún error.
De igual modo, los nombres que pertenecen a una dependencia ascendente no son suyos. Las claves de configuración y los identificadores de paquete de un módulo pertenecen a ese proyecto. Renombrarlos localmente es una bifurcación.
Así que un barrido de nombres nunca es un buscar y reemplazar. Requiere clasificar las ocurrencias en tres categorías (nuestras y renombrables, impuestas externamente, y prosa descriptiva) antes de cambiar nada. La prosa que describe la implementación actual está bien; la regla concierne a interfaces e identificadores, no a fingir que usa una tecnología distinta de la que usa.
Renombrar una interfaz de forma segura
Los nombres de interfaz son contratos en tiempo de ejecución, así que la migración tiene la misma forma que cualquier cambio de protocolo:
- Enseñe al receptor a aceptar ambos nombres, prefiriendo el nuevo. Despliéguelo solo. Nada cambia todavía.
- Cambie el emisor en una versión posterior.
- Elimine el nombre antiguo una vez que la telemetría confirme que nada lo usa.
Hecho en ese orden, no existe ninguna ventana de despliegue en la que las dos partes estén en desacuerdo. Hecho en el orden contrario, hay un período en el que el emisor emite un nombre que el receptor no conoce, y según la interfaz, esa falla puede ser silenciosa.
La misma disciplina se aplica a los nombres de servicios, las variables de entorno y las claves de configuración, con la complicación adicional de que algunos llevan estado. Renombrar el nombre de máquina de un módulo en un sistema de gestión de contenidos no es una edición; el nombre antiguo está registrado en la base de datos y en la configuración exportada, así que necesita una ruta de migración, no una sustitución de texto.
Por qué vale el esfuerzo
El argumento a favor de la nomenclatura basada en roles no es la elegancia. Es que la alternativa cobra intereses.
Un sistema construido con nombres de proveedores en sus interfaces aún puede migrarse de plataforma; solo que cuesta una migración por nombre, cada una con una ventana de transición y despliegues coordinados. Un sistema construido con nombres de rol reemplaza su frontend sin tocar el contrato en absoluto.
El costo de hacerlo bien son unos minutos de reflexión en el momento de nombrar. El costo de hacerlo mal se paga después, por otra persona, normalmente mientras hace algo más urgente.