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):
| proxy: {
'/api': 'http://localhost:8080',
},
|
浏览器向 [GET http://localhost:5173/api/captcha] 发送请求;开发服务器把请求转发到 [http://localhost:8080/api/captcha],然后把响应送回浏览器。从浏览器的角度看,页面和 API 具有 同一个源:

在生产环境中,将不再有开发服务器: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 行:一个新的请求;副作用再次被触发。

如果 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 也处于登录状态。

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

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

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)图片,用一个小样式表缩放到与栏相同的高度:
| /* 验证码的 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 医生,再选择一位患者,并预约第一个时间段:

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

对于事务性操作(预约、取消),[TanStack Query] 还提供了 [useMutation],它处理修改操作的“进行中”状态和错误。我们在这里不使用它:一个 [async] 函数加一个 [try / catch] 就足够了。
8.4. 示例 25:服务器返回的错误
患者管理([admin] 表单)。这个表单在浏览器中不做任何验证:一切都发送给服务器,服务器在拒绝时返回一个 JSON 错误:
| 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”、空姓名和无效的登录名:

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

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

添加成功:

然后是删除它:


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