Skip to content

9. Comunicação com o servidor

O servidor JSON do [RdvMedecins] deve agora ser iniciado (porta 8080), como explicado no capítulo anterior, de preferência no modo de teste do CAPTCHA ([CAPTCHA_TEST=test]), que permite responder “test” a qualquer imagem.

Os exemplos 22 a 25 compartilham alguns arquivos, localizados na pasta [src/app/common/] do projeto: o endereço do servidor ([config.ts]), os tipos de resposta ([types.ts]), as classes de erro ([api-error.ts]), o serviço de requisições ([api.ts]) e uma barra de login ([login-bar.ts]). Eles são apresentados ao longo dos exemplos, à medida que se tornam relevantes.

9.1. Exemplo 22: Uma primeira requisição HTTP

9.1.1. Onde está o servidor?

Para um cliente web servido pelo próprio servidor, a pergunta não se coloca: as requisições são enviadas para a mesma origem da página, usando um endereço relativo ([/api/captcha]). Uma aplicação instalada em um celular não tem uma origem utilizável: sua página é servida pelo próprio [Capacitor] , a partir de https://localhost. É preciso fornecer o endereço completo do servidor, e esse endereço depende de onde a aplicação está sendo executada:

// =========================================================================
// src/app/common/config.ts - ONDE está o servidor JSON?
// -------------------------------------------------------------------------
// A pergunta não se coloca para uma aplicação web servida pelo
// próprio servidor: as requisições vão para a MESMA origem da página
// (um endereço relativo, /api/...). Mas uma aplicação MOBILE não tem origem
// utilizável (no Android, a página é servida pelo Capacitor
// a partir de https://localhost): é preciso informar-lhe o endereço completo do servidor.
//   - no desenvolvimento web (ng serve), o servidor de desenvolvimento
//     do Angular encaminha as requisições /api ao servidor JSON (arquivo
//     proxy.conf.json): um endereço relativo basta;
//   - o emulador Android enxerga o computador que o executa
//     no endereço 10.0.2.2 (localhost, para ele, é o próprio emulador);
//   - um celular real, conectado à mesma rede Wi-Fi do computador, deve
//     usar o endereço do computador nessa rede (192.168.1.20...):
//     ele é informado ao compilar a aplicação:
//         ng build --define "SERVER='http://192.168.1.20:8080'"
//     ou então alteramos a constante androidServer abaixo.
// =========================================================================

import { Capacitor } from '@capacitor/core';

// o endereço do servidor para a aplicação Android, quando nada mais é
// imposto: o do computador, visto do emulador
const androidServer = 'http://10.0.2.2:8080';

// o valor dado por --define "SERVER='...'" na compilação
// (ng build, ng serve). A opção substitui, no código compilado, a palavra
// SERVER pelo valor informado. Sem ela, SERVER não existe: typeof
// nos permite verificá-lo sem causar um erro
declare const SERVER: string | undefined;
const forcedServer = typeof SERVER === 'string' ? SERVER : '';

export const config = {
  // Capacitor.isNativePlatform(): true na aplicação Android (ou iOS),
  // false em um navegador; Capacitor.getPlatform(): 'android', 'ios' ou 'web'
  serverUrl:
    forcedServer !== ''
      ? forcedServer
      : !Capacitor.isNativePlatform()
        ? '' // a web: mesma origem, endereços relativos
        : Capacitor.getPlatform() === 'android'
          ? androidServer
          : 'http://localhost:8080',
};
  • linha 21: [Capacitor], o objeto de [@capacitor/core] que fornece informações sobre a plataforma em que a aplicação está sendo executada. Ele pode ser usado em qualquer lugar, inclusive em um navegador;
  • linha 25: o endereço padrão é o do [Android]. O emulador é uma máquina independente com sua própria rede: para o emulador, [localhost] refere-se ao próprio emulador. O endereço especial [10.0.2.2] refere-se ao computador que o executa;
  • linhas 31–32: um endereço imposto durante o build da aplicação pela opção [--define] do [Angular]: [ng build --define "SERVER='http://192.168.1.20:8080'"]. A compilação substitui o identificador [SERVER] no código pelo valor informado (uma string, daí os apóstrofos). Sem essa opção, [SERVER] não existe: [declare const] informa ao compilador [TypeScript] que [SERVER] é um identificador que ele não vê declarado, e [typeof SERVER] permite testar sua existência sem causar um erro. Este é o equivalente exato de [--dart-define] e de [String.fromEnvironment] no [Flutter];
  • linhas 34–45: caso contrário, um endereço específico da plataforma. [Capacitor.isNativePlatform()] é verdadeiro na aplicação [Android] (ou [iOS]), mas falso em um navegador; [Capacitor.getPlatform()] retorna 'android', 'ios' ou 'web':
  • no navegador (linha 41): uma URL relativa (''), portanto a mesma origem da aplicação;
  • no [Android] (linha 43): o endereço da linha 25;
  • em outros casos (linha 44, [iOS], que este curso não aborda): [localhost].

Um celular real, conectado à mesma rede Wi-Fi do computador servidor, deve usar o endereço do computador nessa rede (o comando [ipconfig] do [Windows] o fornece): você pode passá-lo por meio de [--define] durante a compilação ou modificar a constante da linha 25. O firewall do computador também deve permitir conexões de entrada na porta 8080.

9.1.2. Configurações do projeto Android

O cliente [Flutter] modificava duas linhas no arquivo [android/app/src/main/AndroidManifest.xml]: a permissão para usar a rede e a autorização para se comunicar em HTTP sem criptografia (“plaintext”). Com o [Capacitor], esse arquivo não é modificado:

  • a permissão [android.permission.INTERNET] já está declarada no projeto [Android] criado por [npx cap add android]: uma aplicação [Capacitor] é uma página web, portanto sempre requer acesso à rede;
  • A permissão para HTTP em texto simples é uma configuração do arquivo [capacitor.config.ts], localizado na raiz do projeto:
// =========================================================================
// capacitor.config.ts - a configuração do Capacitor
// -------------------------------------------------------------------------
// O Capacitor transforma a aplicação web (a pasta produzida por ng build)
// em uma aplicação Android: ele a encapsula em um projeto do Android Studio
// (pasta android/), onde é exibida por uma "WebView", o motor do
// navegador Chrome do celular. Comandos (veja o exemplo 01, "Execução"):
//     npx cap add android       (uma única vez: cria a pasta android/)
//     ng build                  (compila a aplicação web)
//     npx cap sync android      (copia-a para o projeto Android)
//     npx cap run android       (executa em um emulador ou em um celular)
// =========================================================================

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  // o identificador único da aplicação no celular (e na Play Store)
  appId: 'fr.stahe.examples',
  // o nome exibido sob o ícone
  appName: 'Ionic Examples',
  // a pasta da aplicação web compilada (ng build)
  webDir: 'dist/examples_ionic/browser',
  server: {
    // permite requisições HTTP não criptografadas (http://10.0.2.2:8080) para
    // o servidor JSON de desenvolvimento (exemplos 22 a 25)
    cleartext: true,
  },
  plugins: {
    // CapacitorHttp: as requisições HTTP da aplicação deixam de ser feitas
    // pela WebView e passam a ser feitas pelo código nativo do Android. Consequências (veja
    // os exemplos 22 e 23): sem verificação de CORS (o servidor JSON não precisa
    // liberar nada), e os cookies (o do token de autenticação) são
    // armazenados pelo Android e reenviados automaticamente
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;
  • Linhas 23–27: [server.cleartext: true]. A partir da versão 9 do [Android], uma aplicação só tem permissão para se comunicar usando HTTPS. Nosso servidor de desenvolvimento usa HTTP: nós o permitimos. O comando [npx cap sync android] transfere essa configuração para o projeto [Android] (o atributo [android:usesCleartextTraffic="true"], adicionado ao manifesto que o [Capacitor] mescla com o manifesto da aplicação). Em produção, o servidor estaria em HTTPS, e essa configuração desapareceria;
  • linhas 28–37: o plugin [CapacitorHttp]. As requisições HTTP da aplicação (as do cliente HTTP do [Angular], assim como as do [fetch]) deixam de ser enviadas pela WebView e passam a ser enviadas pelo código nativo do [Android]. Para um navegador, a aplicação (https://localhost) e o servidor (http://10.0.2.2:8080) pareceriam ter duas origens diferentes: o navegador exigiria que o servidor fornecesse uma autorização CORS, que o servidor não concede, e se recusaria a incluir o cookie do token. O código nativo não tem essas regras. O código [TypeScript] da aplicação, porém, não muda: é o [Capacitor] que redireciona as requisições.

9.1.3. E no navegador?

Durante o desenvolvimento, a aplicação é executada no navegador do computador: [ng serve] a serve na porta 8100, enquanto o servidor JSON está na porta 8080. Novamente, há duas origens, e o [CapacitorHttp] não funciona dentro de um navegador. A solução é um proxy, configurado em [angular.json] (opção ["proxyConfig": "proxy.conf.json"] do target [serve]):

1
2
3
4
5
6
7
8
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": false,
    "logLevel": "warn"
  }
}
  • Linha 2: Qualquer requisição cujo endereço comece com [/api]...
  • linha 3: ... é encaminhada pelo servidor de desenvolvimento do [Angular] ao servidor JSON, e sua resposta é enviada de volta ao navegador. Para o navegador, a aplicação e a API têm a mesma origem (http://localhost:8100): sem CORS, e o cookie é repassado. Este é exatamente o papel do proxy do [Vite] no curso de [React] e do arquivo [web_dev_config.yaml] no curso de [Flutter];
  • linha 4: [secure: false]: não exigir um certificado HTTPS válido do destino (ele está em HTTP de qualquer forma); linha 6: exibir apenas os avisos do proxy.

9.1.4. A requisição

Um CAPTCHA é solicitado ao servidor: [GET /api/captcha], que responde com [{ "id": "...", "svg": "<svg ...>" }].

// =========================================================================
// src/app/ex22-http/ex22.page.ts - uma primeira requisição HTTP ao servidor
// -------------------------------------------------------------------------
// O servidor JSON do RdvMedecins deve estar em execução (porta 8080). Pedimos-lhe
// um captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - HttpClient: o cliente HTTP do Angular (fornecido a toda a aplicação
//     por provideHttpClient(), em main.ts). http.get<T>(address) retorna
//     um Observable: a requisição é enviada quando nos INSCREVEMOS nele (subscribe), e
//     a resposta chega depois, com seu corpo JSON já decodificado;
//   - uma resposta de erro (4xx, 5xx) ou a ausência de resposta chegam
//     na função error da inscrição;
//   - o endereço do servidor depende de onde a aplicação executa
//     (navegador, emulador Android, celular): veja common/config.ts;
//   - três estados a exibir: carregando, com sucesso, com erro;
//   - a imagem do captcha é SVG: uma tag <img> pode exibi-la.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, DestroyRef, inject, signal } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonNote, IonProgressBar,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { Subscription } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';

@Component({
  selector: 'app-ex22',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonProgressBar, IonCard, IonCardContent,
    IonButton, IonNote,
  ],
  templateUrl: './ex22.page.html',
  styles: `
    .error { --background: #ffebee; --color: #333; margin: 12px 0; }
    .image { border: 1px solid #ddd; border-radius: 6px; padding: 4px; text-align: center; }
    .image img { height: 60px; }
    .id { font-family: monospace; font-size: 11px; margin: 8px 0; }
  `,
})
export class Ex22Page {
  private readonly http = inject(HttpClient);
  readonly server = config.serverUrl || '(same origin: /api, ng serve proxy)';
  readonly captchaImage = captchaImage;

  // o estado da tela: signals
  readonly captcha = signal<Captcha | null>(null);
  readonly loading = signal(true);
  readonly error = signal<string | null>(null);
  readonly requestCount = signal(0);

  // a inscrição na requisição em andamento (se houver)
  private request?: Subscription;

  constructor() {
    this.load(); // a primeira requisição, assim que a página é criada
    // a página destruída (botão Voltar): a requisição em andamento é abandonada
    inject(DestroyRef).onDestroy(() => this.request?.unsubscribe());
  }

  load(): void {
    // cancelar a inscrição em uma requisição ainda em andamento a CANCELA: sua resposta,
    // agora inútil, nunca será processada (nenhuma resposta "obsoleta")
    this.request?.unsubscribe();
    this.loading.set(true);
    this.error.set(null);
    // <Captcha>: o tipo do corpo JSON esperado (uma promessa feita ao
    // compilador: nada é verificado em tempo de execução)
    this.request = this.http.get<Captcha>(`${config.serverUrl}/api/captcha`).subscribe({
      // next: a resposta chegou (código 2xx), seu corpo JSON é decodificado
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: uma resposta de erro (4xx, 5xx), ou nenhuma resposta
      // (servidor parado, endereço errado: status é então 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(e.status === 0 ? 'no response (status 0)' : `the server responded ${e.status}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
<!-- ======================================================================
     ex22.page.html - um captcha solicitado ao servidor
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 22 - a first HTTP request</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-note>Server: {{ server }}</ion-note>

  <!-- uma barra de progresso "indeterminada" durante a requisição -->
  @if (loading()) {
    <ion-progress-bar type="indeterminate" class="ion-margin-top" />
  }

  @if (error(); as error) {
    <ion-card class="error">
      <ion-card-content>
        Unable to get a captcha: {{ error }}.<br />
        Is the RdvMedecins JSON server running (port 8080)?
      </ion-card-content>
    </ion-card>
  }

  @if (captcha(); as captcha) {
    @if (!loading()) {
      <!-- a imagem SVG, na forma de um endereço data: (veja common/types.ts) -->
      <div class="image ion-margin-top">
        <img [src]="captchaImage(captcha)" alt="captcha" />
      </div>
      <div class="id">id: {{ captcha.id }}</div>
    }
  }

  <!-- desabilitado durante uma requisição -->
  <ion-button class="ion-margin-top" shape="round" [disabled]="loading()" (click)="load()">Another image</ion-button>
  <p><ion-note>{{ requestCount() }} successful request(s)</ion-note></p>
</ion-content>
  • linha 19 (.ts): [HttpClient], o cliente HTTP do [Angular]. Ele é fornecido a toda a aplicação por [provideHttpClient()], em [main.ts], e a página o obtém por meio de [inject(HttpClient)] (linha 44);
  • linha 45 (.ts): o endereço do servidor, exibido no topo da tela; um endereço vazio significa “mesma origem”;
  • linhas 49–52 (.ts): o estado da tela, representado por signals: o CAPTCHA recebido (ou [null]), os três estados da requisição (em andamento, erro, bem-sucedida) e o número de requisições bem-sucedidas;
  • linha 55 (.ts): a assinatura ([Subscription]) da requisição atual;
  • linhas 57–61 (.ts): a primeira requisição é enviada assim que a página é carregada. [DestroyRef] sinaliza quando a página é fechada (botão Voltar): a assinatura da requisição atual é então cancelada;
  • linhas 63–86 (.ts): a requisição:
  • linha 71 (.ts): [this.http.get<Captcha>(address)] ainda não envia a requisição; ele retorna um [Observable] (exemplo 19) da resposta. A requisição é enviada quando uma assinatura é feita ([subscribe]). O tipo [<Captcha>] é o do corpo JSON esperado: uma promessa feita ao compilador, que não é verificada em tempo de execução;
  • Linhas 73–77 (.ts): [next] recebe a resposta se o código de status for 2xx. Seu corpo, JSON, já foi decodificado: é um objeto [JavaScript] (o pacote [http] do [Flutter] retornava texto, que precisava ser passado para [jsonDecode]);
  • linhas 80–84 (.ts): [error] recebe um [HttpErrorResponse], indicando uma resposta de erro (4xx, 5xx) ou a ausência de resposta (servidor fora do ar, endereço incorreto, queda de rede). Elas são distinguidas por [e.status], que vale 0 quando o servidor não respondeu. Isso difere do [http.get] e do [Flutter], que tratavam uma resposta 4xx ou 5xx como uma resposta comum, exigindo que o código fosse verificado;
  • Linha 66 (.ts): se a requisição anterior não terminou, ela é abandonada: cancelar a assinatura de uma requisição HTTP a cancela (o navegador a interrompe), e sua resposta nunca será processada. É aqui que o [Observable] mostra sua vantagem sobre a [Promise], que não pode ser cancelada: o exemplo do [Flutter] precisava numerar suas requisições para ignorar respostas obsoletas;
  • linhas 18–20 (html): uma barra de progresso ([<ion-progress-bar type="indeterminate">]) durante a requisição;
  • linhas 22–29 (html): o erro, exibido em um card;
  • linhas 31–39 (html): o CAPTCHA. [@if (captcha(); as captcha)] atribui um nome ao valor do signal quando ele não é [null];
  • linha 35 (html): a imagem do CAPTCHA é SVG, em forma de texto. Uma tag [<img>] pode exibi-la, desde que ela seja fornecida na forma de uma URL; esse é o papel da função [captchaImage] em [common/types.ts]:
// o texto SVG -> um endereço "data:" utilizável por <img [src]>: a imagem
// está NO endereço. Uma imagem SVG exibida por <img> não pode executar
// nenhum script: nenhum risco, mesmo que seu conteúdo fosse duvidoso
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}
  • Linha 32: um endereço [data:] contém o próprio arquivo: seu tipo ([image/svg+xml]), seguido de seu conteúdo, codificado por [encodeURIComponent] para que possa aparecer em um endereço. Por que não inserir o texto SVG diretamente na página usando [[innerHTML]]? [Angular] o rejeitaria: um SVG pode conter scripts, e o [Angular] “higieniza” qualquer HTML inserido dessa forma, removendo as tags que não reconhece como seguras, incluindo [<svg>]. Poderíamos forçá-lo ([DomSanitizer.bypassSecurityTrustHtml]), mas uma imagem é mais simples e livre de riscos: uma imagem exibida por [<img>] nunca executa nenhum script. No [Flutter], era o pacote [flutter_svg] que renderizava o SVG;
  • linha 42 (html): “Outra imagem”, desabilitado durante uma requisição.

No navegador, usando o proxy de [ng serve]; o servidor então não responde (nesta captura de tela, o script de captura faz a requisição falhar, como faria um servidor parado):

As ferramentas de desenvolvedor do [Chrome] (F12), na aba “Network”, mostram cada requisição HTTP da aplicação, com seus cabeçalhos e corpo: aqui, [GET http://localhost:8100/api/captcha], transmitida pelo proxy. No celular, a aplicação é inspecionada a partir do computador, no endereço [chrome://inspect] (veja o capítulo “Implantação”); as requisições que passam pelo [CapacitorHttp]—isto é, pelo código nativo—são menos visíveis ali.

O cliente HTTP do [Angular] oferece também, a partir da versão 19, [httpResource()]: o equivalente, para uma requisição GET, do [resource()] do exemplo 19. Você informa o endereço e ele devolve um objeto de signals ([isLoading()], [value()], [error()], [reload()]): todo o gerenciamento dos três estados deste exemplo caberia em uma única linha. Para uma primeira requisição, optamos por escrever esses estados nós mesmos; o estudo de caso usará [resource()].

O servidor armazena o token JWT em um cookie. O cliente [Flutter] precisou, nesse ponto, substituir seu cliente HTTP por um que lê o cabeçalho [Set-Cookie] de cada resposta, organiza os cookies (e os armazena em o dispositivo) e os devolve no cabeçalho [Cookie] de cada requisição: uma aplicação [Flutter] não tem um navegador que faça isso por ela.

Uma aplicação [Ionic], por outro lado, não tem nada a escrever:

  • no navegador do computador, é o navegador que armazena o cookie e o devolve, como faz com qualquer outro site. O proxy de [ng serve] atribui a mesma origem à aplicação e à API: o cookie [SameSite=Strict] é aceito e devolvido. O código da aplicação não pode ler nem escrever esse cookie ([HttpOnly]);
  • no [Android], o plugin [CapacitorHttp] (exemplo 22) encaminha as requisições pelo código nativo. O [Capacitor] configura, na inicialização da aplicação, o gerenciador de cookies do [Android] (o do WebView) como gerenciador das requisições nativas: os cookies recebidos são armazenados ali e devolvidos nas requisições seguintes ao mesmo servidor. Eles são mantidos no dispositivo (o nosso tem uma duração definida por [Max-Age=7200]; apenas os cookies “de sessão”, que não têm data de expiração, são apagados quando o aplicativo inicia): você continua conectado ao fechar e reabrir o aplicativo.

O token, portanto, nunca é manipulado pelo código do aplicativo, nem armazenado em texto simples no dispositivo (o cliente [Flutter] o armazenava em [shared_preferences]).

9.2.2. Um comando

// =========================================================================
// src/app/ex23-login/command.ts - uma AÇÃO, seu estado, seu resultado
// -------------------------------------------------------------------------
// Uma ação assíncrona (fazer login, salvar...) tem um estado que
// a tela deve mostrar: ela está EM EXECUÇÃO (botão desabilitado)? terminou
// com um ERRO (mensagem)? É o padrão "Command" dos
// guias de arquitetura (o do Flutter, por exemplo), reduzido ao essencial:
//
//     readonly loginCommand = new Command();
//     this.loginCommand.execute(() => this.logIn());   // starts the action
//     loginCommand.running(), loginCommand.error()      // its state
//
// Seu estado é feito de SIGNALS: o template que os lê é atualizado
// quando o command inicia e quando termina.
// =========================================================================

import { signal } from '@angular/core';

export class Command {
  private readonly _running = signal(false);
  private readonly _error = signal<unknown>(null);
  readonly running = this._running.asReadonly();
  readonly error = this._error.asReadonly();

  // executa a ação, se outra ainda não estiver em execução
  async execute(action: () => Promise<void>): Promise<void> {
    if (this._running()) return; // sem envio duplo (toque duplo no botão)
    this._running.set(true);
    this._error.set(null);
    try {
      await action();
    } catch (e) {
      this._error.set(e); // o erro é MANTIDO, para ser exibido
    } finally {
      // finally: executado em TODOS os casos, sucesso ou erro
      this._running.set(false);
    }
  }

  clearError(): void {
    this._error.set(null);
  }
}

Uma ação assíncrona (fazer login, salvar etc.) tem um estado que a tela deve exibir: está em andamento (botão desabilitado)? Terminou com um erro (mensagem)? É o modelo “Command” dos guias de arquitetura (o do [Flutter] o chama assim), reduzido ao essencial. O curso de [React] usava, para isso, as “actions” do [React] 19 ([useActionState]).

  • Linhas 19–23: uma classe simples (cada tela cria a sua com [new]), cujo estado é formado por dois signals privados, expostos como somente leitura. O template que lê [running()] ou [error()] é atualizado quando o comando começa e quando termina: é o papel que [ChangeNotifier] e [ListenableBuilder] desempenhavam no [Flutter];
  • linhas 26–38: executar uma ação: se outra ação estiver em andamento, não faz nada (linha 27: evita o envio duplo se o botão for pressionado duas vezes); caso contrário, o comando passa a “em andamento”; em caso de exceção, o erro é registrado para ser exibido (linha 33); em todos os casos ([finally], linhas 34–37), o comando deixa de estar em andamento. O erro é do tipo [unknown]: em [JavaScript], qualquer valor pode ser lançado, e o [TypeScript] não sabe, portanto, o que o [catch] captura.

9.2.3. A tela

// =========================================================================
// src/app/ex23-login/ex23.page.ts - login no servidor RdvMedecins
// -------------------------------------------------------------------------
//   1. na inicialização: GET /api/auth/me - já estamos logados?
//      (a aplicação pode ter sido parada; o servidor, por sua vez, lê o cookie
//      que lhe é apresentado);
//   2. login: POST /api/auth/login, corpo JSON { login, password,
//      captchaId, captcha }. Em caso de sucesso, o servidor envia o cookie
//      do token JWT (cabeçalho Set-Cookie);
//   3. requisição protegida: GET /api/doctors. O cookie a acompanha.
//   4. logout: POST /api/auth/logout - o servidor apaga o cookie.
// E o cookie? O código não tem NADA a fazer: em um navegador, é o
// navegador que o armazena e o reenvia; no Android, é o código nativo
// (plugin CapacitorHttp, veja capacitor.config.ts).
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, inject, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonInput, IonNote, IonText,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { firstValueFrom } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';
import { Command } from './command';

// as poucas mensagens de que este exemplo precisa (o exemplo 25 usará dicionários)
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.',
};

// o que POST /api/auth/login e GET /api/auth/me retornam, e uma linha de GET /api/doctors
interface User {
  login: string;
  name: string;
  role: string;
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
}

@Component({
  selector: 'app-ex23',
  imports: [
    FormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonCard, IonCardContent,
    IonInput, IonButton, IonText, IonNote,
  ],
  templateUrl: './ex23.page.html',
  styles: `
    .captcha { display: flex; align-items: center; margin-top: 12px; }
    .captcha img { height: 50px; }
    .error { --background: #ffebee; --color: #333; }
    h3 { font-size: 14px; font-weight: bold; margin: 12px 0 4px; }
  `,
})
export class Ex23Page {
  private readonly http = inject(HttpClient);
  readonly captchaImage = captchaImage;

  readonly user = signal<User | null>(null); // null: ninguém está logado
  readonly doctors = signal<Doctor[]>([]);
  readonly captcha = signal<Captcha | null>(null);
  readonly ready = signal(false); // a verificação inicial terminou?
  readonly serverError = signal<string | null>(null);
  readonly loginCommand = new Command();
  // os campos do formulário, vinculados por [(ngModel)]
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');

  constructor() {
    this.checkSession();
  }

  private url(path: string): string {
    return `${config.serverUrl}/api${path}`;
  }

  // uma requisição GET cujo corpo JSON queremos. Uma resposta que não seja
  // 2xx (ou a ausência de resposta) rejeita a Promise com um HttpErrorResponse
  private read<T>(path: string): Promise<T> {
    return firstValueFrom(this.http.get<T>(this.url(path)));
  }

  // um POST: o objeto do corpo é enviado como JSON (cabeçalho content-type: application/json)
  private post<T>(path: string, body: object): Promise<T> {
    return firstValueFrom(this.http.post<T>(this.url(path), body));
  }

  async loadCaptcha(): Promise<void> {
    this.captcha.set(await this.read<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  private async loadDoctors(): Promise<void> {
    this.doctors.set(await this.read<Doctor[]>('/doctors'));
  }

  // 1. quem está logado? 200 -> o usuário; 401 -> ninguém
  private async checkSession(): Promise<void> {
    try {
      this.user.set(await this.read<User>('/auth/me'));
      await this.loadDoctors();
    } catch (e) {
      // instanceof: um teste de TIPO; e.status: o código de status (0: sem resposta)
      if (e instanceof HttpErrorResponse && e.status === 401) {
        await this.loadCaptcha();
      } else if (e instanceof HttpErrorResponse && e.status !== 0) {
        this.serverError.set(`The server responded ${e.status}.`);
      } else {
        this.serverError.set(`Is the RdvMedecins JSON server running (${config.serverUrl || 'port 8080'})?`);
      }
    }
    this.ready.set(true);
  }

  // o botão "Entrar": o Command executa a ação e guarda seu erro
  submit(): void {
    this.loginCommand.execute(() => this.logIn());
  }

  // 2. o login
  private async logIn(): Promise<void> {
    try {
      const user = await this.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.user.set(user);
      await this.loadDoctors();
    } catch (e) {
      if (!(e instanceof HttpErrorResponse)) throw e;
      // e.error: o corpo JSON da resposta de erro, { statusCode, key, ... }
      const key: string = e.error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await this.loadCaptcha(); // cada imagem só é usada uma vez
      // o erro que o Command vai guardar
      throw new Error(`${e.status} - ${messages[key] ?? key}`);
    }
  }

  // a mensagem do erro guardado pelo command
  errorMessage(): string {
    const error = this.loginCommand.error();
    return error instanceof Error ? error.message : String(error);
  }

  // 4. o logout
  async logOut(): Promise<void> {
    await this.post('/auth/logout', {});
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
<!-- ======================================================================
     ex23.page.html - login, sessão, logout
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 23 - logging in to the server</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  @if (!ready()) {
    <ion-note>Checking the session...</ion-note>
  } @else if (user(); as u) {
    <!-- logado -->
    <ion-card>
      <ion-card-content>
        <div>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role {{ u.role }}</div>
        <!-- 3. uma requisição protegida: o cookie foi junto -->
        <h3>GET /api/doctors</h3>
        @for (m of doctors(); track m.id) {
          <div>• {{ m.title }} {{ m.firstName }} {{ m.lastName }}</div>
        }
        <p class="ion-margin-top"><ion-note>Stop then restart the application: you stay logged in.</ion-note></p>
        <ion-button fill="outline" shape="round" (click)="logOut()">Log out</ion-button>
      </ion-card-content>
    </ion-card>
  } @else if (serverError() === null) {
    <!-- não logado: o formulário -->
    <ion-card>
      <ion-card-content>
        <ion-input label="Login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="Password" labelPlacement="floating" type="password" [(ngModel)]="password" />
        <div class="captcha">
          @if (captcha(); as c) {
            <img [src]="captchaImage(c)" alt="captcha" />
          }
          <ion-button fill="clear" size="small" (click)="loadCaptcha()">Another image</ion-button>
        </div>
        <ion-input label="Copy the characters of the image" labelPlacement="floating" autocorrect="off"
          autocapitalize="off" [(ngModel)]="captchaAnswer" />
        <!-- o botão acompanha o estado do command -->
        <ion-button class="ion-margin-top" shape="round" [disabled]="loginCommand.running()"
          (click)="submit()">
          {{ loginCommand.running() ? 'Logging in...' : 'Log in' }}
        </ion-button>
        @if (loginCommand.error() !== null) {
          <p><ion-text color="danger">{{ errorMessage() }}</ion-text></p>
        }
        <p><ion-note>Accounts: admin, pelissier, martin... (password = login).</ion-note></p>
      </ion-card-content>
    </ion-card>
  }

  @if (serverError(); as message) {
    <ion-card class="error">
      <ion-card-content>{{ message }}</ion-card-content>
    </ion-card>
  }
</ion-content>

A tela passa pelas quatro etapas de uma sessão: na inicialização, quem está conectado?; o login; uma requisição protegida; e o logout.

  • linhas 29–34 (.ts): as poucas mensagens de que este exemplo precisa (o exemplo 25 usará dicionários);
  • linhas 36–47 (.ts): o formato das respostas utilizadas, descrito por duas interfaces (o exemplo 24 armazenará esses tipos em [common/types.ts]);
  • linhas 67–76 (.ts): o estado: o usuário conectado ([null]: ninguém), os médicos, o CAPTCHA, a conclusão da verificação inicial, um erro do servidor, o comando de login e os campos do formulário;
  • Linhas 86–95 (.ts): dois atalhos. [firstValueFrom(observable)] (do [RxJS]) assina o [Observable] da requisição e devolve uma [Promise] com o primeiro valor, a resposta: ela pode então ser aguardada com [await], em um código que se lê de cima para baixo. Se a requisição falhar, a [Promise] é rejeitada com o [HttpErrorResponse], e o [await] o lança como exceção. Em um POST (linha 94), o corpo é um objeto: o cliente HTTP o envia em JSON, com o cabeçalho [Content-Type: application/json] exigido pelo servidor (caso contrário: 415);
  • linhas 107–122 (.ts): 1. Na inicialização, quem está conectado? [GET /api/auth/me]: 200, o usuário (seguido da lista de médicos); 401 (linha 113), ninguém: um CAPTCHA é carregado para o formulário. [e instanceof HttpErrorResponse] é uma verificação de tipo: no ramo em que ela é verdadeira, o [TypeScript] sabe que [e] tem um [status]. Outro código de erro (linhas 115–116) ou nenhuma resposta (linhas 117–119, [status] 0): uma mensagem;
  • linhas 125–127 (.ts): o botão “Entrar” delega a ação ao comando;
  • linhas 130–149 (.ts): 2. a conexão: [POST /api/auth/login]. Em caso de sucesso, o navegador (ou o [Android]) armazenou o cookie: o usuário é mantido e os médicos são carregados. Se a conexão falhar, [e.error] é o corpo da resposta de erro, já decodificado: ele contém a chave da mensagem (linha 144; [?.] e [??]: uma chave de reserva se o corpo não contiver nenhuma). Uma nova imagem é carregada (cada uma só é usada uma vez) e, em seguida, um erro é lançado, cuja mensagem será exibida (linha 147): é o comando que a captura e a armazena. Uma exceção que não seja um [HttpErrorResponse] (uma anomalia) é relançada como está (linha 142);
  • linhas 152–155 (.ts): a mensagem de erro retida pelo comando;
  • linhas 158–163 (.ts): 4. Logout: [POST /api/auth/logout]; o servidor apaga o cookie (ele envia um cookie vazio que já expirou), e o navegador o esquece;
  • linhas 15–16 (html): enquanto a verificação inicial não estiver concluída;
  • linhas 17–30 (html): 3. conectado: o usuário e a lista de médicos ([GET /api/doctors], uma requisição protegida: o cookie foi incluído sem uma única linha de código);
  • linhas 31–55 (HTML): não conectado: o formulário. Os campos são vinculados aos signals por meio de [[(ngModel)]] (exemplo 05); o CAPTCHA é exibido como no exemplo 22 (linhas 38–40);
  • linhas 46–52 (HTML): o botão reflete o estado da requisição: desabilitado e com “Entrando...” enquanto a requisição é enviada; qualquer mensagem de erro aparece abaixo;
  • linhas 58–62 (HTML): o servidor não está respondendo.

A tela de login; uma senha incorreta; login bem-sucedido:

Recarregue a página do navegador (ou, em um celular, feche e reabra o aplicativo): ela abre com o usuário conectado. O cookie, armazenado pelo navegador (ou pelo [Android]), é enviado a [GET /api/auth/me], e o servidor responde com as credenciais do usuário. O token expira após duas horas: [GET /api/auth/me] passará então a devolver uma resposta 401, e a tela de login reaparecerá.

9.3. Exemplo 24: Uma camada de acesso à API

No exemplo 23, cada requisição repetia as mesmas etapas. Este exemplo as organiza em três camadas, que o estudo de caso retomará.

9.3.1. Os tipos

// =========================================================================
// src/app/common/types.ts - os objetos JSON trocados com a API do RdvMedecins
// (veja o capítulo sobre a caixa-preta, que descreve cada rota)
// -------------------------------------------------------------------------
// A tradução, em tipos TypeScript, das respostas do servidor. São
// apenas DESCRIÇÕES: desaparecem na compilação e não
// verificam nada em tempo de execução. Elas permitem ao compilador
// verificar que o código só usa campos que existem, com o tipo
// correto (e permitem ao editor sugerir seus nomes).
// =========================================================================

// um "union type" de strings: apenas esses três valores são permitidos
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me
export interface User {
  login: string;
  name: string; // nome exibido: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string; // a imagem, em formato SVG (texto)
}

// o texto SVG -> um endereço "data:" utilizável por <img [src]>: a imagem
// está NO endereço. Uma imagem SVG exibida por <img> não pode executar
// nenhum script: nenhum risco, mesmo que seu conteúdo fosse duvidoso
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}

// o nome de uma pessoa, e nada mais
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// um médico ou um cliente (GET /api/doctors, GET /api/clients...)
// "extends": uma Person tem todos os campos de uma Identity, e outros
export interface Person extends Identity {
  id: number;
  version: number; // bloqueio otimista: a ser reenviado com uma atualização
  login?: string; // opcional (?): apenas para o ADMIN
}

// "Mme Alice DURAND"
export function fullName(i: Identity): string {
  return `${i.title} ${i.firstName} ${i.lastName}`;
}

// uma linha de GET /api/schedule: um horário e os DIREITOS do usuário logado
export interface ScheduleSlot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
  free: boolean;
  patient: Identity | null; // null: livre, ou ocupado por outro paciente
  mine: boolean; // a consulta do paciente logado
  bookable: boolean;
  appointmentId: number | null; // definido se o usuário pode cancelar
}

// "8:00 - 8:20"
export function timeRange(c: ScheduleSlot): string {
  const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
  return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // chave de tradução (paciente que já tem uma consulta)
}

As respostas do servidor, descritas em [TypeScript]. São apenas descrições: as interfaces são eliminadas na compilação e não realizam nenhuma verificação durante a execução. Elas permitem que o compilador verifique se o código usa apenas campos que existem, com o tipo correto, e que o editor sugira seus nomes.

  • linha 13: um tipo união de strings: uma variável do tipo [Role] só pode receber uma dessas três strings. O compilador rejeita [role === 'ADMN'];
  • linhas 16–20: o usuário conectado ([POST /api/auth/login], [GET /api/auth/me]);
  • linhas 44–48: uma pessoa (médico ou cliente). [extends Identity]: ela tem todos os campos de uma [Identity] (linhas 36–40), mais alguns outros; [login?]: um campo opcional (somente o ADMIN o recebe);
  • linhas 56–67: uma entrada da agenda. [Identity | null], [number | null]: junto com ["strict": true] e o [TypeScript], isso obriga a testar esses valores antes de usá-los;
  • linhas 51–53, 70–73: funções de formatação: “Mme Alice DURAND”, “8:00 – 8:20”. Elas não são métodos: os objetos recebidos do servidor são objetos [JavaScript] comuns, sem classe;
  • linhas 76–81: a agenda de um médico para um dia.

Esta é uma diferença fundamental em relação ao cliente [Flutter]. Em [Dart], o JSON decodificado não tem tipo ([dynamic]): cada classe tinha um construtor [fromJson], que verificava o formato do JSON recebido por meio da filtragem do [Dart] 3 (“pattern matching”) e o convertia em um objeto. Aqui, o compilador aceita o que lhe dizem sem questionar ([http.get<Schedule>(...)]): uma resposta inesperada só seria detectada quando a exibição encontrasse um campo ausente. Para um servidor sob nosso controle, essa é a prática comum. Para uma API externa, verificaríamos as respostas com uma biblioteca de “schemas” ([Zod], [Valibot]), que realiza em tempo de execução o que a filtragem do [Dart] fazia.

9.3.2. Erros

// =========================================================================
// src/app/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": {...} }
// Mas uma requisição também pode falhar de OUTRA FORMA: nenhuma resposta
// (rede fora do ar, servidor parado, endereço errado), ou uma resposta que não
// vem do nosso servidor (uma página de erro de um proxy). O cliente
// HTTP do Angular relata todas essas falhas com um HttpErrorResponse; nós
// o convertemos 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';

// um objeto { name: texto }
export type Texts = Record<string, string>;

// "extends Error": um erro JavaScript completo, que lançamos
// (throw) e capturamos (catch); message é "409 ERRORS.LOGIN_TAKEN"
export class ApiError extends Error {
  constructor(
    readonly statusCode: number, // 0: o servidor não respondeu
    readonly key: string, // p. ex.: 'ERRORS.LOGIN_TAKEN'
    readonly params: Texts = {},
    readonly fields: Texts = {},
  ) {
    super(`${statusCode} ${key}`);
    this.name = 'ApiError';
  }

  // uma resposta de erro do cliente HTTP do Angular -> um ApiError
  static fromResponse(response: HttpErrorResponse): ApiError {
    // status 0: nenhuma resposta (rede fora do ar, servidor parado, endereço errado)
    if (response.status === 0) {
      return new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    // error: o corpo da resposta, já decodificado se for JSON
    const body: unknown = response.error;
    if (isObject(body) && typeof body['key'] === 'string') {
      return new ApiError(response.status, body['key'], texts(body['params']), texts(body['fields']));
    }
    // sem key: o proxy ou a rede respondeu no lugar do servidor
    return new ApiError(
      response.status,
      response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }
}

// um "type guard": se a função retornar true, o TypeScript sabe que
// value é um objeto cujas propriedades podem ser lidas
function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// um objeto JSON { "name": "ERRORS..." } -> Texts (vazio caso contrário)
function texts(json: unknown): Texts {
  if (!isObject(json)) return {};
  return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, String(value)]));
}

Todas as respostas de erro do servidor têm o mesmo formato. No entanto, uma requisição também pode falhar de OUTRA FORMA: nenhuma resposta, ou uma resposta que não vem do nosso servidor. O cliente HTTP do [Angular] relata todas essas falhas como um [HttpErrorResponse]; nós as convertemos em UMA única classe, [ApiError].

  • Linha 18: [Record<string, string>]: um objeto cujas propriedades são strings;
  • linhas 22–31: [extends Error]: um erro [JavaScript] de pleno direito, que é lançado ([throw]) e capturado ([catch]), com sua pilha de chamadas. Os parâmetros do construtor precedidos por [readonly] declaram e inicializam os campos (um atalho do [TypeScript]): um status (0: nenhuma resposta), uma chave de tradução, seus parâmetros e o erro de cada campo. A mensagem do erro (linha 29) é “401 LOGIN.ERROR”, para exibição rápida;
  • linhas 34–49: um [HttpErrorResponse] → um [ApiError]. Status 0: nenhuma resposta (linhas 36–38). Caso contrário, [response.error] é o corpo da resposta, já decodificado se for JSON (linha 40); se ele tiver uma chave do tipo string [key], nosso servidor respondeu (linhas 41–42). Caso contrário, um intermediário (proxy, rede) respondeu em seu lugar (linhas 45–48);
  • linhas 54–56: um type guard ([value is Record<string, unknown>])—uma função cujo resultado, [true], informa ao compilador o tipo de seu parâmetro. Depois de [isObject(body)], ele sabe que [body] é um objeto cujas propriedades podem ser lidas. É o que a instrução “if-case” do [Dart] fazia em uma única etapa;
  • linhas 59–62: um objeto JSON { "name": "ERRORS..." } → texto (vazio se não for um objeto).

9.3.3. As requisições

// =========================================================================
// src/app/common/api.ts - requisições à API, em uma linha
// -------------------------------------------------------------------------
// No exemplo 23, cada requisição repetia as mesmas etapas: endereço do
// servidor, prefixo /api, transformar o Observable em Promise, ler
// o corpo do erro... Agrupamos tudo isso aqui, em um SERVIÇO:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId: 3 });
//
//   - em caso de sucesso, a Promise retorna o corpo JSON, DECODIFICADO;
//   - em caso de falha, ela é rejeitada com um ApiError.
// Todas as requisições passam pelo método request: é o lugar onde
// trataríamos um problema COMUM a todas elas (veja o estudo de caso e a
// resposta 401). Usado pelos exemplos 24 e 25.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { config } from './config';
import { ApiError } from './api-error';

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

// providedIn: 'root': uma única instância, para toda a aplicação
@Injectable({ providedIn: 'root' })
export class Api {
  private readonly http = inject(HttpClient);

  // <T>: o tipo da resposta esperada, escolhido pelo chamador
  async request<T>(method: Method, url: string, body?: unknown): Promise<T> {
    try {
      // http.request retorna um Observable; firstValueFrom o transforma em
      // Promise (a requisição é enviada nesse momento). Um objeto de corpo é enviado
      // como JSON (cabeçalho content-type: application/json, que o servidor exige
      // para um POST); a resposta JSON é decodificada (null se seu corpo estiver vazio)
      return await firstValueFrom(this.http.request<T>(method, `${config.serverUrl}/api${url}`, { body }));
    } catch (e) {
      // o cliente HTTP relata QUALQUER falha (4xx, 5xx, sem resposta) com um
      // HttpErrorResponse: nós o convertemos. O resto (uma anomalia) passa como está
      throw e instanceof HttpErrorResponse ? ApiError.fromResponse(e) : e;
    }
  }

  get<T>(url: string): Promise<T> {
    return this.request<T>('GET', url);
  }

  // um POST sempre tem um corpo JSON: {} por padrão
  post<T>(url: string, body: unknown = {}): Promise<T> {
    return this.request<T>('POST', url, body);
  }

  put<T>(url: string, body: unknown): Promise<T> {
    return this.request<T>('PUT', url, body);
  }

  delete<T>(url: string, body?: unknown): Promise<T> {
    return this.request<T>('DELETE', url, body);
  }
}

Um serviço (exemplo 14) que executa, de uma vez por todas, as ações repetidas no exemplo 23:

  • linha 27: [@Injectable({ providedIn: 'root' })]: uma única instância, para toda a aplicação, criada na primeira requisição;
  • Linhas 32–44: TODAS as requisições são processadas por este método: o endereço do servidor e o prefixo [/api], o corpo em JSON ([http.request] aceita todos os métodos, e um corpo até mesmo em um DELETE), a resposta decodificada e aguardada com [firstValueFrom] (linha 38), os erros convertidos em [ApiError] (linha 42). O tipo de resposta [<T>] é escolhido por quem chama ([api.get<Person[]>('/doctors')]). É aqui que seria tratado um problema comum a todas as requisições (veja o estudo de caso, e a resposta 401 de uma sessão expirada, tratada em um interceptor do cliente HTTP);
  • linhas 46–61: quatro atalhos. Um POST sempre tem um corpo JSON: [{}] por padrão (linha 51).

9.3.4. Uma barra de conexão

// =========================================================================
// src/app/common/login-bar.ts - login / logout, em uma barra
// -------------------------------------------------------------------------
// O formulário do exemplo 23, reduzido a uma barra e reescrito com o
// serviço Api. O componente emite o evento userChange com
// o usuário logado (ou null) a cada mudança - inclusive
// na inicialização, após consultar GET /api/auth/me:
//
//     <app-login-bar (userChange)="onUserChange($event)" />
//
// O serviço Api é obtido por injeção de dependência (inject).
// =========================================================================

import { Component, inject, output, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { IonButton, IonCard, IonCardContent, IonIcon, IonInput, IonLabel, IonText } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { logInOutline, person } from 'ionicons/icons';
import { Api } from './api';
import { ApiError } from './api-error';
import { Captcha, captchaImage, User } from './types';

@Component({
  selector: 'app-login-bar',
  imports: [FormsModule, IonCard, IonCardContent, IonInput, IonButton, IonIcon, IonLabel, IonText],
  templateUrl: './login-bar.html',
  styles: `
    ion-card { --background: #eceff1; margin: 0 0 8px; }
    ion-card-content { padding: 8px 12px; }
    .line { display: flex; align-items: center; gap: 8px; }
    .line > ion-input, .line > ion-label { flex: 1; }
    img { height: 40px; }
    .error { font-size: 13px; }
  `,
})
export class LoginBar {
  private readonly api = inject(Api);
  readonly captchaImage = captchaImage;

  // o evento emitido ao pai: o usuário logado, ou null
  readonly userChange = output<User | null>();

  readonly user = signal<User | null>(null);
  readonly captcha = signal<Captcha | null>(null);
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');
  readonly error = signal<string | null>(null);

  constructor() {
    addIcons({ person, logInOutline });
    this.start();
  }

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

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

  // na inicialização: já estamos logados?
  private async start(): Promise<void> {
    try {
      this.change(await this.api.get<User>('/auth/me'));
    } catch {
      this.change(null); // 401: ninguém está logado
      try {
        await this.newCaptcha();
      } catch {
        this.error.set('Is the JSON server running (port 8080)?');
      }
    }
  }

  async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await this.api.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.change(u);
    } catch (e) {
      // e.message: "401 LOGIN.ERROR" (o exemplo 25 traduzirá a chave)
      this.error.set(e instanceof ApiError ? e.message : String(e));
      await this.newCaptcha();
    }
  }

  async logOut(): Promise<void> {
    await this.api.post('/auth/logout');
    this.change(null);
    await this.newCaptcha();
  }
}
<!-- ======================================================================
     login-bar.html - o usuário logado, ou um pequeno formulário
     ====================================================================== -->

<ion-card>
  <ion-card-content>
    @if (user(); as u) {
      <div class="line">
        <ion-icon name="person" />
        <ion-label>{{ u.name }} ({{ u.role }})</ion-label>
        <ion-button fill="clear" size="small" (click)="logOut()">Log out</ion-button>
      </div>
    } @else {
      <div class="line">
        <ion-input label="login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="password" labelPlacement="floating" type="password" [(ngModel)]="password" />
      </div>
      <div class="line">
        <!-- a imagem SVG do captcha, feita pelo NOSSO servidor (veja o exemplo 22) -->
        @if (captcha(); as c) {
          <img [src]="captchaImage(c)" alt="captcha" />
        }
        <ion-input label="captcha" labelPlacement="floating" autocorrect="off" autocapitalize="off"
          [(ngModel)]="captchaAnswer" (keyup.enter)="logIn()" />
        <ion-button fill="clear" aria-label="Log in" (click)="logIn()">
          <ion-icon slot="icon-only" name="log-in-outline" />
        </ion-button>
      </div>
      @if (error(); as message) {
        <ion-text color="danger"><div class="error">{{ message }}</div></ion-text>
      }
    }
  </ion-card-content>
</ion-card>

O formulário do exemplo 23, reduzido a uma barra e reescrito com o serviço [Api]. O componente emite o evento [userChange] sempre que o usuário conectado muda, inclusive na inicialização.

  • linha 37 (.ts): o serviço [Api], obtido por injeção ([provider] do [Flutter]);
  • linha 41 (.ts): [output<User | null>()]: um evento que o componente emite para seu pai (exemplo 11), que o assina por meio de [(userChange)="..."];
  • linhas 55–58 (.ts): uma mudança de usuário: nós a retemos e notificamos o pai ([emit]);
  • linhas 66–77 (.ts): na inicialização, quem está conectado? [await this.api.get<User>('/auth/me')]: uma única linha. Qualquer erro significa “ninguém”: um CAPTCHA é então carregado; se isso também falhar, o servidor não está respondendo. [catch] sem variável: o erro em si não é usado;
  • linhas 79–95 (.ts): o processo de login, em poucas linhas: os erros aparecem como [ApiError], e a mensagem é exibida (“401 LOGIN.ERROR”: o exemplo 25 explicará a chave);
  • linhas 7–12 (html): conectado: o usuário e seu papel, e o botão “Sair”;
  • linhas 13–31 (HTML): o formulário, distribuído em duas linhas ([display: flex]); pressionar Enter no campo do CAPTCHA envia o formulário ([(keyup.enter)], linha 24); o botão tem apenas um ícone e seu nome para leitores de tela ([aria-label]).

9.3.5. A camada de acesso à API

// =========================================================================
// src/app/ex24-api-layer/rdvmedecins.ts - a camada de acesso à API
// -------------------------------------------------------------------------
// Um método por rota da API, tipado. As telas não conhecem nem os
// endereços, nem o cliente HTTP, nem o formato JSON: elas chamam
// métodos que retornam objetos tipados (Person, Schedule...).
// É o equivalente, no lado do cliente, da camada DAO do lado do servidor: se a API
// mudar (um endereço, o nome de um campo), só modificamos este arquivo.
// Os guias de arquitetura chamam essa camada de "repositório".
// =========================================================================

import { HttpParams } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { Api } from '../common/api';
import { Schedule, Person } from '../common/types';

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

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

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

  // HttpParams constrói "doctorId=1&day=2030-01-15", codificando o que for necessário
  getSchedule(doctorId: number, day: string): Promise<Schedule> {
    const params = new HttpParams().set('doctorId', doctorId).set('day', day);
    return this.api.get<Schedule>(`/schedule?${params.toString()}`);
  }

  // clientId?: um parâmetro opcional. ...(condição && objeto): a
  // propriedade clientId só é colocada no corpo se clientId for informado
  async book(day: string, slotId: number, clientId?: number | null): Promise<void> {
    await this.api.post('/appointments', { day, slotId, ...(clientId != null && { clientId }) });
  }

  async cancelAppointment(appointmentId: number): Promise<void> {
    await this.api.delete(`/appointments/${appointmentId}`);
  }
}

Um método por rota da API, tipado. As telas desconhecem endereços, o cliente HTTP ou o formato JSON: elas chamam métodos que devolvem objetos tipados. Se a API mudar (um endereço, o nome de um campo), apenas este arquivo é modificado. Os guias de arquitetura chamam essa camada de “repositório”.

  • Linha 19: a camada se apoia no serviço [Api], que ela obtém por injeção: o [Angular] monta as camadas sozinho, enquanto o [main] do cliente [Flutter] as criava uma a uma ([RdvMedecins(api)]);
  • linha 31: [HttpParams] gera a string “doctorId=1&day=2030-01-15” codificando os dados necessários;
  • linha 38: [clientId] só é colocado no corpo se for informado. [...(condition && object)]: se a condição for falsa, [false] é “expandido”, o que não adiciona nada; caso contrário, o objeto [{ clientId }] (forma abreviada de [{ clientId: clientId }]) é expandido. Era [?clientId] no [Dart] 3.8. [clientId != null] (com [!=] e não [!==]) exclui tanto [null] quanto [undefined].

9.3.6. O view model

// =========================================================================
// src/app/ex24-api-layer/schedule-model.ts - o "view model" da tela
// -------------------------------------------------------------------------
// Os guias de arquitetura recomendam separar:
//   - a VIEW: o template e sua classe, que exibem e repassam as
//     ações do usuário;
//   - o VIEW MODEL (ViewModel): um serviço que contém o estado da
//     tela (o médico escolhido, o dia, a agenda recebida...) em
//     SIGNALS, as ações (escolher, agendar, cancelar), e que chama a
//     camada de acesso à API.
// A view não tem mais nenhuma lógica: é simples de ler; o view model
// não tem template: é simples de testar.
// Ele é fornecido pela PÁGINA (providers: [ScheduleModel]): nasce e morre
// com ela.
//
// Ele também faz o que não queremos reescrever para cada tela:
//   - um CACHE: a agenda de cada (médico, dia) já lida é mantida; ao
//     voltar a ela, ela é exibida de imediato, enquanto é lida novamente em segundo plano;
//   - respostas OBSOLETAS são ignoradas (veja o exemplo 19).
// =========================================================================

import { computed, inject, Injectable, signal } from '@angular/core';
import { ApiError } from '../common/api-error';
import { Schedule, ScheduleSlot, timeRange, Person, User } from '../common/types';
import { RdvMedecins } from './rdvmedecins';

// uma data -> "2026-10-07" (o dia LOCAL; toISOString daria o dia em Greenwich)
export function formatDay(d: Date): string {
  const twoDigits = (n: number) => String(n).padStart(2, '0');
  return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}

// amanhã: o dia de hoje, mais um
function tomorrow(): Date {
  const d = new Date();
  d.setDate(d.getDate() + 1);
  return d;
}

export interface Message {
  success: boolean;
  text: string;
}

@Injectable()
export class ScheduleModel {
  private readonly rdvmedecins = inject(RdvMedecins);

  // ---- o estado ----
  readonly user = signal<User | null>(null);
  readonly doctors = signal<Person[]>([]);
  readonly clients = signal<Person[]>([]);
  readonly doctorId = signal<number | null>(null);
  readonly day = signal(formatDay(tomorrow()));
  readonly clientId = signal<number | null>(null);
  readonly schedule = signal<Schedule | null>(null);
  readonly loading = signal(false);
  readonly message = signal<Message | null>(null);

  private readonly cache = new Map<string, Schedule>();
  private readNumber = 0;

  // ---- valores calculados ----
  readonly loggedIn = computed(() => this.user() !== null);
  readonly isManager = computed(() => this.loggedIn() && this.user()?.role !== 'USER');

  // ---- as ações ----
  async changeUser(u: User | null): Promise<void> {
    this.user.set(u);
    this.doctors.set([]);
    this.clients.set([]);
    this.schedule.set(null);
    this.doctorId.set(null);
    this.message.set(null);
    this.cache.clear(); // os direitos mudaram: esquecemos tudo
    if (u === null) return;
    this.doctors.set(await this.rdvmedecins.getDoctors());
    // um USER receberia 403
    if (this.isManager()) this.clients.set(await this.rdvmedecins.getClients());
  }

  chooseDoctor(id: number): void {
    this.doctorId.set(id);
    this.message.set(null);
    this.readSchedule();
  }

  chooseDay(day: string): void {
    this.day.set(day);
    this.message.set(null);
    this.readSchedule();
  }

  chooseClient(id: number | null): void {
    this.clientId.set(id);
  }

  book(c: ScheduleSlot): Promise<void> {
    return this.act(
      () => this.rdvmedecins.book(this.day(), c.id, this.isManager() ? this.clientId() : null),
      `Slot ${timeRange(c)} booked.`,
    );
  }

  cancel(c: ScheduleSlot): Promise<void> {
    return this.act(() => this.rdvmedecins.cancelAppointment(c.appointmentId!), `Appointment of ${timeRange(c)} cancelled.`);
  }

  // uma ação, depois SEMPRE uma nova leitura da agenda: o SERVIDOR é a referência
  private async act(action: () => Promise<void>, success: string): Promise<void> {
    try {
      await action();
      this.message.set({ success: true, text: success });
    } catch (e) {
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    await this.readSchedule();
  }

  private async readSchedule(): Promise<void> {
    const id = this.doctorId();
    if (id === null) return;
    const key = `${id}/${this.day()}`;
    const number = ++this.readNumber;
    // primeiro o cache (ou nada), depois a leitura
    this.schedule.set(this.cache.get(key) ?? null);
    this.loading.set(true);
    try {
      const read = await this.rdvmedecins.getSchedule(id, this.day());
      if (number !== this.readNumber) return; // uma leitura mais recente foi iniciada
      this.cache.set(key, read);
      this.schedule.set(read);
    } catch (e) {
      if (number !== this.readNumber) return;
      this.schedule.set(null);
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    this.loading.set(false);
  }
}

Os guias de arquitetura recomendam separar a view (o template e sua classe, que exibem e transmitem as ações do usuário) do view model (um serviço que contém o estado da tela e suas ações, e que chama a camada de acesso à API). A view deixa de conter qualquer lógica; o view model não tem template: ele pode ser testado sem uma tela.

  • Linhas 28–38: o dia no formato do servidor (“2026-10-07”) e o dia seguinte. Não usamos [toISOString()], que devolveria o dia no horário de Greenwich: às 0h30 em Paris, ainda seria o dia anterior;
  • linha 45: [@Injectable()], sem [providedIn]: o serviço não é fornecido para toda a aplicação, mas pela página que o declara em seus [providers] (veja a tela). Ele é criado e destruído junto com essa página;
  • linhas 50–58: o estado da tela, representado por signals;
  • linhas 60–61: um cache: a agenda de cada (médico, dia) já lida é armazenada; ao voltar a ela, ela é exibida imediatamente enquanto é relida. E o número da última leitura, para ignorar respostas desatualizadas (veja o exemplo 19). Isso, em poucas linhas, é o que a biblioteca [TanStack Query] do curso de [React] faz;
  • linhas 64–65: valores calculados ([computed]): conectado? administrador (ADMIN ou DOCTOR)?
  • linhas 68–80: um novo usuário: ignoramos tudo (as permissões mudaram), depois lemos os médicos e, para ADMIN e DOCTOR, os clientes (um USER receberia um 403);
  • Linhas 98–107: reservar, cancelar. O [!] de [c.appointmentId!] (linha 106) informa ao compilador que o valor não é [null]: o botão “Cancelar” só é exibido nesse caso;
  • linhas 110–118: uma ação, SEMPRE seguida de uma nova leitura da agenda: os dados do servidor prevalecem;
  • linhas 120–139: a leitura da agenda: primeiro o cache, ou nada (linha 126), depois a resposta do servidor, a menos que uma leitura mais recente tenha sido iniciada nesse meio-tempo (linha 130).

9.3.7. A tela

// =========================================================================
// src/app/ex24-api-layer/ex24.page.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 agendar para um paciente e
// cancelar; um paciente (martin...) agenda para si mesmo. Cada ação
// termina com uma nova leitura da agenda.
// Três camadas, de baixo para cima:
//   Api (common/api.ts)                  as requisições HTTP, os erros;
//   RdvMedecins (rdvmedecins.ts)         um método tipado por rota da API;
//   ScheduleModel (schedule-model.ts)    o estado e as ações da tela;
// e a view (esta classe e seu template), que apenas exibe o modelo.
// =========================================================================

import { Component, inject } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonChip, IonContent, IonDatetime, IonHeader,
  IonIcon, IonItem, IonLabel, IonList, IonModal, IonProgressBar, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { addCircleOutline, calendarOutline, closeCircleOutline } from 'ionicons/icons';
import { LoginBar } from '../common/login-bar';
import { timeRange, fullName } from '../common/types';
import { ScheduleModel } from './schedule-model';

@Component({
  selector: 'app-ex24',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSelect, IonSelectOption, IonButton,
    IonIcon, IonModal, IonDatetime, IonCard, IonCardContent, IonProgressBar, IonText, IonList, IonItem, IonLabel,
    IonChip, LoginBar,
  ],
  templateUrl: './ex24.page.html',
  // o view model é fornecido pela PÁGINA: uma instância por página, destruída com ela
  providers: [ScheduleModel],
  styles: `
    .day { display: flex; align-items: center; }
    ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
    .message { margin: 8px 0; }
    .success { --background: #e8f5e9; --color: #333; }
    .failure { --background: #ffebee; --color: #333; }
    .schedule-title { font-weight: bold; font-size: 14px; margin: 8px 0; }
    .time-range { flex: 0 0 90px; font-size: 13px; }
    .free { --background: #c8e6c9; }
    .mine { --background: #c5cae9; }
    .other { --background: #e0e0e0; }
    ion-item ion-icon { font-size: 26px; }
  `,
})
export class Ex24Page {
  readonly model = inject(ScheduleModel);
  readonly timeRange = timeRange;
  readonly fullName = fullName;

  constructor() {
    addIcons({ calendarOutline, addCircleOutline, closeCircleOutline });
  }

  // ion-datetime retorna "2026-10-07" (presentation="date"), ou um array se
  // várias datas puderem ser escolhidas: só mantemos uma string
  chooseDay(value: string | string[] | null | undefined): void {
    if (typeof value === 'string') this.model.chooseDay(value.substring(0, 10));
  }
}
<!-- ======================================================================
     ex24.page.html - a view: ela apenas exibe o view model
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 24 - an API access layer</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <!-- a barra de login notifica o view model -->
  <app-login-bar (userChange)="model.changeUser($event)" />

  @if (model.loggedIn()) {
    <ion-select placeholder="-- choose a doctor --" interface="popover" class="doctor-choice" aria-label="doctor"
      [value]="model.doctorId()" (ionChange)="model.chooseDoctor($event.detail.value)">
      @for (m of model.doctors(); track m.id) {
        <ion-select-option [value]="m.id">{{ fullName(m) }}</ion-select-option>
      }
    </ion-select>

    <div class="day">
      Day: {{ model.day() }}
      <ion-button id="calendar24" fill="clear" aria-label="choose the day">
        <ion-icon slot="icon-only" name="calendar-outline" />
      </ion-button>
    </div>
    <ion-modal class="calendar" trigger="calendar24">
      <ng-template>
        <ion-datetime presentation="date" locale="en-US" [firstDayOfWeek]="1" [showDefaultButtons]="true"
          doneText="OK" cancelText="Cancel" [value]="model.day()" (ionChange)="chooseDay($event.detail.value)" />
      </ng-template>
    </ion-modal>

    <!-- ADMIN e DOCTOR: o paciente para quem agendamos -->
    @if (model.isManager()) {
      <ion-select interface="popover" class="patient-choice" aria-label="patient" [value]="model.clientId()"
        (ionChange)="model.chooseClient($event.detail.value)">
        <ion-select-option [value]="null">-- patient to book --</ion-select-option>
        @for (c of model.clients(); track c.id) {
          <ion-select-option [value]="c.id">{{ fullName(c) }}</ion-select-option>
        }
      </ion-select>
    }

    @if (model.message(); as message) {
      <ion-card class="message" [class.success]="message.success" [class.failure]="!message.success">
        <ion-card-content>{{ message.text }}</ion-card-content>
      </ion-card>
    }
    @if (model.loading()) {
      <ion-progress-bar type="indeterminate" />
    }

    @if (model.schedule(); as schedule) {
      <!-- info: a chave enviada pelo servidor quando um paciente já tem uma consulta futura -->
      @if (schedule.info) {
        <ion-text color="primary"><div>{{ schedule.info }}</div></ion-text>
      }
      <div class="schedule-title">Schedule of {{ schedule.day }} - {{ fullName(schedule.doctor) }}</div>
      <ion-list lines="none">
        <!-- uma linha por horário: o intervalo, o ocupante, o botão permitido -->
        @for (c of schedule.slots; track c.id) {
          <ion-item>
            <ion-label class="time-range">{{ timeRange(c) }}</ion-label>
            @if (c.free) {
              <ion-chip class="free">Free</ion-chip>
            } @else {
              <ion-chip [class.mine]="c.mine" [class.other]="!c.mine">
                {{ c.patient ? fullName(c.patient) : 'Booked' }}
              </ion-chip>
            }
            <!-- os botões acompanham os direitos calculados pelo servidor -->
            @if (c.bookable) {
              <ion-button slot="end" fill="clear" color="success" aria-label="Book" (click)="model.book(c)">
                <ion-icon slot="icon-only" name="add-circle-outline" />
              </ion-button>
            } @else if (c.appointmentId !== null) {
              <ion-button slot="end" fill="clear" color="danger" aria-label="Cancel" (click)="model.cancel(c)">
                <ion-icon slot="icon-only" name="close-circle-outline" />
              </ion-button>
            }
          </ion-item>
        }
      </ion-list>
    }
  }
</ion-content>
  • linha 36 (.ts): [providers: [ScheduleModel]]: a página fornece o view model a si mesma e aos componentes que ela contém. As outras duas camadas ([Api], [RdvMedecins]) são fornecidas para toda a aplicação ([providedIn: 'root']);
  • linha 52 (.ts): a view obtém o view model; ela não tem nenhum outro estado;
  • linhas 53–54 (.ts): as funções de formatação, tornadas acessíveis ao template (um template só enxerga os membros de sua classe);
  • linhas 62–64 (.ts): [ion-datetime] devolve a data selecionada (“2026-10-07”), ou um array se várias datas puderem ser selecionadas: apenas uma string é mantida;
  • linha 16 (html): a barra de login notifica o view model; [$event] é o valor devolvido, seja o usuário ou [null];
  • Linhas 19–24 (HTML): a seleção do médico: um [<ion-select>] cuja lista se abre em uma janela pop-up ([interface="popover"]); seu valor é lido do view model, e cada seleção ([ionChange]) dispara uma ação do view model;
  • linhas 26–37 (HTML): o dia e um calendário em uma janela modal (como no exemplo 21): [ion-datetime], em inglês dos EUA, com a semana começando na segunda-feira; seus botões OK e Cancelar ([showDefaultButtons]) fecham a janela, e OK confirma o dia ([ionChange]);
  • linhas 40–48 (HTML): para ADMIN e DOCTOR, o paciente para quem a consulta está sendo marcada;
  • linhas 50–57 (html): a mensagem da última ação (verde ou vermelha: [[class.success]] adiciona a classe CSS quando a condição é verdadeira) e a barra de progresso durante a leitura;
  • linhas 61–63 (html): [info], a chave enviada pelo servidor quando o paciente já tem uma consulta futura. Ela é exibida como está: o exemplo 25 ensinará a decodificar as chaves;
  • linhas 67–88 (HTML): uma linha por horário: a hora, um [<ion-chip>] (um “marcador”) com o rótulo “Livre” ou o nome do paciente (em índigo se for a consulta do paciente conectado) e o botão correspondente. Os botões seguem as permissões calculadas pelo servidor ([bookable], [appointmentId]): a tela não toma nenhuma decisão.

Conectado como [admin], a agenda da Sra. PELISSIER para o dia seguinte; um horário reservado para o Sr. Jean MARTIN; conectado como [martin] (papel USER), a mesma agenda:

O paciente [martin] vê sua consulta (em índigo, com o botão de cancelar); a chave [SCHEDULE.ALREADY_BOOKED_INFO] indica que ele já tem uma consulta futura: nenhum outro horário está disponível para reserva. A consulta de outro paciente apareceria como “Reservado”, sem nome: o servidor não a envia ao usuário.

9.4. Exemplo 25: Erros devolvidos pelo servidor

9.4.1. Os dicionários

{
  "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.",
    "PAGE_TITLE": "Exemple 25 - les erreurs du serveur",
    "NEW": "Nouveau client"
  },
  "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.",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image."
  }
}

As mensagens de erro do servidor são chaves (“ERRORS.LASTNAME_REQUIRED”): o dicionário as traduz. São os dicionários do exemplo [Flutter], sem alterações; o dicionário em inglês, [ex25-en.json], tem as mesmas chaves. Como os do exemplo 21, eles ficam na pasta [public/i18n/] do projeto, que é entregue sem modificações junto com a aplicação.

9.4.2. A tela

// =========================================================================
// src/app/ex25-server-errors/ex25.page.ts - exibindo os erros do SERVIDOR
// -------------------------------------------------------------------------
// O gerenciamento dos clientes (conta admin). Este formulário não faz
// DELIBERADAMENTE nenhuma validação no celular: tudo é enviado ao
// servidor, que responde, em caso de recusa, com um erro JSON (convertido em
// um ApiError por common/api.ts):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (bloqueio otimista)
//
// O erro de CADA campo (ApiError.fields) é entregue ao seu controle de
// formulário (setErrors): ion-input o exibe sob o campo (errorText).
// Sua mensagem é a CHAVE enviada pelo servidor, que a tela traduz
// (dicionários do exemplo 21). Modificar um campo apaga seu erro.
// Experimente: um nome vazio, um título "Dr", um homônimo (Alice DURAND), um
// login já em uso (martin), o mesmo registro modificado em dois dispositivos...
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { NonNullableFormBuilder, ReactiveFormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonContent, IonHeader,
  IonIcon, IonInput, IonItem, IonLabel, IonList, IonNote, IonPopover, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { createOutline, languageOutline, trashOutline } from 'ionicons/icons';
import { Api } from '../common/api';
import { LoginBar } from '../common/login-bar';
import { ApiError, Texts } from '../common/api-error';
import { fullName, Person, User } from '../common/types';
import { injectConfirmation } from '../ex16-confirmation/confirmation';
import { languages, Translations } from '../ex21-i18n/translations';
import { Command } from '../ex23-login/command';

// os campos do formulário, e uma mensagem a traduzir (uma chave e seus parâmetros)
type Field = 'title' | 'firstName' | 'lastName' | 'login' | 'password';
interface Success {
  key: string;
  params: Texts;
}

@Component({
  selector: 'app-ex25',
  imports: [
    ReactiveFormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonButton, IonIcon, IonPopover,
    IonContent, IonList, IonItem, IonLabel, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonSelect,
    IonSelectOption, IonInput, IonText, IonNote, LoginBar,
  ],
  templateUrl: './ex25.page.html',
  // as traduções da página, com os dicionários ex25-fr.json e ex25-en.json
  providers: [{ provide: Translations, useFactory: () => new Translations('ex25') }],
  styles: `
    .warning { --background: #fff8e1; --color: #333; }
    .message { margin-top: 12px; }
    .status { font-size: 12px; }
  `,
})
export class Ex25Page {
  private readonly api = inject(Api);
  private readonly confirm = injectConfirmation();
  readonly tr = inject(Translations);
  readonly languages = languages;
  readonly titles = ['Mr', 'Mme', 'Melle', 'Dr']; // "Dr": o servidor vai recusá-lo
  readonly fullName = fullName;

  readonly user = signal<User | null>(null);
  readonly clients = signal<Person[]>([]);

  // o formulário: NENHUMA regra de validação, tudo é verificado pelo servidor
  readonly form = inject(NonNullableFormBuilder).group({
    title: ['Mr'],
    firstName: [''],
    lastName: [''],
    login: [''],
    password: [''],
  });
  // null: criação; caso contrário, o id do cliente modificado e a versão lida com seu registro
  readonly editedId = signal<number | null>(null);
  private version = 0;

  // a mensagem geral do último erro, e a de um sucesso
  readonly pageError = signal<ApiError | null>(null);
  readonly success = signal<Success | null>(null);
  // o envio ao servidor: um Command (exemplo 23), que diz se está em execução
  readonly sending = new Command();

  constructor() {
    addIcons({ languageOutline, createOutline, trashOutline });
    this.tr.start();
  }

  isAdmin(): boolean {
    return this.user()?.role === 'ADMIN';
  }

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

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

  // o erro de um campo, retornado pelo servidor, traduzido ('': sem erro)
  fieldError(field: Field): string {
    const key = this.form.controls[field].errors?.['server'];
    return typeof key === 'string' ? this.tr.t(key) : '';
  }

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

  newForm(): void {
    this.editedId.set(null);
    this.version = 0;
    // reset: os valores iniciais, e nenhum erro mais
    this.form.reset();
    this.clearMessages();
  }

  edit(c: Person): void {
    this.editedId.set(c.id);
    // a VERSÃO lida com o registro volta com a modificação: se alguém
    // modificou o registro nesse meio-tempo, o servidor responderá 409 CONCURRENT_UPDATE
    this.version = c.version;
    this.form.reset({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '' });
    this.clearMessages();
  }

  // o botão "Salvar"
  submit(): void {
    this.sending.execute(() => this.save());
  }

  private async save(): Promise<void> {
    this.clearMessages();
    const input = { ...this.form.getRawValue(), version: this.version };
    const id = this.editedId();
    try {
      const client =
        id === null
          ? await this.api.post<Person>('/clients', input)
          : await this.api.put<Person>(`/clients/${id}`, input);
      this.newForm(); // formulário esvaziado, mensagens apagadas...
      // ... exceto esta
      this.success.set({
        key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
        params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
      });
      await this.reload();
    } catch (e) {
      if (!(e instanceof ApiError)) throw e;
      this.pageError.set(e); // a mensagem geral
      // o erro de cada campo: é entregue ao seu controle, que
      // se torna inválido (ng-invalid); markAsTouched o marca como "tocado"
      // (ng-touched): o Ionic então exibe seu errorText
      for (const [field, key] of Object.entries(e.fields)) {
        const control = this.form.get(field);
        control?.setErrors({ server: key });
        control?.markAsTouched();
      }
    }
  }

  async remove(c: Person): Promise<void> {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await this.confirm(this.tr.t('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) {
      if (e instanceof ApiError) this.pageError.set(e);
    }
    await this.reload();
  }
}
<!-- ======================================================================
     ex25.page.html - o gerenciamento dos clientes e os erros do servidor
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('FORM.PAGE_TITLE') }}</ion-title>
    <!-- o idioma: um menu, em uma janela pop-up (ion-popover) -->
    <ion-buttons slot="end">
      <ion-button id="language25" aria-label="language">
        <ion-icon slot="icon-only" name="language-outline" />
      </ion-button>
    </ion-buttons>
    <ion-popover trigger="language25" [dismissOnSelect]="true">
      <ng-template>
        <ion-list>
          @for (l of languages; track l) {
            <ion-item [button]="true" (click)="tr.changeLanguage(l)">{{ l.toUpperCase() }}</ion-item>
          }
        </ion-list>
      </ng-template>
    </ion-popover>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <app-login-bar (userChange)="onUserChange($event)" />

  @if (user() !== null && !isAdmin()) {
    <ion-card class="warning">
      <ion-card-content>{{ tr.t('FORM.ADMIN_ONLY') }}</ion-card-content>
    </ion-card>
  }

  @if (isAdmin()) {
    <ion-list>
      @for (c of clients(); track c.id) {
        <ion-item>
          <ion-label>
            {{ fullName(c) }}
            <p>{{ c.login }}</p>
          </ion-label>
          <ion-button slot="end" fill="clear" color="dark" [attr.aria-label]="tr.t('FORM.EDIT')"
            (click)="edit(c)">
            <ion-icon slot="icon-only" name="create-outline" />
          </ion-button>
          <ion-button slot="end" fill="clear" color="danger" [attr.aria-label]="tr.t('FORM.DELETE')"
            (click)="remove(c)">
            <ion-icon slot="icon-only" name="trash-outline" />
          </ion-button>
        </ion-item>
      }
    </ion-list>

    <ion-card>
      <ion-card-header>
        <ion-card-title>{{ tr.t(editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') }}</ion-card-title>
      </ion-card-header>
      <ion-card-content>
        <!-- não (ngSubmit): o botão Salvar chama submit() -->
        <form [formGroup]="form">
          <!-- errorText: o erro do campo retornado pelo servidor, traduzido. O Ionic
               o exibe quando o controle é inválido (ion-invalid) e tocado (ion-touched) -->
          <ion-select [label]="tr.t('FORM.TITLE')" labelPlacement="floating" interface="popover"
            formControlName="title" [errorText]="fieldError('title')">
            @for (t of titles; track t) {
              <ion-select-option [value]="t">{{ t }}</ion-select-option>
            }
          </ion-select>
          <ion-input [label]="tr.t('FORM.FIRSTNAME')" labelPlacement="floating" formControlName="firstName"
            [errorText]="fieldError('firstName')" />
          <ion-input [label]="tr.t('FORM.LASTNAME')" labelPlacement="floating" formControlName="lastName"
            [errorText]="fieldError('lastName')" />
          <ion-input [label]="tr.t('FORM.LOGIN')" labelPlacement="floating" formControlName="login"
            [errorText]="fieldError('login')" />
          <ion-input [label]="tr.t('FORM.PASSWORD')" labelPlacement="floating" type="password"
            formControlName="password" [errorText]="fieldError('password')" />
        </form>

        <ion-button class="ion-margin-top" shape="round" [disabled]="sending.running()" (click)="submit()">
          {{ tr.t('FORM.SAVE') }}
        </ion-button>
        <ion-button class="ion-margin-top" shape="round" fill="outline" (click)="newForm()">
          {{ tr.t('FORM.CANCEL') }}
        </ion-button>

        @if (success(); as s) {
          <div class="message"><ion-text color="success">{{ tr.t(s.key, s.params) }}</ion-text></div>
        }
        <!-- a mensagem geral, e o status HTTP, para entender -->
        @if (pageError(); as e) {
          <div class="message">
            <ion-text color="danger">{{ tr.t(e.key, e.params) }}</ion-text>
            <ion-note class="status"> ({{ e.message }})</ion-note>
          </div>
        }
      </ion-card-content>
    </ion-card>
  }
</ion-content>

Gerenciamento de clientes (conta admin). Este formulário não realiza nenhuma validação no celular: tudo é enviado ao servidor, que responde, em caso de rejeição, com um JSON de erro, convertido em [ApiError] pelo serviço [Api].

  • Linhas 34–36 (.ts): a página reutiliza três ferramentas dos exemplos anteriores, importando-as de suas respectivas pastas: a confirmação do exemplo 16, as traduções do exemplo 21 e o comando do exemplo 23 (o cliente [Flutter]fazia o mesmo). A classe [Translations] do exemplo 21 foi escrita para isso: ela não é um serviço singleton, mas uma classe configurada pelo prefixo de seus dicionários. A linha 54 cria uma instância dela para esta página, com os dicionários [ex25-fr.json] e [ex25-en.json]. Por que não movê-la para [common/]? Ela caberia ali em uma aplicação; neste curso, cada exemplo é lido em ordem, e o exemplo 21 continua sendo o que a apresenta;
  • linha 63 (.ts): a função de confirmação do exemplo 16 ([AlertController]);
  • linha 66 (.ts): um título “Dr”, que o servidor rejeitará: veja [ERRORS.INVALID_TITLE];
  • linhas 73–79 (.ts): um formulário reativo (exemplo 08), SEM nenhuma regra de validação;
  • linhas 81–82 (.ts): o cliente em edição ([null]: uma nova criação) e a versão obtida junto com seu registro;
  • linhas 85–88 (.ts): a mensagem geral do último erro, a mensagem de sucesso (uma chave e seus parâmetros, traduzidos para exibição: eles acompanham uma mudança de idioma) e o envio, um [Command] (exemplo 23);
  • linhas 110–113 (.ts): a mensagem de erro de um campo. O erro é armazenado na lógica de validação do campo com o nome [server] (veja abaixo); seu valor é a chave enviada pelo servidor, que é traduzida;
  • linhas 120–126 (.ts): um novo cliente: [form.reset()] restaura os valores padrão (o formulário é “não anulável”, exemplo 08) e apaga todos os erros;
  • linhas 128–135 (.ts): editar um cliente: o formulário recebe o registro do cliente. A versão lida do registro é atualizada com a alteração: se alguém tiver modificado o registro nesse meio-tempo, o servidor responderá com um 409 [CONCURRENT_UPDATE] (o bloqueio otimista);
  • linhas 142–170 (.ts): salvar: [POST /api/clients] (criar) ou [PUT /api/clients/:id] (atualizar), com os valores do formulário e a versão (linha 144). Em caso de sucesso, o formulário é limpo e uma mensagem de sucesso é exibida (linhas 151–156). Em caso de rejeição, o [ApiError] exibe a mensagem geral (linha 160) e o erro de cada campo (linhas 164–168):
  • [control.setErrors({ server: key })] devolve um erro na validação do campo: o campo se torna inválido (classe [ng-invalid]);
  • [control.markAsTouched()] o marca como “tocado” (classe [ng-touched]), como se o usuário tivesse saído dele;
  • [Ionic] copies these two classes—[ion-invalid] and [ion-touched]—to the field (example 07): it then displays, below the field, the text from its [errorText], and highlights it in red;
  • e editar o campo apaga o erro sem uma única linha de código: a cada tecla pressionada, o [Angular] valida novamente o campo com suas regras… e ele não tem nenhuma. O erro definido manualmente desaparece. No cliente [Flutter], era preciso escrever um [onChanged] para cada campo;
  • linhas 172–183 (.ts): exclusão, após confirmação (a mensagem de confirmação é traduzida, com o nome do cliente como parâmetro);
  • linhas 11–25 (html): idioma: um botão na barra superior que abre um [<ion-popover>] (uma janela pop-up associada ao botão, cujo [id] é indicado por [trigger]); [dismissOnSelect] a fecha na primeira seleção. Era o [PopupMenuButton] do [Flutter];
  • linhas 32–36 (html): um usuário conectado que não é ADMIN: um aviso;
  • linhas 38–56 (html): a lista de clientes, com seus botões “Editar” e “Excluir”;
  • linhas 64–81 (HTML): o formulário. Cada campo é vinculado ao seu controle ([formControlName]); seus rótulos são traduzidos; [[errorText]] recebe o erro do servidor, traduzido (linhas 67–68: [<ion-select>] também tem um [errorText]). O formulário não tem um [(ngSubmit)]: o botão “Salvar” chama o comando (linhas 83–85);
  • linhas 90–99 (HTML): a mensagem de sucesso e a mensagem geral de erro, traduzidas; para maior clareza, o status HTTP e a chave são exibidos em letras pequenas.

Um formulário vazio; um homônimo (“Alice DURAND”); o mesmo, em francês:

Trocar o idioma traduz novamente toda a tela, inclusive os erros já exibidos: a tela armazena as chaves enviadas pelo servidor—e não o texto—e as traduz toda vez que é exibida. Experimente também: um título “Dr”, um nome de usuário já em uso ([martin]), um nome de usuário inválido (“Jean M”) ou o mesmo registro editado em dois dispositivos (ou em duas abas do navegador, ou no aplicativo e com [curl]).

O princípio é o mesmo de todos os formulários do estudo de caso: as regras residem em um ÚNICO lugar—o servidor; o aplicativo exibe suas respostas no idioma do usuário. Naturalmente, nada impede que você também valide os campos no celular (exemplo 08) para responder mais rapidamente ao usuário; no entanto, o servidor deve validar tudo de novo, e seu veredito é final.

Comparando os dois clientes, vemos o quanto o [Ionic] se apoia no navegador: o cliente HTTP devolve diretamente objetos [JavaScript] (o JSON é a linguagem nativa do [JavaScript]), o cookie do token circula sem uma única linha de código e uma requisição pode ser cancelada. Em contrapartida, o [TypeScript] não valida o formato das respostas em tempo de execução, o que a filtragem do [Dart] fazia naturalmente. O cliente [Angular] do [RdvMedecins] (curso [Angular]) é escrito exatamente como estes exemplos: o mesmo [HttpClient], os mesmos serviços, os mesmos formulários reativos; apenas os componentes de exibição mudam, com os do [Ionic] imitando os de um celular [Android].