Os exemplos deste capítulo consultam o servidor JSON [RdvMedecins]: ele deve estar em execução ([npm run start:dev] na pasta [rdvmedecins-nestjs-json]) na porta 8080, ao mesmo tempo que o servidor [Vite] usado nos exemplos, na porta 5173.
8.1. Exemplo 17: Uma primeira requisição HTTP
8.1.1. O proxy do Vite
A página de exemplo vem de http://localhost:5173 (o servidor [Vite]); a API está em http://localhost:8080. Para um navegador, são duas origens diferentes (a porta faz parte da origem). Ora, por motivos de segurança, um navegador não permite que uma página leia respostas de outra origem, a menos que o servidor a autorize explicitamente (o mecanismo conhecido como CORS). E o [fetch] não envia cookies (e, portanto, nem o token) a outra origem, a menos que isso seja solicitado ([credentials: 'include']) E o servidor o aceite, novamente via CORS.
Em vez de abrir o servidor para outras origens, encaminhamos as requisições para a API por meio do servidor Vite. Esse é o proxy declarado em [vite.config.ts]:
| server: {
port: 5173,
proxy: {
'/api': 'http://localhost:8080',
},
},
|
O navegador envia [GET http://localhost:5173/api/captcha]; o [Vite] encaminha a requisição para [http://localhost:8080/api/captcha]e depois devolve a resposta ao navegador. Do ponto de vista do navegador, a página e a API têm a mesma origem:

Em produção, não haverá mais um [Vite]: o próprio servidor JSON servirá os arquivos compilados do cliente (veja o capítulo “Implantação”). A página e a API continuarão compartilhando a mesma origem.
8.1.2. A requisição
| <!--
=========================================================================
17-fetch/src/App.vue - a first HTTP request to the server
-------------------------------------------------------------------------
The RdvMedecins JSON server must be running (port 8080). We ask it for
a captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
- fetch(url): the browser function that sends an HTTP request.
It returns a PROMISE: we wait for the response with await;
- response.ok: true for a 2xx code; response.json() reads the JSON
body (another promise);
- the address is RELATIVE (/api/captcha): the request goes to the
server of the page, Vite (port 5173), which forwards it to the JSON server
(port 8080) thanks to its proxy (see vite.config.ts);
- three states to display: in progress, succeeded, failed.
=========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';
// o que GET /api/captcha retorna
interface Captcha {
id: string;
svg: string;
}
const captcha = ref<Captcha | null>(null);
const loading = ref(false);
const error = ref<string | null>(null);
const requestCount = ref(0);
async function load(): Promise<void> {
loading.value = true;
error.value = null;
try {
const response = await fetch('/api/captcha');
requestCount.value++;
if (!response.ok) {
// o servidor respondeu, mas com um erro (4xx, 5xx) - ou é o
// Vite que responde 502/504 porque o servidor JSON está parado
throw new Error(`the server responded ${response.status} ${response.statusText}`);
}
captcha.value = (await response.json()) as Captcha;
} catch (e) {
// o próprio fetch falha quando nenhuma resposta chega (rede fora do ar...)
error.value = e instanceof Error ? e.message : String(e);
captcha.value = null;
} finally {
loading.value = false;
}
}
// na primeira exibição, um captcha é carregado
onMounted(load);
</script>
<template>
<div class="container py-4" style="max-width: 640px">
<h1 class="h3 mb-3">Example 17 - a first HTTP request</h1>
<div class="card p-3">
<p v-if="loading" class="text-muted">Loading...</p>
<div v-else-if="error" class="alert alert-danger mb-3">
Unable to get a captcha: {{ error }}.<br>
Is the RdvMedecins JSON server running (port 8080)?
</div>
<template v-else-if="captcha">
<!-- v-html: inserts a string as HTML (here, the SVG image).
To be used ONLY for safe content: this SVG is built by
OUR server. With user input, v-html would open
the door to script injection ({{ }}, for its part, escapes everything). -->
<div class="captcha mb-2" v-html="captcha.svg"></div>
<p class="small text-muted">id: <code>{{ captcha.id }}</code></p>
</template>
<button class="btn btn-primary align-self-start" :disabled="loading" @click="load">Another image</button>
<p class="small text-muted mt-2 mb-0">{{ requestCount }} successful request(s) - open the Network tab of the developer tools (F12).</p>
</div>
</div>
</template>
<style scoped>
/* :deep(svg): a regra alcança o <svg> inserido por v-html, que o "scoped" ignoraria */
.captcha :deep(svg) {
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
</style>
|
- linha 22: o formato da resposta de [GET /api/captcha];
- linhas 27–29: os três estados de uma requisição: em andamento, bem-sucedida (o CAPTCHA) e com erro;
- linha 36: [fetch(url)], a função do navegador que envia uma requisição HTTP. Ela devolve uma promise; o [await] suspende a função [async] até que a promise seja resolvida, sem bloquear a página. O endereço é relativo: a requisição é enviada ao servidor da página, o [Vite], que a encaminha;
- linha 38: o [fetch] NÃO relata um erro quando o servidor devolve uma resposta 404 ou 500: ele recebeu uma resposta. Cabe a nós testar [response.ok] (true para um código 2xx). Se o servidor JSON estiver fora do ar, o [Vite] responde com um erro 5xx;
- linha 43: [response.json()] lê o corpo e o converte em um objeto (mais uma promise). [as Captcha] informa ao [TypeScript] o formato do objeto: o compilador não pode verificar o que o servidor enviará;
- linha 44: o [fetch] em si falha quando nenhuma resposta é recebida (rede fora do ar);
- linha 48: em qualquer caso, a requisição não está mais em andamento;
- linha 54: na primeira exibição, um CAPTCHA é carregado;
- linha 71: [v-html] insere uma string como HTML (aqui, a imagem SVG). Use SOMENTE com conteúdo seguro: este SVG é gerado pelo NOSSO servidor. Com dados digitados pelo usuário, o [v-html] poderia permitir a injeção de scripts na página; já as chaves duplas [{{ }}] escapam tudo;
- linha 82: [:deep(...)]: uma regra [scoped] normalmente afeta apenas os elementos do template; o [<svg>] inserido por [v-html] não faz parte dele.

Nas ferramentas de desenvolvedor do navegador (F12), a aba Network mostra a requisição [captcha], enviada para [localhost:5173], e sua resposta JSON.
8.2. Exemplo 18: Login, cookie e sessão
| <!--
=========================================================================
18-login/src/App.vue - logging in to the RdvMedecins server
-------------------------------------------------------------------------
1. at startup: GET /api/auth/me - are we already logged in?
(after an F5, the client has forgotten everything; the server reads the cookie);
2. login: POST /api/auth/login, JSON body { login, password,
captchaId, captcha }. On success, the server sets the httpOnly
cookie of the JWT token: our code NEVER sees it (try
document.cookie in the console: it is not there);
3. protected request: GET /api/doctors. The browser attaches the cookie
by itself (same origin);
4. logout: POST /api/auth/logout - the server deletes the cookie.
A cookie belongs to a machine (localhost) and to a path (/api): it
is therefore shared by ALL the examples. Once logged in here, examples 19 and 20
are logged in too.
=========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
interface User {
login: string;
name: string;
role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
id: number;
title: string;
firstName: string;
lastName: string;
}
// a forma de TODOS os erros da API
interface ApiError {
statusCode: number;
key: string;
params?: Record<string, string>;
}
// as poucas mensagens de que este exemplo precisa (o exemplo 20 usará vue-i18n)
const MESSAGES: Record<string, string> = {
'LOGIN.ERROR': 'Incorrect login or password.',
'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};
const user = ref<User | null>(null);
const doctors = ref<Doctor[]>([]);
const captcha = ref<{ id: string; svg: string } | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);
const ready = ref(false); // a verificação inicial terminou?
async function loadCaptcha(): Promise<void> {
captcha.value = await (await fetch('/api/captcha')).json();
input.captcha = '';
}
// 1. quem está logado? 200 -> o usuário; 401 -> ninguém
async function checkSession(): Promise<void> {
const response = await fetch('/api/auth/me');
if (response.ok) {
user.value = await response.json();
await loadDoctors();
} else {
await loadCaptcha();
}
ready.value = true;
}
// 2. fazer login
async function logIn(): Promise<void> {
error.value = null;
const response = await fetch('/api/auth/login', {
method: 'POST',
// o servidor rejeita (415) um POST que não seja em JSON
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
login: input.login,
password: input.password,
captchaId: captcha.value?.id,
captcha: input.captcha,
}),
});
if (response.ok) {
user.value = await response.json();
input.password = '';
await loadDoctors();
return;
}
// um erro: o corpo JSON diz qual; cada imagem só pode ser usada uma vez
const e = (await response.json()) as ApiError;
error.value = `${response.status} - ${MESSAGES[e.key] ?? e.key}`;
await loadCaptcha();
}
// 3. uma requisição protegida
async function loadDoctors(): Promise<void> {
const response = await fetch('/api/doctors');
doctors.value = response.ok ? await response.json() : [];
}
// 4. fazer logout
async function logOut(): Promise<void> {
await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
user.value = null;
doctors.value = [];
await loadCaptcha();
}
onMounted(() => {
checkSession().catch(() => {
error.value = 'Is the RdvMedecins JSON server running (port 8080)?';
ready.value = true;
});
});
</script>
<template>
<div class="container py-4" style="max-width: 640px">
<h1 class="h3 mb-3">Example 18 - logging in to the server</h1>
<p v-if="!ready" class="text-muted">Checking the session...</p>
<!-- logado -->
<div v-else-if="user" class="card p-3">
<p>Logged in: <strong>{{ user.name }}</strong> ({{ user.login }}),
role <span class="badge text-bg-primary">{{ user.role }}</span></p>
<h2 class="h6">GET /api/doctors</h2>
<ul>
<li v-for="m in doctors" :key="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</li>
</ul>
<p class="small text-muted">Reload the page (F5): you stay logged in.</p>
<button class="btn btn-outline-secondary align-self-start" @click="logOut">Log out</button>
</div>
<!-- não logado: o formulário -->
<form v-else class="card p-3" @submit.prevent="logIn">
<div class="mb-2">
<label class="form-label" for="login">Login</label>
<input id="login" v-model="input.login" class="form-control" autocomplete="username">
</div>
<div class="mb-2">
<label class="form-label" for="password">Password</label>
<input id="password" v-model="input.password" type="password" class="form-control" autocomplete="current-password">
</div>
<div class="mb-3">
<label class="form-label" for="captcha">Type the characters shown in the image</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div v-if="captcha" v-html="captcha.svg"></div>
<a href="#" class="small" @click.prevent="loadCaptcha">Another image</a>
</div>
<input id="captcha" v-model="input.captcha" class="form-control" autocomplete="off">
</div>
<button class="btn btn-primary">Log in</button>
<p class="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
</form>
<div v-if="error" class="alert alert-danger mt-3">{{ error }}</div>
</div>
</template>
|
- linha 35: o formato de todos os erros da API;
- linha 42: as poucas mensagens necessárias a este exemplo, em inglês; o Exemplo 20 usará o [vue-i18n];
- linhas 61–69: na inicialização, [GET /api/auth/me]: já estamos logados? Depois de recarregar a página (F5), a aplicação [Vue.js] esqueceu tudo; o servidor, porém, lê o cookie. 200: o usuário; 401: ninguém;
- linhas 73–96: a conexão:
- linha 76: [fetch(url, options)]: o método, os cabeçalhos e o corpo;
- linha 78: o servidor rejeita um POST que não esteja em formato JSON;
- linha 79: o corpo, convertido em texto JSON;
- linha 87: se der certo, o servidor definiu o cookie do token. Nosso código NUNCA o vê: digite [document.cookie] no console do navegador; ele não aparece ([HttpOnly]);
- linha 93: se a requisição falhar, o corpo explica o motivo. Exibimos a mensagem e solicitamos uma nova imagem: cada imagem é usada uma única vez;
- linhas 99–102: uma requisição protegida. Não precisamos fazer nada para nos autenticar: o navegador inclui o cookie automaticamente, pois a requisição vai para a mesma origem da página (por padrão, o [fetch] envia cookies em requisições de mesma origem);
- linhas 105–110: logout — o servidor apaga o cookie. O corpo ['{}'] é incluído para que a requisição seja um POST JSON.
O formulário de login:

Com um CAPTCHA digitado incorretamente (o servidor está em modo de teste: qualquer CAPTCHA aceita a resposta [test]):

Logado:

Recarregue a página (F5): você continua logado. Em seguida, abra o Exemplo 19: você também está logado lá. Um cookie pertence a uma máquina (aqui, [localhost]) e a um caminho (aqui, [/api]), que são comuns a todos os exemplos.
8.3. Exemplo 19: Uma camada de acesso à API
O Exemplo 18 repetia as mesmas etapas a cada chamada ao [fetch]: o prefixo [/api], o cabeçalho [Content-Type], o [JSON.stringify], o teste de [response.ok] e a leitura do corpo do erro. Agrupamos tudo em uma única função, na pasta [common] (compartilhada pelos exemplos 19 e 20):
| // =========================================================================
// common/api.ts - UMA função para todas as requisições à API
// -------------------------------------------------------------------------
// No exemplo 18, cada chamada a fetch repetia os mesmos gestos:
// prefixo /api, cabeçalho Content-Type, JSON.stringify, teste de response.ok,
// leitura do corpo do erro... Eles são agrupados aqui, de uma vez por todas:
//
// const doctors = await api.get<Person[]>('/doctors');
// await api.post('/appointments', { day, slotId, clientId });
//
// - em caso de sucesso, a promise retorna o corpo JSON, TIPADO;
// - em caso de falha, ela é REJEITADA com um ApiError, que carrega a
// chave de tradução enviada pelo servidor (e, se houver, seus
// parâmetros e o erro de cada campo).
// Usado pelos exemplos 19 e 20; o estudo de caso retoma seu princípio.
// =========================================================================
export class ApiError extends Error {
constructor(
public readonly statusCode: number, // 0: o servidor não respondeu
public readonly key: string, // p. ex.: 'ERRORS.LOGIN_TAKEN'
public readonly params: Record<string, string> = {},
public readonly fields: Record<string, string> = {},
) {
super(key);
this.name = 'ApiError';
}
}
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
export async function request<T>(method: Method, url: string, body?: unknown): Promise<T> {
let response: Response;
try {
response = await fetch(`/api${url}`, {
method,
// um corpo -> JSON (o servidor rejeita um POST que não seja)
headers: body !== undefined ? { 'Content-Type': 'application/json' } : {},
body: body !== undefined ? JSON.stringify(body) : undefined,
});
} catch {
// sem resposta (rede fora do ar...)
throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
}
// o corpo é lido como texto e depois convertido: uma resposta vazia, ou uma
// que não seja JSON (servidor JSON parado: é o Vite que responde),
// não deve derrubar a aplicação
const text = await response.text();
let data: unknown = null;
try {
data = text ? JSON.parse(text) : null;
} catch {
data = null;
}
if (!response.ok) {
const e = (data ?? {}) as { key?: string; params?: Record<string, string>; fields?: Record<string, string> };
throw new ApiError(response.status, e.key ?? 'ERRORS.SERVER_UNREACHABLE', e.params, e.fields);
}
return data as T;
}
// atalhos, mais legíveis no uso
export const api = {
get: <T>(url: string) => request<T>('GET', url),
post: <T>(url: string, body: unknown = {}) => request<T>('POST', url, body),
put: <T>(url: string, body: unknown) => request<T>('PUT', url, body),
delete: <T>(url: string, body?: unknown) => request<T>('DELETE', url, body),
};
|
- linhas 18–27: uma classe de erro que contém a resposta do servidor: o código HTTP, a chave da mensagem, seus parâmetros e o erro de cada campo. O código 0 significa “nenhuma resposta”;
- linha 32: uma função genérica: [T] é o tipo do corpo esperado em caso de sucesso. [request<Person[]>('GET', '/doctors')] devolve uma [Promise<Person[]>];
- linha 38: um corpo, e somente nesse caso, acompanhado do cabeçalho JSON;
- linhas 49–55: o corpo é lido como texto e depois convertido. Uma resposta vazia, ou que não seja JSON (servidor fora do ar: o [Vite] responde com texto), não deve fazer a aplicação travar;
- linhas 57–60: uma falha resulta em um [ApiError]: a promise devolvida por [request] é rejeitada. O código chamador a captura por meio de [try / catch];
- linhas 65–70: atalhos, mais legíveis: [api.get<T>(url)], [api.post<T>(url, body)]... O [api.post] envia o corpo [{}] por padrão.
Os tipos dos objetos JSON da API, descritos no capítulo anterior:
| // =========================================================================
// common/types.ts - os objetos JSON trocados com a API do RdvMedecins
// (veja o capítulo sobre a caixa-preta, que descreve cada rota)
// =========================================================================
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
// POST /api/auth/login, GET /api/auth/me
export interface User {
login: string;
name: string;
role: Role;
}
// GET /api/captcha
export interface Captcha {
id: string;
svg: string;
}
// um médico ou um paciente (GET /api/doctors, GET /api/clients...)
export interface Person {
id: number;
version: number;
title: string;
firstName: string;
lastName: string;
login?: string; // somente para o ADMIN
}
export interface Identity {
title: string;
firstName: string;
lastName: string;
}
// uma linha de GET /api/schedule
export interface ScheduleSlot {
id: number;
startHour: number;
startMinute: number;
endHour: number;
endMinute: number;
free: boolean;
patient: Identity | null;
mine: boolean;
bookable: boolean;
appointmentId: number | null;
}
// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
doctor: Person;
day: string;
slots: ScheduleSlot[];
info: string | null;
}
|
Um componente de conexão, reescrito com [api.ts] e reduzido a uma barra:
| <!--
=========================================================================
common/LoginBar.vue - logging in / out, in one bar
-------------------------------------------------------------------------
The component of example 18, reduced to a bar and rewritten with
common/api.ts. It emits 'change' with the logged-in user (or null)
each time the user changes - including at startup, after having
queried GET /api/auth/me.
=========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
import { api, ApiError } from './api';
import type { Captcha, User } from './types';
const emit = defineEmits<{ change: [user: User | null] }>();
const user = ref<User | null>(null);
const captcha = ref<Captcha | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);
async function newCaptcha(): Promise<void> {
captcha.value = await api.get<Captcha>('/captcha');
input.captcha = '';
}
function setUser(u: User | null): void {
user.value = u;
emit('change', u);
}
onMounted(async () => {
try {
setUser(await api.get<User>('/auth/me'));
} catch {
setUser(null); // 401: ninguém está logado
await newCaptcha().catch(() => (error.value = 'Is the JSON server running (port 8080)?'));
}
});
async function logIn(): Promise<void> {
error.value = null;
try {
const u = await api.post<User>('/auth/login', {
login: input.login,
password: input.password,
captchaId: captcha.value?.id,
captcha: input.captcha,
});
input.password = '';
setUser(u);
} catch (e) {
error.value = e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e);
await newCaptcha();
}
}
async function logOut(): Promise<void> {
await api.post('/auth/logout');
setUser(null);
await newCaptcha();
}
</script>
<template>
<div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
<template v-if="user">
<span>Logged in: <strong>{{ user.name }}</strong> <span class="badge text-bg-primary">{{ user.role }}</span></span>
<button class="btn btn-sm btn-outline-secondary ms-auto" @click="logOut">Log out</button>
</template>
<form v-else class="d-flex flex-wrap align-items-center gap-2 w-100" @submit.prevent="logIn">
<input v-model="input.login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username">
<input v-model="input.password" type="password" class="form-control form-control-sm w-auto" placeholder="password" autocomplete="current-password">
<div v-if="captcha" class="captcha" v-html="captcha.svg"></div>
<input v-model="input.captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8">
<button class="btn btn-sm btn-primary">Log in</button>
<span v-if="error" class="text-danger small">{{ error }}</span>
</form>
</div>
</template>
<style scoped>
/* a imagem do captcha, reduzida para caber na barra */
.captcha :deep(svg) {
display: block;
height: 32px;
width: auto;
}
</style>
|
- linha 16: o componente emite [change] com o usuário logado (ou [null]) a cada mudança, inclusive na inicialização;
- linha 35: com o [api.ts], uma requisição cabe em uma linha; em caso de falha (401), o fluxo passa para o [catch];
- linha 54: o [instanceof] distingue um erro da API de outra anomalia.
Acima do [api.ts], uma função por rota da API:
| // =========================================================================
// 19-api-service/src/rdvmedecins.service.ts - a camada de acesso à API
// -------------------------------------------------------------------------
// Uma função tipada por rota da API. Os componentes não conhecem nem
// as URLs, nem o fetch, nem o formato JSON: eles chamam funções.
// É o equivalente, no cliente, da camada DAO no servidor: se a API
// mudar (uma URL, um nome de campo), apenas este arquivo é modificado.
// =========================================================================
import { api } from '../../common/api';
import type { Schedule, Person } from '../../common/types';
export const rdvmedecins = {
getDoctors: () => api.get<Person[]>('/doctors'),
getClients: () => api.get<Person[]>('/clients'),
// URLSearchParams constrói "?doctorId=1&day=2030-01-15", codificando o que for necessário
getSchedule: (doctorId: number, day: string) =>
api.get<Schedule>(`/schedule?${new URLSearchParams({ doctorId: String(doctorId), day })}`),
book: (day: string, slotId: number, clientId?: number) =>
api.post<{ id: number }>('/appointments', { day, slotId, clientId }),
cancelAppointment: (appointmentId: number) => api.delete<Record<string, never>>(`/appointments/${appointmentId}`),
};
|
Este é o equivalente, no lado do cliente, da camada DAO do servidor: os componentes não conhecem a URL, o [fetch] nem o formato JSON; eles chamam funções tipadas. Se a API mudar, apenas este arquivo muda.
- linha 18: [URLSearchParams] gera a string [doctorId=1&day=2030-01-15] codificando os caracteres que precisam ser codificados.
A página:
| <!--
=========================================================================
19-api-service/src/App.vue - a schedule, with the API access layer
-------------------------------------------------------------------------
Log in (top bar), choose a doctor and a day: the schedule
is displayed. ADMIN and DOCTOR can book for a patient and cancel;
a patient (martin...) books for themselves. Each action ends with
a reload of the schedule: it is the SERVER that is authoritative.
=========================================================================
-->
<script setup lang="ts">
import { computed, ref, watch } from 'vue';
import LoginBar from '../../common/LoginBar.vue';
import { ApiError } from '../../common/api';
import type { Schedule, ScheduleSlot, Person, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins.service';
const user = ref<User | null>(null);
const doctors = ref<Person[]>([]);
const clients = ref<Person[]>([]);
const doctorId = ref<number | null>(null);
const day = ref(tomorrow());
const schedule = ref<Schedule | null>(null);
const clientId = ref<number | null>(null);
const message = ref<{ type: 'success' | 'danger'; text: string } | null>(null);
const isManager = computed(() => user.value !== null && user.value.role !== 'USER');
function tomorrow(): string {
const d = new Date(Date.now() + 24 * 3600 * 1000);
return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}
function timeRange(c: ScheduleSlot): string {
const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}
// um erro de API vira uma mensagem (sua chave, por falta de dicionário aqui)
function report(e: unknown): void {
message.value = { type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) };
}
// login / logout: (re)carregamos o que este papel pode ver
async function onUserChange(u: User | null): Promise<void> {
user.value = u;
schedule.value = null;
doctors.value = [];
clients.value = [];
if (u === null) {
return;
}
try {
doctors.value = await rdvmedecins.getDoctors();
// a lista de pacientes: somente para ADMIN e DOCTOR (um USER receberia 403)
clients.value = isManager.value ? await rdvmedecins.getClients() : [];
} catch (e) {
report(e);
}
}
async function loadSchedule(): Promise<void> {
if (doctorId.value === null) {
return;
}
try {
schedule.value = await rdvmedecins.getSchedule(doctorId.value, day.value);
} catch (e) {
schedule.value = null;
report(e);
}
}
// a agenda acompanha a escolha do médico e do dia
watch([doctorId, day], () => {
message.value = null;
loadSchedule();
});
async function book(c: ScheduleSlot): Promise<void> {
try {
await rdvmedecins.book(day.value, c.id, isManager.value ? (clientId.value ?? undefined) : undefined);
message.value = { type: 'success', text: `Slot ${timeRange(c)} booked.` };
} catch (e) {
report(e);
}
await loadSchedule();
}
async function cancel(c: ScheduleSlot): Promise<void> {
try {
await rdvmedecins.cancelAppointment(c.appointmentId as number);
message.value = { type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` };
} catch (e) {
report(e);
}
await loadSchedule();
}
</script>
<template>
<div class="container py-4">
<h1 class="h3 mb-3">Example 19 - an API access layer</h1>
<LoginBar @change="onUserChange" />
<template v-if="user">
<div class="row g-2 mb-3">
<div class="col-sm-5">
<select v-model="doctorId" class="form-select">
<option :value="null" disabled>-- choose a doctor --</option>
<option v-for="m in doctors" :key="m.id" :value="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
</select>
</div>
<div class="col-sm-3"><input v-model="day" type="date" class="form-control"></div>
<div v-if="isManager" class="col-sm-4">
<select v-model="clientId" class="form-select">
<option :value="null">-- patient to book for --</option>
<option v-for="c in clients" :key="c.id" :value="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
</select>
</div>
</div>
<div v-if="message" class="alert" :class="`alert-${message.type}`">{{ message.text }}</div>
<!-- info: a chave enviada pelo servidor quando um paciente já tem uma consulta futura -->
<div v-if="schedule?.info" class="alert alert-info">{{ schedule.info }}</div>
<table v-if="schedule" class="table table-sm align-middle">
<caption class="caption-top">Schedule of {{ schedule.day }} - {{ schedule.doctor.title }} {{ schedule.doctor.firstName }} {{ schedule.doctor.lastName }}</caption>
<tbody>
<tr v-for="c in schedule.slots" :key="c.id">
<td>{{ timeRange(c) }}</td>
<td>
<span v-if="c.free" class="badge text-bg-success">Free</span>
<span v-else-if="c.patient" class="badge" :class="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">
{{ c.patient.title }} {{ c.patient.firstName }} {{ c.patient.lastName }}
</span>
<span v-else class="badge text-bg-secondary">Booked</span>
</td>
<td class="text-end">
<!-- os botões acompanham os direitos calculados pelo servidor -->
<button v-if="c.bookable" class="btn btn-sm btn-outline-success" @click="book(c)">Book</button>
<button v-if="c.appointmentId !== null" class="btn btn-sm btn-outline-danger" @click="cancel(c)">Cancel</button>
</td>
</tr>
</tbody>
</table>
</template>
</div>
</template>
|
- linha 27: ADMIN ou DOCTOR;
- linhas 45–60: sempre que um usuário faz login ou logout, o conteúdo que esse papel está autorizado a ver é (re)carregado. Um paciente receberia um erro 403 ao pedir a lista de clientes: nem sequer a solicitamos;
- linha 75: o [watch] pode monitorar várias fontes: o calendário é recarregado quando o médico OU o dia muda;
- linhas 80–87: uma reserva, seguida, QUALQUER QUE SEJA O RESULTADO, de uma atualização do calendário. O registro do servidor é definitivo: se o horário tiver sido ocupado por outra pessoa nesse meio-tempo, o calendário atualizado mostrará isso;
- linhas 141 e 142: os botões refletem as permissões calculadas pelo servidor;
- linha 137: um horário reservado para o qual o servidor não atribuiu um paciente (visto por um paciente).
Logado como [admin], selecione um médico, um paciente e reserve um horário:

Reserve um segundo horário para o mesmo paciente: o servidor recusa. Como não há dicionário neste exemplo, a chave bruta é exibida:

8.4. Exemplo 20: Erros devolvidos pelo servidor
Último exemplo antes do estudo de caso: o gerenciamento de clientes, feito pelo formulário do ADMIN. Este formulário não faz nenhuma validação no navegador: tudo é enviado ao servidor, que valida os dados e, em caso de rejeição, responde com o erro de cada campo. O Exemplo 06 mostrou a abordagem alternativa; esta tem uma vantagem significativa: as regras existem em apenas UM lugar — o servidor — e o cliente não pode deixar de segui-las. A contrapartida: uma ida e volta ao servidor antes de exibir os erros.
Os dicionários usam os códigos de erro do servidor:
| {
"FORM": {
"TITLE_ADD": "Ajouter un client",
"TITLE_EDIT": "Modifier un client",
"TITLE": "Titre",
"FIRSTNAME": "Prénom",
"LASTNAME": "Nom",
"LOGIN": "Login",
"PASSWORD": "Mot de passe",
"SAVE": "Enregistrer",
"CANCEL": "Annuler",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"DELETE_CONFIRM": "Supprimer le client {name}, son compte et ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé.",
"ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients."
},
"ERRORS": {
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
"FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
"AUTH_REQUIRED": "Connectez-vous d'abord.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"SERVER_UNREACHABLE": "Le serveur ne répond pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite."
}
}
|
([locales/en.json] tem os mesmos códigos, em inglês.)
| import { createApp } from 'vue';
import { createI18n } from 'vue-i18n';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App.vue';
import fr from './locales/fr.json';
import en from './locales/en.json';
// mesma configuração do exemplo 16, em forma mais curta
const i18n = createI18n({ legacy: false, locale: 'en', fallbackLocale: 'en', messages: { fr, en } });
createApp(App).use(i18n).mount('#app');
|
A página:
| <!--
=========================================================================
20-server-errors/src/App.vue - displaying the errors of the SERVER
-------------------------------------------------------------------------
The management of the clients (admin account). This form DELIBERATELY
does no validation in the browser: everything is sent to the
server, which answers, in case of refusal, with a JSON error:
400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' } (optimistic lock)
The client translates each key (vue-i18n) and places each message under its
field, the general message at the bottom of the form. Try: an empty last name, a
title modified in the developer tools, a namesake (Alice DURAND),
a login already taken (martin), the same record modified in two tabs...
=========================================================================
-->
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';
import { useI18n } from 'vue-i18n';
import LoginBar from '../../common/LoginBar.vue';
import { api, ApiError } from '../../common/api';
import type { Person, User } from '../../common/types';
// o diálogo de confirmação do exemplo 12, reutilizado tal como está
import ConfirmDialog from '../../12-confirmation/src/components/ConfirmDialog.vue';
import { useConfirmation } from '../../12-confirmation/src/composables/useConfirmation';
const { t, locale } = useI18n();
const { confirm } = useConfirmation();
const user = ref<User | null>(null);
const clients = ref<Person[]>([]);
const isAdmin = computed(() => user.value?.role === 'ADMIN');
// o formulário: editedId === null -> criação, caso contrário atualização
const editedId = ref<number | null>(null);
const input = reactive({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
// os erros retornados pelo servidor
const fieldErrors = ref<Record<string, string>>({});
const pageError = ref<ApiError | null>(null);
const success = ref<string | null>(null);
async function onUserChange(u: User | null): Promise<void> {
user.value = u;
clients.value = [];
if (u?.role === 'ADMIN') {
await reload();
}
}
async function reload(): Promise<void> {
clients.value = await api.get<Person[]>('/clients');
}
function newForm(): void {
editedId.value = null;
Object.assign(input, { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
clearErrors();
}
function edit(c: Person): void {
editedId.value = c.id;
// a VERSÃO lida junto com o registro volta com a atualização: se alguém
// modificou o registro nesse meio tempo, o servidor responderá 409 CONCURRENT_UPDATE
Object.assign(input, { title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
clearErrors();
}
function clearErrors(): void {
fieldErrors.value = {};
pageError.value = null;
success.value = null;
}
// o texto de um erro, no idioma atual, com seus parâmetros
function errorText(e: ApiError): string {
return t(e.key, e.params);
}
async function save(): Promise<void> {
clearErrors();
const body = { ...input };
try {
const client =
editedId.value === null
? await api.post<Person>('/clients', body)
: await api.put<Person>(`/clients/${editedId.value}`, body);
const message = t(editedId.value === null ? 'FORM.ADDED' : 'FORM.UPDATED', {
name: `${client.firstName} ${client.lastName}`,
login: client.login ?? '',
});
newForm(); // formulário esvaziado, mensagens apagadas...
success.value = message; // ... exceto esta
await reload();
} catch (e) {
if (!(e instanceof ApiError)) {
throw e;
}
// o erro de cada campo e a mensagem geral
fieldErrors.value = e.fields;
pageError.value = e;
}
}
async function remove(c: Person): Promise<void> {
const name = `${c.firstName} ${c.lastName}`;
if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
return;
}
clearErrors();
try {
await api.delete(`/clients/${c.id}`);
success.value = t('FORM.DELETED', { name });
} catch (e) {
pageError.value = e instanceof ApiError ? e : null;
}
await reload();
}
</script>
<template>
<div class="container py-4">
<div class="d-flex justify-content-between align-items-center mb-3">
<h1 class="h3 mb-0">Example 20 - the errors returned by the server</h1>
<select v-model="locale" class="form-select form-select-sm w-auto">
<option value="fr">FR</option>
<option value="en">EN</option>
</select>
</div>
<LoginBar @change="onUserChange" />
<p v-if="user && !isAdmin" class="alert alert-warning">{{ t('FORM.ADMIN_ONLY') }}</p>
<div v-if="isAdmin" class="row g-4">
<div class="col-lg-6">
<table class="table table-sm align-middle">
<tbody>
<tr v-for="c in clients" :key="c.id">
<td>{{ c.title }} {{ c.firstName }} {{ c.lastName }}</td>
<td><code>{{ c.login }}</code></td>
<td class="text-end text-nowrap">
<button class="btn btn-sm btn-outline-primary me-1" @click="edit(c)">{{ t('FORM.EDIT') }}</button>
<button class="btn btn-sm btn-outline-danger" @click="remove(c)">{{ t('FORM.DELETE') }}</button>
</td>
</tr>
</tbody>
</table>
</div>
<div class="col-lg-6">
<form class="card p-3" novalidate @submit.prevent="save">
<h2 class="h5">{{ editedId === null ? t('FORM.TITLE_ADD') : t('FORM.TITLE_EDIT') }}</h2>
<div class="mb-2">
<label class="form-label" for="title">{{ t('FORM.TITLE') }}</label>
<!-- uma opção "Dr" que o servidor rejeitará: para ver ERRORS.INVALID_TITLE -->
<select id="title" v-model="input.title" class="form-select" :class="{ 'is-invalid': fieldErrors.title }">
<option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
</select>
<div class="invalid-feedback">{{ fieldErrors.title && t(fieldErrors.title) }}</div>
</div>
<div class="row g-2 mb-2">
<div class="col-sm-6">
<label class="form-label" for="firstName">{{ t('FORM.FIRSTNAME') }}</label>
<input id="firstName" v-model="input.firstName" class="form-control" :class="{ 'is-invalid': fieldErrors.firstName }">
<div class="invalid-feedback">{{ fieldErrors.firstName && t(fieldErrors.firstName) }}</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="lastName">{{ t('FORM.LASTNAME') }}</label>
<input id="lastName" v-model="input.lastName" class="form-control" :class="{ 'is-invalid': fieldErrors.lastName }">
<div class="invalid-feedback">{{ fieldErrors.lastName && t(fieldErrors.lastName) }}</div>
</div>
</div>
<div class="row g-2 mb-3">
<div class="col-sm-6">
<label class="form-label" for="login">{{ t('FORM.LOGIN') }}</label>
<input id="login" v-model="input.login" class="form-control" :class="{ 'is-invalid': fieldErrors.login }">
<div class="invalid-feedback">{{ fieldErrors.login && t(fieldErrors.login) }}</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="password">{{ t('FORM.PASSWORD') }}</label>
<input id="password" v-model="input.password" type="password" class="form-control" autocomplete="new-password"
:class="{ 'is-invalid': fieldErrors.password }">
<div class="invalid-feedback">{{ fieldErrors.password && t(fieldErrors.password) }}</div>
</div>
</div>
<div class="d-flex gap-2">
<button class="btn btn-primary">{{ t('FORM.SAVE') }}</button>
<button type="button" class="btn btn-secondary" @click="newForm">{{ t('FORM.CANCEL') }}</button>
</div>
<div v-if="success" class="alert alert-success mt-3 mb-0">{{ success }}</div>
<!-- a mensagem geral e o status HTTP, para entender -->
<div v-if="pageError" class="alert alert-danger mt-3 mb-0">
{{ errorText(pageError) }} <span class="small text-muted">({{ pageError.statusCode }} {{ pageError.key }})</span>
</div>
</form>
</div>
</div>
</div>
<ConfirmDialog />
</template>
|
- linha 26: a janela de confirmação do Exemplo 12, reutilizada como está — um componente bem projetado é reutilizável;
- linhas 40 e 41: os erros devolvidos pelo servidor: o erro de cada campo e a mensagem geral;
- linhas 62–68: para modificar um registro, copie seus valores para o formulário, incluindo o número da versão: ele será salvo junto com a modificação (bloqueio otimista);
- linhas 77–79: a mensagem de erro, em linguagem do dia a dia, junto com seus parâmetros;
- linhas 81–102: [POST] para uma criação, [PUT] para uma modificação. Se a requisição for rejeitada, os erros devolvidos são armazenados; o template cuida do resto;
- linha 157: um título que o servidor rejeitará, para ver [ERRORS.INVALID_TITLE];
- linhas 164 e 165: um campo rejeitado é destacado em vermelho, e o código de erro traduzido é exibido abaixo dele;
- linha 126: trocar o idioma também retraduz as mensagens de erro já exibidas: apenas as chaves foram mantidas.
Um formulário preenchido incorretamente:

Um nome duplicado (Alice DURAND já existe): o servidor devolve uma resposta 409 e identifica os campos de nome e sobrenome:

O mesmo erro, em francês:

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