Inicio / Artículos

Notas prácticas: Mantener sincronizados los tipos del frontend y el backend con TypeScript

Guía práctica paso a paso: Mantener sincronizados los tipos del frontend y backend con TypeScript: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.

Editor: REACTAPP.TOP7 min de lectura1637 palabras

Fuentes: Keeping Frontend and Backend Types in Sync with Typescript Magic

Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “Mantener sincronizados los tipos del frontend y backend con la magia de TypeScript”: etapas claras, espacios ordenados para el código y notas de recuperación que sobreviven a la transferencia de tareas.

El error que no tiene traza de pila

Ese tipo de error funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. La memorización prematura puede ocultar errores en los props obsoletos.

// backend/src/topics/topics.service.ts
async findAll(): Promise<TopicRow[]> {
  return this.prisma.topic.findMany({ select: TOPIC_SELECT });
}
// frontend/src/types.ts
export interface TopicRow {
  id: string;
  code: string;
  requiresKey: boolean;
  // ...
}

Por qué se volvió urgente

El enfoque de considerar esta etapa como algo urgente funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga 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 estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga que el proceso de renderizado sea económico y reserve las operaciones costosas para después de realizar mediciones, utilizando la memorización solo cuando sea necesario. Una memorización prematura puede ocultar errores relacionados con propiedades obsoletas.

La idea

La etapa de definición de ideas funciona mejor cuando se trata como una superficie medible. Capture un caso exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los valores utilizados.

// backend/contract/assert.ts

/** The wire shape of a server value: JSON.stringify turns Date into string. */
export type Jsonify<T> = T extends Date
  ? string
  : T extends (infer U)[]
    ? Jsonify<U>[]
    : T extends object
      ? { [K in keyof T]: Jsonify<T[K]> }
      : T;
/** Invariant (not merely assignable) equality - catches widened optionals. */
export type Equal<A, B> =
  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
    ? true
    : false;
export type Expect<T extends true> = T;
/** The element type of a service method that resolves to an array. */
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
/** The resolved wire shape of a service method. */
export type ResultOf<T> = Jsonify<Awaited<T>>;
/** The row type of a paginated `{ rows, total }` service method. */
export type PagedRowOf<T> =
  Jsonify<Awaited<T>> extends { rows: (infer U)[] } ? U : never;
// backend/contract/api-contract.ts
import type { Equal, Expect, PagedRowOf, RowOf } from './assert';
import type { TopicsService } from '../src/topics/topics.service';
import type { ContactRequestsService } from '../src/contact-requests/contact-requests.service';
import type { TopicRow, ContactRequestRow } from '../../frontend/src/types';

// GET /topics
export type _Topics = Expect<
  Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
// GET /contact-requests (paginated)
export type _ContactRequests = Expect<
  Equal<PagedRowOf<ReturnType<ContactRequestsService['findAll']>>, ContactRequestRow>
>;

La magia de la escritura, explicada

La magia de la escritura automática funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el procesamiento barato y posponga las operaciones costosas a la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los datos.

export type _Topics = Expect<
  Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
type Equal<A, B> = A extends B ? (B extends A ? true : false) : false; // too loose
(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;

Conéctelo al método, no a la consulta

El proceso de “conectarlo a la etapa” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. La memorización prematura puede ocultar errores en los parámetros obsoletos. El proceso de “conectarlo a la etapa” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.

// Wrong: misses everything the method does after the query
Equal<Jsonify<TopicSelectResult>, TopicRow>
// Right: whatever the method actually resolves to
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>

Hacer que funcione

En la fase de puesta en marcha, defina las entradas, el responsable del 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. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Coloque el estado junto al componente que es responsable de la mutación. Subir todo a un almacenamiento global hace que los errores relacionados con el tiempo sean más difíciles de detectar.

// backend/tsconfig.contract.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "rootDir": "..",              // program spans both packages
    "module": "preserve",
    "moduleResolution": "bundler" // resolve the way the frontend's bundler does
  },
  "include": ["src/**/*", "contract/**/*", "../frontend/src/types.ts"]
}
{ "scripts": { "check:contract": "tsc -p tsconfig.contract.json" } }

Levantamiento de una falla

En la etapa de falla al leer, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso desde un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, la causa debe corresponder a una única responsabilidad y no a un proceso complicado. Coloque el estado junto al componente que gestiona la mutación. Al llevar todo a un almacenamiento global, resulta más difícil detectar errores de sincronización.

type P1 = A extends B ? true : false;        // false => server is narrower / has extra
type P2 = B extends A ? true : false;        // false => frontend is wider
type Extra = Exclude<keyof A, keyof B>;      // fields the server sends, frontend lacks
type Missing = Exclude<keyof B, keyof A>;    // fields the frontend invented

Qué cuesta y dónde no llega

En cuanto a la sección “Qué cuesta” y la etapa correspondiente, 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. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Coloque el estado junto al componente que es responsable de la mutación. Al almacenar todo en una base de datos global, resulta más difícil detectar errores relacionados con los tiempos de ejecución. En cuanto a la sección “Qué cuesta” y la etapa correspondiente, 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. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar al que los operadores puedan acceder para realizar auditorías, sin necesidad de leer todo el sistema.

El punto clave

Al trabajar en la etapa del Punto Clave, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código.

Lista de verificación operativa

Al trabajar en la etapa de la Lista de Verificación Operativa, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código.

Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos.

Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.

Fije las versiones de dependencias y registre el resumen de la imagen que ejecutó la demostración. La reproducibilidad es mejor que el conocimiento tribal.

Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.

Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.

Antes de promocionar la pila tecnológica, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos para hacer un rollback. Los entornos compartidos necesitan límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Nota por lotes para 99a16b87e27d: mantener las claves del proveedor fuera del repositorio, establecer un límite para los tokens por sesión y almacenar las transcripciones junto a los archivos de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.