APIs rápidas y seguras de tipo con Zod y OpenAPI en un único contrato

Esta guía reconstruye un camino práctico para: crear una API Express segura desde el punto de vista tipológico con Zod y OpenAPI. Se enfoca en los contratos, las verificaciones y el código que se puede incorporar a un repositorio sin tener que adivinar su propósito. Para obtener una visión general, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad en lugar de un proceso complicado.

La idea

Para esta idea, defina las entradas, el responsable de la etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Valide en los límites mediante esquemas que también generen documentación; una única fuente de verdad evita desviaciones entre OpenAPI y los procesadores.

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

api.post("/users", {
  body: CreateUserSchema,
  response: {
    201: UserSchema,
  },
  handler: async (req) => {
    const user = await createUser(req.body);
    return {
      status: 201,
      body: user,
    };
  },
});

¿Por qué crear otra biblioteca Express?

En “¿Por qué crear otra biblioteca Express?”, se deben definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido, sin tener que adivinar el estado oculto. Se deben registrar los tiempos y costos junto con los resultados funcionales. La visibilidad temprana evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Se debe validar en los límites mediante esquemas que también generen documentación; tener una única fuente de verdad evita discrepancias entre OpenAPI y los controladores.

Estado actual

En el estado actual, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Valide en los límites mediante esquemas que también generen documentación. Tener una única fuente de verdad evita las discrepancias entre OpenAPI y los procesadores. En el estado actual, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado.

Le encantaría recibir comentarios de los desarrolladores

Si le interesa obtener feedback de los desarrolladores, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Devuelva errores estructurados en los que los clientes puedan basarse para tomar decisiones. Un control estricto de los errores por tipo obliga a hacer conjeturas.

Lista de verificación operativa

Para la lista de verificación operativa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto.

Dokumente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.

Devuelva errores estructurados en los que los clientes puedan basarse para tomar decisiones. Los fallos de tipado estricto obligan a hacer conjeturas.

Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Opte por unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe apuntar a una única responsabilidad y no a un proceso complicado.

Devuelva errores estructurados en los que los clientes puedan basarse para tomar decisiones. Los fallos de tipado estricto obligan a hacer conjeturas.

Antes de promocionar la tecnología, congele las versiones, capture una transcripción de referencia para el camino crítico y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de asignación y un responsable claro para el cambio de credenciales. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Lecturas relacionadas

• Detectando el desvío silencioso del contrato de API con tipos inferidos a partir de ejemplos y Zod — Por qué los tipos de TypeScript escritos a mano para APIs de terceros se vuelven obsoletos, cómo la inferencia de tipos y los esquemas Zod a partir de respuestas reales ayuda, y cómo las diferencias entre snapshots revelan dicho desvío.
• Detectando el desvío del contrato de API en el tiempo de compilación con un despliegue incremental de tRPC — Cómo tRPC convierte un campo del backend renombrado en un error de compilación, cómo adoptarlo endpoint por endpoint junto con REST, y en qué casos no es la herramienta adecuada.