Skip to content

8. Comunicação com o servidor

Os exemplos deste capítulo consultam o servidor JSON [RdvMedecins]: ele deve estar em execução ([npm run start:dev] na pasta [rdvmedecins-nestjs-json]) na porta 8080, ao mesmo tempo que o servidor de desenvolvimento do [Angular] na porta 4200.

8.1. Exemplo 22: uma primeira requisição HTTP

8.1.1. O proxy do servidor de desenvolvimento

A página de exemplo vem de http://localhost:4200 (o servidor de desenvolvimento do [Angular], iniciado por [ng serve]); a API está em http://localhost:8080. Para um navegador, essas são duas origens diferentes (a porta faz parte da origem). Ora, por motivos de segurança, um navegador não permite que uma página leia respostas de outra origem, a menos que o servidor o permita explicitamente (o mecanismo conhecido como CORS). E uma requisição a outra origem não envia cookies (e, portanto, não envia o token), a menos que o código o solicite ([withCredentials: true]) E que o servidor o aceite, novamente por meio do CORS.

Em vez de abrir o servidor a outras origens, encaminhamos as requisições à API pelo servidor de desenvolvimento do [Angular]. Este é o proxy declarado no arquivo do workspace [proxy.conf.json]:

1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}
  • Linha 2: as requisições cujo caminho começa com /api...
  • linha 3: ... são encaminhadas ao servidor JSON.

Para cada exemplo, o arquivo é especificado nas opções do comando [ng serve] no arquivo [angular.json]:

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

O navegador envia [GET http://localhost:4200/api/captcha]; o servidor de desenvolvimento encaminha a requisição para [http://localhost:8080/api/captcha] e depois devolve a resposta ao navegador. Para o navegador, a página e a API têm a mesma origem:

Image

Em produção, não haverá mais servidor de desenvolvimento: o próprio servidor JSON servirá os arquivos compilados do cliente (veja o capítulo “Implantação”). A página e a API continuarão compartilhando a mesma origem.

8.1.2. A requisição

O [Angular] fornece seu próprio cliente HTTP, o serviço [HttpClient]. Ele está automaticamente disponível em qualquer aplicação: basta injetá-lo.

// =========================================================================
// 22-httpclient/src/app/app.ts - uma primeira requisição HTTP ao servidor
// -------------------------------------------------------------------------
// O servidor JSON do RdvMedecins deve estar em execução (porta 8080). Pedimos a ele
// um captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - HttpClient: o cliente HTTP do Angular (fornecido por padrão para toda a
//     aplicação). http.get<T>(url) retorna um OBSERVABLE (veja o exemplo
//     19): a requisição só é enviada quando nos INSCREVEMOS nele (subscribe);
//     a resposta JSON chega já convertida em um objeto, do tipo T anunciado;
//   - o endereço é RELATIVO (/api/captcha): a requisição vai para o
//     servidor da página, o do Angular (porta 4200), que a repassa ao
//     servidor JSON (porta 8080) graças ao seu proxy (veja proxy.conf.json);
//   - três estados a exibir: carregando, sucesso, erro.
// =========================================================================

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

// o que GET /api/captcha retorna
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] insere uma string como HTML. Por segurança, o Angular
  // LIMPA esse HTML ("sanitization"): remove os scripts... e as
  // tags <svg>. bypassSecurityTrustHtml diz ao Angular: "este HTML é
  // seguro, não o limpe". Deve ser usado SOMENTE para conteúdo seguro: este SVG
  // é construído pelo NOSSO servidor. Com dados do usuário, seria
  // abrir a porta para a injeção de scripts ({{ }}, por outro lado, escapa tudo).
  protected readonly svg = computed<SafeHtml | null>(() => {
    const c = this.captcha();
    return c ? this.sanitizer.bypassSecurityTrustHtml(c.svg) : null;
  });

  constructor() {
    this.load(); // no início, carregamos um captcha
  }

  protected load(): void {
    this.loading.set(true);
    this.error.set(null);
    this.http.get<Captcha>('/api/captcha').subscribe({
      // next: a resposta (código 2xx), já convertida do JSON
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: uma resposta 4xx / 5xx, ou nenhuma resposta (status 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(`the server answered ${e.status} ${e.statusText}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
  • linha 22: o formato da resposta de [GET /api/captcha];
  • linha 39: injeta o cliente HTTP;
  • linhas 42–45: os três estados de uma requisição: em andamento, bem-sucedida (o CAPTCHA) e com erro;
  • linha 65: [http.get<Captcha>(url)] prepara uma requisição GET. Ele retorna um observable (exemplo 19): a requisição só é enviada quando há inscrição nele ([subscribe]). O endereço é relativo: a requisição é enviada ao servidor da página, que a encaminha ao servidor JSON;
  • linhas 67–71: [next] recebe a resposta, que já foi convertida de JSON. [<Captcha>] informa ao [TypeScript]o formato do objeto: o compilador não tem como verificar o que o servidor enviará;
  • Linhas 73–77: [error] recebe um [HttpErrorResponse] para qualquer resposta 4xx ou 5xx, bem como quando nenhuma resposta é recebida (servidor fora do ar, rede desconectada: [status] vale então 0). Se o servidor JSON estiver fora do ar, o proxy responde com um erro 5xx;
  • linha 59: na inicialização, um CAPTCHA é carregado;
  • linhas 53–56: a imagem SVG do CAPTCHA é uma cadeia de caracteres, que deve ser inserida como HTML ([[innerHTML]] no template). Por motivos de segurança, o [Angular] higieniza qualquer HTML inserido dessa forma: ele remove os scripts... e as tags [<svg>]. [bypassSecurityTrustHtml] indica que esse HTML é seguro. Nós o usamos SOMENTE para conteúdo seguro: este SVG é gerado pelo NOSSO servidor. Com dados digitados pelo usuário, isso permitiria injetar scripts na página; as chaves duplas [{{ }}], por outro lado, escapam tudo.
<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>
  • linhas 4–14: uma exibição de status;
  • linha 12: a imagem do CAPTCHA.

[npm start 22-httpclient]; clique em [Another image]:

Image

Nas ferramentas do desenvolvedor do navegador (F12), a aba Network mostra a requisição [captcha], enviada a [localhost:4200], e sua resposta JSON.

// =========================================================================
// 23-login/src/app/app.ts - fazendo login no servidor RdvMedecins
// -------------------------------------------------------------------------
//   1. na partida: GET /api/auth/me - já estamos logados?
//      (depois de um F5, o cliente esqueceu tudo; o servidor lê o cookie);
//   2. login: POST /api/auth/login, corpo JSON { login, password,
//      captchaId, captcha }. Em caso de sucesso, o servidor define o
//      cookie httpOnly do token JWT: nosso código NUNCA o vê (tente
//      document.cookie no console: ele não está lá);
//   3. requisição protegida: GET /api/doctors. O navegador anexa o cookie
//      a ela por conta própria (mesma origem);
//   4. logout: POST /api/auth/logout - o servidor apaga o cookie.
//
// firstValueFrom(observable): uma PROMISE do primeiro valor do fluxo.
// Sequências de requisições podem então ser escritas com async / await,
// mais legível do que uma cascata de subscribe. Uma resposta de erro rejeita
// a promise com um HttpErrorResponse: um simples try / catch.
//
// Um cookie pertence a uma máquina (localhost) e a um caminho (/api): ele
// é portanto comum a TODOS os exemplos. Uma vez logado aqui, os exemplos
// 24 e 25 também ficam logados.
// =========================================================================

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;
}
// a forma de TODOS os erros da API
interface ApiError {
  statusCode: number;
  key: string;
  params?: Record<string, string>;
}

// as poucas mensagens de que este exemplo precisa (o exemplo 25 usará o 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); // a verificação inicial terminou?

  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. quem está logado? 200 -> o usuário; 401 -> ninguém
  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; // não é um 401: o servidor não responde
      }
      await this.loadCaptcha();
    }
    this.ready.set(true);
  }

  // 2. o login; post(url, body): o corpo é enviado 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: o corpo JSON da resposta de erro
      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 imagem é usada apenas uma vez
    }
  }

  // 3. uma requisição protegida
  private async loadDoctors(): Promise<void> {
    this.doctors.set(await firstValueFrom(this.http.get<Doctor[]>('/api/doctors')));
  }

  // 4. o logout
  protected async logOut(): Promise<void> {
    await firstValueFrom(this.http.post('/api/auth/logout', {}));
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
  • linhas 30–50: os formatos dos dados trocados com o servidor, incluindo os de todos os erros da API (linhas 46–50);
  • linhas 53–57: as poucas mensagens necessárias a este exemplo, em inglês; o Exemplo 25 usará [ngx-translate];
  • linha 28: [firstValueFrom(observable)] retorna uma promise para o primeiro valor do fluxo. Uma requisição HTTP produz apenas um valor — a resposta: podemos então escrever encadeamentos de requisições com [async] / [await], que são mais legíveis do que uma cascata de [subscribe]. Uma resposta de erro rejeita a promise: um simples [try / catch] a captura;
  • linhas 91–102: na inicialização, [GET /api/auth/me]: já estamos conectados? Depois de recarregar a página (F5), a aplicação [Angular] esqueceu tudo; o servidor, no entanto, lê o cookie. 200: o usuário; 401: ninguém — nesse caso, o formulário de login e seu CAPTCHA são exibidos (linha 99);
  • linha 96: qualquer outro erro significa que o servidor não está respondendo; ele é reportado ao desenvolvedor (linhas 79–82);
  • linhas 105–126: o login:
    • linha 109: [http.post(url, body)]: o objeto [body] é enviado como JSON, com o cabeçalho [Content-Type: application/json];
    • linha 116: em caso de sucesso, o servidor definiu o cookie do token. Nosso código NUNCA o vê: digite [document.cookie] no console do navegador; ele não está lá ([HttpOnly]);
    • linha 121: se a requisição falhar, [error] contém o JSON do corpo da resposta, que explica o motivo. Exibimos a mensagem (linha 123) e solicitamos uma nova imagem (linha 124): cada uma é usada apenas uma vez;
  • linhas 129–131: uma requisição protegida. Nenhuma ação é necessária para autenticar: o navegador inclui automaticamente o cookie, pois a requisição vai para a mesma origem da página;
  • linhas 134–139: logout — o servidor exclui o cookie. O corpo [{}] é incluído para que a requisição seja um POST JSON.

Um cookie pertence a uma máquina (localhost) e a um caminho (/api); ele é, portanto, compartilhado por TODOS os exemplos. Depois de fazer login aqui, os exemplos 24 e 25 também ficam com o login feito.

O formulário de login:

<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) {
    <!-- logado -->
    <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 {
    <!-- não logado: o formulário -->
    <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>
  • Linha 3: enquanto a verificação inicial não termina, não sabemos o que exibir;
  • linhas 5–17: usuário logado: o usuário e a lista de médicos;
  • linhas 20–40: usuário não logado: o formulário, com [ngModel] (exemplo 05);
  • linha 34: [$event.preventDefault()] impede que o link siga seu endereço (#).

[npm start 23-login]. Com uma senha incorreta (o servidor está em modo de teste: qualquer CAPTCHA aceita a resposta [test]):

Image

Com a senha correta, seguida de uma atualização da página (F5): você continua logado.

Image

8.3. Exemplo 24: uma camada de acesso à API

No Exemplo 23, cada requisição repetia as mesmas etapas: o prefixo /api, [firstValueFrom], a leitura do corpo do erro e a escolha de uma mensagem. Este exemplo as agrupa em alguns arquivos, localizados na pasta [common] do workspace, pois o Exemplo 25 também os 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

O arquivo [tsconfig.app.json] do exemplo adiciona esta pasta aos arquivos a serem compilados:

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

8.3.1. Os tipos

Os tipos dos objetos JSON da API, descritos no capítulo anterior:

// =========================================================================
// common/types.ts - os objetos JSON trocados com a API do RdvMedecins
// (veja o capítulo sobre a caixa-preta, que descreve cada rota)
// =========================================================================

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

// um médico ou um cliente (GET /api/doctors, GET /api/clients...)
export interface Person {
  id: number;
  version: number;
  title: string;
  firstName: string;
  lastName: string;
  login?: string; // somente para o ADMIN
}

export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// uma linha 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. Erros

// =========================================================================
// common/api-error.ts - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Todas as respostas de erro do servidor RdvMedecins têm a mesma forma:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// O HttpClient as reporta com um HttpErrorResponse, cuja propriedade error
// contém esse corpo JSON... ou outra coisa: null (nenhuma resposta), texto
// (uma página de erro do proxy quando o servidor JSON está parado). Convertemos
// tudo isso em UMA classe, ApiError, que carrega a chave de tradução
// enviada pelo servidor (e, se houver, seus parâmetros e
// o erro de cada campo).
// =========================================================================

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

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0: o servidor não respondeu
    public readonly key: string, // p. ex.: 'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {},
  ) {
    super(key);
    this.name = 'ApiError';
  }
}

// qualquer erro -> um ApiError
export function toApiError(e: unknown): ApiError {
  if (e instanceof ApiError) {
    return e;
  }
  if (!(e instanceof HttpErrorResponse)) {
    return new ApiError(0, 'ERRORS.SERVER_ERROR');
  }
  // o corpo JSON do erro, se existir e tiver a forma correta
  const body = (typeof e.error === 'object' && e.error !== null ? e.error : {}) as {
    key?: string;
    params?: Record<string, string>;
    fields?: Record<string, string>;
  };
  // sem key: não foi o nosso servidor que respondeu (proxy, rede)
  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);
}
  • Linhas 16–26: uma classe de erro contendo a resposta do servidor: o código HTTP, a chave da mensagem, seus parâmetros e o erro de cada campo. O código 0 significa "sem resposta";
  • linhas 29–45: a conversão de qualquer erro em [ApiError]:
    • linha 37: o corpo da resposta só é usado se for um objeto. Quando o servidor JSON está fora do ar, o proxy responde com texto;
    • linha 43: sem uma chave, não foi o nosso servidor que respondeu.

8.3.3. Um interceptor

Um interceptor é uma função pela qual passam as requisições de [HttpClient] e suas respostas. Ele pode modificar a requisição antes de ser enviada (adicionar um cabeçalho, por exemplo) ou a resposta ao retornar.

// =========================================================================
// common/errors.interceptor.ts - um INTERCEPTOR HTTP
// -------------------------------------------------------------------------
// Um interceptor é uma função pela qual passam TODAS as requisições
// do HttpClient (e suas respostas). Ele recebe a requisição (req) e o restante
// da cadeia (next):
//   - next(req) envia a requisição e retorna o observable da resposta;
//   - a requisição pode ser modificada antes (req.clone({...})), ou a resposta
//     depois (operadores RxJS sobre o observable).
// Este converte qualquer erro em um ApiError (catchError): o restante da
// aplicação nunca mais lida com HttpErrorResponse.
// Ele é declarado na configuração da aplicação:
//     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))));
  • Linha 20: um interceptor recebe a requisição ([req]) e o restante da cadeia ([next]). [next(req)] envia a requisição e retorna o observable da resposta;
  • Linha 21: o operador [catchError] substitui qualquer erro do fluxo por um [ApiError]. O restante da aplicação nunca mais precisa lidar com [HttpErrorResponse].

8.3.4. O serviço ApiService

// =========================================================================
// common/api.service.ts - requisições à API, em uma linha
// -------------------------------------------------------------------------
// No exemplo 23, cada requisição repetia os mesmos passos: o prefixo /api,
// firstValueFrom, a leitura do corpo do erro... Agrupamos tudo aqui:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId, clientId });
//
//   - em caso de sucesso, a promise retorna o corpo JSON, TIPADO;
//   - em caso de falha, ela é REJEITADA com um ApiError (graças ao
//     interceptor errors.interceptor.ts).
// Usado pelos exemplos 24 e 25; o estudo de caso retoma seu princípio.
// =========================================================================

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

  // um POST sempre tem um corpo JSON (o servidor rejeita um POST que não tenha)
  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 }));
  }
}
  • linhas 24–39: um método para cada verbo HTTP. Cada um adiciona o prefixo /api e retorna uma promise para o corpo da resposta, tipada como: [api.get<Person[]>('/doctors')] retorna uma [Promise<Person[]>]. Em caso de falha, a promise é rejeitada com um [ApiError];
  • Linha 29: [post] envia o corpo [{}] por padrão: o servidor rejeita um POST que não esteja em JSON.

8.3.5. A camada de acesso à API

// =========================================================================
// 24-api-service/src/app/rdvmedecins.service.ts - a camada de acesso à API
// -------------------------------------------------------------------------
// Um método tipado por rota da API. Os componentes não conhecem nem
// as URLs, nem o HttpClient, nem o formato JSON: eles chamam métodos.
// É o equivalente, no lado do cliente, da camada DAO do lado do servidor: se a API
// mudar (uma URL, o nome de um campo), apenas este arquivo é modificado.
// =========================================================================

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

  // a DESCRIÇÃO da requisição da agenda, para o httpResource (veja app.ts);
  // params monta "?doctorId=1&day=2030-01-15", codificando o que for necessário
  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}`);
  }
}

Um método por rota da API. Os componentes não conhecem mais os endereços, o [HttpClient] nem o formato JSON: eles chamam métodos. É o equivalente, no lado do cliente, da camada de acesso a dados do lado do servidor: se a API mudar, apenas este arquivo precisa ser modificado.

  • Linhas 29–31: a descrição da requisição da agenda, não a requisição em si: ela será usada por [httpResource] (veja abaixo). [params] gera a string [?doctorId=1&day=2030-01-15] codificando os caracteres que precisam ser codificados.

8.3.6. A barra de login

O formulário do Exemplo 23, reduzido a uma barra e reescrito com [ApiService]:

// =========================================================================
// common/login-bar.ts - login / logout, em uma barra
// -------------------------------------------------------------------------
// O formulário do exemplo 23, reduzido a uma barra e reescrito com
// ApiService. O componente emite userChange com o usuário logado
// (ou null) a cada mudança - inclusive na
// partida, depois de consultar GET /api/auth/me.
//
// ViewEncapsulation.None: os estilos do componente se aplicam à página
// INTEIRA. Necessário aqui: o <svg> do captcha, inserido por [innerHTML], não
// carrega os atributos que o estilo "encapsulado" do Angular exige.
// =========================================================================

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: ninguém está logado
      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();
  }
}
  • linha 56: o componente emite [userChange] com o usuário logado (ou [null]) a cada mudança, inclusive na inicialização;
  • linha 74: com [ApiService], uma requisição cabe em uma única linha; em caso de falha (401), o fluxo passa para [catch];
  • linha 103: [instanceof] distingue um erro da API de outra anomalia;
  • linha 24: [ViewEncapsulation.None]: os estilos do componente se aplicam à página inteira. Por padrão, o [Angular] limita os estilos de um componente ao seu template, adicionando atributos específicos aos seus elementos. O [<svg>] inserido por [[innerHTML]] não tem esses atributos: sem esta opção, a regra das linhas 26–30 não se aplicaria a ele.

8.3.7. A configuração

// =========================================================================
// 24-api-service/src/app/app.config.ts
// -------------------------------------------------------------------------
// provideHttpClient(withInterceptors([...])): o HttpClient é fornecido por padrão
// a qualquer aplicação; ele só é declarado para CONFIGURÁ-LO, aqui
// adicionando o interceptor que converte os erros em 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]))],
};
  • linha 14: [HttpClient] é fornecido por padrão; ele é declarado apenas para configurá-lo, neste caso adicionando o interceptor.

8.3.8. A página

// =========================================================================
// 24-api-service/src/app/app.ts - uma agenda, com a camada de acesso à API
// -------------------------------------------------------------------------
// Faça login (barra superior), escolha um médico e um dia: a agenda
// é exibida. ADMIN e DOCTOR podem marcar consulta para um paciente e cancelar;
// um paciente (martin...) marca para si mesmo. Cada ação termina com
// um recarregamento da agenda: é o SERVIDOR que tem a palavra final.
//
// httpResource: uma requisição GET descrita por uma função que lê
// signals (aqui doctorId e day). O Angular a envia na partida e depois
// A ENVIA DE NOVO sempre que um desses signals muda. O resultado é um
// objeto de signals: value() (a resposta), isLoading(), error()... e
// reload() para enviá-la de novo sob 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: nenhuma requisição (nenhum médico escolhido, ou ninguém logado)
  protected readonly schedule = httpResource<Schedule>(() => {
    const id = this.doctorId();
    return id === null || this.user() === null ? undefined : this.rdv.scheduleRequest(id, this.day());
  });

  // o erro da última requisição da agenda, como um ApiError
  protected readonly scheduleError = computed(() => {
    const e = this.schedule.error();
    return e instanceof ApiError ? `${e.statusCode} ${e.key}` : null;
  });

  constructor() {
    // uma nova escolha de médico ou de dia apaga a mensagem 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)}`;
  }

  // um erro da API vira uma mensagem (sua chave, na falta de um dicionário aqui)
  private report(e: unknown): void {
    this.message.set({ type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) });
  }

  // login / logout: (re)carregamos o que este papel pode 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());
      // a lista de pacientes: somente para ADMIN e DOCTOR (um USER receberia 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();
  }
}
  • linha 45: ADMIN ou DOCTOR;
  • linhas 48–51: [httpResource] descreve uma requisição GET por meio de uma função que lê signals (aqui, [doctorId], [day] e [user]). [Angular] envia a requisição inicialmente e depois a reenvia sempre que um desses signals muda. A função retorna [undefined] quando não há requisição a enviar. O resultado é um conjunto de signals: [value()] (a resposta), [isLoading()], [error()], [hasValue()]... e um método, [reload()], para reenviar a requisição sob demanda. Se uma requisição ainda estiver em andamento quando os signals mudarem, ela é abandonada, como com [switchMap] (Exemplo 19);
  • linhas 54–57: o erro da última requisição da agenda. As requisições de [httpResource] também passam pelo interceptor: o erro é um [ApiError];
  • linhas 61–65: uma função que limpa a mensagem anterior quando o médico ou o dia muda;
  • linhas 79–93: cada vez que um usuário faz login ou logout, o sistema (re)carrega o que aquele papel está autorizado a ver. Um paciente receberia um erro 403 na lista de clientes: nem sequer a solicitamos;
  • linhas 95–103: uma reserva, seguida, SEJA QUAL FOR O RESULTADO, de um recarregamento da agenda (linha 102). O registro do servidor é definitivo: se o horário foi ocupado por outra pessoa nesse meio-tempo, a agenda atualizada mostrará isso;
  • linha 97: um administrador faz uma reserva para o paciente selecionado; um paciente faz a reserva para si mesmo.
<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(): uma resposta está disponível (value() não é undefined) -->
    @if (schedule.hasValue()) {
      @let a = schedule.value();
      <!-- info: a chave enviada pelo servidor quando um paciente já tem uma consulta futura -->
      @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">
                <!-- os botões acompanham os direitos calculados pelo 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>
  • linha 3: a barra de login;
  • linha 34: [isLoading()]: uma requisição está em andamento;
  • linha 39: [hasValue()]: uma resposta está disponível;
  • linha 40: [@let] evita que [schedule.value()] seja repetido;
  • linha 57: um horário ocupado para o qual o servidor não enviou o paciente (como visto por um paciente);
  • linhas 62–67: os botões seguem as permissões calculadas pelo servidor.

[npm start 24-api-service]. O administrador reserva o horário das 8:40 para Alice DURAND:

Image

A mesma agenda, vista pelo paciente Martin: o horário está reservado, sem o nome do paciente.

Image

8.4. Exemplo 25: erros retornados pelo servidor

Este exemplo demonstra o gerenciamento de clientes pelo administrador. O formulário não faz nenhuma validação no navegador: tudo é enviado ao servidor, que responde — em caso de rejeição — com um erro:

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

É preciso então exibir a mensagem geral e colocar o erro de cada campo abaixo dele, no idioma do usuário.

Os dicionários contêm os códigos de erro do 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 no exemplo 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' });
}

A configuração da aplicação combina os elementos apresentados nos exemplos anteriores:

// =========================================================================
// 25-server-errors/src/app/app.config.ts
// -------------------------------------------------------------------------
//   - HttpClient e o interceptor de erros (veja o exemplo 24);
//   - ngx-translate (veja o exemplo 21);
//   - as classes Bootstrap dos campos (veja o exemplo 07). Aqui, sem
//     "touched": um campo ganha uma borda vermelha assim que apresenta um erro,
//     ou seja, assim que o SERVIDOR reportou um.
// =========================================================================

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() } }),
  ],
};
  • linha 19: o cliente HTTP e seu interceptor (exemplo 24);
  • linha 20: [ngx-translate] (exemplo 21);
  • linha 21: as classes de campo do [Bootstrap] (Exemplo 07). Aqui, um campo é destacado em vermelho assim que contém um erro, ou seja, assim que o servidor reportou um.

A página:

// =========================================================================
// 25-server-errors/src/app/app.ts - exibindo os erros do SERVIDOR
// -------------------------------------------------------------------------
// O gerenciamento dos clientes (conta admin). Este formulário
// DELIBERADAMENTE não faz nenhuma validação no navegador: seu schema está vazio.
// Tudo é enviado ao servidor, que responde, em caso de recusa, com um erro
// JSON (convertido em um ApiError pelo 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' }         (bloqueio otimista)
//
// submit(form, action): a action envia o modelo ao servidor. Se ela
// retornar ERRORS (um array), os signal forms os associam
// aos campos designados (fieldTree): eles aparecem em f.lastName().errors(),
// como os erros de um validador. Sua mensagem é aqui a CHAVE enviada pelo
// servidor, que o template traduz (ngx-translate). Experimente: um sobrenome
// vazio, um título "Dr", um homônimo (Alice DURAND), um login já em uso
// (martin), o mesmo registro modificado em duas abas...
// =========================================================================

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';
// o diálogo de confirmação do exemplo 16, reutilizado como está
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');

  // o formulário: editedId === null -> criação, caso contrário atualização
  protected readonly editedId = signal<number | null>(null);
  protected readonly model = signal<ClientInput>({ ...EMPTY });
  protected readonly f = form(this.model); // nenhum validador: o servidor valida
  // a mensagem geral do último erro e a de um sucesso
  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(); // o estado dos campos (e seus erros) parte do zero
    this.clearMessages();
  }

  protected edit(c: Person): void {
    this.editedId.set(c.id);
    // a VERSÃO lida com o registro volta com a atualização: se alguém
    // modificou o registro nesse meio tempo, o 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);
  }

  // o erro de CADA campo, retornado pelo servidor -> um erro do formulário
  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(); // formulário limpo, mensagens limpas...
        // ... exceto esta
        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); // a mensagem geral
        return this.fieldErrors(e); // o erro 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();
  }
}
  • linhas 30–31: a janela de confirmação do Exemplo 16, reutilizada sem alterações: um componente bem projetado é reutilizável;
  • linha 61: um formulário com signals (exemplo 06), sem schema: nenhum validador;
  • linhas 63–64: a mensagem geral do último erro e a mensagem de sucesso;
  • linhas 85–92: para editar um registro, copie seus valores para o formulário, inclusive o número de versão: o registro será atualizado com a alteração (bloqueio otimista). [reset()] redefine o estado dos campos e seus erros;
  • linhas 107–134: o salvamento do registro. [submit(form, action)] executa a ação, que envia o formulário ao servidor: POST para uma criação (linha 116), PUT para uma modificação (linha 117). Durante sua execução, [f().submitting()] é verdadeiro;
  • linha 125: [null]: nenhum erro;
  • linhas 130–131: em caso de rejeição, a mensagem geral é mantida e os erros de campo são retornados. O sistema de validação de formulários os associa então aos campos designados: eles aparecem em [f.lastName().errors()], exatamente como os erros de validadores; eles desaparecem assim que o usuário modifica o campo;
  • linhas 100–105: a conversão. Cada erro identifica seu campo ([fieldTree], linha 104); sua mensagem é a chave enviada pelo servidor. A linha 103 ignora um campo desconhecido no formulário;
  • linha 138: [translate.instant(key, params)]: a tradução de uma chave no código;
  • linha 146: a exclusão de um cliente também pode ser rejeitada.
<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>
            <!-- uma opção "Dr" que o servidor rejeitará: 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>
            <!-- a mensagem de um erro do servidor é uma CHAVE: nós a traduzimos -->
            <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 enquanto a action de submit() está em execução -->
            <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>
          }
          <!-- a mensagem geral e o status 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 />
  • linha 4: seleção do idioma;
  • linha 40: um título "Dr." que o servidor rejeitará; veja [ERRORS.INVALID_TITLE];
  • linha 43 e seguintes: sob cada campo, o primeiro erro; sua mensagem é uma chave, que o pipe [translate] traduz. [?? '']: sem erro, sem texto;
  • linha 71: o botão fica desabilitado durante o envio;
  • linha 80: a mensagem geral, no idioma atual, com seus parâmetros, seguida do status HTTP e da chave, para esclarecimento;
  • Linha 88: a janela de confirmação.

Trocar o idioma também retraduz as mensagens de erro já exibidas: guardamos apenas as chaves.

[npm start 25-server-errors]; logados como admin, enviamos o título "Dr", um nome muito longo, um sobrenome vazio e um nome de usuário inválido:

Image

Começamos com um formulário em branco: o título "Dr", o nome "Jean" e um sobrenome vazio. O servidor rejeita o título e o sobrenome; em seguida corrigimos o título e informamos um sobrenome: os erros desses dois campos desaparecem imediatamente, sem precisar reenviar. A mensagem geral continua exibida até o próximo envio:

Image

Um homônimo (Alice DURAND já existe): o servidor retorna uma resposta 409 e sinaliza os campos de nome e sobrenome. O nome de usuário "martin", que já está em uso, não é sinalizado: o servidor para na primeira regra de validação violada. Em seguida mudamos para o francês: as mensagens já exibidas são retraduzidas (o título da página e a barra de login, escritos em inglês, não são):

Image

Experimente também editar o mesmo registro em duas abas: o segundo salvamento recebe [ERRORS.CONCURRENT_UPDATE].