Skip to content

8. 与服务器通信

本章的示例查询 [RdvMedecins] JSON 服务器:它必须处于运行状态(在 [npm run start:dev] 于 [rdvmedecins-nestjs-json] 文件夹中),监听 8080 端口,同时 [Vite] 开发服务器监听 5173 端口。

8.1. 示例 22:第一个 HTTP 请求

8.1.1. 开发服务器的代理

本示例的页面来自 http://localhost:5173([Vite] 开发服务器);API 位于 http://localhost:8080。对浏览器来说,这是两个不同的 源 (端口是源的一部分)。然而出于安全原因,浏览器不允许页面读取来自另一个源的响应,除非服务器明确允许(即所谓的 CORS 机制)。而且,发往另一个源的请求不会携带 Cookie(因此也不会携带令牌),除非代码提出要求([credentials: 'include']),并且服务器同样通过 CORS 表示接受。

我们不向其他源开放服务器,而是让 API 请求经过 [Vite] 开发服务器。这就是在示例的 代理 中声明的、位于 [vite.config.ts] 文件里的配置(见示例 01):

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

浏览器向 [GET http://localhost:5173/api/captcha] 发送请求;开发服务器把请求转发到 [http://localhost:8080/api/captcha],然后把响应送回浏览器。从浏览器的角度看,页面和 API 具有 同一个源:

Image

在生产环境中,将不再有开发服务器:JSON 服务器本身会提供编译后的客户端文件(见“部署”一章)。页面和 API 仍然同源。

8.1.2. 请求

[React] 没有自己的 HTTP 客户端:可以使用浏览器的 [fetch] 函数,或使用某个库([axios]……)。[fetch] 已经绰绰有余。

// =========================================================================
// 22-fetch/src/App.tsx - 向服务器发出的第一个 HTTP 请求
// -------------------------------------------------------------------------
// 必须先启动 RdvMedecins JSON 服务器(端口 8080)。我们向它请求
// 一个验证码:GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }。
//
//   - fetch(url):发送 HTTP 请求的浏览器函数。
//     它返回响应的 PROMISE;response.json() 返回
//     由 JSON 转换而来的响应体的 promise。React 本身没有 HTTP 客户端;
//   - 地址是相对的(/api/captcha):请求发往
//     页面所在的服务器,即 Vite 的服务器(端口 5173),它借助其代理(参见 vite.config.ts)
//     把请求转发给 JSON 服务器(端口 8080);
//   - 需要显示三种状态:进行中、成功、失败。
// =========================================================================

import { useEffect, useState } from 'react';

// GET /api/captcha 返回的内容
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);
  // 每次点击“Another image”都会改变这个数字,从而重新启动该副作用
  const [demand, setDemand] = useState(0);

  useEffect(() => {
    // AbortController:取消正在进行的请求的方法
    const cancellation = new AbortController();
    setLoading(true);
    setError(null);
    fetch('/api/captcha', { signal: cancellation.signal })
      .then(async (response) => {
        // fetch 不会因错误响应(4xx、5xx)而 reject:因此要检测 ok
        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; // 请求已取消:无需显示任何内容
        setError(e.message);
        setCaptcha(null);
        setLoading(false);
      });
    // 如果副作用被重新启动,或组件在收到响应之前消失,清理函数会取消该请求
    // 。在开发模式下,StrictMode
    // 会在启动时执行两次副作用:第一次请求会被
    // 取消(Network 标签页中显示“canceled”),只有第二次才算数。
    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:把字符串作为 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>
  );
}
  • 第 19–22 行:[GET /api/captcha] 返回的内容;
  • 第 27–30 行:需要显示的三种状态:进行中、成功(验证码(CAPTCHA))、错误;
  • 第 32 行:请求编号:每次点击“换一张图片”都会使它加 1,从而再次触发副作用;
  • 第 34–61 行:请求就是一个 副作用:它在初次显示时以及之后每次新请求时,让组件与服务器保持同步:
    • 第 36 行:[AbortController] 可以取消一个进行中的请求:它的 [signal] 会传给 [fetch];
    • 第 39 行:[fetch(url)] 发送一个请求(GET),并返回响应的 promise 。地址是相对的:请求发送给页面所在的服务器 [Vite],由它转发给 JSON 服务器;
    • 第 42–44 行:警告:当 [fetch] 收到错误响应(4xx、5xx)时,它不会被拒绝;只有在没有任何响应到达(网络中断)时,它的 promise 才会被拒绝。因此要检查 [response.ok](2xx 状态码时为 true);
    • 第 45 行:[response.json()] 读取响应体并从 JSON 转换(又是一个 promise)。[as Captcha]:我们把收到的数据的格式告诉 [TypeScript] ;它无法验证这一点;
    • 第 50–55 行:错误;[AbortError]:请求已被取消;没有什么需要显示;
    • 第 60 行:如果副作用被重新触发,或者组件在响应到达之前消失,清理函数会取消请求。在开发环境中,[<StrictMode>] 会在启动时运行两次副作用:第一个请求被取消(Network 选项卡中显示为“canceled”);只有第二个请求有效;
  • 第 77 行:图片是一段 SVG,一个要像 HTML 那样插入的字符串。[{captcha.svg}] 会把文本 [<svg ...>] 转义后显示出来。[dangerouslySetInnerHTML] 原样插入该字符串:它的名字就在警告其中的危险。只能用于安全的内容:这个 SVG 由我们自己的服务器生成。如果用于用户输入,就会为脚本注入打开大门;
  • 第 81 行:一个新的请求;副作用再次被触发。

Image

如果 JSON 服务器已关闭,[Vite] 代理会返回 500 错误:“Unable to get a captcha: the server answered 500 Internal Server Error.”

8.2. 示例 23:登录、Cookie 与会话

// =========================================================================
// 23-login/src/App.tsx - 登录 RdvMedecins 服务器
// -------------------------------------------------------------------------
//   1. 启动时:GET /api/auth/me - 我们是否已经登录?
//      (刷新(F5)后,客户端什么都忘了;由服务器读取 Cookie);
//   2. 登录:POST /api/auth/login,JSON 请求体 { login, password,
//      captchaId, captcha }。成功后,服务器设置 JWT 令牌的 httpOnly
//      Cookie:我们的代码绝对看不到它(可在控制台中试试
//      document.cookie:里面没有它);
//   3. 受保护的请求:GET /api/doctors。浏览器会自动
//      附带该 Cookie(同源);
//   4. 退出登录:POST /api/auth/logout - 服务器删除该 Cookie。
//
// 该表单使用 React 19 的 ACTIONS:<form action={function}>。
// 我们不再处理 onSubmit 和每个字段,而是接收表单的
// 所有值(FormData),useActionState 保存
// 上一次 action 的结果(这里是一条错误消息),并告知它是否正在进行中。
//
// Cookie 属于一个主机(localhost)和一个路径(/api):因此
// 它为所有示例所共用。在这里登录之后,示例
// 24 和 25 也处于已登录状态。
// =========================================================================

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;
}
// API 所有错误的形状
interface ApiError {
  statusCode: number;
  key: string;
  params?: Record<string, string>;
}

// 本示例所需的少量消息(示例 25 将使用 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.',
};

// 一个 GET 请求,其 JSON 响应带有类型;如果不是 2xx 则报错
async function read<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw response; // 响应本身被“抛出”:由它的 status 决定下一步怎么做
  }
  return (await response.json()) as T;
}

// 提交按钮:useFormStatus() 告知包含它的表单
// 是否正在发送(因此它必须是放在表单内部的独立组件)
function LoginButton() {
  const { pending } = useFormStatus();
  return <button className="btn btn-primary" disabled={pending}>{pending ? 'Logging in...' : 'Log in'}</button>;
}

// 最近一次登录尝试的结果
interface LoginState {
  error: string | null;
  login: string; // 已输入的登录名,用于再次显示
}

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); // 初始检查是否已结束?
  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. 谁已登录?200 -> 该用户;401 -> 无人
  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. 登录:一个 ACTION,它接收先前的状态和
  // 表单的数据,并返回新状态
  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' }, // 请求体是 JSON
      body: JSON.stringify({ login, password: data.get('password'), captchaId: captcha?.id, captcha: data.get('captcha') }),
    });
    if (!response.ok) {
      // 错误响应的 JSON 请求体
      const error = (await response.json().catch(() => null)) as ApiError | null;
      const key = error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await loadCaptcha(); // 每张图片只使用一次
      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. 退出登录
  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) {
    // 已登录
    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) {
    // 未登录:显示表单。这些字段不是受控的:name
    // 用于在 FormData 中标识它们;每次 action 之后,React 会把它们重置为
    // 初始值(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>
  );
}

流程(第 4–12 行):启动时,先向服务器查询当前连接的是谁;然后是登录、一个受保护的请求,以及登出。

  • 第 27–47 行:一些 API 类型,包括所有错误的结构;
  • 第 50–54 行:本示例用来翻译服务器键所需的少量消息(示例 25 将使用 [i18next]);
  • 第 57–63 行:一个用于 GET 请求的小型泛型函数:返回带类型的 JSON 响应;如果状态码不是 2xx,我们就“抛出”响应本身:它的状态码会指示该怎么做;
  • 第 67–70 行:表单的提交按钮。[useFormStatus()] (来自 [react-dom])指示包含它的表单当前是否正在提交:因此它必须是放在表单内部的一个独立组件;
  • 第 94–109 行:启动时,[GET /api/auth/me]:我们是否已经登录?F5 刷新之后,客户端已经忘记了一切;而服务器可以读取 Cookie。200:返回用户;401:没有人(随后加载一个验证码(CAPTCHA));其他情况:服务器没有响应。[async] 函数不能作为副作用本身(副作用返回的是它的清理函数,而不是 promise):我们在副作用内部声明它,再调用它;
  • 第 113–130 行:登录,写成 action ([React] 19,见下文)。它接收之前的状态和表单数据([FormData]),并返回新的状态:
    • 第 114 行:[data.get(name)] 读取表单中的一个字段,由它的 [name] 属性标识;
    • 第 115–119 行:[POST /api/auth/login],带 JSON 请求体:[method]、请求头 [Content-Type],以及由 [JSON.stringify] 生成的请求体。如果成功,服务器会用 JWT 令牌设置 [httpOnly] Cookie:我们的代码永远看不到它(可以在控制台中试试 [document.cookie] :它不在里面);
    • 第 120–126 行:失败:JSON 格式的错误响应体提供消息键;每张验证码(CAPTCHA)图片只能使用一次:随后会加载另一张;
    • 第 127–129 行:成功:先得到用户,然后发出一个 受保护的 请求 [GET /api/doctors]:浏览器会自动带上 Cookie(同源);
  • 第 131 行:[useActionState(action, initialState)] ([React] 19)返回 action 最近一次执行所产生的状态,以及一个要传给表单的 action 版本;
  • 第 134–139 行:登出;[POST /api/auth/logout]:服务器删除 Cookie。每个 POST 都必须带 JSON 请求体(服务器会拒绝其他请求;见上一章):['{}'];
  • 第 165 行:[<form action={function}>]:从 [React] 19 开始,表单的 [action] 属性可以接受一个函数。提交时,[React] 会阻止浏览器提交表单,把各字段汇总成一个 [FormData],并调用该函数,在此期间 [useFormStatus] 显示“进行中”。[onSubmit]、[preventDefault]以及按字段维护的状态都不再需要;
  • 第 168–180 行:这些字段不是受控的:它们由 [name] 标识。每次 action 之后,[React] 都会重置表单:每个字段恢复为它的初始值([defaultValue])。因此密码和验证码(CAPTCHA)字段会被清空;登录名字段则恢复为 action 存入状态中的值([state.login]),也就是刚刚输入的那个值;
  • 第 184 行:最近一次 action 产生的错误消息。

Cookie 属于一台机器(localhost)和一个路径([/api]):因此所有示例共享它。在这里登录之后,示例 24 和 25 也处于登录状态。

Image

密码错误:登录名被保留,并显示一张新图片:

Image

以 [admin] 登录;你可以重新加载页面(F5):仍然保持登录:

Image

8.3. 示例 24:API 访问层

示例 23 对每个请求都重复了相同的步骤:前缀 [/api]、JSON 请求头、检查 [response.ok]、读取错误响应体……示例 24 和 25 把这些都集中放在 [common/] 文件夹中,案例研究也将沿用这种做法。

8.3.1. 类型

// =========================================================================
// common/types.ts - 与 RdvMedecins API 交换的 JSON 对象
// (参见黑盒一章,其中描述了每个路由)
// =========================================================================

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;
}

// 一名医生或一位客户(GET /api/doctors、GET /api/clients……)
export interface Person {
  id: number;
  version: number;
  title: string;
  firstName: string;
  lastName: string;
  login?: string; // 仅限 ADMIN
}

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

// 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;
}

上一章所述 API 的 [TypeScript] 接口翻译。日程中的一行([ScheduleSlot])描述一个时间段,以及已登录用户被授权对它执行的操作。

8.3.2. 错误

// =========================================================================
// common/api-error.ts - 用同一个类表示 API 的所有错误
// -------------------------------------------------------------------------
// RdvMedecins 服务器的所有错误响应都具有相同的形状:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// 但请求也可能以其他方式失败:根本没有响应
// (网络中断:fetch 抛出 TypeError),或者响应并非
// 来自我们的服务器(JSON 服务器停止时 Vite 代理返回的错误页面)。
// 所有这些都被转换成同一个类
// ApiError,它携带服务器发送的翻译键(以及
// 若有的话,它的参数和每个字段的错误)。
// =========================================================================

export class ApiError extends Error {
  readonly statusCode: number; // 0:服务器没有响应
  readonly key: string; // 例如:'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;
  }
}

// 错误响应(4xx、5xx)-> 一个 ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
  // 错误的 JSON 请求体(如果存在且形状正确)
  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 {
    // 不是 JSON:回应的不是我们的服务器
  }
  // 没有键:由代理或网络代为回应
  const key = body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
  return new ApiError(response.status, key, body.params, body.fields);
}
  • 第 14–28 行:所有 API 错误共用一个类:HTTP 状态码(0:没有响应)、服务器发送的翻译键、它的参数,以及被拒绝表单中每个字段的错误。它继承自 [Error]:可以被抛出([throw])并被识别([instanceof ApiError])。[TypeScript] 的“参数属性”([constructor(public readonly key: string)])没有使用:[erasableSyntaxOnly] 选项在 [tsconfig.json] 中禁用了它们,因为它们会生成代码;
  • 第 31–45 行:错误响应会变成一个 [ApiError]。响应体并不总是来自我们服务器的 JSON:当 JSON 服务器关闭时,[Vite] 代理返回的响应没有 JSON 响应体。没有键:状态码为 500 或更高,表示“服务器无法访问”。

8.3.3. 请求

// =========================================================================
// common/api.ts - 一行代码完成对 API 的请求
// -------------------------------------------------------------------------
// 在示例 23 中,每个请求都重复着相同的动作:/api
// 前缀、JSON 头、response.ok 的检测、错误响应体的读取……它们
// 在这里被集中起来:
//
//   const doctors = await api.get<Person[]>('/doctors');
//   await api.post('/appointments', { day, slotId, clientId });
//
//   - 成功时,promise 返回带类型的 JSON 响应体;
//   - 失败时,它会以 ApiError 被 REJECT。
// 所有请求都经过 request 函数:所有请求共有的问题
// 将在这里处理(参见案例研究和
// 401 响应)。供示例 24 和 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,
      // JSON 请求体(服务器会拒绝不是 JSON 的 POST)
      headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  } catch {
    // fetch 没有得到任何响应(网络问题、服务器已停止)
    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),
  // POST 总是带有 JSON 请求体:默认为 {}
  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),
};
  • 第 20–37 行:所有请求都经过这个通用函数:
    • 第 23–28 行:前缀 [/api],以及(如果有请求体)请求头和 JSON;
    • 第 29–32 行:没有响应:状态码为 0 的 [ApiError];
    • 第 33–35 行:错误响应:一个 [ApiError];
    • 第 36 行:成功:带类型的响应体;
  • 第 39–45 行:快捷函数,每种 HTTP 方法一个函数。POST 总是带 JSON 请求体:默认为 [{}] 。

这里是处理所有请求的共同问题的地方:案例研究将在这里处理 401 响应(会话过期)。

8.3.4. 登录栏

// =========================================================================
// common/LoginBar.tsx - 栏中的登录/退出登录
// -------------------------------------------------------------------------
// 示例 23 的表单,精简成一个栏,并用 api.ts 重写。
// 每当登录用户变化时(包括启动时、
// 查询 GET /api/auth/me 之后),组件都会用已登录的用户(或
// null)调用 onUserChange。
// =========================================================================

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('');
  }

  // 启动时:我们是否已经登录?
  const start = useEffectEvent(async () => {
    try {
      changeUser(await api.get<User>('/auth/me'));
    } catch {
      changeUser(null); // 401:无人登录
      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)} />
          {/* 验证码的 SVG 图像,由我们自己的服务器生成(参见示例 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>
  );
}

示例 23 的表单,缩减为一个栏,并使用 [api.ts] 重写(为了对比,字段带有验证):

  • 第 17 行:每当已登录的用户变化时,组件就通知它的父组件;
  • 第 39–46 行和第 47–49 行:启动时,[GET /api/auth/me]。副作用调用的函数通知父组件:[useEffectEvent] 避免把它变成依赖项(见示例 13);
  • 第 55 行:一行代码的请求;如果失败,抛出 [ApiError];
  • 第 86 行:验证码(CAPTCHA)图片,用一个小样式表缩放到与栏相同的高度:
1
2
3
4
5
6
7
8
/* 验证码的 SVG 图像,原样插入页面:它会被缩小
   to the height of the bar. An imported style sheet applies to the
   WHOLE page: the .captcha-bar class limits it to our element. */
.captcha-bar svg {
  display: block;
  height: 32px;
  width: auto;
}

8.3.5. API 访问层

// =========================================================================
// 24-api-layer/src/rdvmedecins.ts - API 访问层
// -------------------------------------------------------------------------
// API 的每个路由对应一个带类型的函数。组件既不知道
// URL,也不知道 fetch,更不知道 JSON 格式:它们只调用函数。
// 这相当于服务器端 DAO 层在客户端的对应物:如果 API
// 发生变化(URL、字段名),只需修改这个文件。
// =========================================================================

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 构建出 "doctorId=1&day=2030-01-15",并对需要编码的内容进行编码
  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}`),
};

每个 API 路由对应一个带类型的函数。组件不需要了解 URL、[fetch] 或 JSON 格式:它们只调用函数。这相当于服务器端 DAO 层在客户端的对应物:如果 API 发生变化(某个 URL、某个字段名),只需修改这个文件。[URLSearchParams] (第 18 行)通过对所需数据进行编码,生成地址中的 [doctorId=1&day=2030-01-15] 部分。

8.3.6. TanStack Query

像示例 22 那样在副作用中读取服务器数据,需要处理所有事情:“进行中”状态、错误、过期响应、取消、重复发送两次的请求,以及已经收到、本可复用的数据……[TanStack Query] (以前叫 [React Query])是为此目的使用最广泛的库,它会处理所有这些事情。

// =========================================================================
// 24-api-layer/src/main.tsx
// -------------------------------------------------------------------------
// TanStack Query(原名 React Query):React 应用中最常用的
// 读取服务器数据的库。
// QueryClient 把已收到的响应保存在内存中(即“缓存”);
// <QueryClientProvider> 把它提供给整个应用(一个上下文(Context),
// 参见示例 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({
  // 失败时不再重试:我们想看到错误
  defaultOptions: { queries: { retry: false } },
});

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);
  • 第 17 行:[TanStack Query] 客户端,它把先前收到的响应存放在内存中(“缓存”);[retry: false]:失败时不重试(默认会尝试三次);
  • 第 24 行:它通过上下文提供给整个应用(见示例 14)。

8.3.7. 页面

// =========================================================================
// 24-api-layer/src/App.tsx - 使用 API 访问层的日程
// -------------------------------------------------------------------------
// 登录(顶部栏),选择医生和日期:随即显示日程
// 。ADMIN 和 DOCTOR 可以为患者预约和取消预约;
// 患者(martin……)为自己预约。每个操作之后
// 都会重新加载日程:以服务器为准。
//
// useQuery({ queryKey, queryFn }):数据的一次读取,由以下内容描述
//   - queryFn:获取数据的函数(一个 promise);
//   - queryKey:标识这些数据的内容:['schedule', doctorId, day]。
// TanStack Query 一开始会调用 queryFn,之后每当键
// 变化(换了医生、换了日期)时再次调用。它返回一个对象:data(响应)、
// isPending、isFetching、error……以及用于再次读取的 refetch()。
// 它还处理了用 useEffect 时必须手工编写的那些事:取消
// 过期的响应、避免重复发送同一个请求、
// 把响应保存在缓存中。
// =========================================================================

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)}`;
}

// 一个错误 -> 一段文字(这里没有字典,就用它的键)
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';

  // 医生,然后(ADMIN、DOCTOR)是客户:当
  // 用户变化时重新读取(用户是键的一部分)
  const doctors = useQuery({
    queryKey: ['doctors', user?.login],
    queryFn: rdvmedecins.getDoctors,
    enabled: loggedIn, // false:不发请求(无人登录)
  });
  const clients = useQuery({
    queryKey: ['clients', user?.login],
    queryFn: rdvmedecins.getClients,
    enabled: isManager, // USER 会收到 403
  });

  // 日程:键中包含医生和日期
  const schedule = useQuery({
    queryKey: ['schedule', doctorId, day, user?.login],
    queryFn: () => rdvmedecins.getSchedule(doctorId!, day),
    enabled: loggedIn && doctorId !== null,
  });

  // 重新选择医生或日期会清除之前的消息
  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 && (
            <>
              {/* 提示:患者已有一个即将到来的预约时,服务器发送的键 */}
              {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">
                        {/* 按钮遵循由服务器计算出的权限 */}
                        {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>
  );
}
  • 第 54–58 行:[useQuery({ queryKey, queryFn, enabled })] 描述对数据的读取:
    • [queryFn]:获取数据的函数,返回一个 promise;
    • [queryKey]:标识数据的内容——一个数组。[TanStack Query] 先调用 [queryFn],之后每当键变化时再次调用;请求同一个键的两个组件共享同一个请求和同一个响应。用户被加入其中:当用户变化时,列表会被重新加载;
    • [enabled: false]:不发请求(没有人登录);
    • 结果是一个对象:[data] (响应,在它到达之前为 [undefined] )、[isPending]、[isFetching] (有请求正在进行)、[error],以及用于重新读取的 [refetch()] ;
  • 第 59–63 行:患者列表,仅限 ADMIN 和 DOCTOR(USER 会收到 403);
  • 第 66–70 行:日程:键中包含医生和日期;改变其中任何一个都会发出新请求。过期的响应会被自动忽略;
  • 第 82–90 行:预约:[POST /api/appointments],然后 [schedule.refetch()]:重新读取日程。以服务器为准;
  • 第 106 行:登录栏通知页面;
  • 第 114 行:医生列表,如果它们已经到达([?.]:如果 [data] 是 [undefined],则什么都没有);
  • 第 133 行:日程请求正在进行;
  • 第 160–161 行:按钮遵循服务器计算出的权限;
  • 第 138 行:[info]:当患者已经有一个即将到来的预约时,服务器发送的键(原样显示:这里没有词典)。

以 [admin] 登录后,我们选择 PELISSIER 医生,再选择一位患者,并预约第一个时间段:

Image

以 [martin] 登录后,我们预约一个时间段:患者看到自己的姓名,但永远不会收到其他患者的姓名;“预约”按钮不再可用(只能有一个即将到来的预约):

Image

对于事务性操作(预约、取消),[TanStack Query] 还提供了 [useMutation],它处理修改操作的“进行中”状态和错误。我们在这里不使用它:一个 [async] 函数加一个 [try / catch] 就足够了。

8.4. 示例 25:服务器返回的错误

患者管理([admin] 表单)。这个表单在浏览器中不做任何验证:一切都发送给服务器,服务器在拒绝时返回一个 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. 词典

{
  "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."
  }
}

键 [ERRORS.*] 就是服务器返回的那些键。英文词典 [en.json] 有同样的键。[i18next] 的配置与示例 21 相同,但更简单:

// =========================================================================
// 25-server-errors/src/i18n/i18n.ts - i18next,与示例 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(参见示例 21);
//   - 示例 16 的确认对话框,原样复用。
// =========================================================================

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>,
);

示例 16 中的确认窗口被原样复用:只需导入它的提供者。

8.4.2. 页面

// =========================================================================
// 25-server-errors/src/App.tsx - 显示服务器的错误
// -------------------------------------------------------------------------
// 客户管理(管理员账户)。这个表单有意
// 不在浏览器中做任何验证:所有内容都发送
// 给服务器,被拒绝时服务器会返回一个 JSON 错误(由 common/api.ts
// 转换成 ApiError):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (乐观锁)
//
// 每个字段的错误(ApiError.fields)保存在状态中,并
// 显示在该字段下方;它的消息是服务器发送的键
// ,由组件负责翻译(i18next)。修改字段会清除它的错误。
// 试试:空的姓氏、称谓 "Dr"、同名同姓者(Alice DURAND)、
// 已被占用的登录名(martin)、在两个标签页中编辑同一条记录……
// =========================================================================

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';

  // 表单:editedId === null -> 创建,否则为更新
  const [editedId, setEditedId] = useState<number | null>(null);
  const [input, setInput] = useState<ClientInput>(EMPTY);
  // 每个字段的错误(一个翻译键),由服务器返回
  const [errors, setErrors] = useState<Partial<Record<Field, string>>>({});
  // 最近一次错误的总体消息,以及成功时的消息
  const [pageError, setPageError] = useState<ApiError | null>(null);
  const [success, setSuccess] = useState<Message | null>(null);
  // useTransition:在传给 startTransition 的 action 执行期间 isPending 为 true
  // - 这里就是向服务器发送的过程
  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);
    // 随记录一起读取的 VERSION 会随更新一并回传:如果有人
    // 在此期间修改了该记录,服务器将返回 409 CONCURRENT_UPDATE
    setInput({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
    clearMessages();
  }

  // 被修改的字段:它的值改变,它的错误消失
  function change(field: Field, value: string) {
    setInput((s) => ({ ...s, [field]: value }));
    setErrors((e) => ({ ...e, [field]: undefined }));
  }

  function save(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    clearMessages();
    // 一个异步 transition(React 19):sending 一直为 true,直到
    // 函数结束
    startTransition(async () => {
      try {
        const client =
          editedId === null
            ? await api.post<Person>('/clients', input)
            : await api.put<Person>(`/clients/${editedId}`, input);
        newForm(); // 表单已清空,消息已清除……
        // ……除了这一条
        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); // 总体消息
        setErrors(e.fields); // 每个字段的错误
      }
    });
  }

  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();
  }

  // 一个输入字段,带有已翻译的错误
  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)} />
        {/* 服务器错误的消息是一个键:它会被翻译 */}
        {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>
                {/* 一个服务器会拒绝的选项 "Dr":用来看到 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>}
              {/* 总体消息和 HTTP 状态,以便理解 */}
              {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>
  );
}
  • 第 54–55 行:表单:[editedId === null] 表示创建患者,否则 [editedId] 表示修改患者;
  • 第 57 行:每个字段的错误,是服务器返回的一个翻译键;
  • 第 63 行:[useTransition] 返回一个“进行中”标志和一个函数 [startTransition(action)]。从 [React] 19 开始,action 可以是 [async]:在函数结束之前,该指示器一直为 true,无需任何手工处理;
  • 第 89–95 行:修改患者。从主记录中读取的版本号(VERSION)反映了这次修改:如果在此期间有人修改了主记录,服务器会返回 409 [ERRORS.CONCURRENT_UPDATE] (乐观锁);
  • 第 98–101 行:被修改的字段:它的值改变,它的错误消失;
  • 第 103–129 行:发送:
    • [POST /api/clients] (创建)或 [PUT /api/clients/:id] (更新);
    • 如果成功:表单被清空,并翻译一条带参数的消息;
    • 对于 [ApiError] (第 125–126 行):显示总体消息和每个字段的错误;行就保持报告中的样子:[e.fields] 的格式正好是所需要的;
  • 第 131–144 行:确认之后删除。确认消息由 [t] 翻译,并带一个参数;
  • 第 147–158 行:一个创建输入字段及其标签和错误消息的函数:[t(error)] 翻译服务器发送的键;
  • 第 164 行:选择语言:已经显示的错误会被重新翻译,因为它们是键;
  • 第 199 行:一个服务器会拒绝的“Dr”选项,结果是 [ERRORS.INVALID_TITLE];
  • 第 212 行:发送期间按钮被禁用;
  • 第 219 行:总体消息和 HTTP 状态码,作为上下文。

以 [admin] 登录,使用称谓“Dr”、空姓名和无效的登录名:

Image

一个同名同姓者(已存在的 Alice Durand)和一个已被使用的登录名([martin]):409,两个相关的字段都被标出:

Image

同一个页面的法语版:服务器的消息被翻译回法语:

Image

添加成功:

Image

然后是删除它:

Image

Image

要观察乐观锁,请在两个标签页中打开同一条记录,先在第一个标签页中保存,再在第二个标签页中保存:服务器会返回 409 错误([ERRORS.CONCURRENT_UPDATE])。