Skip to content

8. Comunicación con el servidor

Los ejemplos de este capítulo consultan el servidor JSON [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 [Vite] utilizado en los ejemplos, en el puerto 5173.

8.1. Ejemplo 17: una primera solicitud HTTP

8.1.1. El proxy de Vite

La página de ejemplo proviene de http://localhost:5173 (el servidor [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 [fetch] no envía cookies (y por lo tanto tampoco el token) a otro origen salvo que se le indique ([credentials: 'include']) Y el servidor lo acepte, de nuevo mediante CORS.

En lugar de abrir el servidor a otros orígenes, enrutamos las solicitudes de la API a través del servidor de Vite. Este es el proxy declarado en [vite.config.ts]:

1
2
3
4
5
6
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },

El navegador envía [GET http://localhost:5173/api/captcha]; [Vite] 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:

Image

En producción, ya no habrá un [Vite]: el propio servidor JSON servirá los archivos compilados del cliente (véase el capítulo “Despliegue”). La página y la API seguirán compartiendo el mismo origen.

8.1.2. La solicitud

<!--
  =========================================================================
  17-fetch/src/App.vue - una primera solicitud HTTP al servidor
  -------------------------------------------------------------------------
  El servidor JSON de RdvMedecins debe estar en ejecución (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: esperamos la respuesta con await;
    - response.ok: true para un código 2xx; response.json() lee el cuerpo
      JSON (otra promesa);
    - la dirección es RELATIVA (/api/captcha): la solicitud va al
      servidor de la página, Vite (puerto 5173), que la reenvía al servidor JSON
      (puerto 8080) gracias a su proxy (vea vite.config.ts);
    - tres estados a mostrar: en curso, exitoso, fallido.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';

// lo que devuelve GET /api/captcha
interface Captcha {
  id: string;
  svg: string;
}

const captcha = ref<Captcha | null>(null);
const loading = ref(false);
const error = ref<string | null>(null);
const requestCount = ref(0);

async function load(): Promise<void> {
  loading.value = true;
  error.value = null;
  try {
    const response = await fetch('/api/captcha');
    requestCount.value++;
    if (!response.ok) {
      // el servidor respondió, pero con un error (4xx, 5xx) - o es
      // Vite quien responde 502/504 porque el servidor JSON está detenido
      throw new Error(`the server responded ${response.status} ${response.statusText}`);
    }
    captcha.value = (await response.json()) as Captcha;
  } catch (e) {
    // fetch mismo falla cuando no llega ninguna respuesta (red caída...)
    error.value = e instanceof Error ? e.message : String(e);
    captcha.value = null;
  } finally {
    loading.value = false;
  }
}

// en la primera visualización, se carga un captcha
onMounted(load);
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 17 - a first HTTP request</h1>
    <div class="card p-3">
      <p v-if="loading" class="text-muted">Loading...</p>
      <div v-else-if="error" class="alert alert-danger mb-3">
        Unable to get a captcha: {{ error }}.<br>
        Is the RdvMedecins JSON server running (port 8080)?
      </div>
      <template v-else-if="captcha">
        <!-- v-html: inserta una cadena como HTML (aquí, la imagen SVG).
             Usar SOLO para contenido seguro: este SVG lo construye
             NUESTRO servidor. Con datos del usuario, v-html abriría
             la puerta a la inyección de scripts ({{ }}, por su parte, escapa todo). -->
        <div class="captcha mb-2" v-html="captcha.svg"></div>
        <p class="small text-muted">id: <code>{{ captcha.id }}</code></p>
      </template>
      <button class="btn btn-primary align-self-start" :disabled="loading" @click="load">Another image</button>
      <p class="small text-muted mt-2 mb-0">{{ requestCount }} successful request(s) - open the Network tab of the developer tools (F12).</p>
    </div>
  </div>
</template>

<style scoped>
/* :deep(svg): la regla alcanza el <svg> insertado por v-html, que "scoped" ignoraría de otro modo */
.captcha :deep(svg) {
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
</style>
  • línea 22: el formato de la respuesta de [GET /api/captcha];
  • líneas 27–29: los tres estados de una solicitud: en curso, exitosa (el CAPTCHA) y con error;
  • línea 36: [fetch(url)], la función del navegador que envía una solicitud HTTP. Devuelve una promesa de respuesta; [await] suspende la función [async] hasta que la promesa se resuelve, sin bloquear la página. La dirección es relativa: la solicitud se envía al servidor de la página, [Vite], que la reenvía;
  • línea 38: [fetch] NO informa un error cuando el servidor devuelve una respuesta 404 o 500: sí recibió una respuesta. Nos corresponde a nosotros comprobar [response.ok] (true para un código 2xx). Si el servidor JSON está caído, [Vite] responde con un error 5xx;
  • línea 43: [response.json()] lee el cuerpo y lo convierte en un objeto (otra promesa más). [as Captcha] informa a [TypeScript] del formato del objeto: el compilador no puede verificar lo que enviará el servidor;
  • línea 44: [fetch] falla por sí mismo cuando no se recibe ninguna respuesta (red caída);
  • línea 48: en cualquier caso, la solicitud ya no está en curso;
  • línea 54: en la primera visualización, se carga un CAPTCHA;
  • línea 71: [v-html] inserta una cadena como HTML (aquí, la imagen SVG). Úselo ÚNICAMENTE con contenido seguro: este SVG lo genera NUESTRO servidor. Con datos ingresados por el usuario, [v-html] podría permitir la inyección de scripts en la página; las llaves [{{ }}], en cambio, escapan todo;
  • línea 82: [:deep(...)]: una regla [scoped] normalmente solo afecta a los elementos de la plantilla; el [<svg>] insertado por [v-html] no forma parte de ella.

Image

En las herramientas de desarrollo del navegador (F12), la pestaña Network muestra la solicitud [captcha], enviada a [localhost:5173], y su respuesta JSON.

<!--
  =========================================================================
  18-login/src/App.vue - inicio de sesión en el servidor RdvMedecins
  -------------------------------------------------------------------------
    1. 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 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 aparece);
    3. solicitud protegida: GET /api/doctors. El navegador adjunta la cookie
       por sí mismo (mismo origen);
    4. logout: POST /api/auth/logout - el servidor elimina la cookie.

  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 19 y 20
  también tienen la sesión iniciada.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';

interface User {
  login: string;
  name: string;
  role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: 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 20 usará vue-i18n)
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.',
};

const user = ref<User | null>(null);
const doctors = ref<Doctor[]>([]);
const captcha = ref<{ id: string; svg: string } | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);
const ready = ref(false); // ¿ya terminó la verificación inicial?

async function loadCaptcha(): Promise<void> {
  captcha.value = await (await fetch('/api/captcha')).json();
  input.captcha = '';
}

// 1. ¿quién ha iniciado sesión? 200 -> el usuario; 401 -> nadie
async function checkSession(): Promise<void> {
  const response = await fetch('/api/auth/me');
  if (response.ok) {
    user.value = await response.json();
    await loadDoctors();
  } else {
    await loadCaptcha();
  }
  ready.value = true;
}

// 2. iniciar sesión
async function logIn(): Promise<void> {
  error.value = null;
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    // el servidor rechaza (415) un POST que no esté en JSON
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      login: input.login,
      password: input.password,
      captchaId: captcha.value?.id,
      captcha: input.captcha,
    }),
  });
  if (response.ok) {
    user.value = await response.json();
    input.password = '';
    await loadDoctors();
    return;
  }
  // un error: el cuerpo JSON indica cuál; cada imagen solo puede usarse una vez
  const e = (await response.json()) as ApiError;
  error.value = `${response.status} - ${MESSAGES[e.key] ?? e.key}`;
  await loadCaptcha();
}

// 3. una solicitud protegida
async function loadDoctors(): Promise<void> {
  const response = await fetch('/api/doctors');
  doctors.value = response.ok ? await response.json() : [];
}

// 4. cerrar sesión
async function logOut(): Promise<void> {
  await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
  user.value = null;
  doctors.value = [];
  await loadCaptcha();
}

onMounted(() => {
  checkSession().catch(() => {
    error.value = 'Is the RdvMedecins JSON server running (port 8080)?';
    ready.value = true;
  });
});
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 18 - logging in to the server</h1>
    <p v-if="!ready" class="text-muted">Checking the session...</p>

    <!-- sesión iniciada -->
    <div v-else-if="user" class="card p-3">
      <p>Logged in: <strong>{{ user.name }}</strong> ({{ user.login }}),
        role <span class="badge text-bg-primary">{{ user.role }}</span></p>
      <h2 class="h6">GET /api/doctors</h2>
      <ul>
        <li v-for="m in doctors" :key="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</li>
      </ul>
      <p class="small text-muted">Reload the page (F5): you stay logged in.</p>
      <button class="btn btn-outline-secondary align-self-start" @click="logOut">Log out</button>
    </div>

    <!-- sin sesión iniciada: el formulario -->
    <form v-else class="card p-3" @submit.prevent="logIn">
      <div class="mb-2">
        <label class="form-label" for="login">Login</label>
        <input id="login" v-model="input.login" class="form-control" autocomplete="username">
      </div>
      <div class="mb-2">
        <label class="form-label" for="password">Password</label>
        <input id="password" v-model="input.password" type="password" class="form-control" autocomplete="current-password">
      </div>
      <div class="mb-3">
        <label class="form-label" for="captcha">Type the characters shown in the image</label>
        <div class="d-flex align-items-center gap-3 mb-2">
          <div v-if="captcha" v-html="captcha.svg"></div>
          <a href="#" class="small" @click.prevent="loadCaptcha">Another image</a>
        </div>
        <input id="captcha" v-model="input.captcha" class="form-control" autocomplete="off">
      </div>
      <button class="btn btn-primary">Log in</button>
      <p class="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
    </form>

    <div v-if="error" class="alert alert-danger mt-3">{{ error }}</div>
  </div>
</template>
  • línea 35: el formato de todos los errores de la API;
  • línea 42: los pocos mensajes que requiere este ejemplo, en inglés; el Ejemplo 20 utilizará [vue-i18n];
  • líneas 61–69: al iniciar, [GET /api/auth/me]: ¿ya hay una sesión iniciada? Después de recargar la página (F5), la aplicación [Vue.js] lo ha olvidado todo; el servidor, en cambio, lee la cookie. 200: el usuario; 401: nadie;
  • líneas 73–96: la conexión:
    • línea 76: [fetch(url, options)]: el método, los encabezados y el cuerpo;
    • línea 78: el servidor rechaza un POST que no está en formato JSON;
    • línea 79: el cuerpo, convertido a texto JSON;
    • línea 87: si tiene éxito, el servidor ha establecido la cookie del token. Nuestro código NUNCA la ve: escriba [document.cookie] en la consola del navegador; no aparece ([HttpOnly]);
    • línea 93: si la solicitud falla, el cuerpo explica el motivo. Mostramos el mensaje y solicitamos una nueva imagen: cada imagen se usa una sola vez;
  • líneas 99–102: una solicitud protegida. No necesitamos hacer nada para autenticarnos: el navegador incluye la cookie automáticamente porque la solicitud va al mismo origen que la página (por defecto, [fetch] envía las cookies en las solicitudes del mismo origen);
  • líneas 105–110: cierre de sesión: el servidor elimina la cookie. El cuerpo ['{}'] se incluye para que la solicitud sea un POST JSON.

El formulario de inicio de sesión:

Image

Con un CAPTCHA ingresado incorrectamente (el servidor está en modo de prueba: cualquier CAPTCHA acepta la respuesta [test]):

Image

Sesión iniciada:

Image

Recargue la página (F5): la sesión permanece iniciada. A continuación, abra el Ejemplo 19: allí también tiene la sesión iniciada. Una cookie pertenece a una máquina (aquí, [localhost]) y a una ruta (aquí, [/api]), que son comunes a todos los ejemplos.

8.3. Ejemplo 19: una capa de acceso a la API

El Ejemplo 18 repetía los mismos pasos en cada llamada a [fetch]: el prefijo [/api], el encabezado [Content-Type], [JSON.stringify], la comprobación de [response.ok] y la lectura del cuerpo del error. Los agrupamos en una sola función, en la carpeta [common] (compartida por los ejemplos 19 y 20):

// =========================================================================
// common/api.ts - UNA función para todas las solicitudes a la API
// -------------------------------------------------------------------------
// En el ejemplo 18, cada llamada a fetch repetía los mismos gestos:
// prefijo /api, encabezado Content-Type, JSON.stringify, prueba de response.ok,
// lectura del cuerpo del error... Aquí se agrupan, de una vez por todas:
//
//   const doctors = await api.get<Person[]>('/doctors');
//   await api.post('/appointments', { day, slotId, clientId });
//
//   - en caso de éxito, la promesa devuelve el cuerpo JSON, TIPADO;
//   - en caso de fallo, es RECHAZADA con un ApiError, que transporta la
//     clave de traducción enviada por el servidor (y, si los hay, sus
//     parámetros y el error de cada campo).
// Usado por los ejemplos 19 y 20; el caso de estudio retoma su principio.
// =========================================================================

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0: el servidor no respondió
    public readonly key: string, // p. ej.: 'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {},
  ) {
    super(key);
    this.name = 'ApiError';
  }
}

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

export async function request<T>(method: Method, 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 sea)
      headers: body !== undefined ? { 'Content-Type': 'application/json' } : {},
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
  } catch {
    // sin respuesta (red caída...)
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }

  // el cuerpo se lee como texto y luego se convierte: una respuesta vacía, o una
  // que no es JSON (servidor JSON detenido: es Vite quien responde),
  // no debe bloquear la aplicación
  const text = await response.text();
  let data: unknown = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    data = null;
  }

  if (!response.ok) {
    const e = (data ?? {}) as { key?: string; params?: Record<string, string>; fields?: Record<string, string> };
    throw new ApiError(response.status, e.key ?? 'ERRORS.SERVER_UNREACHABLE', e.params, e.fields);
  }
  return data as T;
}

// atajos, más legibles al usarlos
export const api = {
  get: <T>(url: string) => request<T>('GET', url),
  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 18–27: una clase de error que contiene la respuesta del servidor: el código HTTP, la clave del mensaje, sus parámetros y el error de cada campo. El código 0 significa “sin respuesta”;
  • línea 32: una función genérica: [T] es el tipo del cuerpo esperado en caso de éxito. [request<Person[]>('GET', '/doctors')] devuelve una [Promise<Person[]>];
  • línea 38: un cuerpo, y solo en ese caso, acompañado del encabezado JSON;
  • líneas 49–55: el cuerpo se lee como texto y luego se convierte. Una respuesta vacía, o que no sea JSON (servidor caído: [Vite] responde con texto), no debe hacer que la aplicación falle;
  • líneas 57–60: un fallo produce un [ApiError]: la promesa devuelta por [request] es rechazada. El código que llama la captura mediante [try / catch];
  • líneas 65–70: atajos, más legibles: [api.get<T>(url)], [api.post<T>(url, body)]... [api.post] envía por defecto el cuerpo [{}].

Los tipos de objeto JSON de la API, descritos en el capítulo anterior:

// =========================================================================
// common/types.ts - los objetos JSON intercambiados con la API de RdvMedecins
// (vea 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;
}

Un componente de conexión, reescrito con [api.ts] y reducido a una barra:

<!--
  =========================================================================
  common/LoginBar.vue - iniciar / cerrar sesión, en una sola barra
  -------------------------------------------------------------------------
  El componente del ejemplo 18, reducido a una barra y reescrito con
  common/api.ts. Emite 'change' con el usuario conectado (o null)
  cada vez que cambia el usuario - incluso al arrancar, después de haber
  consultado GET /api/auth/me.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
import { api, ApiError } from './api';
import type { Captcha, User } from './types';

const emit = defineEmits<{ change: [user: User | null] }>();

const user = ref<User | null>(null);
const captcha = ref<Captcha | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);

async function newCaptcha(): Promise<void> {
  captcha.value = await api.get<Captcha>('/captcha');
  input.captcha = '';
}

function setUser(u: User | null): void {
  user.value = u;
  emit('change', u);
}

onMounted(async () => {
  try {
    setUser(await api.get<User>('/auth/me'));
  } catch {
    setUser(null); // 401: nadie ha iniciado sesión
    await newCaptcha().catch(() => (error.value = 'Is the JSON server running (port 8080)?'));
  }
});

async function logIn(): Promise<void> {
  error.value = null;
  try {
    const u = await api.post<User>('/auth/login', {
      login: input.login,
      password: input.password,
      captchaId: captcha.value?.id,
      captcha: input.captcha,
    });
    input.password = '';
    setUser(u);
  } catch (e) {
    error.value = e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e);
    await newCaptcha();
  }
}

async function logOut(): Promise<void> {
  await api.post('/auth/logout');
  setUser(null);
  await newCaptcha();
}
</script>

<template>
  <div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
    <template v-if="user">
      <span>Logged in: <strong>{{ user.name }}</strong> <span class="badge text-bg-primary">{{ user.role }}</span></span>
      <button class="btn btn-sm btn-outline-secondary ms-auto" @click="logOut">Log out</button>
    </template>
    <form v-else class="d-flex flex-wrap align-items-center gap-2 w-100" @submit.prevent="logIn">
      <input v-model="input.login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username">
      <input v-model="input.password" type="password" class="form-control form-control-sm w-auto" placeholder="password" autocomplete="current-password">
      <div v-if="captcha" class="captcha" v-html="captcha.svg"></div>
      <input v-model="input.captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8">
      <button class="btn btn-sm btn-primary">Log in</button>
      <span v-if="error" class="text-danger small">{{ error }}</span>
    </form>
  </div>
</template>

<style scoped>
/* la imagen del captcha, reducida para caber en la barra */
.captcha :deep(svg) {
  display: block;
  height: 32px;
  width: auto;
}
</style>
  • línea 16: el componente emite [change] con el usuario conectado (o [null]) cada vez que cambia, incluso al iniciar;
  • línea 35: con [api.ts], una solicitud cabe en una línea; en caso de fallo (401), pasa a [catch];
  • línea 54: [instanceof] distingue un error de la API de otra anomalía.

Encima de [api.ts], una función por ruta de la API:

// =========================================================================
// 19-api-service/src/rdvmedecins.service.ts - la capa de acceso a la API
// -------------------------------------------------------------------------
// Una función tipada por cada ruta de la API. Los componentes no conocen
// 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, el nombre de un 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}`),
};

Este es el equivalente en el cliente de la capa DAO del servidor: los componentes no conocen las URL, [fetch] ni el formato JSON; llaman a funciones tipadas. Si la API cambia, solo cambia este archivo.

  • línea 18: [URLSearchParams] genera la cadena [doctorId=1&day=2030-01-15] codificando los caracteres que deben codificarse.

La página:

<!--
  =========================================================================
  19-api-service/src/App.vue - 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 autoridad.
  =========================================================================
-->
<script setup lang="ts">
import { computed, ref, watch } from 'vue';
import LoginBar from '../../common/LoginBar.vue';
import { ApiError } from '../../common/api';
import type { Schedule, ScheduleSlot, Person, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins.service';

const user = ref<User | null>(null);
const doctors = ref<Person[]>([]);
const clients = ref<Person[]>([]);
const doctorId = ref<number | null>(null);
const day = ref(tomorrow());
const schedule = ref<Schedule | null>(null);
const clientId = ref<number | null>(null);
const message = ref<{ type: 'success' | 'danger'; text: string } | null>(null);

const isManager = computed(() => user.value !== null && user.value.role !== 'USER');

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 de la API se convierte en un mensaje (su clave, a falta de un diccionario aquí)
function report(e: unknown): void {
  message.value = { type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) };
}

// login / logout: (re)cargamos lo que este rol tiene permitido ver
async function onUserChange(u: User | null): Promise<void> {
  user.value = u;
  schedule.value = null;
  doctors.value = [];
  clients.value = [];
  if (u === null) {
    return;
  }
  try {
    doctors.value = await rdvmedecins.getDoctors();
    // la lista de pacientes: solo para ADMIN y DOCTOR (un USER recibiría 403)
    clients.value = isManager.value ? await rdvmedecins.getClients() : [];
  } catch (e) {
    report(e);
  }
}

async function loadSchedule(): Promise<void> {
  if (doctorId.value === null) {
    return;
  }
  try {
    schedule.value = await rdvmedecins.getSchedule(doctorId.value, day.value);
  } catch (e) {
    schedule.value = null;
    report(e);
  }
}

// la agenda sigue la elección del médico y del día
watch([doctorId, day], () => {
  message.value = null;
  loadSchedule();
});

async function book(c: ScheduleSlot): Promise<void> {
  try {
    await rdvmedecins.book(day.value, c.id, isManager.value ? (clientId.value ?? undefined) : undefined);
    message.value = { type: 'success', text: `Slot ${timeRange(c)} booked.` };
  } catch (e) {
    report(e);
  }
  await loadSchedule();
}

async function cancel(c: ScheduleSlot): Promise<void> {
  try {
    await rdvmedecins.cancelAppointment(c.appointmentId as number);
    message.value = { type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` };
  } catch (e) {
    report(e);
  }
  await loadSchedule();
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 19 - an API access layer</h1>
    <LoginBar @change="onUserChange" />

    <template v-if="user">
      <div class="row g-2 mb-3">
        <div class="col-sm-5">
          <select v-model="doctorId" class="form-select">
            <option :value="null" disabled>-- choose a doctor --</option>
            <option v-for="m in doctors" :key="m.id" :value="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
          </select>
        </div>
        <div class="col-sm-3"><input v-model="day" type="date" class="form-control"></div>
        <div v-if="isManager" class="col-sm-4">
          <select v-model="clientId" class="form-select">
            <option :value="null">-- patient to book for --</option>
            <option v-for="c in clients" :key="c.id" :value="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
          </select>
        </div>
      </div>

      <div v-if="message" class="alert" :class="`alert-${message.type}`">{{ message.text }}</div>
      <!-- info: la clave enviada por el servidor cuando un paciente ya tiene una cita próxima -->
      <div v-if="schedule?.info" class="alert alert-info">{{ schedule.info }}</div>

      <table v-if="schedule" class="table table-sm align-middle">
        <caption class="caption-top">Schedule of {{ schedule.day }} - {{ schedule.doctor.title }} {{ schedule.doctor.firstName }} {{ schedule.doctor.lastName }}</caption>
        <tbody>
          <tr v-for="c in schedule.slots" :key="c.id">
            <td>{{ timeRange(c) }}</td>
            <td>
              <span v-if="c.free" class="badge text-bg-success">Free</span>
              <span v-else-if="c.patient" class="badge" :class="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">
                {{ c.patient.title }} {{ c.patient.firstName }} {{ c.patient.lastName }}
              </span>
              <span v-else class="badge text-bg-secondary">Booked</span>
            </td>
            <td class="text-end">
              <!-- los botones siguen los derechos calculados por el servidor -->
              <button v-if="c.bookable" class="btn btn-sm btn-outline-success" @click="book(c)">Book</button>
              <button v-if="c.appointmentId !== null" class="btn btn-sm btn-outline-danger" @click="cancel(c)">Cancel</button>
            </td>
          </tr>
        </tbody>
      </table>
    </template>
  </div>
</template>
  • línea 27: ADMIN o DOCTOR;
  • líneas 45–60: cada vez que un usuario inicia o cierra sesión, se (re)carga el contenido que este rol está autorizado a ver. Un paciente recibiría un error 403 al pedir la lista de clientes: ni siquiera la solicitamos;
  • línea 75: [watch] puede observar varias fuentes: el calendario se recarga cuando cambia el médico O el día;
  • líneas 80–87: una reserva, seguida, PASE LO QUE PASE, de una actualización del calendario. El registro del servidor es el definitivo: si el horario fue tomado por otra persona entretanto, el calendario actualizado lo mostrará;
  • líneas 141 y 142: los botones reflejan los permisos calculados por el servidor;
  • línea 137: un horario reservado para el cual el servidor no ha asignado un paciente (visto por un paciente).

Con la sesión iniciada como [admin], seleccione un médico, un paciente y reserve un horario:

Image

Reserve una segunda cita para el mismo paciente: el servidor la rechaza. Como en este ejemplo no hay diccionario, se muestra la clave sin procesar:

Image

8.4. Ejemplo 20: errores devueltos por el servidor

Último ejemplo antes del caso de estudio: la gestión de clientes, a cargo del formulario de ADMIN. Este formulario no realiza ninguna validación en el navegador: todo se envía al servidor, que valida los datos y, en caso de rechazo, responde con el error de cada campo. El Ejemplo 06 mostró el enfoque alternativo; este tiene una ventaja importante: las reglas existen en un SOLO lugar (el servidor) y el cliente no puede pasarlas por alto. La contrapartida: un viaje de ida y vuelta al servidor antes de mostrar los errores.

Los diccionarios utilizan los códigos de error del servidor:

{
  "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."
  }
}

([locales/en.json] tiene los mismos códigos, en inglés.)

import { createApp } from 'vue';
import { createI18n } from 'vue-i18n';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App.vue';
import fr from './locales/fr.json';
import en from './locales/en.json';

// la misma configuración que el ejemplo 16, en forma abreviada
const i18n = createI18n({ legacy: false, locale: 'en', fallbackLocale: 'en', messages: { fr, en } });

createApp(App).use(i18n).mount('#app');

La página:

<!--
  =========================================================================
  20-server-errors/src/App.vue - mostrar los errores del SERVIDOR
  -------------------------------------------------------------------------
  La gestión de los clientes (cuenta de administrador). Este formulario
  DELIBERADAMENTE no hace 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' }         (bloqueo optimista)

  El cliente traduce cada clave (vue-i18n) y coloca cada mensaje debajo de su
  campo, el mensaje general al final del formulario. Pruebe: un apellido vacío, un
  título modificado en las herramientas de desarrollo, un homónimo (Alice DURAND),
  un login ya tomado (martin), el mismo registro modificado en dos pestañas...
  =========================================================================
-->
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';
import { useI18n } from 'vue-i18n';
import LoginBar from '../../common/LoginBar.vue';
import { api, ApiError } from '../../common/api';
import type { Person, User } from '../../common/types';
// el cuadro de diálogo de confirmación del ejemplo 12, reutilizado tal cual
import ConfirmDialog from '../../12-confirmation/src/components/ConfirmDialog.vue';
import { useConfirmation } from '../../12-confirmation/src/composables/useConfirmation';

const { t, locale } = useI18n();
const { confirm } = useConfirmation();

const user = ref<User | null>(null);
const clients = ref<Person[]>([]);
const isAdmin = computed(() => user.value?.role === 'ADMIN');

// el formulario: editedId === null -> creación, de lo contrario actualización
const editedId = ref<number | null>(null);
const input = reactive({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
// los errores devueltos por el servidor
const fieldErrors = ref<Record<string, string>>({});
const pageError = ref<ApiError | null>(null);
const success = ref<string | null>(null);

async function onUserChange(u: User | null): Promise<void> {
  user.value = u;
  clients.value = [];
  if (u?.role === 'ADMIN') {
    await reload();
  }
}

async function reload(): Promise<void> {
  clients.value = await api.get<Person[]>('/clients');
}

function newForm(): void {
  editedId.value = null;
  Object.assign(input, { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
  clearErrors();
}

function edit(c: Person): void {
  editedId.value = c.id;
  // la VERSIÓN leída con el registro se devuelve con la actualización: si alguien
  // ha modificado el registro mientras tanto, el servidor responderá 409 CONCURRENT_UPDATE
  Object.assign(input, { title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
  clearErrors();
}

function clearErrors(): void {
  fieldErrors.value = {};
  pageError.value = null;
  success.value = null;
}

// el texto de un error, en el idioma actual, con sus parámetros
function errorText(e: ApiError): string {
  return t(e.key, e.params);
}

async function save(): Promise<void> {
  clearErrors();
  const body = { ...input };
  try {
    const client =
      editedId.value === null
        ? await api.post<Person>('/clients', body)
        : await api.put<Person>(`/clients/${editedId.value}`, body);
    const message = t(editedId.value === null ? 'FORM.ADDED' : 'FORM.UPDATED', {
      name: `${client.firstName} ${client.lastName}`,
      login: client.login ?? '',
    });
    newForm(); // formulario vaciado, mensajes borrados...
    success.value = message; // ... excepto este
    await reload();
  } catch (e) {
    if (!(e instanceof ApiError)) {
      throw e;
    }
    // el error de cada campo, y el mensaje general
    fieldErrors.value = e.fields;
    pageError.value = e;
  }
}

async function remove(c: Person): Promise<void> {
  const name = `${c.firstName} ${c.lastName}`;
  if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
    return;
  }
  clearErrors();
  try {
    await api.delete(`/clients/${c.id}`);
    success.value = t('FORM.DELETED', { name });
  } catch (e) {
    pageError.value = e instanceof ApiError ? e : null;
  }
  await reload();
}
</script>

<template>
  <div class="container py-4">
    <div class="d-flex justify-content-between align-items-center mb-3">
      <h1 class="h3 mb-0">Example 20 - the errors returned by the server</h1>
      <select v-model="locale" class="form-select form-select-sm w-auto">
        <option value="fr">FR</option>
        <option value="en">EN</option>
      </select>
    </div>
    <LoginBar @change="onUserChange" />
    <p v-if="user && !isAdmin" class="alert alert-warning">{{ t('FORM.ADMIN_ONLY') }}</p>

    <div v-if="isAdmin" class="row g-4">
      <div class="col-lg-6">
        <table class="table table-sm align-middle">
          <tbody>
            <tr v-for="c in clients" :key="c.id">
              <td>{{ c.title }} {{ c.firstName }} {{ c.lastName }}</td>
              <td><code>{{ c.login }}</code></td>
              <td class="text-end text-nowrap">
                <button class="btn btn-sm btn-outline-primary me-1" @click="edit(c)">{{ t('FORM.EDIT') }}</button>
                <button class="btn btn-sm btn-outline-danger" @click="remove(c)">{{ t('FORM.DELETE') }}</button>
              </td>
            </tr>
          </tbody>
        </table>
      </div>

      <div class="col-lg-6">
        <form class="card p-3" novalidate @submit.prevent="save">
          <h2 class="h5">{{ editedId === null ? t('FORM.TITLE_ADD') : t('FORM.TITLE_EDIT') }}</h2>
          <div class="mb-2">
            <label class="form-label" for="title">{{ t('FORM.TITLE') }}</label>
            <!-- una opción "Dr" que el servidor rechazará: para ver ERRORS.INVALID_TITLE -->
            <select id="title" v-model="input.title" class="form-select" :class="{ 'is-invalid': fieldErrors.title }">
              <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
            </select>
            <div class="invalid-feedback">{{ fieldErrors.title && t(fieldErrors.title) }}</div>
          </div>
          <div class="row g-2 mb-2">
            <div class="col-sm-6">
              <label class="form-label" for="firstName">{{ t('FORM.FIRSTNAME') }}</label>
              <input id="firstName" v-model="input.firstName" class="form-control" :class="{ 'is-invalid': fieldErrors.firstName }">
              <div class="invalid-feedback">{{ fieldErrors.firstName && t(fieldErrors.firstName) }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="lastName">{{ t('FORM.LASTNAME') }}</label>
              <input id="lastName" v-model="input.lastName" class="form-control" :class="{ 'is-invalid': fieldErrors.lastName }">
              <div class="invalid-feedback">{{ fieldErrors.lastName && t(fieldErrors.lastName) }}</div>
            </div>
          </div>
          <div class="row g-2 mb-3">
            <div class="col-sm-6">
              <label class="form-label" for="login">{{ t('FORM.LOGIN') }}</label>
              <input id="login" v-model="input.login" class="form-control" :class="{ 'is-invalid': fieldErrors.login }">
              <div class="invalid-feedback">{{ fieldErrors.login && t(fieldErrors.login) }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="password">{{ t('FORM.PASSWORD') }}</label>
              <input id="password" v-model="input.password" type="password" class="form-control" autocomplete="new-password"
                     :class="{ 'is-invalid': fieldErrors.password }">
              <div class="invalid-feedback">{{ fieldErrors.password && t(fieldErrors.password) }}</div>
            </div>
          </div>
          <div class="d-flex gap-2">
            <button class="btn btn-primary">{{ t('FORM.SAVE') }}</button>
            <button type="button" class="btn btn-secondary" @click="newForm">{{ t('FORM.CANCEL') }}</button>
          </div>
          <div v-if="success" class="alert alert-success mt-3 mb-0">{{ success }}</div>
          <!-- el mensaje general, y el estado HTTP, para entender -->
          <div v-if="pageError" class="alert alert-danger mt-3 mb-0">
            {{ errorText(pageError) }} <span class="small text-muted">({{ pageError.statusCode }} {{ pageError.key }})</span>
          </div>
        </form>
      </div>
    </div>
  </div>
  <ConfirmDialog />
</template>
  • línea 26: la ventana de confirmación del Ejemplo 12, reutilizada tal cual: un componente bien diseñado es reutilizable;
  • líneas 40 y 41: los errores devueltos por el servidor: el error de cada campo y el mensaje general;
  • líneas 62–68: para modificar un registro, se copian sus valores en el formulario, incluido el número de versión: se guardará junto con la modificación (bloqueo optimista);
  • líneas 77–79: el mensaje de error, en lenguaje cotidiano, junto con sus parámetros;
  • líneas 81–102: [POST] para una creación, [PUT] para una modificación. Si la solicitud es rechazada, se almacenan los errores devueltos; la plantilla se encarga del resto;
  • línea 157: un título que el servidor rechazará, para ver [ERRORS.INVALID_TITLE];
  • líneas 164 y 165: un campo rechazado se resalta en rojo y debajo de él se muestra su código de error traducido;
  • línea 126: cambiar el idioma también vuelve a traducir los mensajes de error ya mostrados: solo se conservaron las claves.

Un formulario llenado incorrectamente:

Image

Un nombre duplicado (Alice DURAND ya existe): el servidor devuelve una respuesta 409 e identifica los campos de nombre y apellido:

Image

El mismo error, en francés:

Image

Pruebe también a editar el mismo registro en dos pestañas: el segundo registro recibe [ERRORS.CONCURRENT_UPDATE].