Skip to content

8. Comunicação com o servidor

Os exemplos deste capítulo consultam o servidor JSON [RdvMedecins]: ele deve estar em execução ([npm run start:dev] na pasta [rdvmedecins-nestjs-json]) na porta 8080, ao mesmo tempo que o servidor [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]:

1
2
3
4
5
6
  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:

Image

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.

Image

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

<!--
  =========================================================================
  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:

Image

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

Image

Logado:

Image

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:

Image

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

Image

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:

Image

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

Image

O mesmo erro, em francês:

Image

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