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 de desarrollo de [Angular] en el puerto 4200.

8.1. Ejemplo 22: una primera solicitud HTTP

8.1.1. El proxy del servidor de desarrollo

La página del ejemplo proviene de http://localhost:4200 (el servidor de desarrollo de [Angular], iniciado por [ng serve]); la API está en http://localhost:8080. Para un navegador, son dos orígenes distintos (el puerto forma parte del origen). Sin embargo, 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 ([withCredentials: true]) Y el servidor lo acepte, de nuevo mediante CORS.

En lugar de abrir el servidor a otros orígenes, hacemos pasar las solicitudes a la API por el servidor de desarrollo de [Angular]. Este es el proxy declarado en el archivo del espacio de trabajo [proxy.conf.json]:

1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}
  • Línea 2: las solicitudes cuya ruta empieza por /api...
  • línea 3: ... se reenvían al servidor JSON.

Para cada ejemplo, el archivo se especifica en las opciones del comando [ng serve] en el archivo [angular.json]:

1
2
3
4
5
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          },

El navegador envía [GET http://localhost:4200/api/captcha]; el servidor de desarrollo reenvía la solicitud a [http://localhost:8080/api/captcha] y luego devuelve la respuesta al navegador. Para el navegador, la página y la API tienen el mismo origen:

Image

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 “Deployment”). La página y la API seguirán compartiendo el mismo origen.

8.1.2. La solicitud

[Angular] proporciona su propio cliente HTTP, el servicio [HttpClient]. Está disponible automáticamente en cualquier aplicación: basta con inyectarlo.

// =========================================================================
// 22-httpclient/src/app/app.ts - una primera petición 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 ...>" }.
//
//   - HttpClient: el cliente HTTP de Angular (proporcionado por defecto a toda la
//     aplicación). http.get<T>(url) devuelve un OBSERVABLE (ver ejemplo
//     19): la petición solo se envía cuando nos SUSCRIBIMOS a él (subscribe);
//     la respuesta JSON llega ya convertida en un objeto, del tipo anunciado T;
//   - la dirección es RELATIVA (/api/captcha): la petición va al
//     servidor de la página, el de Angular (puerto 4200), que la reenvía al
//     servidor JSON (puerto 8080) gracias a su proxy (ver proxy.conf.json);
//   - tres estados que mostrar: cargando, éxito, error.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';

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

@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styles: `
    .captcha {
      display: inline-block;
      border: 1px solid #dee2e6;
      border-radius: 0.375rem;
    }
  `,
})
export class App {
  private readonly http = inject(HttpClient);
  private readonly sanitizer = inject(DomSanitizer);

  protected readonly captcha = signal<Captcha | null>(null);
  protected readonly loading = signal(false);
  protected readonly error = signal<string | null>(null);
  protected readonly requestCount = signal(0);

  // [innerHTML] inserta una cadena como HTML. Por seguridad, Angular
  // LIMPIA este HTML ("sanitization"): elimina los scripts... y las
  // etiquetas <svg>. bypassSecurityTrustHtml le dice a Angular: "este HTML es
  // seguro, no lo limpies". Debe usarse ÚNICAMENTE con contenido seguro: este SVG
  // lo construye NUESTRO servidor. Con datos del usuario, sería
  // abrir la puerta a la inyección de scripts ({{ }}, en cambio, escapa todo).
  protected readonly svg = computed<SafeHtml | null>(() => {
    const c = this.captcha();
    return c ? this.sanitizer.bypassSecurityTrustHtml(c.svg) : null;
  });

  constructor() {
    this.load(); // al iniciar, cargamos un captcha
  }

  protected load(): void {
    this.loading.set(true);
    this.error.set(null);
    this.http.get<Captcha>('/api/captcha').subscribe({
      // next: la respuesta (código 2xx), ya convertida desde JSON
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: una respuesta 4xx / 5xx, o ninguna respuesta (status 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(`the server answered ${e.status} ${e.statusText}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
  • línea 22: el formato de la respuesta de [GET /api/captcha];
  • línea 39: se inyecta el cliente HTTP;
  • líneas 42–45: los tres estados de una solicitud: en curso, exitosa (el CAPTCHA) y con error;
  • línea 65: [http.get<Captcha>(url)] prepara una solicitud GET. Devuelve un observable (ejemplo 19): la solicitud se envía solo cuando se suscribe a él ([subscribe]). La dirección es relativa: la solicitud se envía al servidor de la página, que la reenvía al servidor JSON;
  • líneas 67–71: [next] recibe la respuesta, que ya se ha convertido desde JSON. [<Captcha>] informa a [TypeScript] del formato del objeto: el compilador no puede verificar lo que enviará el servidor;
  • Líneas 73–77: [error] recibe un [HttpErrorResponse] ante cualquier respuesta 4xx o 5xx, así como cuando no se recibe ninguna respuesta (servidor caído, red desconectada: [status] vale entonces 0). Si el servidor JSON está caído, el proxy responde con un error 5xx;
  • línea 59: al iniciar, se carga un CAPTCHA;
  • líneas 53–56: la imagen SVG del CAPTCHA es una cadena de caracteres, que debe insertarse como HTML ([[innerHTML]] en la plantilla). Por razones de seguridad, [Angular] depura cualquier HTML insertado de esta manera: elimina los scripts... y las etiquetas [<svg>]. [bypassSecurityTrustHtml] indica que este HTML es seguro. Lo usamos SOLO para contenido seguro: este SVG lo genera NUESTRO servidor. Con datos introducidos por el usuario, esto permitiría inyectar scripts en la página; las dobles llaves [{{ }}], en cambio, escapan todo.
<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 22 - a first HTTP request</h1>
  <div class="card p-3">
    @if (loading()) {
      <p class="text-muted">Loading...</p>
    } @else if (error()) {
      <div class="alert alert-danger mb-3">
        Unable to get a captcha: {{ error() }}.<br>
        Is the RdvMedecins JSON server running (port 8080)?
      </div>
    } @else if (captcha(); as c) {
      <div class="mb-2"><div class="captcha" [innerHTML]="svg()"></div></div>
      <p class="small text-muted">id: <code>{{ c.id }}</code></p>
    }
    <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>
  • líneas 4–14: una visualización de estado;
  • línea 12: la imagen del CAPTCHA.

[npm start 22-httpclient]; haga clic en [Another image]:

Image

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

// =========================================================================
// 23-login/src/app/app.ts - 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. petición protegida: GET /api/doctors. El navegador le adjunta la cookie
//      por sí mismo (mismo origen);
//   4. logout: POST /api/auth/logout - el servidor elimina la cookie.
//
// firstValueFrom(observable): una PROMESA del primer valor del flujo.
// Las cadenas de peticiones pueden escribirse entonces con async / await,
// más legible que una cascada de subscribe. Una respuesta de error rechaza
// la promesa con una HttpErrorResponse: un simple try / catch.
//
// Una cookie pertenece a una máquina (localhost) y a un path (/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 iniciada.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import { firstValueFrom } from 'rxjs';

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á ngx-translate)
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.',
};

@Component({
  selector: 'app-root',
  imports: [FormsModule],
  templateUrl: './app.html',
})
export class App {
  private readonly http = inject(HttpClient);
  private readonly sanitizer = inject(DomSanitizer);

  protected readonly user = signal<User | null>(null);
  protected readonly doctors = signal<Doctor[]>([]);
  protected readonly captcha = signal<Captcha | null>(null);
  protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
  protected readonly login = signal('admin');
  protected readonly password = signal('');
  protected readonly captchaAnswer = signal('');
  protected readonly error = signal<string | null>(null);
  protected readonly ready = signal(false); // ¿terminó la verificación inicial?

  constructor() {
    this.checkSession().catch(() => {
      this.error.set('Is the RdvMedecins JSON server running (port 8080)?');
      this.ready.set(true);
    });
  }

  protected async loadCaptcha(): Promise<void> {
    this.captcha.set(await firstValueFrom(this.http.get<Captcha>('/api/captcha')));
    this.captchaAnswer.set('');
  }

  // 1. ¿quién ha iniciado sesión? 200 -> el usuario; 401 -> nadie
  private async checkSession(): Promise<void> {
    try {
      this.user.set(await firstValueFrom(this.http.get<User>('/api/auth/me')));
      await this.loadDoctors();
    } catch (e) {
      if (!(e instanceof HttpErrorResponse) || e.status !== 401) {
        throw e; // no es un 401: el servidor no responde
      }
      await this.loadCaptcha();
    }
    this.ready.set(true);
  }

  // 2. el login; post(url, body): el cuerpo se envía como JSON
  protected async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await firstValueFrom(
        this.http.post<User>('/api/auth/login', {
          login: this.login(),
          password: this.password(),
          captchaId: this.captcha()?.id,
          captcha: this.captchaAnswer(),
        }),
      );
      this.user.set(u);
      this.password.set('');
      await this.loadDoctors();
    } catch (e) {
      // e.error: el cuerpo JSON de la respuesta de error
      const apiError = (e as HttpErrorResponse).error as ApiError | null;
      const key = apiError?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      this.error.set(`${(e as HttpErrorResponse).status} - ${MESSAGES[key] ?? key}`);
      await this.loadCaptcha(); // cada imagen se usa una sola vez
    }
  }

  // 3. una petición protegida
  private async loadDoctors(): Promise<void> {
    this.doctors.set(await firstValueFrom(this.http.get<Doctor[]>('/api/doctors')));
  }

  // 4. el logout
  protected async logOut(): Promise<void> {
    await firstValueFrom(this.http.post('/api/auth/logout', {}));
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
  • líneas 30–50: los formatos de los datos intercambiados con el servidor, incluidos los de todos los errores de la API (líneas 46–50);
  • líneas 53–57: los pocos mensajes que necesita este ejemplo, en inglés; el ejemplo 25 usará [ngx-translate];
  • línea 28: [firstValueFrom(observable)] devuelve una promesa con el primer valor del flujo. Una solicitud HTTP produce un único valor, la respuesta: así podemos escribir cadenas de solicitudes con [async] / [await], que son más legibles que una cascada de [subscribe]. Una respuesta de error rechaza la promesa: un simple [try / catch] la captura;
  • líneas 91–102: al iniciar, [GET /api/auth/me]: ¿ya hemos iniciado sesión? Después de recargar la página (F5), la aplicación [Angular] lo ha olvidado todo; el servidor, en cambio, lee la cookie. 200: el usuario; 401: nadie; en ese caso, se muestran el formulario de inicio de sesión y su CAPTCHA (línea 99);
  • línea 96: cualquier otro error significa que el servidor no responde; se informa al desarrollador (líneas 79–82);
  • líneas 105–126: el inicio de sesión:
    • línea 109: [http.post(url, body)]: el objeto [body] se envía como JSON, con el encabezado [Content-Type: application/json];
    • línea 116: 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 121: si la solicitud falla, [error] contiene el cuerpo JSON de la respuesta, que explica el motivo. Mostramos el mensaje (línea 123) y solicitamos una nueva imagen (línea 124): cada una se usa una sola vez;
  • líneas 129–131: una solicitud protegida. No se requiere ninguna acción para autenticarse: el navegador incluye automáticamente la cookie porque la solicitud se dirige al mismo origen que la página;
  • líneas 134–139: cierre de sesión: el servidor elimina la cookie. El cuerpo [{}] se incluye para que la solicitud sea un POST JSON.

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 tienen la sesión iniciada.

El formulario de inicio de sesión:

<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 23 - logging in to the server</h1>
  @if (!ready()) {
    <p class="text-muted">Checking the session...</p>
  } @else if (user(); as u) {
    <!-- sesión iniciada -->
    <div class="card p-3">
      <p>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role <span class="badge text-bg-primary">{{ u.role }}</span></p>
      <h2 class="h6">GET /api/doctors</h2>
      <ul>
        @for (m of doctors(); track m.id) {
          <li>{{ 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>
  } @else {
    <!-- sesión no iniciada: el formulario -->
    <form class="card p-3" (ngSubmit)="logIn()">
      <div class="mb-2">
        <label class="form-label" for="login">Login</label>
        <input id="login" name="login" class="form-control" autocomplete="username" [(ngModel)]="login">
      </div>
      <div class="mb-2">
        <label class="form-label" for="password">Password</label>
        <input id="password" name="password" type="password" class="form-control" autocomplete="current-password"
               [(ngModel)]="password">
      </div>
      <div class="mb-3">
        <label class="form-label" for="captcha">Copy the characters of the image</label>
        <div class="d-flex align-items-center gap-3 mb-2">
          <div [innerHTML]="svg()"></div>
          <a href="#" class="small" (click)="$event.preventDefault(); loadCaptcha()">Another image</a>
        </div>
        <input id="captcha" name="captcha" class="form-control" autocomplete="off" [(ngModel)]="captchaAnswer">
      </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>
  }
  @if (error()) {
    <div class="alert alert-danger mt-3">{{ error() }}</div>
  }
</div>
  • Línea 3: hasta que la verificación inicial termine, no sabemos qué mostrar;
  • líneas 5–17: sesión iniciada: el usuario y la lista de médicos;
  • líneas 20–40: sesión no iniciada: el formulario, con [ngModel] (ejemplo 05);
  • línea 34: [$event.preventDefault()] impide que el enlace siga su dirección (#).

[npm start 23-login]. Con una contraseña incorrecta (el servidor está en modo de prueba: cualquier CAPTCHA acepta la respuesta [test]):

Image

Con la contraseña correcta, seguida de una actualización de la página (F5): la sesión permanece iniciada.

Image

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

En el Ejemplo 23, cada solicitud repetía los mismos pasos: el prefijo /api, [firstValueFrom], la lectura del cuerpo del error y la selección de un mensaje. Este ejemplo los agrupa en unos pocos archivos, ubicados en la carpeta [common] del espacio de trabajo, porque el Ejemplo 25 también los utiliza:

1
2
3
4
5
6
examples-angular/common/
├── types.ts                the JSON objects of the API
├── api-error.ts            a class for all the API errors
├── errors.interceptor.ts   an HTTP interceptor
├── api.service.ts          one-line requests
└── login-bar.ts            the login, in a bar

El archivo [tsconfig.app.json] del ejemplo agrega esta carpeta a los archivos que se van a compilar:

1
2
3
4
{
  "extends": "../tsconfig.json",
  "include": ["src/**/*.ts", "../common/**/*.ts"]
}

8.3.1. Los tipos

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

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

8.3.2. 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": {...} }
// HttpClient las reporta con una HttpErrorResponse, cuya propiedad error
// contiene este cuerpo JSON... u otra cosa: null (sin respuesta), texto
// (una página de error del proxy cuando el servidor JSON está detenido).
// Convertimos todo esto en UNA 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).
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

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';
  }
}

// cualquier error -> un ApiError
export function toApiError(e: unknown): ApiError {
  if (e instanceof ApiError) {
    return e;
  }
  if (!(e instanceof HttpErrorResponse)) {
    return new ApiError(0, 'ERRORS.SERVER_ERROR');
  }
  // el cuerpo JSON del error, si existe y tiene la forma correcta
  const body = (typeof e.error === 'object' && e.error !== null ? e.error : {}) as {
    key?: string;
    params?: Record<string, string>;
    fields?: Record<string, string>;
  };
  // sin key: no fue nuestro servidor el que respondió (proxy, red)
  const key = body.key ?? (e.status === 0 || e.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
  return new ApiError(e.status, key, body.params, body.fields);
}
  • Líneas 16–26: 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íneas 29–45: la conversión de cualquier error a [ApiError]:
    • línea 37: el cuerpo de la respuesta se usa solo si es un objeto. Cuando el servidor JSON está caído, el proxy responde con texto;
    • línea 43: sin una clave, no fue nuestro servidor el que respondió.

8.3.3. Un interceptor

Un interceptor es una función por la que pasan las solicitudes de [HttpClient] y sus respuestas. Puede modificar la solicitud antes de enviarla (por ejemplo, agregar un encabezado) o la respuesta a su regreso.

// =========================================================================
// common/errors.interceptor.ts - un INTERCEPTOR HTTP
// -------------------------------------------------------------------------
// Un interceptor es una función por la que pasan TODAS las peticiones
// de HttpClient (y sus respuestas). Recibe la petición (req) y el resto
// de la cadena (next):
//   - next(req) envía la petición y devuelve el observable de la respuesta;
//   - la petición puede modificarse antes (req.clone({...})), o la respuesta
//     después (operadores de RxJS sobre el observable).
// Este convierte cualquier error en un ApiError (catchError): el resto de
// la aplicación nunca vuelve a tratar con HttpErrorResponse.
// Se declara en la configuración de la aplicación:
//     provideHttpClient(withInterceptors([errorsInterceptor]))
// =========================================================================

import { HttpInterceptorFn } from '@angular/common/http';
import { catchError, throwError } from 'rxjs';
import { toApiError } from './api-error';

export const errorsInterceptor: HttpInterceptorFn = (req, next) =>
  next(req).pipe(catchError((e: unknown) => throwError(() => toApiError(e))));
  • Línea 20: un interceptor recibe la solicitud ([req]) y el resto de la cadena ([next]). [next(req)] envía la solicitud y devuelve el observable de la respuesta;
  • Línea 21: el operador [catchError] reemplaza cualquier error del flujo por un [ApiError]. El resto de la aplicación nunca vuelve a tener que ocuparse de [HttpErrorResponse].

8.3.4. El servicio ApiService

// =========================================================================
// common/api.service.ts - peticiones a la API, en una línea
// -------------------------------------------------------------------------
// En el ejemplo 23, cada petición repetía los mismos pasos: prefijo /api,
// firstValueFrom, lectura del cuerpo del error... Aquí los agrupamos:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId, clientId });
//
//   - si tiene éxito, la promesa devuelve el cuerpo JSON, TIPADO;
//   - si falla, es RECHAZADA con un ApiError (gracias al
//     interceptor errors.interceptor.ts).
// Usado por los ejemplos 24 y 25; el caso de estudio retoma su principio.
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class ApiService {
  private readonly http = inject(HttpClient);

  get<T>(url: string): Promise<T> {
    return firstValueFrom(this.http.get<T>(`/api${url}`));
  }

  // un POST siempre tiene un cuerpo JSON (el servidor rechaza un POST que no lo tenga)
  post<T>(url: string, body: unknown = {}): Promise<T> {
    return firstValueFrom(this.http.post<T>(`/api${url}`, body));
  }

  put<T>(url: string, body: unknown): Promise<T> {
    return firstValueFrom(this.http.put<T>(`/api${url}`, body));
  }

  delete<T>(url: string, body?: unknown): Promise<T> {
    return firstValueFrom(this.http.delete<T>(`/api${url}`, { body: body }));
  }
}
  • líneas 24–39: un método por cada verbo HTTP. Cada uno agrega el prefijo /api y devuelve una promesa del cuerpo de la respuesta, tipada así: [api.get<Person[]>('/doctors')] devuelve una [Promise<Person[]>]. En caso de fallo, la promesa se rechaza con un [ApiError];
  • Línea 29: [post] envía por defecto el cuerpo [{}]: el servidor rechaza un POST que no sea JSON.

8.3.5. La capa de acceso a la API

// =========================================================================
// 24-api-service/src/app/rdvmedecins.service.ts - la capa de acceso a la API
// -------------------------------------------------------------------------
// Un método tipado por ruta de la API. Los componentes no conocen ni
// las URL, ni HttpClient, ni el formato JSON: llaman a métodos.
// Es el equivalente del lado cliente de la capa DAO del lado servidor: si la API
// cambia (una URL, el nombre de un campo), solo se modifica este archivo.
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { HttpResourceRequest } from '@angular/common/http';
import { ApiService } from '../../../common/api.service';
import { Person } from '../../../common/types';

@Injectable({ providedIn: 'root' })
export class RdvMedecinsService {
  private readonly api = inject(ApiService);

  getDoctors(): Promise<Person[]> {
    return this.api.get<Person[]>('/doctors');
  }

  getClients(): Promise<Person[]> {
    return this.api.get<Person[]>('/clients');
  }

  // la DESCRIPCIÓN de la petición de la agenda, para httpResource (ver app.ts);
  // params construye "?doctorId=1&day=2030-01-15", codificando lo que haga falta
  scheduleRequest(doctorId: number, day: string): HttpResourceRequest {
    return { url: '/api/schedule', params: { doctorId, day } };
  }

  book(day: string, slotId: number, clientId?: number): Promise<{ id: number }> {
    return this.api.post<{ id: number }>('/appointments', { day, slotId, clientId });
  }

  cancelAppointment(appointmentId: number): Promise<Record<string, never>> {
    return this.api.delete<Record<string, never>>(`/appointments/${appointmentId}`);
  }
}

Un método por cada ruta de la API. Los componentes ya no conocen las direcciones, el [HttpClient] ni el formato JSON: llaman a métodos. Es el equivalente en el cliente de la capa de acceso a datos del servidor: si la API cambia, solo hay que modificar este archivo.

  • Líneas 29–31: la descripción de la solicitud del calendario, no la solicitud en sí: la utilizará [httpResource] (véase más adelante). [params] genera la cadena [?doctorId=1&day=2030-01-15] codificando los caracteres que deben codificarse.

8.3.6. La barra de inicio de sesión

El formulario del Ejemplo 23, reducido a una barra y reescrito con [ApiService]:

// =========================================================================
// common/login-bar.ts - login / logout, en una barra
// -------------------------------------------------------------------------
// El formulario del ejemplo 23, reducido a una barra y reescrito con
// ApiService. El componente emite userChange con el usuario que ha iniciado
// sesión (o null) cada vez que cambia - incluido al
// iniciar, tras haber consultado GET /api/auth/me.
//
// ViewEncapsulation.None: los estilos del componente se aplican a TODA la
// página. Necesario aquí: el <svg> del captcha, insertado por [innerHTML], no
// lleva los atributos que exige el estilo "encapsulado" de Angular.
// =========================================================================

import { Component, computed, inject, output, signal, ViewEncapsulation } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DomSanitizer } from '@angular/platform-browser';
import { ApiService } from './api.service';
import { ApiError } from './api-error';
import { Captcha, User } from './types';

@Component({
  selector: 'app-login-bar',
  imports: [FormsModule],
  encapsulation: ViewEncapsulation.None,
  styles: `
    .login-bar-captcha svg {
      display: block;
      height: 32px;
      width: auto;
    }
  `,
  template: `
    <div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
      @if (user(); as u) {
        <span>Logged in: <strong>{{ u.name }}</strong> <span class="badge text-bg-primary ms-1">{{ u.role }}</span></span>
        <button class="btn btn-sm btn-outline-secondary ms-auto" (click)="logOut()">Log out</button>
      } @else {
        <form class="d-flex flex-wrap align-items-center gap-2 w-100" (ngSubmit)="logIn()">
          <input name="login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username"
                 [(ngModel)]="login">
          <input name="password" type="password" class="form-control form-control-sm w-auto" placeholder="password"
                 autocomplete="current-password" [(ngModel)]="password">
          <div class="login-bar-captcha" [innerHTML]="svg()"></div>
          <input name="captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8"
                 [(ngModel)]="captchaAnswer">
          <button class="btn btn-sm btn-primary">Log in</button>
          @if (error()) {
            <span class="text-danger small">{{ error() }}</span>
          }
        </form>
      }
    </div>
  `,
})
export class LoginBar {
  readonly userChange = output<User | null>();

  private readonly api = inject(ApiService);
  private readonly sanitizer = inject(DomSanitizer);
  protected readonly user = signal<User | null>(null);
  private readonly captcha = signal<Captcha | null>(null);
  protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
  protected readonly login = signal('admin');
  protected readonly password = signal('');
  protected readonly captchaAnswer = signal('');
  protected readonly error = signal<string | null>(null);

  constructor() {
    this.start();
  }

  private async start(): Promise<void> {
    try {
      this.change(await this.api.get<User>('/auth/me'));
    } catch {
      this.change(null); // 401: nadie ha iniciado sesión
      await this.newCaptcha().catch(() => this.error.set('Is the JSON server running (port 8080)?'));
    }
  }

  private async newCaptcha(): Promise<void> {
    this.captcha.set(await this.api.get<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  private change(u: User | null): void {
    this.user.set(u);
    this.userChange.emit(u);
  }

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

  protected async logOut(): Promise<void> {
    await this.api.post('/auth/logout');
    this.change(null);
    await this.newCaptcha();
  }
}
  • línea 56: el componente emite [userChange] con el usuario que inició sesión (o [null]) cada vez que cambia, incluso al inicio;
  • línea 74: con [ApiService], una solicitud cabe en una sola línea; en caso de fallo (401), pasa a [catch];
  • línea 103: [instanceof] distingue un error de la API de otra anomalía;
  • línea 24: [ViewEncapsulation.None]: los estilos del componente se aplican a toda la página. Por defecto, [Angular] limita los estilos de un componente a su plantilla agregando atributos específicos a sus elementos. El [<svg>] insertado mediante [[innerHTML]] no tiene estos atributos: sin esta opción, la regla de las líneas 26–30 no se le aplicaría.

8.3.7. La configuración

// =========================================================================
// 24-api-service/src/app/app.config.ts
// -------------------------------------------------------------------------
// provideHttpClient(withInterceptors([...])): HttpClient se proporciona por defecto
// a toda aplicación; solo se declara para CONFIGURARLO, aquí
// agregando el interceptor que convierte los errores en ApiError.
// =========================================================================

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { errorsInterceptor } from '../../../common/errors.interceptor';

export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withInterceptors([errorsInterceptor]))],
};
  • línea 14: [HttpClient] se proporciona por defecto; se declara solo para configurarlo, en este caso agregando el interceptor.

8.3.8. La página

// =========================================================================
// 24-api-service/src/app/app.ts - 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: el SERVIDOR es quien tiene la autoridad.
//
// httpResource: una petición GET descrita por una función que lee
// signals (aquí doctorId y day). Angular la envía al iniciar, y luego
// LA ENVÍA DE NUEVO cada vez que uno de estos signals cambia. El resultado es un
// objeto de signals: value() (la respuesta), isLoading(), error()... y
// reload() para enviarla de nuevo a demanda.
// =========================================================================

import { Component, computed, effect, inject, signal } from '@angular/core';
import { httpResource } from '@angular/common/http';
import { FormsModule } from '@angular/forms';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Schedule, ScheduleSlot, Person, User } from '../../../common/types';
import { RdvMedecinsService } from './rdvmedecins.service';

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')}`;
}

@Component({
  selector: 'app-root',
  imports: [FormsModule, LoginBar],
  templateUrl: './app.html',
})
export class App {
  private readonly rdv = inject(RdvMedecinsService);

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

  protected readonly isManager = computed(() => this.user() !== null && this.user()?.role !== 'USER');

  // undefined: ninguna petición (ningún médico elegido, o nadie ha iniciado sesión)
  protected readonly schedule = httpResource<Schedule>(() => {
    const id = this.doctorId();
    return id === null || this.user() === null ? undefined : this.rdv.scheduleRequest(id, this.day());
  });

  // el error de la última petición de la agenda, como un ApiError
  protected readonly scheduleError = computed(() => {
    const e = this.schedule.error();
    return e instanceof ApiError ? `${e.statusCode} ${e.key}` : null;
  });

  constructor() {
    // una nueva elección de médico o de día borra el mensaje anterior
    effect(() => {
      this.doctorId();
      this.day();
      this.message.set(null);
    });
  }

  protected 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, por falta de un diccionario aquí)
  private report(e: unknown): void {
    this.message.set({ type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) });
  }

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

  protected async book(c: ScheduleSlot): Promise<void> {
    try {
      await this.rdv.book(this.day(), c.id, this.isManager() ? (this.clientId() ?? undefined) : undefined);
      this.message.set({ type: 'success', text: `Slot ${this.timeRange(c)} booked.` });
    } catch (e) {
      this.report(e);
    }
    this.schedule.reload();
  }

  protected async cancel(c: ScheduleSlot): Promise<void> {
    try {
      await this.rdv.cancelAppointment(c.appointmentId as number);
      this.message.set({ type: 'success', text: `Appointment of ${this.timeRange(c)} cancelled.` });
    } catch (e) {
      this.report(e);
    }
    this.schedule.reload();
  }
}
  • línea 45: ADMIN o DOCTOR;
  • líneas 48–51: [httpResource] describe una solicitud GET mediante una función que lee señales (aquí, [doctorId], [day] y [user]). [Angular] envía inicialmente la solicitud y luego la reenvía cada vez que una de estas señales cambia. La función devuelve [undefined] cuando no hay ninguna solicitud que enviar. El resultado es un conjunto de señales: [value()] (la respuesta), [isLoading()], [error()], [hasValue()]... y un método, [reload()], para reenviar la solicitud a demanda. Si una solicitud sigue en curso cuando cambian las señales, se abandona, como con [switchMap] (Ejemplo 19);
  • líneas 54–57: el error de la última solicitud del calendario. Las solicitudes de [httpResource] también pasan por el interceptor: el error es un [ApiError];
  • líneas 61–65: una función que borra el mensaje anterior cuando cambia el médico o el día;
  • líneas 79–93: cada vez que un usuario inicia o cierra sesión, el sistema (re)carga lo que ese rol está autorizado a ver. Un paciente recibiría un error 403 para la lista de clientes: ni siquiera la solicitamos;
  • líneas 95–103: una reserva, seguida, SEA CUAL SEA EL RESULTADO, de una recarga del calendario (línea 102). El registro del servidor es definitivo: si otra persona tomó el horario mientras tanto, el calendario actualizado lo mostrará;
  • línea 97: un administrador hace una reserva para el paciente seleccionado; un paciente hace una reserva para sí mismo.
<div class="container py-4">
  <h1 class="h3 mb-3">Example 24 - an API access layer</h1>
  <app-login-bar (userChange)="onUserChange($event)" />

  @if (user()) {
    <div class="row g-2 mb-3">
      <div class="col-sm-5">
        <select class="form-select" [(ngModel)]="doctorId">
          <option [ngValue]="null" disabled>-- choose a doctor --</option>
          @for (m of doctors(); track m.id) {
            <option [ngValue]="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
          }
        </select>
      </div>
      <div class="col-sm-3"><input type="date" class="form-control" [(ngModel)]="day"></div>
      @if (isManager()) {
        <div class="col-sm-4">
          <select class="form-select" [(ngModel)]="clientId">
            <option [ngValue]="null">-- patient to book for --</option>
            @for (c of clients(); track c.id) {
              <option [ngValue]="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
            }
          </select>
        </div>
      }
    </div>

    @if (message(); as m) {
      <div class="alert" [class]="'alert-' + m.type">{{ m.text }}</div>
    }
    @if (scheduleError()) {
      <div class="alert alert-danger">{{ scheduleError() }}</div>
    }
    @if (schedule.isLoading()) {
      <p class="small text-muted">loading the schedule...</p>
    }

    <!-- hasValue(): hay una respuesta disponible (value() no es undefined) -->
    @if (schedule.hasValue()) {
      @let a = schedule.value();
      <!-- info: la clave enviada por el servidor cuando un paciente ya tiene una cita próxima -->
      @if (a.info) {
        <div class="alert alert-info">{{ a.info }}</div>
      }
      <table class="table table-sm align-middle">
        <caption class="caption-top">Schedule of {{ a.day }} - {{ a.doctor.title }} {{ a.doctor.firstName }} {{ a.doctor.lastName }}</caption>
        <tbody>
          @for (c of a.slots; track c.id) {
            <tr>
              <td>{{ timeRange(c) }}</td>
              <td>
                @if (c.free) {
                  <span class="badge text-bg-success">Free</span>
                } @else if (c.patient; as p) {
                  <span class="badge" [class]="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ p.title }} {{ p.firstName }} {{ p.lastName }}</span>
                } @else {
                  <span class="badge text-bg-secondary">Booked</span>
                }
              </td>
              <td class="text-end">
                <!-- los botones siguen los derechos calculados por el servidor -->
                @if (c.bookable) {
                  <button class="btn btn-sm btn-outline-success" (click)="book(c)">Book</button>
                }
                @if (c.appointmentId !== null) {
                  <button class="btn btn-sm btn-outline-danger" (click)="cancel(c)">Cancel</button>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    }
  }
</div>
  • línea 3: la barra de inicio de sesión;
  • línea 34: [isLoading()]: hay una solicitud en curso;
  • línea 39: [hasValue()]: hay una respuesta disponible;
  • línea 40: [@let] evita que [schedule.value()] se repita;
  • línea 57: un horario ocupado para el cual el servidor no envió el paciente (visto por un paciente);
  • líneas 62–67: los botones siguen los permisos calculados por el servidor.

[npm start 24-api-service]. El administrador reserva el horario de las 8:40 para Alice DURAND:

Image

El mismo calendario, visto por la paciente Martin: el horario está reservado, sin que aparezca el nombre de ningún paciente.

Image

8.4. Ejemplo 25: errores devueltos por el servidor

Este ejemplo muestra la gestión de clientes por parte del administrador. El formulario no realiza ninguna validación en el navegador: todo se envía al servidor, que responde con un error en caso de rechazo:

1
2
3
400 { "key": "ERRORS.INVALID_FORM", "fields": { "lastName": "ERRORS.LASTNAME_REQUIRED" } }
409 { "key": "ERRORS.PATIENT_ALREADY_EXISTS", "fields": { "firstName": "...", "lastName": "..." } }
409 { "key": "ERRORS.CONCURRENT_UPDATE" }

Luego hay que mostrar el mensaje general y colocar el error de cada campo debajo de ese campo, en el idioma del usuario.

Los diccionarios contienen 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."
  }
}
{
  "FORM": {
    "TITLE_ADD": "Add a patient",
    "TITLE_EDIT": "Edit a patient",
    "TITLE": "Title",
    "FIRSTNAME": "First name",
    "LASTNAME": "Last name",
    "LOGIN": "Login",
    "PASSWORD": "Password",
    "SAVE": "Save",
    "CANCEL": "Cancel",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "DELETE_CONFIRM": "Delete patient {{name}}, their account and their appointments?",
    "ADDED": "Patient {{name}} has been added (login: {{login}}).",
    "UPDATED": "Patient {{name}} has been updated.",
    "DELETED": "Patient {{name}} has been deleted.",
    "ADMIN_ONLY": "Log in with the admin account: only the ADMIN role manages patients."
  },
  "ERRORS": {
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "First name is required.",
    "FIRSTNAME_TOO_LONG": "First name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "Last name is required.",
    "LASTNAME_TOO_LONG": "Last name must not exceed 20 characters.",
    "INVALID_LOGIN": "30 characters max: unaccented lowercase letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "Password must not exceed 72 characters.",
    "LOGIN_TAKEN": "This login is already used by another account.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "PATIENT_NOT_FOUND": "This patient does not exist (anymore).",
    "CONCURRENT_UPDATE": "This record was changed meanwhile by another user. Reload it before trying again.",
    "FORBIDDEN": "Your role does not allow this action.",
    "AUTH_REQUIRED": "Please log in first.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "SERVER_UNREACHABLE": "The server does not respond.",
    "SERVER_ERROR": "An unexpected error occurred."
  }
}
// =========================================================================
// 25-server-errors/src/app/i18n/i18n.ts - ngx-translate, como en el ejemplo 21
// =========================================================================

import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';

class DictionariesLoader implements TranslateLoader {
  getTranslation(language: string): Observable<TranslationObject> {
    return of(language === 'en' ? en : fr);
  }
}

export function provideI18n(): Provider[] {
  return provideTranslateService({ loader: provideTranslateLoader(DictionariesLoader), fallbackLang: 'en', lang: 'en' });
}

La configuración de la aplicación combina los elementos presentados en los ejemplos anteriores:

// =========================================================================
// 25-server-errors/src/app/app.config.ts
// -------------------------------------------------------------------------
//   - HttpClient y el interceptor de errores (ver ejemplo 24);
//   - ngx-translate (ver ejemplo 21);
//   - las clases de Bootstrap de los campos (ver ejemplo 07). Aquí no hay
//     "touched": un campo recibe un borde rojo apenas lleva un error,
//     es decir, apenas el SERVIDOR ha reportado uno.
// =========================================================================

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideSignalFormsConfig } from '@angular/forms/signals';
import { errorsInterceptor } from '../../../common/errors.interceptor';
import { provideI18n } from './i18n/i18n';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([errorsInterceptor])),
    provideI18n(),
    provideSignalFormsConfig({ classes: { 'is-invalid': (field) => field.state().invalid() } }),
  ],
};
  • línea 19: el cliente HTTP y su interceptor (ejemplo 24);
  • línea 20: [ngx-translate] (ejemplo 21);
  • línea 21: las clases de campo de [Bootstrap] (Ejemplo 07). Aquí, un campo se resalta en rojo en cuanto contiene un error, es decir, en cuanto el servidor ha informado de uno.

La página:

// =========================================================================
// 25-server-errors/src/app/app.ts - mostrar los errores del SERVIDOR
// -------------------------------------------------------------------------
// La gestión de los clientes (cuenta admin). Este formulario
// NO hace DELIBERADAMENTE ninguna validación en el navegador: su schema está vacío.
// Todo se envía al servidor, que responde, en caso de rechazo, con un error
// JSON (convertido en un ApiError por el interceptor):
//
//   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)
//
// submit(form, action): la action envía el modelo al servidor. Si
// devuelve ERRORS (un arreglo), los formularios con signals los adjuntan
// a los campos designados (fieldTree): aparecen en f.lastName().errors(),
// como los errores de un validador. Su mensaje es aquí la CLAVE enviada por
// el servidor, que la plantilla traduce (ngx-translate). Pruebe: un apellido
// vacío, un título "Dr", un homónimo (Alice DURAND), un login ya usado
// (martin), el mismo registro modificado en dos pestañas...
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { FormField, form, submit, ValidationError } from '@angular/forms/signals';
import { TranslatePipe, TranslateService } from '@ngx-translate/core';
import { ApiService } from '../../../common/api.service';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Person, User } from '../../../common/types';
// el diálogo de confirmación del ejemplo 16, reutilizado tal cual
import { ConfirmationService } from '../../../16-confirmation/src/app/confirmation/confirmation.service';
import { ConfirmDialog } from '../../../16-confirmation/src/app/confirmation/confirm-dialog';

interface ClientInput {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  version: number;
}

const EMPTY: ClientInput = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 };

@Component({
  selector: 'app-root',
  imports: [FormField, TranslatePipe, LoginBar, ConfirmDialog],
  templateUrl: './app.html',
})
export class App {
  private readonly api = inject(ApiService);
  private readonly confirmation = inject(ConfirmationService);
  protected readonly translate = inject(TranslateService);

  protected readonly user = signal<User | null>(null);
  protected readonly clients = signal<Person[]>([]);
  protected readonly isAdmin = computed(() => this.user()?.role === 'ADMIN');

  // el formulario: editedId === null -> creación, de lo contrario actualización
  protected readonly editedId = signal<number | null>(null);
  protected readonly model = signal<ClientInput>({ ...EMPTY });
  protected readonly f = form(this.model); // sin validador: el servidor valida
  // el mensaje general del último error, y el de un éxito
  protected readonly pageError = signal<ApiError | null>(null);
  protected readonly success = signal<{ key: string; params: Record<string, string> } | null>(null);

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

  private async reload(): Promise<void> {
    this.clients.set(await this.api.get<Person[]>('/clients'));
  }

  protected newForm(): void {
    this.editedId.set(null);
    this.model.set({ ...EMPTY });
    this.f().reset(); // el estado de los campos (y sus errores) parte de cero
    this.clearMessages();
  }

  protected edit(c: Person): void {
    this.editedId.set(c.id);
    // la VERSIÓN leída con el registro vuelve con la actualización: si alguien
    // ha modificado el registro mientras tanto, el servidor responderá 409 CONCURRENT_UPDATE
    this.model.set({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
    this.f().reset();
    this.clearMessages();
  }

  private clearMessages(): void {
    this.pageError.set(null);
    this.success.set(null);
  }

  // el error de CADA campo, devuelto por el servidor -> un error del formulario
  private fieldErrors(e: ApiError): ValidationError.WithOptionalFieldTree[] {
    const fields = Object.keys(this.model()) as (keyof ClientInput)[];
    return Object.entries(e.fields)
      .filter(([field]) => fields.includes(field as keyof ClientInput))
      .map(([field, key]) => ({ kind: 'server', message: key, fieldTree: this.f[field as keyof ClientInput] }));
  }

  protected async save(event: SubmitEvent): Promise<void> {
    event.preventDefault();
    this.clearMessages();
    const id = this.editedId();
    await submit(this.f, async () => {
      try {
        const body = this.model();
        const client =
          id === null
            ? await this.api.post<Person>('/clients', body)
            : await this.api.put<Person>(`/clients/${id}`, body);
        this.newForm(); // formulario limpiado, mensajes limpiados...
        // ... excepto este
        this.success.set({
          key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
          params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
        });
        await this.reload();
        return null;
      } catch (e) {
        if (!(e instanceof ApiError)) {
          throw e;
        }
        this.pageError.set(e); // el mensaje general
        return this.fieldErrors(e); // el error de cada campo
      }
    });
  }

  protected async remove(c: Person): Promise<void> {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await this.confirmation.confirm(this.translate.instant('FORM.DELETE_CONFIRM', { name })))) {
      return;
    }
    this.clearMessages();
    try {
      await this.api.delete(`/clients/${c.id}`);
      this.success.set({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      this.pageError.set(e instanceof ApiError ? e : null);
    }
    await this.reload();
  }
}
  • líneas 30–31: la ventana de confirmación del Ejemplo 16, reutilizada tal cual: un componente bien diseñado es reutilizable;
  • línea 61: un formulario con señales (ejemplo 06), sin esquema: sin validador;
  • líneas 63–64: el mensaje general del último error y el mensaje de éxito;
  • líneas 85–92: para editar un registro, se copian sus valores en el formulario, incluido el número de versión: el registro se actualizará con el cambio (bloqueo optimista). [reset()] restablece el estado de los campos y sus errores;
  • líneas 107–134: el guardado del registro. [submit(form, action)] ejecuta la acción, que envía el formulario al servidor: POST para una creación (línea 116), PUT para una modificación (línea 117). Durante su ejecución, [f().submitting()] es verdadero;
  • línea 125: [null]: sin error;
  • líneas 130–131: en caso de rechazo, se conserva el mensaje general y se devuelven los errores de campo. El sistema de validación de formularios los asocia entonces a los campos designados: aparecen en [f.lastName().errors()], exactamente como los errores de los validadores; desaparecen en cuanto el usuario modifica el campo;
  • líneas 100–105: la conversión. Cada error identifica su campo ([fieldTree], línea 104); su mensaje es la clave enviada por el servidor. La línea 103 ignora un campo desconocido del formulario;
  • línea 138: [translate.instant(key, params)]: la traducción de una clave en el código;
  • línea 146: la eliminación de un cliente también puede ser rechazada.
<div class="container py-4">
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h1 class="h3 mb-0">Example 25 - the errors returned by the server</h1>
    <select #language class="form-select form-select-sm w-auto" (change)="translate.use(language.value)">
      <option value="fr">FR</option>
      <option value="en" selected>EN</option>
    </select>
  </div>
  <app-login-bar (userChange)="onUserChange($event)" />
  @if (user() && !isAdmin()) {
    <p class="alert alert-warning">{{ 'FORM.ADMIN_ONLY' | translate }}</p>
  }

  @if (isAdmin()) {
    <div class="row g-4">
      <div class="col-lg-6">
        <table class="table table-sm align-middle">
          <tbody>
            @for (c of clients(); track c.id) {
              <tr>
                <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)">{{ 'FORM.EDIT' | translate }}</button>
                  <button class="btn btn-sm btn-outline-danger" (click)="remove(c)">{{ 'FORM.DELETE' | translate }}</button>
                </td>
              </tr>
            }
          </tbody>
        </table>
      </div>

      <div class="col-lg-6">
        <form class="card p-3" novalidate (submit)="save($event)">
          <h2 class="h5">{{ (editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') | translate }}</h2>
          <div class="mb-2">
            <label class="form-label" for="title">{{ 'FORM.TITLE' | translate }}</label>
            <!-- una opción "Dr" que el servidor rechazará: para ver ERRORS.INVALID_TITLE -->
            <select id="title" class="form-select" [formField]="f.title">
              <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
            </select>
            <!-- el mensaje de un error del servidor es una CLAVE: la traducimos -->
            <div class="invalid-feedback">{{ f.title().errors()[0]?.message ?? '' | translate }}</div>
          </div>
          <div class="row g-2 mb-2">
            <div class="col-sm-6">
              <label class="form-label" for="firstName">{{ 'FORM.FIRSTNAME' | translate }}</label>
              <input id="firstName" class="form-control" [formField]="f.firstName">
              <div class="invalid-feedback">{{ f.firstName().errors()[0]?.message ?? '' | translate }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="lastName">{{ 'FORM.LASTNAME' | translate }}</label>
              <input id="lastName" class="form-control" [formField]="f.lastName">
              <div class="invalid-feedback">{{ f.lastName().errors()[0]?.message ?? '' | translate }}</div>
            </div>
          </div>
          <div class="row g-2 mb-3">
            <div class="col-sm-6">
              <label class="form-label" for="login">{{ 'FORM.LOGIN' | translate }}</label>
              <input id="login" class="form-control" [formField]="f.login">
              <div class="invalid-feedback">{{ f.login().errors()[0]?.message ?? '' | translate }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="password">{{ 'FORM.PASSWORD' | translate }}</label>
              <input id="password" type="password" class="form-control" autocomplete="new-password" [formField]="f.password">
              <div class="invalid-feedback">{{ f.password().errors()[0]?.message ?? '' | translate }}</div>
            </div>
          </div>
          <div class="d-flex gap-2">
            <!-- submitting(): true mientras se ejecuta la action de submit() -->
            <button class="btn btn-primary" [disabled]="f().submitting()">{{ 'FORM.SAVE' | translate }}</button>
            <button type="button" class="btn btn-secondary" (click)="newForm()">{{ 'FORM.CANCEL' | translate }}</button>
          </div>
          @if (success(); as s) {
            <div class="alert alert-success mt-3 mb-0">{{ s.key | translate: s.params }}</div>
          }
          <!-- el mensaje general y el estado HTTP, para entender -->
          @if (pageError(); as e) {
            <div class="alert alert-danger mt-3 mb-0">
              {{ e.key | translate: e.params }} <span class="small text-muted">({{ e.statusCode }} {{ e.key }})</span>
            </div>
          }
        </form>
      </div>
    </div>
  }
</div>
<app-confirm-dialog />
  • línea 4: selección del idioma;
  • línea 40: un título «Dr.» que el servidor rechazará; véase [ERRORS.INVALID_TITLE];
  • línea 43 y siguientes: bajo cada campo, el primer error; su mensaje es una clave, que el pipe [translate] traduce. [?? '']: sin error, sin texto;
  • línea 71: el botón está deshabilitado durante el envío;
  • línea 80: el mensaje general, en el idioma actual, con sus parámetros, seguido del estado HTTP y de la clave, como aclaración;
  • Línea 88: la ventana de confirmación.

Cambiar el idioma también vuelve a traducir los mensajes de error que ya se mostraron: solo conservamos las claves.

[npm start 25-server-errors]; con la sesión iniciada como admin, enviamos el título «Dr,», un nombre demasiado largo, un apellido vacío y un nombre de usuario no válido:

Image

Partimos de un formulario en blanco: el título «Dr,», el nombre «Jean» y un apellido vacío. El servidor rechaza el título y el apellido; luego corregimos el título e ingresamos un apellido: los errores de estos dos campos desaparecen de inmediato, sin necesidad de reenviar. El mensaje general permanece visible hasta el siguiente envío:

Image

Un homónimo (Alice DURAND ya existe): el servidor devuelve una respuesta 409 y señala los campos de nombre y apellido. El nombre de usuario «martin», que ya está en uso, no se señala: el servidor se detiene en la primera regla de validación incumplida. Luego cambiamos a francés: los mensajes ya mostrados se vuelven a traducir (el título de la página y la barra de inicio de sesión, escritos en inglés, no):

Image

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