Skip to content

8. Comunicação com o servidor

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

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

8.1.1. O proxy do servidor de desenvolvimento

A página deste exemplo vem de http://localhost:5173 (o servidor de desenvolvimento do [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 o autorize explicitamente (o mecanismo conhecido como CORS). E uma requisição a outra origem não leva cookies (e, portanto, nem o token), a menos que o código o solicite ([credentials: 'include']) E o servidor o aceite, novamente via CORS.

Em vez de abrir o servidor para outras origens, fazemos as requisições à API passarem pelo servidor de desenvolvimento do [Vite]. Esse é o proxy declarado no arquivo [vite.config.ts] dos exemplos (veja o Exemplo 01):

1
2
3
    proxy: {
      '/api': 'http://localhost:8080',
    },

O navegador envia uma requisição para [GET http://localhost:5173/api/captcha]; o servidor de desenvolvimento 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 servidor de desenvolvimento: o próprio servidor JSON servirá os arquivos compilados do cliente (veja o capítulo “Implantação”). A página e a API continuarão a ter a mesma origem.

8.1.2. A requisição

O [React] não tem um cliente HTTP próprio: usa-se a função [fetch] do navegador ou uma biblioteca ([axios]...). [fetch] é mais do que suficiente.

// =========================================================================
// 22-fetch/src/App.tsx - uma primeira requisição HTTP ao servidor
// -------------------------------------------------------------------------
// O servidor JSON do RdvMedecins deve estar iniciado (porta 8080). Pedimos a ele
// um captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - fetch(url): a função do navegador que envia uma requisição HTTP.
//     Ela retorna uma PROMISE da resposta; response.json() uma promise
//     do corpo, convertido de JSON. O React não tem cliente HTTP próprio;
//   - o endereço é RELATIVO (/api/captcha): a requisição vai ao
//     servidor da página, o do Vite (porta 5173), que a repassa ao
//     servidor JSON (porta 8080) graças ao seu proxy (cf. vite.config.ts);
//   - três estados a exibir: em andamento, bem-sucedido, falhou.
// =========================================================================

import { useEffect, useState } from 'react';

// o que GET /api/captcha retorna
interface Captcha {
  id: string;
  svg: string;
}

const captchaStyle = { display: 'inline-block', border: '1px solid #dee2e6', borderRadius: '0.375rem' };

export default function App() {
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [requestCount, setRequestCount] = useState(0);
  // cada clique em "Outra imagem" muda este número, o que reinicia o efeito
  const [demand, setDemand] = useState(0);

  useEffect(() => {
    // AbortController: o meio de CANCELAR uma requisição em andamento
    const cancellation = new AbortController();
    setLoading(true);
    setError(null);
    fetch('/api/captcha', { signal: cancellation.signal })
      .then(async (response) => {
        // fetch NÃO rejeita uma resposta de erro (4xx, 5xx): ok é testado
        if (!response.ok) {
          throw new Error(`the server answered ${response.status} ${response.statusText}`);
        }
        const c = (await response.json()) as Captcha;
        setCaptcha(c);
        setRequestCount((n) => n + 1);
        setLoading(false);
      })
      .catch((e: Error) => {
        if (e.name === 'AbortError') return; // requisição cancelada: nada a exibir
        setError(e.message);
        setCaptcha(null);
        setLoading(false);
      });
    // a limpeza CANCELA a requisição se o efeito for reiniciado ou se o
    // componente desaparecer antes da resposta. Em desenvolvimento, o StrictMode
    // executa o efeito duas vezes na inicialização: a primeira requisição é
    // cancelada (aba Network: "canceled"), só a segunda conta.
    return () => cancellation.abort();
  }, [demand]);

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 22 - a first HTTP request</h1>
      <div className="card p-3">
        {loading && <p className="text-muted">Loading...</p>}
        {error && (
          <div className="alert alert-danger mb-3">
            Unable to get a captcha: {error}.<br />
            Is the RdvMedecins JSON server started (port 8080)?
          </div>
        )}
        {captcha && !loading && (
          <>
            {/* dangerouslySetInnerHTML: inserir uma string como HTML */}
            <div className="mb-2"><div style={captchaStyle} dangerouslySetInnerHTML={{ __html: captcha.svg }} /></div>
            <p className="small text-muted">id: <code>{captcha.id}</code></p>
          </>
        )}
        <button className="btn btn-primary align-self-start" disabled={loading} onClick={() => setDemand((d) => d + 1)}>
          Another image
        </button>
        <p className="small text-muted mt-2 mb-0">
          {requestCount} successful request(s) - open the Network tab of the developer tools (F12).
        </p>
      </div>
    </div>
  );
}
  • linhas 19–22: o que [GET /api/captcha] retorna;
  • linhas 27–30: três estados a exibir: em andamento, bem-sucedido (o CAPTCHA), erro;
  • linha 32: um número de requisição: cada clique em “Another image” o incrementa, o que dispara o efeito novamente;
  • linhas 34–61: a requisição é um efeito: ele sincroniza o componente com o servidor, na exibição inicial e depois a cada nova requisição:
    • linha 36: um [AbortController] permite cancelar uma requisição pendente: seu [signal] é passado ao [fetch];
    • linha 39: [fetch(url)] envia uma requisição (GET) e retorna uma promise para a resposta. O endereço é RELATIVO: a requisição é enviada ao servidor da página, o [Vite], que a encaminha ao servidor JSON;
    • linhas 42–44: ATENÇÃO: [fetch] NÃO rejeita a promise se receber uma resposta de erro (4xx, 5xx); sua promise só é rejeitada se NENHUMA resposta chegar (queda de rede). Por isso, verifica-se [response.ok] (true para um código 2xx);
    • Linha 45: [response.json()] lê o corpo e o converte de JSON (outra promise). [as Captcha]: informamos ao [TypeScript] o formato dos dados recebidos; ele não tem como verificá-lo;
    • linhas 50–55: um erro; [AbortError]: a requisição foi cancelada; não há nada a exibir;
    • Linha 60: a limpeza CANCELA a requisição se o efeito for disparado novamente ou se o componente desaparecer antes da resposta. Em desenvolvimento, o [<StrictMode>] executa o efeito duas vezes na inicialização: a primeira requisição é cancelada (a aba Rede a mostra como “canceled”); só a segunda conta;
  • linha 77: a imagem é um trecho de SVG, uma string a ser inserida como HTML. [{captcha.svg}] exibiria o texto [<svg ...>], com escape. [dangerouslySetInnerHTML] insere a string como está: seu nome alerta para o perigo. Use-o SOMENTE com conteúdo seguro: este SVG é gerado pelo NOSSO servidor. Com dados informados pelo usuário, isso abriria a porta para a injeção de scripts;
  • Linha 81: uma nova requisição; o efeito é disparado novamente.

Image

Se o servidor JSON estiver fora do ar, o proxy do [Vite] retorna um erro 500: “Unable to get a captcha: the server answered 500 Internal Server Error.”

// =========================================================================
// 23-login/src/App.tsx - fazendo login no servidor RdvMedecins
// -------------------------------------------------------------------------
//   1. na inicialização: GET /api/auth/me - já estamos logados?
//      (após um F5, o cliente esqueceu tudo; o servidor lê o cookie);
//   2. login: POST /api/auth/login, corpo JSON { login, password,
//      captchaId, captcha }. Em caso de sucesso, o servidor define o cookie
//      httpOnly do token JWT: nosso código NUNCA o vê (tente
//      document.cookie no console: ele não está lá);
//   3. requisição protegida: GET /api/doctors. O navegador anexa o cookie
//      a ela por conta própria (mesma origem);
//   4. logout: POST /api/auth/logout - o servidor apaga o cookie.
//
// O formulário usa as ACTIONS do React 19: <form action={function}>.
// Em vez de tratar onSubmit e cada campo, recebemos todos os valores
// do formulário (FormData), e useActionState guarda o resultado da
// última action (aqui, uma mensagem de erro) e indica se ela está em andamento.
//
// Um cookie pertence a um host (localhost) e a um caminho (/api): ele
// é portanto comum a TODOS os exemplos. Uma vez logado aqui, os exemplos
// 24 e 25 também estão.
// =========================================================================

import { useActionState, useEffect, useState } from 'react';
import { useFormStatus } from 'react-dom';

interface User {
  login: string;
  name: string;
  role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
}
interface Captcha {
  id: string;
  svg: string;
}
// o formato de TODOS os erros da API
interface ApiError {
  statusCode: number;
  key: string;
  params?: Record<string, string>;
}

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

// uma requisição GET, cuja resposta JSON é tipada; um erro se não for 2xx
async function read<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw response; // a própria resposta é "lançada": seu status dirá o que fazer
  }
  return (await response.json()) as T;
}

// o botão de envio: useFormStatus() indica se o formulário QUE O CONTÉM
// está sendo enviado (ele deve portanto ser um componente separado, colocado dentro)
function LoginButton() {
  const { pending } = useFormStatus();
  return <button className="btn btn-primary" disabled={pending}>{pending ? 'Logging in...' : 'Log in'}</button>;
}

// o resultado da última tentativa de login
interface LoginState {
  error: string | null;
  login: string; // o login digitado, para exibi-lo de novo
}

export default function App() {
  const [user, setUser] = useState<User | null>(null);
  const [doctors, setDoctors] = useState<Doctor[]>([]);
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [ready, setReady] = useState(false); // a verificação inicial terminou?
  const [serverError, setServerError] = useState<string | null>(null);

  async function loadCaptcha() {
    setCaptcha(await read<Captcha>('/api/captcha'));
  }

  async function loadDoctors() {
    setDoctors(await read<Doctor[]>('/api/doctors'));
  }

  // 1. quem está logado? 200 -> o usuário; 401 -> ninguém
  useEffect(() => {
    async function checkSession() {
      try {
        setUser(await read<User>('/api/auth/me'));
        await loadDoctors();
      } catch (e) {
        if (!(e instanceof Response) || e.status !== 401) {
          setServerError('Is the RdvMedecins JSON server started (port 8080)?');
        } else {
          await loadCaptcha();
        }
      }
      setReady(true);
    }
    checkSession();
  }, []);

  // 2. o login: uma ACTION, que recebe o estado anterior e os
  // dados do formulário, e retorna o novo estado
  async function logIn(_previous: LoginState, data: FormData): Promise<LoginState> {
    const login = String(data.get('login'));
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }, // o corpo é JSON
      body: JSON.stringify({ login, password: data.get('password'), captchaId: captcha?.id, captcha: data.get('captcha') }),
    });
    if (!response.ok) {
      // o corpo JSON da resposta de erro
      const error = (await response.json().catch(() => null)) as ApiError | null;
      const key = error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await loadCaptcha(); // cada imagem só é usada uma vez
      return { error: `${response.status} - ${MESSAGES[key] ?? key}`, login };
    }
    setUser((await response.json()) as User);
    await loadDoctors();
    return { error: null, login };
  }
  const [state, loginAction] = useActionState(logIn, { error: null, login: 'admin' });

  // 4. o logout
  async function logOut() {
    await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
    setUser(null);
    setDoctors([]);
    await loadCaptcha();
  }

  let content;
  if (!ready) {
    content = <p className="text-muted">Checking the session...</p>;
  } else if (user) {
    // logado
    content = (
      <div className="card p-3">
        <p>
          Logged in: <strong>{user.name}</strong> ({user.login}), role{' '}
          <span className="badge text-bg-primary">{user.role}</span>
        </p>
        <h2 className="h6">GET /api/doctors</h2>
        <ul>
          {doctors.map((m) => <li key={m.id}>{m.title} {m.firstName} {m.lastName}</li>)}
        </ul>
        <p className="small text-muted">Reload the page (F5): you remain logged in.</p>
        <button className="btn btn-outline-secondary align-self-start" onClick={logOut}>Log out</button>
      </div>
    );
  } else if (!serverError) {
    // não logado: o formulário. Os campos NÃO são controlados: name
    // os designa no FormData; após cada action, o React os redefine para
    // seu valor inicial (defaultValue)
    content = (
      <form className="card p-3" action={loginAction}>
        <div className="mb-2">
          <label className="form-label" htmlFor="login">Login</label>
          <input id="login" name="login" className="form-control" autoComplete="username" defaultValue={state.login} />
        </div>
        <div className="mb-2">
          <label className="form-label" htmlFor="password">Password</label>
          <input id="password" name="password" type="password" className="form-control" autoComplete="current-password" />
        </div>
        <div className="mb-3">
          <label className="form-label" htmlFor="captcha">Type the characters of the image</label>
          <div className="d-flex align-items-center gap-3 mb-2">
            <div dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
            <button type="button" className="btn btn-link btn-sm" onClick={loadCaptcha}>Another image</button>
          </div>
          <input id="captcha" name="captcha" className="form-control" autoComplete="off" />
        </div>
        <LoginButton />
        <p className="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
        {state.error && <div className="alert alert-danger mt-3 mb-0">{state.error}</div>}
      </form>
    );
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 23 - logging in to the server</h1>
      {content}
      {serverError && <div className="alert alert-danger mt-3">{serverError}</div>}
    </div>
  );
}

O fluxo (linhas 4–12): na inicialização, o servidor é consultado para saber quem está conectado; depois vêm o login, uma requisição protegida e o logout.

  • Linhas 27–47: alguns tipos da API, incluindo o formato de TODOS os erros;
  • linhas 50–54: as poucas mensagens de que este exemplo precisa para traduzir as chaves do servidor (o Exemplo 25 usará o [i18next]);
  • linhas 57–63: uma pequena função genérica para requisições GET: a resposta JSON, com um tipo; e, se não for 2xx, “lançamos” a própria resposta: seu status indicará o que fazer;
  • linhas 67–70: o botão de envio do formulário. [useFormStatus()] (do [react-dom]) indica se o formulário QUE O CONTÉM está sendo enviado no momento: por isso, ele deve ser um componente separado, colocado dentro do formulário;
  • Linhas 94–109: na inicialização, [GET /api/auth/me]: já estamos autenticados? Após um F5, o cliente esqueceu tudo; o servidor, porém, lê o cookie. 200: o usuário; 401: ninguém (um CAPTCHA é então carregado); qualquer outra coisa: o servidor não responde. Uma função [async] não pode ser o próprio efeito (um efeito retorna sua limpeza, não uma promise): nós a declaramos dentro do efeito e depois a chamamos;
  • linhas 113–130: o login, escrito como uma ação do [React] 19 (veja adiante). Ela recebe o estado anterior e os dados do formulário ([FormData]) e retorna o novo estado:
    • linha 114: [data.get(name)] lê um campo do formulário, identificado por seu atributo [name];
    • linhas 115–119: [POST /api/auth/login], com um corpo JSON: [method], o cabeçalho [Content-Type] e o corpo, gerado por [JSON.stringify]. Se tiver êxito, o servidor define o cookie [httpOnly] a partir do token JWT: nosso código NUNCA o vê (experimente [document.cookie] no console: ele não está lá);
    • linhas 120–126: uma falha: o corpo da resposta de erro, em JSON, fornece a chave da mensagem; cada imagem de CAPTCHA só é usada uma vez: outra é carregada;
    • linhas 127–129: um sucesso: o usuário, seguido de uma requisição protegida, [GET /api/doctors]: o navegador inclui o cookie automaticamente (mesma origem);
  • linha 131: [useActionState(action, initialState)] ([React] 19) retorna o estado gerado pela última execução da ação e uma versão da ação a ser passada ao formulário;
  • linhas 134–139: logout; [POST /api/auth/logout]: o servidor exclui o cookie. Todo POST deve ter um corpo JSON (o servidor rejeita os demais; veja o capítulo anterior): ['{}'];
  • linha 165: [<form action={function}>]: a partir do [React] 19, o atributo [action] de um formulário pode aceitar uma função. No envio, o [React] impede o navegador de enviar o formulário, reúne os campos em um [FormData] e chama a função, durante a qual o [useFormStatus] exibe “em andamento”. [onSubmit], [preventDefault] e um estado por campo deixam de ser necessários;
  • Linhas 168–180: os campos não são controlados: eles são identificados por seu [name]. Após cada ação, o [React] redefine o formulário: cada campo volta ao seu valor inicial ([defaultValue]). Os campos de senha e de CAPTCHA são, portanto, limpos; o campo de login volta ao valor armazenado no estado pela ação ([state.login]), ou seja, o que acabou de ser digitado;
  • linha 184: a mensagem de erro gerada pela última ação.

Um cookie pertence a uma máquina (localhost) e a um caminho ([/api]): ele é, portanto, compartilhado por TODOS os exemplos. Uma vez autenticado aqui, os exemplos 24 e 25 também estão autenticados.

Image

Uma senha incorreta: o login é mantido, e uma nova imagem é exibida:

Image

Autenticado como [admin]; você pode recarregar a página (F5): continua autenticado:

Image

8.3. Exemplo 24: uma camada de acesso à API

O Exemplo 23 repetia as mesmas etapas a cada requisição: prefixo [/api], cabeçalho JSON, verificação de [response.ok], leitura do corpo do erro... Os Exemplos 24 e 25 as reúnem na pasta [common/], e o estudo de caso seguirá essa mesma abordagem.

8.3.1. Os tipos

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

export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me
export interface User {
  login: string;
  name: string;
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string;
}

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

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

// uma linha de GET /api/schedule
export interface ScheduleSlot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
  free: boolean;
  patient: Identity | null;
  mine: boolean;
  bookable: boolean;
  appointmentId: number | null;
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string;
  slots: ScheduleSlot[];
  info: string | null;
}

A tradução, em interfaces [TypeScript], da API descrita no capítulo anterior. Uma linha da agenda ([ScheduleSlot]) descreve um horário E o que o usuário autenticado está autorizado a fazer com ele.

8.3.2. Os erros

// =========================================================================
// common/api-error.ts - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Todas as respostas de erro do servidor RdvMedecins têm o mesmo formato:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Mas uma requisição também pode falhar de OUTRO modo: nenhuma resposta
// (rede fora do ar: fetch lança um TypeError), ou uma resposta que não
// vem do nosso servidor (uma página de erro do proxy do Vite quando o
// servidor JSON está parado). Tudo isso é convertido 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).
// =========================================================================

export class ApiError extends Error {
  readonly statusCode: number; // 0: o servidor não respondeu
  readonly key: string; // ex.: 'ERRORS.LOGIN_TAKEN'
  readonly params: Record<string, string>;
  readonly fields: Record<string, string>;

  constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
    super(key);
    this.name = 'ApiError';
    this.statusCode = statusCode;
    this.key = key;
    this.params = params;
    this.fields = fields;
  }
}

// uma resposta de erro (4xx, 5xx) -> um ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
  // o corpo JSON do erro, se existir e tiver o formato certo
  let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
  try {
    const json: unknown = await response.json();
    if (typeof json === 'object' && json !== null) {
      body = json;
    }
  } catch {
    // não é JSON: não foi o nosso servidor que respondeu
  }
  // sem key: o proxy ou a rede respondeu no lugar dele
  const key = body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
  return new ApiError(response.status, key, body.params, body.fields);
}
  • Linhas 14–28: UMA classe para todos os erros da API: o status HTTP (0: nenhuma resposta), a chave de tradução enviada pelo servidor, seus parâmetros e o erro de cada campo em um formulário rejeitado. Ela herda de [Error]: pode ser lançada ([throw]) e reconhecida ([instanceof ApiError]). As “propriedades de parâmetro” do [TypeScript] ([constructor(public readonly key: string)]) não são usadas: a opção [erasableSyntaxOnly] do [tsconfig.json] as desativa, porque elas geram código;
  • Linhas 31–45: uma resposta de erro se torna um [ApiError]. O corpo nem sempre é o JSON do nosso servidor: quando o servidor JSON está fora do ar, o proxy do [Vite] responde sem corpo JSON. Sem chave: um código de status 500 ou superior significa “servidor inacessível”.

8.3.3. As requisições

// =========================================================================
// common/api.ts - requisições à API, em uma linha
// -------------------------------------------------------------------------
// No exemplo 23, cada requisição repetia os mesmos gestos: prefixo
// /api, cabeçalho JSON, teste de response.ok, leitura do corpo do erro... Eles
// são reunidos aqui:
//
//   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.
// Todas as requisições passam pela função request: é o lugar
// onde um problema COMUM a todas elas seria tratado (cf. o estudo de caso e a
// resposta 401). Usada pelos exemplos 24 e 25.
// =========================================================================

import { fromResponse, ApiError } from './api-error';

export async function request<T>(method: string, 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 o tenha)
      headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  } catch {
    // o fetch NÃO obteve resposta (rede, servidor parado)
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }
  if (!response.ok) {
    throw await fromResponse(response);
  }
  return (await response.json()) as T;
}

export const api = {
  get: <T>(url: string) => request<T>('GET', url),
  // um POST sempre tem um corpo JSON: {} por padrão
  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 20–37: TODAS as requisições passam por esta função genérica:
    • linhas 23–28: o prefixo [/api] e, se houver um corpo, o cabeçalho e o JSON;
    • linhas 29–32: nenhuma resposta: um [ApiError] com status 0;
    • linhas 33–35: uma resposta de erro: um [ApiError];
    • linha 36: um sucesso: o corpo, tipado;
  • linhas 39–45: atalhos, uma função por método HTTP. Um POST sempre tem um corpo JSON: [{}] por padrão.

É aqui que um problema COMUM seria tratado para todas as requisições: o estudo de caso tratará aqui a resposta 401 (sessão expirada).

8.3.4. Uma barra de login

// =========================================================================
// common/LoginBar.tsx - login / logout, em uma barra
// -------------------------------------------------------------------------
// O formulário do exemplo 23, reduzido a uma barra e reescrito com api.ts.
// O componente chama onUserChange com o usuário logado (ou
// null) a cada vez que ele muda - inclusive na inicialização, depois de
// ter consultado GET /api/auth/me.
// =========================================================================

import { useEffect, useEffectEvent, useState, type FormEvent } from 'react';
import { api } from './api';
import { ApiError } from './api-error';
import type { Captcha, User } from './types';
import './LoginBar.css';

interface Props {
  onUserChange: (user: User | null) => void;
}

export default function LoginBar({ onUserChange }: Props) {
  const [user, setUser] = useState<User | null>(null);
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [login, setLogin] = useState('admin');
  const [password, setPassword] = useState('');
  const [captchaAnswer, setCaptchaAnswer] = useState('');
  const [error, setError] = useState<string | null>(null);

  function changeUser(u: User | null) {
    setUser(u);
    onUserChange(u);
  }

  async function newCaptcha() {
    setCaptcha(await api.get<Captcha>('/captcha'));
    setCaptchaAnswer('');
  }

  // na inicialização: já estamos logados?
  const start = useEffectEvent(async () => {
    try {
      changeUser(await api.get<User>('/auth/me'));
    } catch {
      changeUser(null); // 401: ninguém está logado
      await newCaptcha().catch(() => setError('Is the JSON server started (port 8080)?'));
    }
  });
  useEffect(() => {
    start();
  }, []);

  async function logIn(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    setError(null);
    try {
      const u = await api.post<User>('/auth/login', { login, password, captchaId: captcha?.id, captcha: captchaAnswer });
      setPassword('');
      changeUser(u);
    } catch (err) {
      setError(err instanceof ApiError ? `${err.statusCode} ${err.key}` : String(err));
      await newCaptcha();
    }
  }

  async function logOut() {
    await api.post('/auth/logout');
    changeUser(null);
    await newCaptcha();
  }

  return (
    <div className="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
      {user ? (
        <>
          <span>
            Logged in: <strong>{user.name}</strong> <span className="badge text-bg-primary ms-1">{user.role}</span>
          </span>
          <button className="btn btn-sm btn-outline-secondary ms-auto" onClick={logOut}>Log out</button>
        </>
      ) : (
        <form className="d-flex flex-wrap align-items-center gap-2 w-100" onSubmit={logIn}>
          <input className="form-control form-control-sm w-auto" placeholder="login" autoComplete="username" value={login}
                 onChange={(e) => setLogin(e.target.value)} />
          <input type="password" className="form-control form-control-sm w-auto" placeholder="password"
                 autoComplete="current-password" value={password} onChange={(e) => setPassword(e.target.value)} />
          {/* a imagem SVG do captcha, montada pelo NOSSO servidor (cf. exemplo 22) */}
          <div className="captcha-bar" dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
          <input className="form-control form-control-sm w-auto" placeholder="captcha" autoComplete="off" size={8}
                 value={captchaAnswer} onChange={(e) => setCaptchaAnswer(e.target.value)} />
          <button className="btn btn-sm btn-primary">Log in</button>
          {error && <span className="text-danger small">{error}</span>}
        </form>
      )}
    </div>
  );
}

O formulário do Exemplo 23, reduzido a uma barra e reescrito com o [api.ts] (e com campos validados, para comparação):

  • linha 17: o componente notifica seu pai sempre que o usuário autenticado muda;
  • linhas 39–46 e 47–49: na inicialização, [GET /api/auth/me]. A função chamada pelo efeito notifica o pai: [useEffectEvent] evita que ela seja uma dependência (veja o Exemplo 13);
  • linha 55: uma requisição de uma linha; se falhar, um [ApiError];
  • linha 86: a imagem do CAPTCHA, ajustada à altura da barra por meio de uma pequena folha de estilos:
1
2
3
4
5
6
7
8
/* a imagem SVG do captcha, inserida como está na página: ela é reduzida
   à altura da barra. Uma folha de estilo importada se aplica à
   página INTEIRA: a classe .captcha-bar a limita ao nosso elemento. */
.captcha-bar svg {
  display: block;
  height: 32px;
  width: auto;
}

8.3.5. A camada de acesso à API

// =========================================================================
// 24-api-layer/src/rdvmedecins.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 lado do cliente, da camada DAO do lado do servidor: se a API
// muda (uma URL, o nome de um campo), só 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 monta "doctorId=1&day=2030-01-15", codificando o que precisa
  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}`),
};

Uma função por rota da API, tipada. Os componentes não conhecem a URL, o [fetch] nem o formato JSON: eles chamam funções. Este é o equivalente, no lado do cliente, da camada DAO do lado do servidor: se a API mudar (uma URL, o nome de um campo), apenas este arquivo é modificado. [URLSearchParams] (linha 18) gera a parte [doctorId=1&day=2030-01-15] de um endereço, codificando os dados necessários.

8.3.6. TanStack Query

Ler dados de um servidor em um efeito, como no Exemplo 22, exige tratar tudo: o estado “em andamento”, erros, respostas obsoletas, cancelamentos, requisições duplicadas enviadas duas vezes e dados já recebidos que poderiam ser reaproveitados... O [TanStack Query] (antes chamado [React Query]), a biblioteca mais utilizada para essa finalidade, cuida de tudo isso.

// =========================================================================
// 24-api-layer/src/main.tsx
// -------------------------------------------------------------------------
// TanStack Query (antigo React Query): a biblioteca mais usada
// para LER dados de um servidor em uma aplicação React.
// O QueryClient guarda na memória (em "cache") as respostas já recebidas;
// <QueryClientProvider> o fornece a toda a aplicação (um contexto,
// cf. exemplo 14).
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';

const queryClient = new QueryClient({
  // em caso de falha, nenhuma nova tentativa: queremos ver o erro
  defaultOptions: { queries: { retry: false } },
});

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);
  • linha 17: o cliente do [TanStack Query], que armazena na memória as respostas já recebidas (no “cache”); [retry: false]: em caso de falha, sem nova tentativa (por padrão, ele faz três);
  • linha 24: ele é fornecido a toda a aplicação por meio de um contexto (veja o Exemplo 14).

8.3.7. A página

// =========================================================================
// 24-api-layer/src/App.tsx - uma agenda, com a camada de acesso à API
// -------------------------------------------------------------------------
// Faça login (barra superior), escolha um médico e um dia: a agenda
// é exibida. ADMIN e DOCTOR podem marcar consulta para um paciente e cancelar;
// um paciente (martin...) marca para si mesmo. Cada ação termina com
// um recarregamento da agenda: é o SERVIDOR que tem a palavra final.
//
// useQuery({ queryKey, queryFn }): uma LEITURA de dados, descrita por
//   - queryFn: a função que os obtém (uma promise);
//   - queryKey: o que IDENTIFICA esses dados: ['schedule', doctorId, day].
// O TanStack Query chama queryFn no início, e depois a cada vez que a chave
// MUDA (outro médico, outro dia). Ele retorna um objeto: data (a
// resposta), isPending, isFetching, error... e refetch() para ler de novo.
// Ele também cuida do que precisaria ser escrito à mão com useEffect: cancelar
// uma resposta obsoleta, não enviar a mesma requisição duas vezes, manter
// as respostas em cache.
// =========================================================================

import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { ScheduleSlot, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins';

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 -> um texto (sua chave, na falta de um dicionário aqui)
function errorText(e: unknown): string {
  return e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e);
}

export default function App() {
  const [user, setUser] = useState<User | null>(null);
  const [doctorId, setDoctorId] = useState<number | null>(null);
  const [day, setDay] = useState(tomorrow);
  const [clientId, setClientId] = useState<number | null>(null);
  const [message, setMessage] = useState<{ type: 'success' | 'danger'; text: string } | null>(null);

  const loggedIn = user !== null;
  const isManager = loggedIn && user.role !== 'USER';

  // os médicos e depois (ADMIN, DOCTOR) os clientes: lidos de novo quando
  // o usuário muda (ele faz parte da chave)
  const doctors = useQuery({
    queryKey: ['doctors', user?.login],
    queryFn: rdvmedecins.getDoctors,
    enabled: loggedIn, // false: nenhuma requisição (ninguém logado)
  });
  const clients = useQuery({
    queryKey: ['clients', user?.login],
    queryFn: rdvmedecins.getClients,
    enabled: isManager, // um USER receberia 403
  });

  // a agenda: a chave contém o médico e o dia
  const schedule = useQuery({
    queryKey: ['schedule', doctorId, day, user?.login],
    queryFn: () => rdvmedecins.getSchedule(doctorId!, day),
    enabled: loggedIn && doctorId !== null,
  });

  // uma nova escolha de médico ou de dia apaga a mensagem anterior
  function chooseDoctor(id: number) {
    setDoctorId(id);
    setMessage(null);
  }
  function chooseDay(d: string) {
    setDay(d);
    setMessage(null);
  }

  async function book(c: ScheduleSlot) {
    try {
      await rdvmedecins.book(day, c.id, isManager ? (clientId ?? undefined) : undefined);
      setMessage({ type: 'success', text: `Slot ${timeRange(c)} booked.` });
    } catch (e) {
      setMessage({ type: 'danger', text: errorText(e) });
    }
    schedule.refetch();
  }

  async function cancel(c: ScheduleSlot) {
    try {
      await rdvmedecins.cancelAppointment(c.appointmentId!);
      setMessage({ type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` });
    } catch (e) {
      setMessage({ type: 'danger', text: errorText(e) });
    }
    schedule.refetch();
  }

  const a = schedule.data;
  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 24 - an API access layer</h1>
      <LoginBar onUserChange={setUser} />

      {loggedIn && (
        <>
          <div className="row g-2 mb-3">
            <div className="col-sm-5">
              <select className="form-select" value={doctorId ?? ''} onChange={(e) => chooseDoctor(Number(e.target.value))}>
                <option value="" disabled>-- choose a doctor --</option>
                {doctors.data?.map((m) => <option key={m.id} value={m.id}>{m.title} {m.firstName} {m.lastName}</option>)}
              </select>
            </div>
            <div className="col-sm-3">
              <input type="date" className="form-control" value={day} onChange={(e) => chooseDay(e.target.value)} />
            </div>
            {isManager && (
              <div className="col-sm-4">
                <select className="form-select" value={clientId ?? ''}
                        onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
                  <option value="">-- patient to book for --</option>
                  {clients.data?.map((c) => <option key={c.id} value={c.id}>{c.title} {c.firstName} {c.lastName}</option>)}
                </select>
              </div>
            )}
          </div>

          {message && <div className={`alert alert-${message.type}`}>{message.text}</div>}
          {schedule.error && <div className="alert alert-danger">{errorText(schedule.error)}</div>}
          {schedule.isFetching && <p className="small text-muted">loading the schedule...</p>}

          {a && (
            <>
              {/* info: a chave enviada pelo servidor quando um paciente já tem uma consulta futura */}
              {a.info && <div className="alert alert-info">{a.info}</div>}
              <table className="table table-sm align-middle">
                <caption className="caption-top">
                  Schedule of {a.day} - {a.doctor.title} {a.doctor.firstName} {a.doctor.lastName}
                </caption>
                <tbody>
                  {a.slots.map((c) => (
                    <tr key={c.id}>
                      <td>{timeRange(c)}</td>
                      <td>
                        {c.free ? (
                          <span className="badge text-bg-success">Free</span>
                        ) : c.patient ? (
                          <span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>
                            {c.patient.title} {c.patient.firstName} {c.patient.lastName}
                          </span>
                        ) : (
                          <span className="badge text-bg-secondary">Booked</span>
                        )}
                      </td>
                      <td className="text-end">
                        {/* os botões seguem os direitos calculados pelo servidor */}
                        {c.bookable && <button className="btn btn-sm btn-outline-success" onClick={() => book(c)}>Book</button>}
                        {c.appointmentId !== null && <button className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>Cancel</button>}
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </>
          )}
        </>
      )}
    </div>
  );
}
  • linhas 54–58: [useQuery({ queryKey, queryFn, enabled })] descreve uma LEITURA de dados:
    • [queryFn]: a função que os obtém, uma promise;
    • [queryKey]: o que IDENTIFICA os dados — um array. O [TanStack Query] chama [queryFn] primeiro e depois a cada vez que a chave MUDA; dois componentes que solicitam a mesma chave compartilham a mesma requisição e a mesma resposta. O usuário é adicionado a ela: a lista é recarregada quando o usuário muda;
    • [enabled: false]: nenhuma requisição (ninguém está autenticado);
    • O resultado é um objeto: [data] (a resposta, [undefined] até que ela chegue), [isPending], [isFetching] (uma requisição está em andamento), [error] e [refetch()] para relê-lo;
  • linhas 59–63: a lista de pacientes, somente para ADMIN e DOCTOR (um USER receberia um 403);
  • linhas 66–70: a agenda: a chave contém o médico e o dia; alterar qualquer um deles envia uma nova requisição. Uma resposta expirada é ignorada automaticamente;
  • linhas 82–90: uma reserva: [POST /api/appointments], depois [schedule.refetch()]: a agenda é relida. O SERVIDOR é quem tem a palavra final;
  • linha 106: a barra de login notifica a página;
  • linha 114: os médicos, se já tiverem chegado ([?.]: nada se [data] for [undefined]);
  • linha 133: uma requisição da agenda está em andamento;
  • linhas 160–161: os botões seguem as permissões calculadas pelo servidor;
  • linha 138: [info]: a chave enviada pelo servidor quando um paciente já tem uma consulta futura (exibida sem tratamento: aqui não há dicionário).

Autenticados como [admin], selecionamos a Sra. PELISSIER, depois um paciente, e reservamos o primeiro horário:

Image

Autenticados como [martin], reservamos um horário: o paciente vê o próprio nome, mas o nome de outro paciente nunca lhe é enviado; o botão “Book” não está mais disponível (apenas uma consulta futura):

Image

Para o processamento de transações (reservar, cancelar), o [TanStack Query] também oferece o [useMutation], que trata o estado “em andamento” e os erros das modificações. Não o usaremos aqui: uma função [async] e um [try / catch] bastam.

8.4. Exemplo 25: erros retornados pelo servidor

Gerenciamento de pacientes (formulário [admin]). Este formulário não faz nenhuma validação no navegador: tudo é enviado ao servidor, que responde — em caso de rejeição — com um erro JSON:

1
2
3
400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (optimistic lock)

8.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."
  },
  "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."
  }
}

As chaves [ERRORS.*] são as retornadas pelo servidor. O dicionário em inglês, [en.json], tem as mesmas chaves. A configuração do [i18next] é a mesma do Exemplo 21, mas mais simples:

// =========================================================================
// 25-server-errors/src/i18n/i18n.ts - i18next, como no exemplo 21
// =========================================================================

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';

i18n.use(initReactI18next).init({
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: { escapeValue: false },
});
// =========================================================================
// 25-server-errors/src/main.tsx
// -------------------------------------------------------------------------
//   - i18next (cf. exemplo 21);
//   - o diálogo de confirmação do exemplo 16, reutilizado como está.
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import './i18n/i18n';
import App from './App';
import { ConfirmationProvider } from '../../16-confirmation/src/confirmation/confirmation';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfirmationProvider>
      <App />
    </ConfirmationProvider>
  </StrictMode>,
);

A janela de confirmação do Exemplo 16 é reutilizada como está: seu provider é importado.

8.4.2. A página

// =========================================================================
// 25-server-errors/src/App.tsx - exibindo os erros do SERVIDOR
// -------------------------------------------------------------------------
// O gerenciamento dos clientes (conta de administrador). Este formulário faz
// DELIBERADAMENTE nenhuma validação no navegador: 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) é guardado no estado e
// exibido sob o campo; sua mensagem é a CHAVE enviada pelo servidor,
// que o componente traduz (i18next). Modificar um campo apaga seu erro.
// Experimente: um sobrenome vazio, um título "Dr", um homônimo (Alice DURAND), um
// login já em uso (martin), o mesmo registro editado em duas abas...
// =========================================================================

import { useState, useTransition, type FormEvent } from 'react';
import { useTranslation } from 'react-i18next';
import { api } from '../../common/api';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { Person, User } from '../../common/types';
import { useConfirmation } from '../../16-confirmation/src/confirmation/confirmation';

interface ClientInput {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  version: number;
}
type Field = keyof ClientInput;

const EMPTY: ClientInput = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 };

interface Message {
  key: string;
  params?: Record<string, string>;
}

export default function App() {
  const { t, i18n } = useTranslation();
  const confirm = useConfirmation();

  const [user, setUser] = useState<User | null>(null);
  const [clients, setClients] = useState<Person[]>([]);
  const isAdmin = user?.role === 'ADMIN';

  // o formulário: editedId === null -> criação, caso contrário atualização
  const [editedId, setEditedId] = useState<number | null>(null);
  const [input, setInput] = useState<ClientInput>(EMPTY);
  // o erro de cada campo (uma CHAVE de tradução), retornado pelo servidor
  const [errors, setErrors] = useState<Partial<Record<Field, string>>>({});
  // a mensagem geral do último erro, e a de um sucesso
  const [pageError, setPageError] = useState<ApiError | null>(null);
  const [success, setSuccess] = useState<Message | null>(null);
  // useTransition: isPending é true durante a execução da action
  // passada a startTransition - aqui, o envio ao servidor
  const [sending, startTransition] = useTransition();

  async function reload() {
    setClients(await api.get<Person[]>('/clients'));
  }

  async function onUserChange(u: User | null) {
    setUser(u);
    setClients([]);
    if (u?.role === 'ADMIN') {
      await reload();
    }
  }

  function clearMessages() {
    setErrors({});
    setPageError(null);
    setSuccess(null);
  }

  function newForm() {
    setEditedId(null);
    setInput(EMPTY);
    clearMessages();
  }

  function edit(c: Person) {
    setEditedId(c.id);
    // a VERSÃO lida com o registro volta com a atualização: se alguém
    // modificou o registro nesse meio-tempo, o servidor responderá 409 CONCURRENT_UPDATE
    setInput({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
    clearMessages();
  }

  // um campo modificado: seu valor muda, seu erro desaparece
  function change(field: Field, value: string) {
    setInput((s) => ({ ...s, [field]: value }));
    setErrors((e) => ({ ...e, [field]: undefined }));
  }

  function save(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    clearMessages();
    // uma transição ASSÍNCRONA (React 19): sending permanece true até
    // o fim da função
    startTransition(async () => {
      try {
        const client =
          editedId === null
            ? await api.post<Person>('/clients', input)
            : await api.put<Person>(`/clients/${editedId}`, input);
        newForm(); // formulário esvaziado, mensagens apagadas...
        // ... exceto esta
        setSuccess({
          key: editedId === null ? 'FORM.ADDED' : 'FORM.UPDATED',
          params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
        });
        await reload();
      } catch (e) {
        if (!(e instanceof ApiError)) {
          throw e;
        }
        setPageError(e); // a mensagem geral
        setErrors(e.fields); // o erro de cada campo
      }
    });
  }

  async function remove(c: Person) {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
      return;
    }
    clearMessages();
    try {
      await api.delete(`/clients/${c.id}`);
      setSuccess({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      setPageError(e instanceof ApiError ? e : null);
    }
    await reload();
  }

  // um campo de entrada, com seu erro traduzido
  function field(name: 'firstName' | 'lastName' | 'login' | 'password', type = 'text') {
    const error = errors[name];
    return (
      <>
        <label className="form-label" htmlFor={name}>{t(`FORM.${name.toUpperCase()}`)}</label>
        <input id={name} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={input[name]}
               autoComplete={type === 'password' ? 'new-password' : 'off'} onChange={(e) => change(name, e.target.value)} />
        {/* a mensagem de um erro do servidor é uma CHAVE: ela é traduzida */}
        {error && <div className="invalid-feedback">{t(error)}</div>}
      </>
    );
  }

  return (
    <div className="container py-4">
      <div className="d-flex justify-content-between align-items-center mb-3">
        <h1 className="h3 mb-0">Example 25 - the errors returned by the server</h1>
        <select className="form-select form-select-sm w-auto" value={i18n.language} onChange={(e) => i18n.changeLanguage(e.target.value)}>
          <option value="fr">FR</option>
          <option value="en">EN</option>
        </select>
      </div>
      <LoginBar onUserChange={onUserChange} />
      {user && !isAdmin && <p className="alert alert-warning">{t('FORM.ADMIN_ONLY')}</p>}

      {isAdmin && (
        <div className="row g-4">
          <div className="col-lg-6">
            <table className="table table-sm align-middle">
              <tbody>
                {clients.map((c) => (
                  <tr key={c.id}>
                    <td>{c.title} {c.firstName} {c.lastName}</td>
                    <td><code>{c.login}</code></td>
                    <td className="text-end text-nowrap">
                      <button className="btn btn-sm btn-outline-primary me-1" onClick={() => edit(c)}>{t('FORM.EDIT')}</button>
                      <button className="btn btn-sm btn-outline-danger" onClick={() => remove(c)}>{t('FORM.DELETE')}</button>
                    </td>
                  </tr>
                ))}
              </tbody>
            </table>
          </div>

          <div className="col-lg-6">
            <form className="card p-3" noValidate onSubmit={save}>
              <h2 className="h5">{t(editedId === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT')}</h2>
              <div className="mb-2">
                <label className="form-label" htmlFor="title">{t('FORM.TITLE')}</label>
                {/* uma opção "Dr" que o servidor rejeitará: para ver ERRORS.INVALID_TITLE */}
                <select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={input.title}
                        onChange={(e) => change('title', e.target.value)}>
                  <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
                </select>
                {errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
              </div>
              <div className="row g-2 mb-2">
                <div className="col-sm-6">{field('firstName')}</div>
                <div className="col-sm-6">{field('lastName')}</div>
              </div>
              <div className="row g-2 mb-3">
                <div className="col-sm-6">{field('login')}</div>
                <div className="col-sm-6">{field('password', 'password')}</div>
              </div>
              <div className="d-flex gap-2">
                <button className="btn btn-primary" disabled={sending}>{t('FORM.SAVE')}</button>
                <button type="button" className="btn btn-secondary" onClick={newForm}>{t('FORM.CANCEL')}</button>
              </div>
              {success && <div className="alert alert-success mt-3 mb-0">{t(success.key, success.params)}</div>}
              {/* a mensagem geral e o status HTTP, para entender */}
              {pageError && (
                <div className="alert alert-danger mt-3 mb-0">
                  {t(pageError.key, pageError.params)}{' '}
                  <span className="small text-muted">({pageError.statusCode} {pageError.key})</span>
                </div>
              )}
            </form>
          </div>
        </div>
      )}
    </div>
  );
}
  • linhas 54–55: o formulário: [editedId === null] para criar um paciente, ou [editedId] para modificar um paciente;
  • linha 57: o erro de cada campo, uma CHAVE de tradução, retornada pelo servidor;
  • linha 63: [useTransition] retorna um indicador de “em andamento” e uma função [startTransition(action)]. A partir do [React] 19, a ação pode ser [async]: o indicador permanece true até o fim da função, sem exigir nenhum tratamento manual;
  • linhas 89–95: modificação de um paciente. A VERSÃO lida do registro mestre reflete a modificação: se alguém tiver modificado o registro mestre nesse meio tempo, o servidor responderá com um 409 [ERRORS.CONCURRENT_UPDATE] (bloqueio otimista);
  • linhas 98–101: um campo modificado: seu valor muda, e seu erro desaparece;
  • linhas 103–129: o envio:
    • [POST /api/clients] (criação) ou [PUT /api/clients/:id] (atualização);
    • em caso de sucesso: o formulário é limpo, e uma mensagem é traduzida, junto com seus parâmetros;
    • no caso de um [ApiError] (linhas 125–126): a mensagem geral e o erro de CADA campo; a linha como aparece no relatório: [e.fields] tem exatamente o formato desejado;
  • linhas 131–144: exclusão, após confirmação. A mensagem de confirmação é traduzida por [t], com um parâmetro;
  • linhas 147–158: uma função que cria um campo de entrada com seu rótulo e sua mensagem de erro: [t(error)] traduz a CHAVE enviada pelo servidor;
  • linha 164: seleção do idioma: os erros já exibidos são traduzidos novamente, pois são chaves;
  • linha 199: uma opção “Dr” que o servidor rejeitará, resultando em [ERRORS.INVALID_TITLE];
  • linha 212: o botão fica desabilitado durante a transmissão;
  • linha 219: a mensagem geral e o status HTTP, para contexto.

Autenticados como [admin], com o título “Dr”, um nome vazio e um login inválido:

Image

Um homônimo (Alice Durand, que já existe) e um login já em uso ([martin]): 409, e os dois campos afetados são sinalizados:

Image

A mesma página em francês: as mensagens do servidor são traduzidas de volta:

Image

Uma inclusão bem-sucedida:

Image

Depois sua exclusão:

Image

Image

Para ver o bloqueio otimista, abra o mesmo registro em duas abas, salve-o na primeira aba e depois na segunda: o servidor responde com um erro 409 ([ERRORS.CONCURRENT_UPDATE]).