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]):
| {
"/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()].
9.2. Exemplo 23: Login, cookie e sessão
9.2.1. E o cookie?
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].