Contrato de API generado desde la base de datos
Generé el contrato de la API desde la base de datos hacia las capas externas — OpenAPI, un cliente TypeScript tipado de 44.076 líneas, 61 manejadores simulados y los límites que aplica la interfaz — con una comprobación en cada paso que falla ante cualquier divergencia.
Trabajo realizado: 2025
44,076 líneas de cliente tipado generadas desde la base de datos
Situación. El frontend y el backend avanzan a su propio ritmo, y sus supuestos sobre el contenido de una solicitud pueden separarse sin que nadie lo advierta. La forma habitual de descubrirlo es un 422 en el navegador — después de que la discrepancia ya se haya publicado, que es el momento más caro para enterarse. Escribir ambos lados a mano a partir del mismo documento no lo resuelve; solo traslada la divergencia a quien se olvidó de volver a leer el documento.
Tarea. Había que generar ambos lados a partir de una única fuente, en lugar de acordarlos entre dos, comprobando cada paso de la generación en vez de darlo por fiable.
Acción. La cadena empieza en la base de datos y avanza hacia fuera. El esquema y sus funciones definen las estructuras; los tipos Go definen la API; Huma genera a partir de ellos la descripción OpenAPI; se genera un cliente TypeScript tipado — de 44.076 líneas — a partir de esa descripción; junto a él se generan 61 controladores simulados para que las propias pruebas del frontend se ejecuten contra el contrato real en lugar de datos de prueba escritos a mano; y los límites que la interfaz impone en un formulario proceden del mismo lugar en vez de volver a introducirse en un validador. Cada paso tiene una protección. Una comprobación de contrato en CI compara lo que envía el frontend con lo que espera la API y hace fallar la compilación si divergen, con una inspección del esquema subyacente que comprueba las estructuras reales en lugar de una descripción de ellas. Cubre deliberadamente los lugares donde suelen ocultarse las divergencias: campos opcionales del cuerpo, donde se confunden «ausente» y «null», y enumeraciones de parámetros de consulta, donde ambos lados pueden discrepar silenciosamente sobre los valores permitidos.
Resultado. Un campo no puede cambiar solo en un lado — falla en el primer paso que lo detecta, durante una compilación, minutos después del cambio. Eso eliminó una clase recurrente y realmente molesta de errores, de los que son invisibles en una revisión de código y solo aparecen durante la ejecución. El costo es un paso de generación en medio de todo: regenerar es una tarea tediosa, y la cadena solo es tan fiable como su eslabón menos protegido, motivo por el que se protegió cada paso.

Foto: 422737 / Pixabay 
Foto: rkit / Pixabay
Aplique esta experiencia a su proyecto
Utilice «Contrato de API generado desde la base de datos» como punto de partida para un reto similar en su organización. Los servicios que respaldan este trabajo están disponibles para su proyecto. La parte que el usuario no ve: dónde se guardan los datos, qué reglas se aplican y cómo pueden comunicarse otros sistemas con ella.
Mire más allá del resultado
Lea la situación, las decisiones y el resultado de este ejemplo. Podemos hablar de qué partes se adaptan a sus restricciones y cuáles necesitan otro enfoque. Contrato de API generado desde la base de datos — 44,076 líneas de cliente tipado generadas desde la base de datos
Vuelva a ver API migrada a Huma v2 con paridad del 100 %. Lea a continuación: Correo con conmutación y registro de entregas. O eche un vistazo al Portafolio completo.
Una parte de una trayectoria más amplia — y toda ella está en este sitio.
Cada entrada sigue la misma estructura: la situación, la tarea, lo que hicimos y lo que cambió.

