8. Comunicación con el servidor
Los ejemplos de este capítulo consultan el servidor JSON de [RdvMedecins]: debe estar en ejecución ([npm run start:dev] en la carpeta [rdvmedecins-nestjs-json]) en el puerto 8080, al mismo tiempo que el servidor de desarrollo de [Vite] en el puerto 5173.
8.1. Ejemplo 22: una primera solicitud HTTP
8.1.1. El proxy del servidor de desarrollo
La página de este ejemplo proviene de http://localhost:5173 (el servidor de desarrollo de [Vite]); la API se encuentra en http://localhost:8080. Para un navegador, son dos orígenes distintos (el puerto forma parte del origen). Ahora bien, por razones de seguridad, un navegador no permite que una página lea las respuestas de otro origen a menos que el servidor lo autorice explícitamente (el mecanismo conocido como CORS). Y una solicitud a otro origen no lleva cookies (y, por lo tanto, tampoco el token), a menos que el código lo pida ([credentials: 'include']) Y el servidor lo acepte, nuevamente mediante CORS.
En lugar de abrir el servidor a otros orígenes, las solicitudes a la API se enrutan a través del servidor de desarrollo de [Vite]. Este es el proxy declarado en el archivo [vite.config.ts] de los ejemplos (véase el ejemplo 01):
| proxy: {
'/api': 'http://localhost:8080',
},
|
El navegador envía una solicitud a [GET http://localhost:5173/api/captcha]; el servidor de desarrollo reenvía la solicitud a [http://localhost:8080/api/captcha] y luego devuelve la respuesta al navegador. Desde el punto de vista del navegador, la página y la API tienen el mismo origen:

En producción, ya no habrá un servidor de desarrollo: el propio servidor JSON servirá los archivos compilados del cliente (véase el capítulo “Despliegue”). La página y la API seguirán teniendo el mismo origen.
8.1.2. La solicitud
[React] no tiene un cliente HTTP propio: se usa la función [fetch] del navegador o una biblioteca ([axios]...). [fetch] es más que suficiente.
| // =========================================================================
// 22-fetch/src/App.tsx - una primera solicitud HTTP al servidor
// -------------------------------------------------------------------------
// Hay que iniciar el servidor JSON de RdvMedecins (puerto 8080). Le pedimos
// un captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
// - fetch(url): la función del navegador que envía una solicitud HTTP.
// Devuelve una PROMESA de la respuesta; response.json() una promesa
// del cuerpo, convertido desde JSON. React no tiene cliente HTTP propio;
// - la dirección es RELATIVA (/api/captcha): la solicitud va al
// servidor de la página, el de Vite (puerto 5173), que la reenvía al
// servidor JSON (puerto 8080) gracias a su proxy (cf. vite.config.ts);
// - tres estados para mostrar: en curso, exitoso, fallido.
// =========================================================================
import { useEffect, useState } from 'react';
// lo que devuelve GET /api/captcha
interface Captcha {
id: string;
svg: string;
}
const captchaStyle = { display: 'inline-block', border: '1px solid #dee2e6', borderRadius: '0.375rem' };
export default function App() {
const [captcha, setCaptcha] = useState<Captcha | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [requestCount, setRequestCount] = useState(0);
// cada clic en "Another image" cambia este número, lo que reinicia el efecto
const [demand, setDemand] = useState(0);
useEffect(() => {
// AbortController: el medio para CANCELAR una solicitud en curso
const cancellation = new AbortController();
setLoading(true);
setError(null);
fetch('/api/captcha', { signal: cancellation.signal })
.then(async (response) => {
// fetch NO rechaza una respuesta de error (4xx, 5xx): se prueba ok
if (!response.ok) {
throw new Error(`the server answered ${response.status} ${response.statusText}`);
}
const c = (await response.json()) as Captcha;
setCaptcha(c);
setRequestCount((n) => n + 1);
setLoading(false);
})
.catch((e: Error) => {
if (e.name === 'AbortError') return; // solicitud cancelada: nada que mostrar
setError(e.message);
setCaptcha(null);
setLoading(false);
});
// la limpieza CANCELA la solicitud si el efecto se reinicia o si el
// componente desaparece antes de la respuesta. En desarrollo, StrictMode
// ejecuta el efecto dos veces al iniciar: la primera solicitud se
// cancela (pestaña Network: "canceled"), solo cuenta la segunda.
return () => cancellation.abort();
}, [demand]);
return (
<div className="container py-4" style={{ maxWidth: 640 }}>
<h1 className="h3 mb-3">Example 22 - a first HTTP request</h1>
<div className="card p-3">
{loading && <p className="text-muted">Loading...</p>}
{error && (
<div className="alert alert-danger mb-3">
Unable to get a captcha: {error}.<br />
Is the RdvMedecins JSON server started (port 8080)?
</div>
)}
{captcha && !loading && (
<>
{/* dangerouslySetInnerHTML: insertar una cadena como HTML */}
<div className="mb-2"><div style={captchaStyle} dangerouslySetInnerHTML={{ __html: captcha.svg }} /></div>
<p className="small text-muted">id: <code>{captcha.id}</code></p>
</>
)}
<button className="btn btn-primary align-self-start" disabled={loading} onClick={() => setDemand((d) => d + 1)}>
Another image
</button>
<p className="small text-muted mt-2 mb-0">
{requestCount} successful request(s) - open the Network tab of the developer tools (F12).
</p>
</div>
</div>
);
}
|
- líneas 19–22: lo que devuelve [GET /api/captcha];
- líneas 27–30: tres estados que mostrar: en curso, exitoso (el CAPTCHA), error;
- línea 32: un número de solicitud: cada clic en “Another image” lo incrementa, lo que vuelve a activar el efecto;
- líneas 34–61: la solicitud es un efecto: sincroniza el componente con el servidor, en la visualización inicial y luego con cada nueva solicitud:
- línea 36: un [AbortController] permite cancelar una solicitud pendiente: su [signal] se pasa a [fetch];
- línea 39: [fetch(url)] envía una solicitud (GET) y devuelve una promesa de la respuesta. La dirección es RELATIVA: la solicitud se envía al servidor de la página, [Vite], que la reenvía al servidor JSON;
- líneas 42–44: ADVERTENCIA: [fetch] NO rechaza la promesa si recibe una respuesta de error (4xx, 5xx); su promesa se rechaza solo si NO llega ninguna respuesta (corte de red). Por lo tanto, se verifica [response.ok] (true para un código 2xx);
- Línea 45: [response.json()] lee el cuerpo y lo convierte desde JSON (otra promesa). [as Captcha]: le indicamos a [TypeScript] el formato de los datos recibidos; no puede verificarlo;
- líneas 50–55: un error; [AbortError]: la solicitud fue cancelada; no hay nada que mostrar;
- Línea 60: la limpieza CANCELA la solicitud si el efecto se vuelve a activar o si el componente desaparece antes de la respuesta. En desarrollo, [<StrictMode>] ejecuta el efecto dos veces al inicio: la primera solicitud se cancela (la pestaña Red la muestra como “canceled”); solo cuenta la segunda;
- línea 77: la imagen es un fragmento de SVG, una cadena que se inserta como HTML. [{captcha.svg}] mostraría el texto [<svg ...>], escapado. [dangerouslySetInnerHTML] inserta la cadena tal cual: su nombre advierte del peligro. Úselo SOLO con contenido seguro: este SVG lo genera NUESTRO servidor. Con datos ingresados por el usuario, esto abriría la puerta a la inyección de scripts;
- Línea 81: una nueva solicitud; el efecto se vuelve a activar.

Si el servidor JSON está caído, el proxy de [Vite] devuelve un error 500: “Unable to get a captcha: the server answered 500 Internal Server Error.”
8.2. Ejemplo 23: inicio de sesión, cookie y sesión
| // =========================================================================
// 23-login/src/App.tsx - iniciar sesión en el servidor RdvMedecins
// -------------------------------------------------------------------------
// 1. al iniciar: GET /api/auth/me - ¿ya hay una sesión iniciada?
// (tras un F5, el cliente lo ha olvidado todo; el servidor lee la cookie);
// 2. login: POST /api/auth/login, cuerpo JSON { login, password,
// captchaId, captcha }. Si tiene éxito, el servidor establece la cookie httpOnly
// del token JWT: nuestro código NUNCA la ve (pruebe
// document.cookie en la consola: no está);
// 3. solicitud protegida: GET /api/doctors. El navegador le adjunta la cookie
// por su cuenta (mismo origen);
// 4. logout: POST /api/auth/logout - el servidor elimina la cookie.
//
// El formulario usa las ACCIONES de React 19: <form action={función}>.
// En lugar de manejar onSubmit y cada campo, recibimos todos los valores
// del formulario (FormData), y useActionState conserva el resultado de la
// última acción (aquí, un mensaje de error) e indica si está en curso.
//
// Una cookie pertenece a un host (localhost) y a una ruta (/api): por lo
// tanto, es común a TODOS los ejemplos. Una vez iniciada la sesión aquí, los ejemplos
// 24 y 25 también la tienen.
// =========================================================================
import { useActionState, useEffect, useState } from 'react';
import { useFormStatus } from 'react-dom';
interface User {
login: string;
name: string;
role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
id: number;
title: string;
firstName: string;
lastName: string;
}
interface Captcha {
id: string;
svg: string;
}
// la forma de TODOS los errores de la API
interface ApiError {
statusCode: number;
key: string;
params?: Record<string, string>;
}
// los pocos mensajes que necesita este ejemplo (el ejemplo 25 usará i18next)
const MESSAGES: Record<string, string> = {
'LOGIN.ERROR': 'Incorrect login or password.',
'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};
// una solicitud GET, cuya respuesta JSON está tipada; un error si no es 2xx
async function read<T>(url: string): Promise<T> {
const response = await fetch(url);
if (!response.ok) {
throw response; // la propia respuesta se "lanza": su status indicará qué hacer
}
return (await response.json()) as T;
}
// el botón de envío: useFormStatus() indica si el formulario QUE LO CONTIENE
// se está enviando (por lo tanto debe ser un componente aparte, colocado dentro)
function LoginButton() {
const { pending } = useFormStatus();
return <button className="btn btn-primary" disabled={pending}>{pending ? 'Logging in...' : 'Log in'}</button>;
}
// el resultado del último intento de inicio de sesión
interface LoginState {
error: string | null;
login: string; // el login escrito, para volver a mostrarlo
}
export default function App() {
const [user, setUser] = useState<User | null>(null);
const [doctors, setDoctors] = useState<Doctor[]>([]);
const [captcha, setCaptcha] = useState<Captcha | null>(null);
const [ready, setReady] = useState(false); // ¿ha terminado la verificación inicial?
const [serverError, setServerError] = useState<string | null>(null);
async function loadCaptcha() {
setCaptcha(await read<Captcha>('/api/captcha'));
}
async function loadDoctors() {
setDoctors(await read<Doctor[]>('/api/doctors'));
}
// 1. ¿quién ha iniciado sesión? 200 -> el usuario; 401 -> nadie
useEffect(() => {
async function checkSession() {
try {
setUser(await read<User>('/api/auth/me'));
await loadDoctors();
} catch (e) {
if (!(e instanceof Response) || e.status !== 401) {
setServerError('Is the RdvMedecins JSON server started (port 8080)?');
} else {
await loadCaptcha();
}
}
setReady(true);
}
checkSession();
}, []);
// 2. el inicio de sesión: una ACCIÓN, que recibe el estado anterior y los
// datos del formulario, y devuelve el nuevo estado
async function logIn(_previous: LoginState, data: FormData): Promise<LoginState> {
const login = String(data.get('login'));
const response = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' }, // el cuerpo es JSON
body: JSON.stringify({ login, password: data.get('password'), captchaId: captcha?.id, captcha: data.get('captcha') }),
});
if (!response.ok) {
// el cuerpo JSON de la respuesta de error
const error = (await response.json().catch(() => null)) as ApiError | null;
const key = error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
await loadCaptcha(); // cada imagen se usa una sola vez
return { error: `${response.status} - ${MESSAGES[key] ?? key}`, login };
}
setUser((await response.json()) as User);
await loadDoctors();
return { error: null, login };
}
const [state, loginAction] = useActionState(logIn, { error: null, login: 'admin' });
// 4. el cierre de sesión
async function logOut() {
await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
setUser(null);
setDoctors([]);
await loadCaptcha();
}
let content;
if (!ready) {
content = <p className="text-muted">Checking the session...</p>;
} else if (user) {
// sesión iniciada
content = (
<div className="card p-3">
<p>
Logged in: <strong>{user.name}</strong> ({user.login}), role{' '}
<span className="badge text-bg-primary">{user.role}</span>
</p>
<h2 className="h6">GET /api/doctors</h2>
<ul>
{doctors.map((m) => <li key={m.id}>{m.title} {m.firstName} {m.lastName}</li>)}
</ul>
<p className="small text-muted">Reload the page (F5): you remain logged in.</p>
<button className="btn btn-outline-secondary align-self-start" onClick={logOut}>Log out</button>
</div>
);
} else if (!serverError) {
// sin sesión iniciada: el formulario. Los campos NO son controlados: name
// los designa en FormData; después de cada acción, React los restablece a
// su valor inicial (defaultValue)
content = (
<form className="card p-3" action={loginAction}>
<div className="mb-2">
<label className="form-label" htmlFor="login">Login</label>
<input id="login" name="login" className="form-control" autoComplete="username" defaultValue={state.login} />
</div>
<div className="mb-2">
<label className="form-label" htmlFor="password">Password</label>
<input id="password" name="password" type="password" className="form-control" autoComplete="current-password" />
</div>
<div className="mb-3">
<label className="form-label" htmlFor="captcha">Type the characters of the image</label>
<div className="d-flex align-items-center gap-3 mb-2">
<div dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
<button type="button" className="btn btn-link btn-sm" onClick={loadCaptcha}>Another image</button>
</div>
<input id="captcha" name="captcha" className="form-control" autoComplete="off" />
</div>
<LoginButton />
<p className="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
{state.error && <div className="alert alert-danger mt-3 mb-0">{state.error}</div>}
</form>
);
}
return (
<div className="container py-4" style={{ maxWidth: 640 }}>
<h1 className="h3 mb-3">Example 23 - logging in to the server</h1>
{content}
{serverError && <div className="alert alert-danger mt-3">{serverError}</div>}
</div>
);
}
|
El flujo (líneas 4–12): al arrancar, se consulta al servidor para saber quién está conectado; luego vienen el inicio de sesión, una solicitud protegida y el cierre de sesión.
- Líneas 27–47: algunos tipos de la API, incluida la forma de TODOS los errores;
- líneas 50–54: los pocos mensajes que este ejemplo necesita para traducir las claves del servidor (el ejemplo 25 usará [i18next]);
- líneas 57–63: una pequeña función genérica para solicitudes GET: la respuesta JSON, con un tipo; y, si no es 2xx, se “lanza” la propia respuesta: su estado indicará qué hacer;
- líneas 67–70: el botón de envío del formulario. [useFormStatus()] (de [react-dom]) indica si el formulario QUE LO CONTIENE se está enviando en ese momento: por lo tanto, debe ser un componente separado colocado dentro del formulario;
- Líneas 94–109: al arrancar, [GET /api/auth/me]: ¿ya hay una sesión iniciada? Después de un F5, el cliente lo ha olvidado todo; el servidor, en cambio, lee la cookie. 200: el usuario; 401: nadie (entonces se carga un CAPTCHA); cualquier otra cosa: el servidor no responde. Una función [async] no puede ser el efecto en sí (un efecto devuelve su limpieza, no una promesa): se declara dentro del efecto y luego se llama;
- líneas 113–130: el inicio de sesión, escrito como una acción de [React] 19 (véase más adelante). Recibe el estado anterior y los datos del formulario ([FormData]), y devuelve el nuevo estado:
- línea 114: [data.get(name)] lee un campo del formulario, identificado por su atributo [name];
- líneas 115–119: [POST /api/auth/login], con un cuerpo JSON: [method], el encabezado [Content-Type] y el cuerpo, generado por [JSON.stringify]. Si tiene éxito, el servidor establece la cookie [httpOnly] con el token JWT: nuestro código NUNCA la ve (pruebe [document.cookie] en la consola: no está allí);
- líneas 120–126: un fallo: el cuerpo de la respuesta de error, en JSON, proporciona la clave del mensaje; cada imagen de CAPTCHA se usa una sola vez: se carga otra;
- líneas 127–129: un éxito: el usuario, seguido de una solicitud protegida, [GET /api/doctors]: el navegador incluye automáticamente la cookie (mismo origen);
- línea 131: [useActionState(action, initialState)] ([React] 19) devuelve el estado generado por la última ejecución de la acción, y una versión de la acción que se pasa al formulario;
- líneas 134–139: cierre de sesión; [POST /api/auth/logout]: el servidor elimina la cookie. Todo POST debe tener un cuerpo JSON (el servidor rechaza los demás; véase el capítulo anterior): ['{}'];
- línea 165: [<form action={function}>]: a partir de [React] 19, el atributo [action] de un formulario puede aceptar una función. Al enviarlo, [React] impide que el navegador envíe el formulario, reúne los campos en un [FormData] y llama a la función, durante la cual [useFormStatus] muestra “en curso”. [onSubmit], [preventDefault] y un estado por campo ya no son necesarios;
- Líneas 168–180: los campos no están controlados: se identifican por su [name]. Después de cada acción, [React] restablece el formulario: cada campo vuelve a su valor inicial ([defaultValue]). Por lo tanto, los campos de contraseña y CAPTCHA se vacían; el campo de login vuelve al valor almacenado en el estado por la acción ([state.login]), es decir, el que se acaba de ingresar;
- línea 184: el mensaje de error generado por la última acción.
Una cookie pertenece a una máquina (localhost) y a una ruta ([/api]): por lo tanto, es compartida por TODOS los ejemplos. Una vez iniciada la sesión aquí, los ejemplos 24 y 25 también la tienen iniciada.

Una contraseña incorrecta: se conserva el login y se muestra una nueva imagen:

Sesión iniciada como [admin]; se puede recargar la página (F5): la sesión se mantiene:

8.3. Ejemplo 24: una capa de acceso a la API
El ejemplo 23 repetía los mismos pasos para cada solicitud: prefijo [/api], encabezado JSON, verificación de [response.ok], lectura del cuerpo del error... Los ejemplos 24 y 25 los agrupan en la carpeta [common/], y el caso de estudio seguirá este mismo enfoque.
8.3.1. Los tipos
| // =========================================================================
// common/types.ts - los objetos JSON intercambiados con la API de RdvMedecins
// (cf. el capítulo sobre la caja negra, que describe cada ruta)
// =========================================================================
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
// POST /api/auth/login, GET /api/auth/me
export interface User {
login: string;
name: string;
role: Role;
}
// GET /api/captcha
export interface Captcha {
id: string;
svg: string;
}
// un médico o un cliente (GET /api/doctors, GET /api/clients...)
export interface Person {
id: number;
version: number;
title: string;
firstName: string;
lastName: string;
login?: string; // solo para el ADMIN
}
export interface Identity {
title: string;
firstName: string;
lastName: string;
}
// una fila de GET /api/schedule
export interface ScheduleSlot {
id: number;
startHour: number;
startMinute: number;
endHour: number;
endMinute: number;
free: boolean;
patient: Identity | null;
mine: boolean;
bookable: boolean;
appointmentId: number | null;
}
// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
doctor: Person;
day: string;
slots: ScheduleSlot[];
info: string | null;
}
|
La traducción, en interfaces [TypeScript], de la API descrita en el capítulo anterior. Una línea de la agenda ([ScheduleSlot]) describe una franja horaria Y lo que el usuario con sesión iniciada está autorizado a hacer con ella.
8.3.2. Los errores
| // =========================================================================
// common/api-error.ts - UNA clase para todos los errores de la API
// -------------------------------------------------------------------------
// Todas las respuestas de error del servidor RdvMedecins tienen la misma forma:
// { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Pero una solicitud también puede fallar de OTRO modo: ninguna respuesta
// (red caída: fetch lanza un TypeError), o una respuesta que no
// proviene de nuestro servidor (una página de error del proxy de Vite cuando el
// servidor JSON está detenido). Todo esto se convierte en UNA sola clase,
// ApiError, que lleva la clave de traducción enviada por el servidor (y,
// si los hay, sus parámetros y el error de cada campo).
// =========================================================================
export class ApiError extends Error {
readonly statusCode: number; // 0: el servidor no respondió
readonly key: string; // p. ej.: 'ERRORS.LOGIN_TAKEN'
readonly params: Record<string, string>;
readonly fields: Record<string, string>;
constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
super(key);
this.name = 'ApiError';
this.statusCode = statusCode;
this.key = key;
this.params = params;
this.fields = fields;
}
}
// una respuesta de error (4xx, 5xx) -> un ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
// el cuerpo JSON del error, si existe y tiene la forma correcta
let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
try {
const json: unknown = await response.json();
if (typeof json === 'object' && json !== null) {
body = json;
}
} catch {
// no es JSON: no fue nuestro servidor quien respondió
}
// sin clave: respondió el proxy o la red en su lugar
const key = body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
return new ApiError(response.status, key, body.params, body.fields);
}
|
- Líneas 14–28: UNA clase para todos los errores de la API: el estado HTTP (0: sin respuesta), la clave de traducción enviada por el servidor, sus parámetros y el error de cada campo en un formulario rechazado. Hereda de [Error]: se puede lanzar ([throw]) y reconocer ([instanceof ApiError]). No se usan las “propiedades de parámetro” de [TypeScript] ([constructor(public readonly key: string)]): la opción [erasableSyntaxOnly] de [tsconfig.json] las deshabilita, porque generan código;
- Líneas 31–45: una respuesta de error se convierte en un [ApiError]. El cuerpo no siempre es el JSON de nuestro servidor: cuando el servidor JSON está caído, el proxy de [Vite] responde sin cuerpo JSON. Sin clave: un código de estado de 500 o superior significa “servidor inaccesible”.
8.3.3. Las solicitudes
| // =========================================================================
// common/api.ts - solicitudes a la API, en una línea
// -------------------------------------------------------------------------
// En el ejemplo 23, cada solicitud repetía los mismos gestos: prefijo
// /api, encabezado JSON, prueba de response.ok, lectura del cuerpo del error... Se
// agrupan aquí:
//
// const doctors = await api.get<Person[]>('/doctors');
// await api.post('/appointments', { day, slotId, clientId });
//
// - si tiene éxito, la promesa devuelve el cuerpo JSON, TIPADO;
// - si falla, es RECHAZADA con un ApiError.
// Todas las solicitudes pasan por la función request: es el lugar
// donde se manejaría un problema COMÚN a todas ellas (cf. el caso de estudio y la
// respuesta 401). Usado por los ejemplos 24 y 25.
// =========================================================================
import { fromResponse, ApiError } from './api-error';
export async function request<T>(method: string, url: string, body?: unknown): Promise<T> {
let response: Response;
try {
response = await fetch(`/api${url}`, {
method,
// un cuerpo JSON (el servidor rechaza un POST que no lo tenga)
headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
});
} catch {
// fetch NO obtuvo respuesta (red, servidor detenido)
throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
}
if (!response.ok) {
throw await fromResponse(response);
}
return (await response.json()) as T;
}
export const api = {
get: <T>(url: string) => request<T>('GET', url),
// un POST siempre tiene un cuerpo JSON: {} por defecto
post: <T>(url: string, body: unknown = {}) => request<T>('POST', url, body),
put: <T>(url: string, body: unknown) => request<T>('PUT', url, body),
delete: <T>(url: string, body?: unknown) => request<T>('DELETE', url, body),
};
|
- líneas 20–37: TODAS las solicitudes pasan por esta función genérica:
- líneas 23–28: el prefijo [/api] y, si hay cuerpo, el encabezado y el JSON;
- líneas 29–32: sin respuesta: un [ApiError] con estado 0;
- líneas 33–35: una respuesta de error: un [ApiError];
- línea 36: un éxito: el cuerpo, tipado;
- líneas 39–45: atajos, una función por método HTTP. Un POST siempre tiene un cuerpo JSON: [{}] por defecto.
Aquí es donde se manejaría un problema COMÚN para todas las solicitudes: el caso de estudio abordará aquí la respuesta 401 (sesión vencida).
8.3.4. Una barra de inicio de sesión
| // =========================================================================
// common/LoginBar.tsx - inicio / cierre de sesión, en una barra
// -------------------------------------------------------------------------
// El formulario del ejemplo 23, reducido a una barra y reescrito con api.ts.
// El componente llama a onUserChange con el usuario conectado (o
// null) cada vez que cambia, incluido al iniciar, después de
// haber consultado GET /api/auth/me.
// =========================================================================
import { useEffect, useEffectEvent, useState, type FormEvent } from 'react';
import { api } from './api';
import { ApiError } from './api-error';
import type { Captcha, User } from './types';
import './LoginBar.css';
interface Props {
onUserChange: (user: User | null) => void;
}
export default function LoginBar({ onUserChange }: Props) {
const [user, setUser] = useState<User | null>(null);
const [captcha, setCaptcha] = useState<Captcha | null>(null);
const [login, setLogin] = useState('admin');
const [password, setPassword] = useState('');
const [captchaAnswer, setCaptchaAnswer] = useState('');
const [error, setError] = useState<string | null>(null);
function changeUser(u: User | null) {
setUser(u);
onUserChange(u);
}
async function newCaptcha() {
setCaptcha(await api.get<Captcha>('/captcha'));
setCaptchaAnswer('');
}
// al iniciar: ¿ya hay una sesión iniciada?
const start = useEffectEvent(async () => {
try {
changeUser(await api.get<User>('/auth/me'));
} catch {
changeUser(null); // 401: nadie ha iniciado sesión
await newCaptcha().catch(() => setError('Is the JSON server started (port 8080)?'));
}
});
useEffect(() => {
start();
}, []);
async function logIn(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
setError(null);
try {
const u = await api.post<User>('/auth/login', { login, password, captchaId: captcha?.id, captcha: captchaAnswer });
setPassword('');
changeUser(u);
} catch (err) {
setError(err instanceof ApiError ? `${err.statusCode} ${err.key}` : String(err));
await newCaptcha();
}
}
async function logOut() {
await api.post('/auth/logout');
changeUser(null);
await newCaptcha();
}
return (
<div className="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
{user ? (
<>
<span>
Logged in: <strong>{user.name}</strong> <span className="badge text-bg-primary ms-1">{user.role}</span>
</span>
<button className="btn btn-sm btn-outline-secondary ms-auto" onClick={logOut}>Log out</button>
</>
) : (
<form className="d-flex flex-wrap align-items-center gap-2 w-100" onSubmit={logIn}>
<input className="form-control form-control-sm w-auto" placeholder="login" autoComplete="username" value={login}
onChange={(e) => setLogin(e.target.value)} />
<input type="password" className="form-control form-control-sm w-auto" placeholder="password"
autoComplete="current-password" value={password} onChange={(e) => setPassword(e.target.value)} />
{/* la imagen SVG del captcha, construida por NUESTRO servidor (cf. ejemplo 22) */}
<div className="captcha-bar" dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
<input className="form-control form-control-sm w-auto" placeholder="captcha" autoComplete="off" size={8}
value={captchaAnswer} onChange={(e) => setCaptchaAnswer(e.target.value)} />
<button className="btn btn-sm btn-primary">Log in</button>
{error && <span className="text-danger small">{error}</span>}
</form>
)}
</div>
);
}
|
El formulario del ejemplo 23, reducido a una barra y reescrito con [api.ts] (y con campos validados, a modo de comparación):
- línea 17: el componente notifica a su padre cada vez que cambia el usuario con sesión iniciada;
- líneas 39–46 y 47–49: al arrancar, [GET /api/auth/me]. La función que llama el efecto notifica al padre: [useEffectEvent] evita que esto sea una dependencia (véase el ejemplo 13);
- línea 55: una solicitud de una línea; si falla, se lanza un [ApiError];
- línea 86: la imagen del CAPTCHA, escalada a la altura de la barra mediante una pequeña hoja de estilos:
| /* la imagen SVG del captcha, insertada tal cual en la página: se reduce
a la altura de la barra. Una hoja de estilos importada se aplica a
TODA la página: la clase .captcha-bar la limita a nuestro elemento. */
.captcha-bar svg {
display: block;
height: 32px;
width: auto;
}
|
8.3.5. La capa de acceso a la API
| // =========================================================================
// 24-api-layer/src/rdvmedecins.ts - la capa de acceso a la API
// -------------------------------------------------------------------------
// Una función tipada por cada ruta de la API. Los componentes no conocen ni
// las URL, ni fetch, ni el formato JSON: llaman a funciones.
// Es el equivalente en el cliente de la capa DAO del lado del servidor: si la API
// cambia (una URL, un nombre de campo), solo se modifica este archivo.
// =========================================================================
import { api } from '../../common/api';
import type { Schedule, Person } from '../../common/types';
export const rdvmedecins = {
getDoctors: () => api.get<Person[]>('/doctors'),
getClients: () => api.get<Person[]>('/clients'),
// URLSearchParams construye "doctorId=1&day=2030-01-15", codificando lo que sea necesario
getSchedule: (doctorId: number, day: string) =>
api.get<Schedule>(`/schedule?${new URLSearchParams({ doctorId: String(doctorId), day })}`),
book: (day: string, slotId: number, clientId?: number) =>
api.post<{ id: number }>('/appointments', { day, slotId, clientId }),
cancelAppointment: (appointmentId: number) => api.delete<Record<string, never>>(`/appointments/${appointmentId}`),
};
|
Una función por ruta de la API, tipada. Los componentes no conocen la URL, [fetch] ni el formato JSON: llaman a funciones. Es el equivalente, del lado del cliente, de la capa DAO del lado del servidor: si la API cambia (una URL, el nombre de un campo), solo se modifica este archivo. [URLSearchParams] (línea 18) genera la parte [doctorId=1&day=2030-01-15] de una dirección codificando los datos necesarios.
8.3.6. TanStack Query
Leer datos de un servidor en un efecto, como en el ejemplo 22, obliga a manejarlo todo: el estado “en curso”, los errores, las respuestas obsoletas, las cancelaciones, las solicitudes duplicadas enviadas dos veces y los datos ya recibidos que podrían reutilizarse... [TanStack Query] (antes [React Query]), la biblioteca más utilizada para este fin, se encarga de todo esto.
| // =========================================================================
// 24-api-layer/src/main.tsx
// -------------------------------------------------------------------------
// TanStack Query (antes React Query): la biblioteca más usada
// para LEER datos de un servidor en una aplicación React.
// El QueryClient conserva en memoria (en "caché") las respuestas ya recibidas;
// <QueryClientProvider> lo proporciona a toda la aplicación (un contexto,
// cf. ejemplo 14).
// =========================================================================
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';
const queryClient = new QueryClient({
// si falla, no se reintenta: queremos ver el error
defaultOptions: { queries: { retry: false } },
});
createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
</StrictMode>,
);
|
- línea 17: el cliente de [TanStack Query], que almacena en memoria las respuestas recibidas previamente (en la “caché”); [retry: false]: en caso de fallo, no se reintenta (por defecto, hace tres intentos);
- línea 24: se proporciona a toda la aplicación mediante un contexto (véase el ejemplo 14).
8.3.7. La página
| // =========================================================================
// 24-api-layer/src/App.tsx - una agenda, con la capa de acceso a la API
// -------------------------------------------------------------------------
// Inicie sesión (barra superior), elija un médico y un día: se muestra la
// agenda. ADMIN y DOCTOR pueden reservar para un paciente y cancelar;
// un paciente (martin...) reserva para sí mismo. Cada acción termina con
// una recarga de la agenda: es el SERVIDOR quien tiene la última palabra.
//
// useQuery({ queryKey, queryFn }): una LECTURA de datos, descrita por
// - queryFn: la función que los obtiene (una promesa);
// - queryKey: lo que IDENTIFICA estos datos: ['schedule', doctorId, day].
// TanStack Query llama a queryFn al inicio, y luego cada vez que la clave
// CAMBIA (otro médico, otro día). Devuelve un objeto: data (la
// respuesta), isPending, isFetching, error... y refetch() para leer de nuevo.
// También se encarga de lo que habría que escribir a mano con useEffect: cancelar
// una respuesta obsoleta, no enviar dos veces la misma solicitud, conservar
// las respuestas en caché.
// =========================================================================
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { ScheduleSlot, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins';
function tomorrow(): string {
const d = new Date(Date.now() + 24 * 3600 * 1000);
return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}
function timeRange(c: ScheduleSlot): string {
const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}
// un error -> un texto (su clave, a falta de un diccionario aquí)
function errorText(e: unknown): string {
return e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e);
}
export default function App() {
const [user, setUser] = useState<User | null>(null);
const [doctorId, setDoctorId] = useState<number | null>(null);
const [day, setDay] = useState(tomorrow);
const [clientId, setClientId] = useState<number | null>(null);
const [message, setMessage] = useState<{ type: 'success' | 'danger'; text: string } | null>(null);
const loggedIn = user !== null;
const isManager = loggedIn && user.role !== 'USER';
// los médicos, y luego (ADMIN, DOCTOR) los clientes: se leen de nuevo cuando
// cambia el usuario (forma parte de la clave)
const doctors = useQuery({
queryKey: ['doctors', user?.login],
queryFn: rdvmedecins.getDoctors,
enabled: loggedIn, // false: ninguna solicitud (nadie ha iniciado sesión)
});
const clients = useQuery({
queryKey: ['clients', user?.login],
queryFn: rdvmedecins.getClients,
enabled: isManager, // un USER recibiría 403
});
// la agenda: la clave contiene el médico y el día
const schedule = useQuery({
queryKey: ['schedule', doctorId, day, user?.login],
queryFn: () => rdvmedecins.getSchedule(doctorId!, day),
enabled: loggedIn && doctorId !== null,
});
// una nueva elección de médico o de día borra el mensaje anterior
function chooseDoctor(id: number) {
setDoctorId(id);
setMessage(null);
}
function chooseDay(d: string) {
setDay(d);
setMessage(null);
}
async function book(c: ScheduleSlot) {
try {
await rdvmedecins.book(day, c.id, isManager ? (clientId ?? undefined) : undefined);
setMessage({ type: 'success', text: `Slot ${timeRange(c)} booked.` });
} catch (e) {
setMessage({ type: 'danger', text: errorText(e) });
}
schedule.refetch();
}
async function cancel(c: ScheduleSlot) {
try {
await rdvmedecins.cancelAppointment(c.appointmentId!);
setMessage({ type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` });
} catch (e) {
setMessage({ type: 'danger', text: errorText(e) });
}
schedule.refetch();
}
const a = schedule.data;
return (
<div className="container py-4">
<h1 className="h3 mb-3">Example 24 - an API access layer</h1>
<LoginBar onUserChange={setUser} />
{loggedIn && (
<>
<div className="row g-2 mb-3">
<div className="col-sm-5">
<select className="form-select" value={doctorId ?? ''} onChange={(e) => chooseDoctor(Number(e.target.value))}>
<option value="" disabled>-- choose a doctor --</option>
{doctors.data?.map((m) => <option key={m.id} value={m.id}>{m.title} {m.firstName} {m.lastName}</option>)}
</select>
</div>
<div className="col-sm-3">
<input type="date" className="form-control" value={day} onChange={(e) => chooseDay(e.target.value)} />
</div>
{isManager && (
<div className="col-sm-4">
<select className="form-select" value={clientId ?? ''}
onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
<option value="">-- patient to book for --</option>
{clients.data?.map((c) => <option key={c.id} value={c.id}>{c.title} {c.firstName} {c.lastName}</option>)}
</select>
</div>
)}
</div>
{message && <div className={`alert alert-${message.type}`}>{message.text}</div>}
{schedule.error && <div className="alert alert-danger">{errorText(schedule.error)}</div>}
{schedule.isFetching && <p className="small text-muted">loading the schedule...</p>}
{a && (
<>
{/* info: la clave enviada por el servidor cuando un paciente ya tiene una cita próxima */}
{a.info && <div className="alert alert-info">{a.info}</div>}
<table className="table table-sm align-middle">
<caption className="caption-top">
Schedule of {a.day} - {a.doctor.title} {a.doctor.firstName} {a.doctor.lastName}
</caption>
<tbody>
{a.slots.map((c) => (
<tr key={c.id}>
<td>{timeRange(c)}</td>
<td>
{c.free ? (
<span className="badge text-bg-success">Free</span>
) : c.patient ? (
<span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>
{c.patient.title} {c.patient.firstName} {c.patient.lastName}
</span>
) : (
<span className="badge text-bg-secondary">Booked</span>
)}
</td>
<td className="text-end">
{/* los botones siguen los permisos calculados por el servidor */}
{c.bookable && <button className="btn btn-sm btn-outline-success" onClick={() => book(c)}>Book</button>}
{c.appointmentId !== null && <button className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>Cancel</button>}
</td>
</tr>
))}
</tbody>
</table>
</>
)}
</>
)}
</div>
);
}
|
- líneas 54–58: [useQuery({ queryKey, queryFn, enabled })] describe una LECTURA de datos:
- [queryFn]: la función que los obtiene, una promesa;
- [queryKey]: lo que IDENTIFICA los datos, un arreglo. [TanStack Query] llama a [queryFn] primero, y luego cada vez que la clave CAMBIA; dos componentes que piden la misma clave comparten la misma solicitud y la misma respuesta. Se le agrega el usuario: la lista se vuelve a cargar cuando cambia el usuario;
- [enabled: false]: sin solicitud (nadie tiene la sesión iniciada);
- El resultado es un objeto: [data] (la respuesta, [undefined] hasta que llega), [isPending], [isFetching] (hay una solicitud en curso), [error] y [refetch()] para volver a leerlos;
- líneas 59–63: la lista de pacientes, solo para ADMIN y DOCTOR (un USER recibiría un 403);
- líneas 66–70: la agenda: la clave contiene el médico y el día; cambiar cualquiera de los dos envía una nueva solicitud. Una respuesta vencida se ignora automáticamente;
- líneas 82–90: una reserva: [POST /api/appointments], luego [schedule.refetch()]: la agenda se vuelve a leer. El SERVIDOR es la fuente de autoridad;
- línea 106: la barra de conexión notifica a la página;
- línea 114: los médicos, si ya llegaron ([?.]: nada si [data] es [undefined]);
- línea 133: hay una solicitud de la agenda en curso;
- líneas 160–161: los botones siguen los permisos calculados por el servidor;
- línea 138: [info]: la clave enviada por el servidor cuando un paciente ya tiene una cita futura (se muestra sin procesar: aquí no hay diccionario).
Con la sesión iniciada como [admin], se selecciona a la Sra. PELISSIER, luego a un paciente, y se reserva la primera franja horaria:

Con la sesión iniciada como [martin], se reserva una franja horaria: el paciente ve su propio nombre, pero nunca se le envía el nombre de otro paciente; el botón “Book” ya no está disponible (solo una cita futura):

Para el procesamiento de transacciones (reservar, cancelar), [TanStack Query] también ofrece [useMutation], que maneja el estado “en curso” y los errores de las modificaciones. Aquí no lo usaremos: bastan una función [async] y un [try / catch].
8.4. Ejemplo 25: errores devueltos por el servidor
Gestión de pacientes (formulario de [admin]). Este formulario no realiza ninguna validación en el navegador: todo se envía al servidor, que responde, en caso de rechazo, con un error JSON:
| 400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' } (optimistic lock)
|
8.4.1. Diccionarios
| {
"FORM": {
"TITLE_ADD": "Ajouter un client",
"TITLE_EDIT": "Modifier un client",
"TITLE": "Titre",
"FIRSTNAME": "Prénom",
"LASTNAME": "Nom",
"LOGIN": "Login",
"PASSWORD": "Mot de passe",
"SAVE": "Enregistrer",
"CANCEL": "Annuler",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"DELETE_CONFIRM": "Supprimer le client {{name}}, son compte et ses rendez-vous ?",
"ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
"UPDATED": "Le client {{name}} a été modifié.",
"DELETED": "Le client {{name}} a été supprimé.",
"ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients."
},
"ERRORS": {
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
"FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
"AUTH_REQUIRED": "Connectez-vous d'abord.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"SERVER_UNREACHABLE": "Le serveur ne répond pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite."
}
}
|
Las claves [ERRORS.*] son las que devuelve el servidor. El diccionario en inglés, [en.json], tiene las mismas claves. La configuración de [i18next] es la misma que en el ejemplo 21, pero más simple:
| // =========================================================================
// 25-server-errors/src/i18n/i18n.ts - i18next, como en el ejemplo 21
// =========================================================================
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';
i18n.use(initReactI18next).init({
resources: { fr: { translation: fr }, en: { translation: en } },
lng: 'en',
fallbackLng: 'en',
interpolation: { escapeValue: false },
});
|
| // =========================================================================
// 25-server-errors/src/main.tsx
// -------------------------------------------------------------------------
// - i18next (cf. ejemplo 21);
// - el cuadro de diálogo de confirmación del ejemplo 16, reutilizado tal cual.
// =========================================================================
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import './i18n/i18n';
import App from './App';
import { ConfirmationProvider } from '../../16-confirmation/src/confirmation/confirmation';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<ConfirmationProvider>
<App />
</ConfirmationProvider>
</StrictMode>,
);
|
La ventana de confirmación del ejemplo 16 se reutiliza tal cual: se importa su proveedor.
8.4.2. La página
| // =========================================================================
// 25-server-errors/src/App.tsx - mostrar los errores del SERVIDOR
// -------------------------------------------------------------------------
// La gestión de los clientes (cuenta de administrador). Este formulario no hace
// DELIBERADAMENTE ninguna validación en el navegador: todo se envía
// al servidor, que responde, en caso de rechazo, con un error JSON (convertido
// en un ApiError por common/api.ts):
//
// 400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
// 409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
// 409 { key: 'ERRORS.CONCURRENT_UPDATE' } (bloqueo optimista)
//
// El error de CADA campo (ApiError.fields) se almacena en el estado y se
// muestra bajo el campo; su mensaje es la CLAVE enviada por el servidor,
// que el componente traduce (i18next). Modificar un campo borra su error.
// Pruebe: un apellido vacío, un título "Dr", un homónimo (Alice DURAND), un
// login ya usado (martin), el mismo registro editado en dos pestañas...
// =========================================================================
import { useState, useTransition, type FormEvent } from 'react';
import { useTranslation } from 'react-i18next';
import { api } from '../../common/api';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { Person, User } from '../../common/types';
import { useConfirmation } from '../../16-confirmation/src/confirmation/confirmation';
interface ClientInput {
title: string;
firstName: string;
lastName: string;
login: string;
password: string;
version: number;
}
type Field = keyof ClientInput;
const EMPTY: ClientInput = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 };
interface Message {
key: string;
params?: Record<string, string>;
}
export default function App() {
const { t, i18n } = useTranslation();
const confirm = useConfirmation();
const [user, setUser] = useState<User | null>(null);
const [clients, setClients] = useState<Person[]>([]);
const isAdmin = user?.role === 'ADMIN';
// el formulario: editedId === null -> creación, de lo contrario actualización
const [editedId, setEditedId] = useState<number | null>(null);
const [input, setInput] = useState<ClientInput>(EMPTY);
// el error de cada campo (una CLAVE de traducción), devuelto por el servidor
const [errors, setErrors] = useState<Partial<Record<Field, string>>>({});
// el mensaje general del último error, y el de un éxito
const [pageError, setPageError] = useState<ApiError | null>(null);
const [success, setSuccess] = useState<Message | null>(null);
// useTransition: isPending es true durante la ejecución de la acción
// pasada a startTransition - aquí, el envío al servidor
const [sending, startTransition] = useTransition();
async function reload() {
setClients(await api.get<Person[]>('/clients'));
}
async function onUserChange(u: User | null) {
setUser(u);
setClients([]);
if (u?.role === 'ADMIN') {
await reload();
}
}
function clearMessages() {
setErrors({});
setPageError(null);
setSuccess(null);
}
function newForm() {
setEditedId(null);
setInput(EMPTY);
clearMessages();
}
function edit(c: Person) {
setEditedId(c.id);
// la VERSIÓN leída con el registro regresa con la actualización: si alguien
// ha modificado el registro mientras tanto, el servidor responderá 409 CONCURRENT_UPDATE
setInput({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
clearMessages();
}
// un campo modificado: su valor cambia, su error desaparece
function change(field: Field, value: string) {
setInput((s) => ({ ...s, [field]: value }));
setErrors((e) => ({ ...e, [field]: undefined }));
}
function save(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
clearMessages();
// una transición ASÍNCRONA (React 19): sending sigue siendo true hasta
// el final de la función
startTransition(async () => {
try {
const client =
editedId === null
? await api.post<Person>('/clients', input)
: await api.put<Person>(`/clients/${editedId}`, input);
newForm(); // formulario vaciado, mensajes borrados...
// ... excepto este
setSuccess({
key: editedId === null ? 'FORM.ADDED' : 'FORM.UPDATED',
params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
});
await reload();
} catch (e) {
if (!(e instanceof ApiError)) {
throw e;
}
setPageError(e); // el mensaje general
setErrors(e.fields); // el error de cada campo
}
});
}
async function remove(c: Person) {
const name = `${c.firstName} ${c.lastName}`;
if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
return;
}
clearMessages();
try {
await api.delete(`/clients/${c.id}`);
setSuccess({ key: 'FORM.DELETED', params: { name } });
} catch (e) {
setPageError(e instanceof ApiError ? e : null);
}
await reload();
}
// un campo de entrada, con su error traducido
function field(name: 'firstName' | 'lastName' | 'login' | 'password', type = 'text') {
const error = errors[name];
return (
<>
<label className="form-label" htmlFor={name}>{t(`FORM.${name.toUpperCase()}`)}</label>
<input id={name} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={input[name]}
autoComplete={type === 'password' ? 'new-password' : 'off'} onChange={(e) => change(name, e.target.value)} />
{/* el mensaje de un error del servidor es una CLAVE: se traduce */}
{error && <div className="invalid-feedback">{t(error)}</div>}
</>
);
}
return (
<div className="container py-4">
<div className="d-flex justify-content-between align-items-center mb-3">
<h1 className="h3 mb-0">Example 25 - the errors returned by the server</h1>
<select className="form-select form-select-sm w-auto" value={i18n.language} onChange={(e) => i18n.changeLanguage(e.target.value)}>
<option value="fr">FR</option>
<option value="en">EN</option>
</select>
</div>
<LoginBar onUserChange={onUserChange} />
{user && !isAdmin && <p className="alert alert-warning">{t('FORM.ADMIN_ONLY')}</p>}
{isAdmin && (
<div className="row g-4">
<div className="col-lg-6">
<table className="table table-sm align-middle">
<tbody>
{clients.map((c) => (
<tr key={c.id}>
<td>{c.title} {c.firstName} {c.lastName}</td>
<td><code>{c.login}</code></td>
<td className="text-end text-nowrap">
<button className="btn btn-sm btn-outline-primary me-1" onClick={() => edit(c)}>{t('FORM.EDIT')}</button>
<button className="btn btn-sm btn-outline-danger" onClick={() => remove(c)}>{t('FORM.DELETE')}</button>
</td>
</tr>
))}
</tbody>
</table>
</div>
<div className="col-lg-6">
<form className="card p-3" noValidate onSubmit={save}>
<h2 className="h5">{t(editedId === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT')}</h2>
<div className="mb-2">
<label className="form-label" htmlFor="title">{t('FORM.TITLE')}</label>
{/* una opción "Dr" que el servidor rechazará: para ver ERRORS.INVALID_TITLE */}
<select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={input.title}
onChange={(e) => change('title', e.target.value)}>
<option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
</select>
{errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
</div>
<div className="row g-2 mb-2">
<div className="col-sm-6">{field('firstName')}</div>
<div className="col-sm-6">{field('lastName')}</div>
</div>
<div className="row g-2 mb-3">
<div className="col-sm-6">{field('login')}</div>
<div className="col-sm-6">{field('password', 'password')}</div>
</div>
<div className="d-flex gap-2">
<button className="btn btn-primary" disabled={sending}>{t('FORM.SAVE')}</button>
<button type="button" className="btn btn-secondary" onClick={newForm}>{t('FORM.CANCEL')}</button>
</div>
{success && <div className="alert alert-success mt-3 mb-0">{t(success.key, success.params)}</div>}
{/* el mensaje general y el estado HTTP, para entender */}
{pageError && (
<div className="alert alert-danger mt-3 mb-0">
{t(pageError.key, pageError.params)}{' '}
<span className="small text-muted">({pageError.statusCode} {pageError.key})</span>
</div>
)}
</form>
</div>
</div>
)}
</div>
);
}
|
- líneas 54–55: el formulario: [editedId === null] para crear un paciente, o [editedId] para modificar un paciente;
- línea 57: el error de cada campo, una CLAVE de traducción, devuelta por el servidor;
- línea 63: [useTransition] devuelve un indicador de “en curso” y una función [startTransition(action)]. A partir de [React] 19, la acción puede ser [async]: el indicador permanece en true hasta el final de la función, sin necesidad de ningún manejo manual;
- líneas 89–95: modificación de un paciente. La VERSIÓN leída del registro maestro refleja la modificación: si alguien ha modificado el registro maestro entretanto, el servidor responderá con un 409 [ERRORS.CONCURRENT_UPDATE] (bloqueo optimista);
- líneas 98–101: un campo modificado: su valor cambia y su error desaparece;
- líneas 103–129: envío:
- [POST /api/clients] (creación) o [PUT /api/clients/:id] (actualización);
- si tiene éxito: el formulario se limpia y se traduce un mensaje, junto con sus parámetros;
- en el caso de [ApiError] (líneas 125–126): el mensaje general y el error de CADA campo; la fila tal como aparece en el informe: [e.fields] tiene exactamente el formato deseado;
- líneas 131–144: eliminación, tras la confirmación. El mensaje de confirmación lo traduce [t], con un parámetro;
- líneas 147–158: una función que crea un campo de entrada con su etiqueta y su mensaje de error: [t(error)] traduce la CLAVE enviada por el servidor;
- línea 164: selección del idioma: los errores ya mostrados se vuelven a traducir, ya que son claves;
- línea 199: una opción “Dr” que el servidor rechazará, con el resultado [ERRORS.INVALID_TITLE];
- línea 212: el botón se deshabilita durante el envío;
- línea 219: el mensaje general y el estado HTTP, para dar contexto.
Con la sesión iniciada como [admin], con el título “Dr”, un nombre vacío y un login no válido:

Un homónimo (Alice Durand, que ya existe) y un login ya en uso ([martin]): 409, y se señalan los dos campos afectados:

La misma página en francés: los mensajes del servidor se traducen de nuevo:

Una incorporación exitosa:

Luego, su eliminación:


Para ver el bloqueo optimista, abra el mismo registro en dos pestañas, guárdelo en la primera pestaña y luego en la segunda: el servidor responde con un error 409 ([ERRORS.CONCURRENT_UPDATE]).