8. 与服务器通信
本章的示例会查询 JSON 服务器 [RdvMedecins]:它必须处于运行状态(在 [npm run start:dev] 文件夹 [rdvmedecins-nestjs-json] 中,端口 8080),并与端口 4200 上的 [Angular] 开发服务器同时运行。
8.1. 示例 22:第一个 HTTP 请求
8.1.1. 开发服务器的代理
示例页面来自 http://localhost:4200([Angular] 开发服务器,由 [ng serve] 启动);API 位于 http://localhost:8080。对浏览器而言,这是两个不同的 源 (端口是源的一部分)。然而,出于安全原因,除非服务器明确允许(即所谓的 CORS 机制),浏览器不允许页面读取来自另一个源的响应。并且发往另一个源的请求不会携带 Cookie(因此也不会携带令牌),除非代码请求这样做([withCredentials: true])并且服务器也接受,这同样要通过 CORS 实现。
我们不向其他源开放服务器,而是让 API 请求经由 [Angular] 开发服务器转发。这就是 代理 ,声明于工作区文件 [proxy.conf.json]:
| {
"/api": {
"target": "http://localhost:8080",
"secure": false
}
}
|
- 第 2 行:路径以 /api 开头的请求……
- 第 3 行:……会被转发到 JSON 服务器。
对于每个示例,该文件都在 [ng serve] 命令的选项中指定,位于 [angular.json] 文件里:
| "serve": {
"builder": "@angular/build:dev-server",
"options": {
"proxyConfig": "proxy.conf.json"
},
|
浏览器发送 [GET http://localhost:4200/api/captcha];开发服务器将请求转发到 [http://localhost:8080/api/captcha],然后把响应返回给浏览器。对浏览器来说,页面和 API 具有同一个源:

在生产环境中,将不再有开发服务器:JSON 服务器本身会提供编译后的客户端文件(见“部署”一章)。页面和 API 仍然共享同一个源。
8.1.2. 请求
[Angular] 提供了自己的 HTTP 客户端,即服务 [HttpClient]。它在任何应用中都自动可用:只需注入即可。
| // =========================================================================
// 22-httpclient/src/app/app.ts - 向服务器发出的第一个 HTTP 请求
// -------------------------------------------------------------------------
// RdvMedecins JSON 服务器必须处于运行状态(端口 8080)。我们向它请求
// 一个验证码:GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }。
//
// - HttpClient:Angular 的 HTTP 客户端(默认提供给整个
// 应用)。http.get<T>(url) 返回一个 OBSERVABLE(参见示例
// 19):只有在订阅(subscribe)时才会真正发送请求;
// JSON 响应到达时已转换为对象,类型即声明的类型 T;
// - 地址是相对的(/api/captcha):请求发往页面
// 所在的服务器,即 Angular 的服务器(端口 4200),再由它的代理
// 转发到 JSON 服务器(端口 8080)(参见 proxy.conf.json);
// - 三种需要显示的状态:加载中、成功、出错。
// =========================================================================
import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
// GET /api/captcha 返回的内容
interface Captcha {
id: string;
svg: string;
}
@Component({
selector: 'app-root',
templateUrl: './app.html',
styles: `
.captcha {
display: inline-block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
`,
})
export class App {
private readonly http = inject(HttpClient);
private readonly sanitizer = inject(DomSanitizer);
protected readonly captcha = signal<Captcha | null>(null);
protected readonly loading = signal(false);
protected readonly error = signal<string | null>(null);
protected readonly requestCount = signal(0);
// [innerHTML] 会将字符串作为 HTML 插入。出于安全考虑,Angular
// 会清理(CLEANS)这段 HTML(“净化”):移除脚本……以及
// <svg> 标签。bypassSecurityTrustHtml 则告诉 Angular:"这段 HTML 是
// 安全的,不要清理"。仅可用于安全的内容:此 SVG
// 由我们自己的服务器生成。若是用户输入,就等于
// 为脚本注入敞开大门(而 {{ }} 则会转义所有内容)。
protected readonly svg = computed<SafeHtml | null>(() => {
const c = this.captcha();
return c ? this.sanitizer.bypassSecurityTrustHtml(c.svg) : null;
});
constructor() {
this.load(); // 启动时,加载验证码
}
protected load(): void {
this.loading.set(true);
this.error.set(null);
this.http.get<Captcha>('/api/captcha').subscribe({
// next:响应(2xx 状态码),已从 JSON 转换完成
next: (captcha) => {
this.captcha.set(captcha);
this.requestCount.update((n) => n + 1);
this.loading.set(false);
},
// error:4xx / 5xx 响应,或根本没有响应(状态码 0)
error: (e: HttpErrorResponse) => {
this.error.set(`the server answered ${e.status} ${e.statusText}`);
this.captcha.set(null);
this.loading.set(false);
},
});
}
}
|
- 第 22 行:来自 [GET /api/captcha] 的响应格式;
- 第 39 行:注入 HTTP 客户端;
- 第 42–45 行:请求的三种状态:进行中、成功(得到验证码)和错误;
- 第 65 行:[http.get<Captcha>(url)] 准备一个 GET 请求。它返回一个可观察对象 (示例 19):只有在被订阅([subscribe])时才会发送请求。该地址是相对地址:请求被发送到页面所在的服务器,再由它转发给 JSON 服务器;
- 第 67–71 行:[next] 接收已从 JSON 转换好的响应。[<Captcha>] 向 [TypeScript] 说明对象的格式:编译器无法验证服务器将发送什么;
- 第 73–77 行:[error] 会在收到任何 4xx 或 5xx 响应时接收一个 [HttpErrorResponse] ,在没有收到响应时(服务器宕机、网络断开:此时 [status] 为 0)也是如此。如果 JSON 服务器宕机,代理会以 5xx 错误响应;
- 第 59 行:启动时加载一个验证码(CAPTCHA);
- 第 53–56 行:来自验证码(CAPTCHA)的 SVG 图像是一个字符串,必须作为 HTML 插入(模板中的 [[innerHTML]] )。出于安全原因,[Angular] 会清理以这种方式插入的任何 HTML:它会移除脚本……以及 [<svg>] 标签。[bypassSecurityTrustHtml] 表明这段 HTML 是安全的。我们只对安全内容使用它:这个 SVG 由我们自己的服务器生成。对于用户输入的数据,这会允许脚本被注入页面;而双花括号 [{{ }}] 则会对一切进行转义。
| <div class="container py-4" style="max-width: 640px">
<h1 class="h3 mb-3">Example 22 - a first HTTP request</h1>
<div class="card p-3">
@if (loading()) {
<p class="text-muted">Loading...</p>
} @else if (error()) {
<div class="alert alert-danger mb-3">
Unable to get a captcha: {{ error() }}.<br>
Is the RdvMedecins JSON server running (port 8080)?
</div>
} @else if (captcha(); as c) {
<div class="mb-2"><div class="captcha" [innerHTML]="svg()"></div></div>
<p class="small text-muted">id: <code>{{ c.id }}</code></p>
}
<button class="btn btn-primary align-self-start" [disabled]="loading()" (click)="load()">Another image</button>
<p class="small text-muted mt-2 mb-0">{{ requestCount() }} successful request(s) - open the Network tab of the developer tools (F12).</p>
</div>
</div>
|
- 第 4–14 行:状态显示;
- 第 12 行:验证码(CAPTCHA)图像。
[npm start 22-httpclient];点击 [Another image]:

在浏览器的开发者工具(F12)中,“网络”选项卡显示请求 [captcha],它被发送到 [localhost:4200],以及它的 JSON 响应。
8.2. 示例 23:登录、Cookie 和会话
| // =========================================================================
// 23-login/src/app/app.ts - 登录 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。
//
// firstValueFrom(observable):返回流中第一个值的 PROMISE。
// 这样,请求链就可以用 async / await 来编写,
// 比层层嵌套的 subscribe 更易读。错误响应会使
// promise 以 HttpErrorResponse 被拒绝:用简单的 try / catch 即可处理。
//
// Cookie 属于某台机器(localhost)和某个路径(/api):因此
// 所有示例共用它。在这里登录之后,示例
// 24 和 25 也处于已登录状态。
// =========================================================================
import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import { firstValueFrom } from 'rxjs';
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 将使用 ngx-translate)
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.',
};
@Component({
selector: 'app-root',
imports: [FormsModule],
templateUrl: './app.html',
})
export class App {
private readonly http = inject(HttpClient);
private readonly sanitizer = inject(DomSanitizer);
protected readonly user = signal<User | null>(null);
protected readonly doctors = signal<Doctor[]>([]);
protected readonly captcha = signal<Captcha | null>(null);
protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
protected readonly login = signal('admin');
protected readonly password = signal('');
protected readonly captchaAnswer = signal('');
protected readonly error = signal<string | null>(null);
protected readonly ready = signal(false); // 初始检查是否已完成?
constructor() {
this.checkSession().catch(() => {
this.error.set('Is the RdvMedecins JSON server running (port 8080)?');
this.ready.set(true);
});
}
protected async loadCaptcha(): Promise<void> {
this.captcha.set(await firstValueFrom(this.http.get<Captcha>('/api/captcha')));
this.captchaAnswer.set('');
}
// 1. 谁已登录?200 -> 用户;401 -> 无人登录
private async checkSession(): Promise<void> {
try {
this.user.set(await firstValueFrom(this.http.get<User>('/api/auth/me')));
await this.loadDoctors();
} catch (e) {
if (!(e instanceof HttpErrorResponse) || e.status !== 401) {
throw e; // 不是 401:服务器没有响应
}
await this.loadCaptcha();
}
this.ready.set(true);
}
// 2. 登录;post(url, body):请求体以 JSON 发送
protected async logIn(): Promise<void> {
this.error.set(null);
try {
const u = await firstValueFrom(
this.http.post<User>('/api/auth/login', {
login: this.login(),
password: this.password(),
captchaId: this.captcha()?.id,
captcha: this.captchaAnswer(),
}),
);
this.user.set(u);
this.password.set('');
await this.loadDoctors();
} catch (e) {
// e.error:错误响应的 JSON 请求体
const apiError = (e as HttpErrorResponse).error as ApiError | null;
const key = apiError?.key ?? 'ERRORS.SERVER_UNREACHABLE';
this.error.set(`${(e as HttpErrorResponse).status} - ${MESSAGES[key] ?? key}`);
await this.loadCaptcha(); // 每张图片只使用一次
}
}
// 3. 受保护的请求
private async loadDoctors(): Promise<void> {
this.doctors.set(await firstValueFrom(this.http.get<Doctor[]>('/api/doctors')));
}
// 4. 登出
protected async logOut(): Promise<void> {
await firstValueFrom(this.http.post('/api/auth/logout', {}));
this.user.set(null);
this.doctors.set([]);
await this.loadCaptcha();
}
}
|
- 第 30–50 行:与服务器交换的数据格式,包括 API 所有错误的格式(第 46–50 行);
- 第 53–57 行:本示例所需的少量消息,使用英文;示例 25 将使用 [ngx-translate];
- 第 28 行:[firstValueFrom(observable)] 返回一个关于流中第一个值的 Promise 。HTTP 请求只产生一个值——响应:这样我们就可以使用 [async] / [await] 编写请求链,这比层层嵌套的 [subscribe] 更易读。错误响应会使 Promise 被拒绝(rejected):一个简单的 [try / catch] 就能捕获它;
- 第 91–102 行:启动时执行 [GET /api/auth/me]:我们是否已经登录?重新加载页面(F5)之后,[Angular] 应用忘记了一切;然而服务器会读取 Cookie。200:返回用户;401:无人登录——这种情况下会显示登录表单及其验证码(CAPTCHA)(第 99 行);
- 第 96 行:任何其他错误都表示服务器没有响应;它会被报告给开发者(第 79–82 行);
- 第 105–126 行:登录:
- 第 109 行:[http.post(url, body)]:对象 [body] 以 JSON 形式发送,并带有请求头 [Content-Type: application/json];
- 第 116 行:如果成功,服务器已经设置了令牌 Cookie。我们的代码绝对看不到它:在浏览器控制台中输入 [document.cookie] ,它不在其中([HttpOnly]);
- 第 121 行:如果请求失败,[error] 包含 JSON 响应体,其中解释了原因。我们显示该消息(第 123 行),并请求一张新图像(第 124 行):每张图像只能使用一次;
- 第 129–131 行:受保护的请求。无需任何操作来进行身份验证:浏览器会自动带上 Cookie,因为该请求发往与页面相同的源;
- 第 134–139 行:注销——服务器删除 Cookie。请求体 [{}] 的加入使该请求成为一个 JSON POST 请求。
Cookie 属于一台机器(localhost)和一个路径(/api);因此它被所有示例共享。在这里登录一次之后,示例 24 和 25 也处于登录状态。
登录表单:
| <div class="container py-4" style="max-width: 640px">
<h1 class="h3 mb-3">Example 23 - logging in to the server</h1>
@if (!ready()) {
<p class="text-muted">Checking the session...</p>
} @else if (user(); as u) {
<!-- 已登录 -->
<div class="card p-3">
<p>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role <span class="badge text-bg-primary">{{ u.role }}</span></p>
<h2 class="h6">GET /api/doctors</h2>
<ul>
@for (m of doctors(); track m.id) {
<li>{{ m.title }} {{ m.firstName }} {{ m.lastName }}</li>
}
</ul>
<p class="small text-muted">Reload the page (F5): you stay logged in.</p>
<button class="btn btn-outline-secondary align-self-start" (click)="logOut()">Log out</button>
</div>
} @else {
<!-- 未登录:显示表单 -->
<form class="card p-3" (ngSubmit)="logIn()">
<div class="mb-2">
<label class="form-label" for="login">Login</label>
<input id="login" name="login" class="form-control" autocomplete="username" [(ngModel)]="login">
</div>
<div class="mb-2">
<label class="form-label" for="password">Password</label>
<input id="password" name="password" type="password" class="form-control" autocomplete="current-password"
[(ngModel)]="password">
</div>
<div class="mb-3">
<label class="form-label" for="captcha">Copy the characters of the image</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div [innerHTML]="svg()"></div>
<a href="#" class="small" (click)="$event.preventDefault(); loadCaptcha()">Another image</a>
</div>
<input id="captcha" name="captcha" class="form-control" autocomplete="off" [(ngModel)]="captchaAnswer">
</div>
<button class="btn btn-primary">Log in</button>
<p class="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
</form>
}
@if (error()) {
<div class="alert alert-danger mt-3">{{ error() }}</div>
}
</div>
|
- 第 3 行:在初始验证完成之前,我们不知道该显示什么;
- 第 5–17 行:已登录:显示用户和医生列表;
- 第 20–40 行:未登录:显示表单,使用 [ngModel] (示例 05);
- 第 34 行:[$event.preventDefault()] 阻止链接跳转到其地址(#)。
[npm start 23-login]。输入错误的密码时(服务器处于测试模式:任何验证码(CAPTCHA)都接受响应 [test]):

输入正确的密码,然后刷新页面(F5):你仍保持登录状态。

8.3. 示例 24:API 的访问层
在示例 23 中,每个请求都重复相同的步骤:/api 前缀、[firstValueFrom]、读取错误响应体,以及选择消息。本示例把它们归并到几个文件中,这些文件位于工作区的 [common] 文件夹 中,因为示例 25 也会用到它们:
| examples-angular/common/
├── types.ts API 的 JSON 对象
├── api-error.ts 所有 API 错误的类
├── errors.interceptor.ts HTTP 拦截器
├── api.service.ts 单行请求
└── login-bar.ts 栏中的登录
|
示例中的 [tsconfig.app.json] 文件把该文件夹加入要编译的文件中:
| {
"extends": "../tsconfig.json",
"include": ["src/**/*.ts", "../common/**/*.ts"]
}
|
8.3.1. 类型
API 中 JSON 对象的类型,已在上一章中描述:
| // =========================================================================
// 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;
}
|
8.3.2. 错误
| // =========================================================================
// common/api-error.ts - 用一个类处理 API 的所有错误
// -------------------------------------------------------------------------
// RdvMedecins 服务器的所有错误响应都具有相同的结构:
// { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// HttpClient 用 HttpErrorResponse 来报告它们,其 error 属性
// 包含这个 JSON 请求体……或者其他内容:null(没有响应)、文本
// (JSON 服务器停止时代理返回的错误页面)。我们把这一切
// 转换成一个类 ApiError,它携带服务器发送的翻译键
// (以及它的参数,如果有的话,还有
// 每个字段的错误)。
// =========================================================================
import { HttpErrorResponse } from '@angular/common/http';
export class ApiError extends Error {
constructor(
public readonly statusCode: number, // 0:服务器没有响应
public readonly key: string, // 例如:'ERRORS.LOGIN_TAKEN'
public readonly params: Record<string, string> = {},
public readonly fields: Record<string, string> = {},
) {
super(key);
this.name = 'ApiError';
}
}
// 任何错误 -> 一个 ApiError
export function toApiError(e: unknown): ApiError {
if (e instanceof ApiError) {
return e;
}
if (!(e instanceof HttpErrorResponse)) {
return new ApiError(0, 'ERRORS.SERVER_ERROR');
}
// 错误的 JSON 请求体,如果存在且结构正确
const body = (typeof e.error === 'object' && e.error !== null ? e.error : {}) as {
key?: string;
params?: Record<string, string>;
fields?: Record<string, string>;
};
// 没有 key:响应的不是我们的服务器(代理、网络)
const key = body.key ?? (e.status === 0 || e.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
return new ApiError(e.status, key, body.params, body.fields);
}
|
- 第 16–26 行:一个包含服务器响应的错误类:HTTP 状态码、消息键、其参数,以及每个字段的错误。状态码 0 表示“没有响应”;
- 第 29–45 行:将任何错误转换为 [ApiError]:
- 第 37 行:只有当响应体是对象时才使用它。当 JSON 服务器宕机时,代理会以文本响应;
- 第 43 行:没有键,说明响应的不是我们的服务器。
8.3.3. 拦截器
拦截器 是一个函数,[HttpClient] 的请求及其响应都会经过它。它可以在请求发送之前修改请求(例如添加请求头),或在响应返回时修改响应。
| // =========================================================================
// common/errors.interceptor.ts - 一个 HTTP 拦截器
// -------------------------------------------------------------------------
// 拦截器是一个函数,HttpClient 的所有请求
// (及其响应)都要经过它。它接收请求(req)和链中的其余部分
// (next):
// - next(req) 发送请求并返回响应的 observable;
// - 可以事先修改请求(req.clone({...})),也可以事后
// 修改响应(对 observable 使用 RxJS 操作符)。
// 这个拦截器把任何错误转换成 ApiError(catchError):应用的其余部分
// 再也不用处理 HttpErrorResponse。
// 它在应用的配置中声明:
// provideHttpClient(withInterceptors([errorsInterceptor]))
// =========================================================================
import { HttpInterceptorFn } from '@angular/common/http';
import { catchError, throwError } from 'rxjs';
import { toApiError } from './api-error';
export const errorsInterceptor: HttpInterceptorFn = (req, next) =>
next(req).pipe(catchError((e: unknown) => throwError(() => toApiError(e))));
|
- 第 20 行:拦截器接收请求([req])和链的其余部分([next])。[next(req)] 发送请求并返回响应的可观察对象;
- 第 21 行:[catchError] 操作符将流中的任何错误替换为一个 [ApiError]。应用的其余部分再也不必处理 [HttpErrorResponse] 了。
8.3.4. ApiService 服务
| // =========================================================================
// common/api.service.ts - 一行代码完成对 API 的请求
// -------------------------------------------------------------------------
// 在示例 23 中,每个请求都重复相同的步骤:/api
// 前缀、firstValueFrom、读取错误请求体……我们在这里把它们统一起来:
//
// const doctors = await this.api.get<Person[]>('/doctors');
// await this.api.post('/appointments', { day, slotId, clientId });
//
// - 成功时,promise 返回带类型的 JSON 请求体;
// - 失败时,它以 ApiError 被拒绝(得益于
// errors.interceptor.ts 拦截器)。
// 示例 24 和 25 使用它;案例研究沿用了它的原理。
// =========================================================================
import { inject, Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
@Injectable({ providedIn: 'root' })
export class ApiService {
private readonly http = inject(HttpClient);
get<T>(url: string): Promise<T> {
return firstValueFrom(this.http.get<T>(`/api${url}`));
}
// POST 总是带有 JSON 请求体(服务器会拒绝没有请求体的 POST)
post<T>(url: string, body: unknown = {}): Promise<T> {
return firstValueFrom(this.http.post<T>(`/api${url}`, body));
}
put<T>(url: string, body: unknown): Promise<T> {
return firstValueFrom(this.http.put<T>(`/api${url}`, body));
}
delete<T>(url: string, body?: unknown): Promise<T> {
return firstValueFrom(this.http.delete<T>(`/api${url}`, { body: body }));
}
}
|
- 第 24–39 行:每个 HTTP 动词对应一个方法。每个方法都会添加 /api 前缀,并返回响应体的 Promise ,其类型为:[api.get<Person[]>('/doctors')] 返回一个 [Promise<Person[]>]。失败时,该 Promise 会以 [ApiError] 被拒绝;
- 第 29 行:[post] 默认发送请求体 [{}]:服务器会拒绝不是 JSON 的 POST 请求。
8.3.5. API 访问层
| // =========================================================================
// 24-api-service/src/app/rdvmedecins.service.ts - API 访问层
// -------------------------------------------------------------------------
// API 的每条路由对应一个带类型的方法。组件既不知道
// URL,也不知道 HttpClient,更不知道 JSON 格式:它们只调用方法。
// 这相当于服务器端 DAO 层在客户端的对应物:如果 API
// 发生变化(URL、字段名),只需修改这个文件。
// =========================================================================
import { inject, Injectable } from '@angular/core';
import { HttpResourceRequest } from '@angular/common/http';
import { ApiService } from '../../../common/api.service';
import { Person } from '../../../common/types';
@Injectable({ providedIn: 'root' })
export class RdvMedecinsService {
private readonly api = inject(ApiService);
getDoctors(): Promise<Person[]> {
return this.api.get<Person[]>('/doctors');
}
getClients(): Promise<Person[]> {
return this.api.get<Person[]>('/clients');
}
// 日程请求的描述,供 httpResource 使用(参见 app.ts);
// params 构建 "?doctorId=1&day=2030-01-15",并对需要编码的部分进行编码
scheduleRequest(doctorId: number, day: string): HttpResourceRequest {
return { url: '/api/schedule', params: { doctorId, day } };
}
book(day: string, slotId: number, clientId?: number): Promise<{ id: number }> {
return this.api.post<{ id: number }>('/appointments', { day, slotId, clientId });
}
cancelAppointment(appointmentId: number): Promise<Record<string, never>> {
return this.api.delete<Record<string, never>>(`/appointments/${appointmentId}`);
}
}
|
API 的每条路由对应一个方法。组件不再知道地址、[HttpClient]或 JSON 格式:它们只调用方法。这相当于服务器端数据访问层在客户端的对应物:如果 API 发生变化,只需修改这个文件。
- 第 29–31 行:日程请求的描述 ,而不是请求本身:它将由 [httpResource] 使用(见下文)。[params] 通过对需要编码的字符进行编码,生成字符串 [?doctorId=1&day=2030-01-15] 。
8.3.6. 登录栏
示例 23 中的表单,缩减为一个栏,并使用 [ApiService] 重写:
| // =========================================================================
// common/login-bar.ts - 登录 / 登出,集于一个栏中
// -------------------------------------------------------------------------
// 示例 23 的表单,缩减为一个栏,并用
// ApiService 重写。每当已登录用户发生变化时(包括启动时
// 查询 GET /api/auth/me 之后),组件都会用该用户
// (或 null)触发 userChange。
//
// ViewEncapsulation.None:组件的样式应用于整个
// 页面。此处必须如此:由 [innerHTML] 插入的验证码 <svg> 不带有
// Angular“封装”样式所要求的属性。
// =========================================================================
import { Component, computed, inject, output, signal, ViewEncapsulation } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DomSanitizer } from '@angular/platform-browser';
import { ApiService } from './api.service';
import { ApiError } from './api-error';
import { Captcha, User } from './types';
@Component({
selector: 'app-login-bar',
imports: [FormsModule],
encapsulation: ViewEncapsulation.None,
styles: `
.login-bar-captcha svg {
display: block;
height: 32px;
width: auto;
}
`,
template: `
<div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
@if (user(); as u) {
<span>Logged in: <strong>{{ u.name }}</strong> <span class="badge text-bg-primary ms-1">{{ u.role }}</span></span>
<button class="btn btn-sm btn-outline-secondary ms-auto" (click)="logOut()">Log out</button>
} @else {
<form class="d-flex flex-wrap align-items-center gap-2 w-100" (ngSubmit)="logIn()">
<input name="login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username"
[(ngModel)]="login">
<input name="password" type="password" class="form-control form-control-sm w-auto" placeholder="password"
autocomplete="current-password" [(ngModel)]="password">
<div class="login-bar-captcha" [innerHTML]="svg()"></div>
<input name="captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8"
[(ngModel)]="captchaAnswer">
<button class="btn btn-sm btn-primary">Log in</button>
@if (error()) {
<span class="text-danger small">{{ error() }}</span>
}
</form>
}
</div>
`,
})
export class LoginBar {
readonly userChange = output<User | null>();
private readonly api = inject(ApiService);
private readonly sanitizer = inject(DomSanitizer);
protected readonly user = signal<User | null>(null);
private readonly captcha = signal<Captcha | null>(null);
protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
protected readonly login = signal('admin');
protected readonly password = signal('');
protected readonly captchaAnswer = signal('');
protected readonly error = signal<string | null>(null);
constructor() {
this.start();
}
private async start(): Promise<void> {
try {
this.change(await this.api.get<User>('/auth/me'));
} catch {
this.change(null); // 401:无人登录
await this.newCaptcha().catch(() => this.error.set('Is the JSON server running (port 8080)?'));
}
}
private async newCaptcha(): Promise<void> {
this.captcha.set(await this.api.get<Captcha>('/captcha'));
this.captchaAnswer.set('');
}
private change(u: User | null): void {
this.user.set(u);
this.userChange.emit(u);
}
protected async logIn(): Promise<void> {
this.error.set(null);
try {
const u = await this.api.post<User>('/auth/login', {
login: this.login(),
password: this.password(),
captchaId: this.captcha()?.id,
captcha: this.captchaAnswer(),
});
this.password.set('');
this.change(u);
} catch (e) {
this.error.set(e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e));
await this.newCaptcha();
}
}
protected async logOut(): Promise<void> {
await this.api.post('/auth/logout');
this.change(null);
await this.newCaptcha();
}
}
|
- 第 56 行:每当已登录用户发生变化(包括启动时),组件都会发出 [userChange] 事件,携带该用户(或 [null]);
- 第 74 行:有了 [ApiService],一个请求只需一行;失败(401)时,会转入 [catch];
- 第 103 行:[instanceof] 用于区分 API 错误和其他异常;
- 第 24 行:[ViewEncapsulation.None]:组件的样式应用于整个页面。默认情况下,[Angular] 通过给组件的元素添加特定属性,把组件的样式限制在其模板内。由 [<svg>] 通过 [[innerHTML]] 插入的元素没有这些属性:没有这个选项,第 26–30 行的规则就不会应用到它。
8.3.7. 配置
| // =========================================================================
// 24-api-service/src/app/app.config.ts
// -------------------------------------------------------------------------
// provideHttpClient(withInterceptors([...])):HttpClient 默认提供给
// 任何应用;在此声明只是为了对其进行配置,这里是
// 添加把错误转换成 ApiError 的拦截器。
// =========================================================================
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { errorsInterceptor } from '../../../common/errors.interceptor';
export const appConfig: ApplicationConfig = {
providers: [provideHttpClient(withInterceptors([errorsInterceptor]))],
};
|
- 第 14 行:[HttpClient] 默认已提供;声明它只是为了配置它,此处是添加拦截器。
8.3.8. 页面
| // =========================================================================
// 24-api-service/src/app/app.ts - 使用 API 访问层的日程
// -------------------------------------------------------------------------
// 登录(顶部栏),选择医生和日期:就会显示日程。
// ADMIN 和 DOCTOR 可以为患者预约和取消;
// 患者(martin...)只能为自己预约。每个操作之后都会
// 重新加载日程:以服务器为准。
//
// httpResource:由读取信号(这里是 doctorId 和 day)的函数描述的 GET 请求。
// Angular 在启动时发送它,之后每当其中一个信号变化时
// 都会再次发送。结果是一个
// 信号对象:value()(响应)、isLoading()、error()……
// 以及 reload(),用于按需再次发送。
// =========================================================================
import { Component, computed, effect, inject, signal } from '@angular/core';
import { httpResource } from '@angular/common/http';
import { FormsModule } from '@angular/forms';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Schedule, ScheduleSlot, Person, User } from '../../../common/types';
import { RdvMedecinsService } from './rdvmedecins.service';
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')}`;
}
@Component({
selector: 'app-root',
imports: [FormsModule, LoginBar],
templateUrl: './app.html',
})
export class App {
private readonly rdv = inject(RdvMedecinsService);
protected readonly user = signal<User | null>(null);
protected readonly doctors = signal<Person[]>([]);
protected readonly clients = signal<Person[]>([]);
protected readonly doctorId = signal<number | null>(null);
protected readonly day = signal(tomorrow());
protected readonly clientId = signal<number | null>(null);
protected readonly message = signal<{ type: 'success' | 'danger'; text: string } | null>(null);
protected readonly isManager = computed(() => this.user() !== null && this.user()?.role !== 'USER');
// undefined:不发送请求(没有选择医生,或无人登录)
protected readonly schedule = httpResource<Schedule>(() => {
const id = this.doctorId();
return id === null || this.user() === null ? undefined : this.rdv.scheduleRequest(id, this.day());
});
// 日程最近一次请求的错误,以 ApiError 表示
protected readonly scheduleError = computed(() => {
const e = this.schedule.error();
return e instanceof ApiError ? `${e.statusCode} ${e.key}` : null;
});
constructor() {
// 重新选择医生或日期会清除之前的消息
effect(() => {
this.doctorId();
this.day();
this.message.set(null);
});
}
protected 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)}`;
}
// API 错误变成一条消息(此处没有字典,所以用它的 key)
private report(e: unknown): void {
this.message.set({ type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) });
}
// 登录 / 登出:(重新)加载该角色被允许查看的内容
protected async onUserChange(u: User | null): Promise<void> {
this.user.set(u);
this.doctors.set([]);
this.clients.set([]);
if (u === null) {
return;
}
try {
this.doctors.set(await this.rdv.getDoctors());
// 患者列表:仅限 ADMIN 和 DOCTOR(USER 会收到 403)
this.clients.set(this.isManager() ? await this.rdv.getClients() : []);
} catch (e) {
this.report(e);
}
}
protected async book(c: ScheduleSlot): Promise<void> {
try {
await this.rdv.book(this.day(), c.id, this.isManager() ? (this.clientId() ?? undefined) : undefined);
this.message.set({ type: 'success', text: `Slot ${this.timeRange(c)} booked.` });
} catch (e) {
this.report(e);
}
this.schedule.reload();
}
protected async cancel(c: ScheduleSlot): Promise<void> {
try {
await this.rdv.cancelAppointment(c.appointmentId as number);
this.message.set({ type: 'success', text: `Appointment of ${this.timeRange(c)} cancelled.` });
} catch (e) {
this.report(e);
}
this.schedule.reload();
}
}
|
- 第 45 行:ADMIN 或 DOCTOR;
- 第 48–51 行:[httpResource] 通过一个读取信号的函数来描述 GET 请求(此处为 [doctorId]、[day] 和 [user])。[Angular] 先发送请求,之后每当其中一个信号变化时就重新发送它。当没有请求可发送时,该函数返回 [undefined] 。结果是一组信号:[value()] (响应)、[isLoading()]、[error()]、[hasValue()]……以及一个方法 [reload()],用于按需重新发送请求。如果信号变化时某个请求仍在进行中,它会被放弃,就像 [switchMap] (示例 19)一样;
- 第 54–57 行:最近一次日程请求的错误。来自 [httpResource] 的请求同样会经过拦截器:该错误是一个 [ApiError];
- 第 61–65 行:一个在医生或日期变化时清除先前消息的函数;
- 第 79–93 行:每当用户登录或注销,系统就(重新)加载该角色有权查看的内容。患者在请求客户列表时会收到 403 错误:我们甚至不会去请求它;
- 第 95–103 行:进行预订,随后无论发生什么,都会重新加载日程(第 102 行)。服务器的记录才是最终结果:如果该时间段在此期间被别人占用,刷新后的日程会显示出来;
- 第 97 行:管理员为所选患者进行预订;患者则为自己预订。
| <div class="container py-4">
<h1 class="h3 mb-3">Example 24 - an API access layer</h1>
<app-login-bar (userChange)="onUserChange($event)" />
@if (user()) {
<div class="row g-2 mb-3">
<div class="col-sm-5">
<select class="form-select" [(ngModel)]="doctorId">
<option [ngValue]="null" disabled>-- choose a doctor --</option>
@for (m of doctors(); track m.id) {
<option [ngValue]="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
}
</select>
</div>
<div class="col-sm-3"><input type="date" class="form-control" [(ngModel)]="day"></div>
@if (isManager()) {
<div class="col-sm-4">
<select class="form-select" [(ngModel)]="clientId">
<option [ngValue]="null">-- patient to book for --</option>
@for (c of clients(); track c.id) {
<option [ngValue]="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
}
</select>
</div>
}
</div>
@if (message(); as m) {
<div class="alert" [class]="'alert-' + m.type">{{ m.text }}</div>
}
@if (scheduleError()) {
<div class="alert alert-danger">{{ scheduleError() }}</div>
}
@if (schedule.isLoading()) {
<p class="small text-muted">loading the schedule...</p>
}
<!-- hasValue():已有可用的响应(value() 不是 undefined) -->
@if (schedule.hasValue()) {
@let a = schedule.value();
<!-- info:患者已有一个未来的预约时,服务器发送的 key -->
@if (a.info) {
<div class="alert alert-info">{{ a.info }}</div>
}
<table class="table table-sm align-middle">
<caption class="caption-top">Schedule of {{ a.day }} - {{ a.doctor.title }} {{ a.doctor.firstName }} {{ a.doctor.lastName }}</caption>
<tbody>
@for (c of a.slots; track c.id) {
<tr>
<td>{{ timeRange(c) }}</td>
<td>
@if (c.free) {
<span class="badge text-bg-success">Free</span>
} @else if (c.patient; as p) {
<span class="badge" [class]="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ p.title }} {{ p.firstName }} {{ p.lastName }}</span>
} @else {
<span class="badge text-bg-secondary">Booked</span>
}
</td>
<td class="text-end">
<!-- 按钮遵循服务器计算出的权限 -->
@if (c.bookable) {
<button class="btn btn-sm btn-outline-success" (click)="book(c)">Book</button>
}
@if (c.appointmentId !== null) {
<button class="btn btn-sm btn-outline-danger" (click)="cancel(c)">Cancel</button>
}
</td>
</tr>
}
</tbody>
</table>
}
}
</div>
|
- 第 3 行:登录栏;
- 第 34 行:[isLoading()]:有请求正在进行;
- 第 39 行:[hasValue()]:有可用的响应;
- 第 40 行:[@let] 避免[schedule.value()] 被重复书写;
- 第 57 行:一个被占用的时间段,服务器没有为其发送患者信息(患者视角);
- 第 62–67 行:按钮遵循服务器计算出的权限。
[npm start 24-api-service]。管理员为 Alice DURAND 预订 8:40 的时间段:

患者 Martin 看到的同一份日程:该时间段已被预订,但没有列出患者姓名。

8.4. 示例 25:服务器返回的错误
本示例演示管理员对客户的管理。表单在浏览器中不做任何验证:所有内容都发送给服务器,服务器在拒绝时会以错误作出响应:
| 400 { "key": "ERRORS.INVALID_FORM", "fields": { "lastName": "ERRORS.LASTNAME_REQUIRED" } }
409 { "key": "ERRORS.PATIENT_ALREADY_EXISTS", "fields": { "firstName": "...", "lastName": "..." } }
409 { "key": "ERRORS.CONCURRENT_UPDATE" }
|
然后必须显示总体消息,并以用户的语言,把每个字段的错误显示在该字段下方。
字典包含服务器的错误代码:
| {
"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."
}
}
|
| {
"FORM": {
"TITLE_ADD": "Add a patient",
"TITLE_EDIT": "Edit a patient",
"TITLE": "Title",
"FIRSTNAME": "First name",
"LASTNAME": "Last name",
"LOGIN": "Login",
"PASSWORD": "Password",
"SAVE": "Save",
"CANCEL": "Cancel",
"EDIT": "Edit",
"DELETE": "Delete",
"DELETE_CONFIRM": "Delete patient {{name}}, their account and their appointments?",
"ADDED": "Patient {{name}} has been added (login: {{login}}).",
"UPDATED": "Patient {{name}} has been updated.",
"DELETED": "Patient {{name}} has been deleted.",
"ADMIN_ONLY": "Log in with the admin account: only the ADMIN role manages patients."
},
"ERRORS": {
"INVALID_FORM": "The form contains errors.",
"INVALID_TITLE": "Choose a title from the list.",
"FIRSTNAME_REQUIRED": "First name is required.",
"FIRSTNAME_TOO_LONG": "First name must not exceed 20 characters.",
"LASTNAME_REQUIRED": "Last name is required.",
"LASTNAME_TOO_LONG": "Last name must not exceed 20 characters.",
"INVALID_LOGIN": "30 characters max: unaccented lowercase letters, digits, dot, hyphen, underscore.",
"PASSWORD_TOO_LONG": "Password must not exceed 72 characters.",
"LOGIN_TAKEN": "This login is already used by another account.",
"PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
"PATIENT_NOT_FOUND": "This patient does not exist (anymore).",
"CONCURRENT_UPDATE": "This record was changed meanwhile by another user. Reload it before trying again.",
"FORBIDDEN": "Your role does not allow this action.",
"AUTH_REQUIRED": "Please log in first.",
"SESSION_EXPIRED": "Your session has expired: please log in again.",
"SERVER_UNREACHABLE": "The server does not respond.",
"SERVER_ERROR": "An unexpected error occurred."
}
}
|
| // =========================================================================
// 25-server-errors/src/app/i18n/i18n.ts - ngx-translate,与示例 21 相同
// =========================================================================
import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';
class DictionariesLoader implements TranslateLoader {
getTranslation(language: string): Observable<TranslationObject> {
return of(language === 'en' ? en : fr);
}
}
export function provideI18n(): Provider[] {
return provideTranslateService({ loader: provideTranslateLoader(DictionariesLoader), fallbackLang: 'en', lang: 'en' });
}
|
应用配置整合了前面示例中介绍的各个元素:
| // =========================================================================
// 25-server-errors/src/app/app.config.ts
// -------------------------------------------------------------------------
// - HttpClient 和错误拦截器(参见示例 24);
// - ngx-translate(参见示例 21);
// - 字段的 Bootstrap 类(参见示例 07)。这里没有
// “touched”:字段只要带有错误就会出现红色边框,
// 也就是说,只要服务器报告了错误就会如此。
// =========================================================================
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideSignalFormsConfig } from '@angular/forms/signals';
import { errorsInterceptor } from '../../../common/errors.interceptor';
import { provideI18n } from './i18n/i18n';
export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(withInterceptors([errorsInterceptor])),
provideI18n(),
provideSignalFormsConfig({ classes: { 'is-invalid': (field) => field.state().invalid() } }),
],
};
|
- 第 19 行:HTTP 客户端及其拦截器(示例 24);
- 第 20 行:[ngx-translate] (示例 21);
- 第 21 行:[Bootstrap] 字段类(示例 07)。在这里,字段一旦包含错误(也就是服务器一旦报告了错误)就会以红色突出显示。
页面:
| // =========================================================================
// 25-server-errors/src/app/app.ts - 显示服务器的错误
// -------------------------------------------------------------------------
// 客户管理(管理员账户)。此表单
// 有意不在浏览器中做任何验证:它的 schema 是空的。
// 一切都发送到服务器,服务器在拒绝时会返回一个 JSON
// 错误(由拦截器转换成 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' } (乐观锁)
//
// submit(form, action):action 把模型发送到服务器。如果它
// 返回 ERRORS(一个数组),信号表单会把它们附加
// 到指定的字段(fieldTree):它们会出现在 f.lastName().errors() 中,
// 就像验证器的错误一样。这里它们的消息是服务器发送的 KEY,
// 由模板进行翻译(ngx-translate)。试试:空的
// 姓、"Dr" 称谓、重名(Alice DURAND)、已被占用的登录名
// (martin)、在两个标签页中修改同一条记录……
// =========================================================================
import { Component, computed, inject, signal } from '@angular/core';
import { FormField, form, submit, ValidationError } from '@angular/forms/signals';
import { TranslatePipe, TranslateService } from '@ngx-translate/core';
import { ApiService } from '../../../common/api.service';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Person, User } from '../../../common/types';
// 示例 16 的确认对话框,原样复用
import { ConfirmationService } from '../../../16-confirmation/src/app/confirmation/confirmation.service';
import { ConfirmDialog } from '../../../16-confirmation/src/app/confirmation/confirm-dialog';
interface ClientInput {
title: string;
firstName: string;
lastName: string;
login: string;
password: string;
version: number;
}
const EMPTY: ClientInput = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 };
@Component({
selector: 'app-root',
imports: [FormField, TranslatePipe, LoginBar, ConfirmDialog],
templateUrl: './app.html',
})
export class App {
private readonly api = inject(ApiService);
private readonly confirmation = inject(ConfirmationService);
protected readonly translate = inject(TranslateService);
protected readonly user = signal<User | null>(null);
protected readonly clients = signal<Person[]>([]);
protected readonly isAdmin = computed(() => this.user()?.role === 'ADMIN');
// 表单:editedId === null -> 创建,否则更新
protected readonly editedId = signal<number | null>(null);
protected readonly model = signal<ClientInput>({ ...EMPTY });
protected readonly f = form(this.model); // 没有验证器:由服务器验证
// 最近一次错误的通用消息,以及成功时的消息
protected readonly pageError = signal<ApiError | null>(null);
protected readonly success = signal<{ key: string; params: Record<string, string> } | null>(null);
protected async onUserChange(u: User | null): Promise<void> {
this.user.set(u);
this.clients.set([]);
if (u?.role === 'ADMIN') {
await this.reload();
}
}
private async reload(): Promise<void> {
this.clients.set(await this.api.get<Person[]>('/clients'));
}
protected newForm(): void {
this.editedId.set(null);
this.model.set({ ...EMPTY });
this.f().reset(); // 字段的状态(及其错误)从零开始
this.clearMessages();
}
protected edit(c: Person): void {
this.editedId.set(c.id);
// 随记录一起读取的 VERSION 会随更新一起发回:如果有人
// 在此期间修改了该记录,服务器会返回 409 CONCURRENT_UPDATE
this.model.set({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
this.f().reset();
this.clearMessages();
}
private clearMessages(): void {
this.pageError.set(null);
this.success.set(null);
}
// 服务器返回的每个字段的错误 -> 表单的一个错误
private fieldErrors(e: ApiError): ValidationError.WithOptionalFieldTree[] {
const fields = Object.keys(this.model()) as (keyof ClientInput)[];
return Object.entries(e.fields)
.filter(([field]) => fields.includes(field as keyof ClientInput))
.map(([field, key]) => ({ kind: 'server', message: key, fieldTree: this.f[field as keyof ClientInput] }));
}
protected async save(event: SubmitEvent): Promise<void> {
event.preventDefault();
this.clearMessages();
const id = this.editedId();
await submit(this.f, async () => {
try {
const body = this.model();
const client =
id === null
? await this.api.post<Person>('/clients', body)
: await this.api.put<Person>(`/clients/${id}`, body);
this.newForm(); // 表单已清空,消息已清除……
// ……除了这一条
this.success.set({
key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
});
await this.reload();
return null;
} catch (e) {
if (!(e instanceof ApiError)) {
throw e;
}
this.pageError.set(e); // 通用消息
return this.fieldErrors(e); // 每个字段的错误
}
});
}
protected async remove(c: Person): Promise<void> {
const name = `${c.firstName} ${c.lastName}`;
if (!(await this.confirmation.confirm(this.translate.instant('FORM.DELETE_CONFIRM', { name })))) {
return;
}
this.clearMessages();
try {
await this.api.delete(`/clients/${c.id}`);
this.success.set({ key: 'FORM.DELETED', params: { name } });
} catch (e) {
this.pageError.set(e instanceof ApiError ? e : null);
}
await this.reload();
}
}
|
- 第 30–31 行:示例 16 中的确认窗口,原样复用:设计良好的组件是可复用的;
- 第 61 行:一个信号表单(示例 06),没有模式(schema):没有验证器;
- 第 63–64 行:针对最后一个错误的通用消息,以及成功消息;
- 第 85–92 行:要编辑一条记录,需将其值复制到表单中,包括版本号:记录将随该变更一并更新(乐观锁)。[reset()] 重置各字段的状态及其错误;
- 第 107–134 行:保存记录。[submit(form, action)] 执行该 action,将表单发送到服务器:创建时使用 POST(第 116 行),修改时使用 PUT(第 117 行)。在其执行期间,[f().submitting()] 为 true;
- 第 125 行:[null]:没有错误;
- 第 130–131 行:如果被拒绝,则保留通用消息,字段错误则被返回。表单验证系统随后将它们附加到指定的字段上:它们出现在[f.lastName().errors()]中,与验证器错误完全一样;一旦用户修改该字段,它们就会消失;
- 第 100–105 行:转换。每个错误都标明其所属字段([fieldTree],第 104 行);其消息是服务器发送的键。第 103 行忽略表单中不存在的未知字段;
- 第 138 行:[translate.instant(key, params)]:在代码中翻译一个键;
- 第 146 行:删除客户也可能被拒绝。
| <div class="container py-4">
<div class="d-flex justify-content-between align-items-center mb-3">
<h1 class="h3 mb-0">Example 25 - the errors returned by the server</h1>
<select #language class="form-select form-select-sm w-auto" (change)="translate.use(language.value)">
<option value="fr">FR</option>
<option value="en" selected>EN</option>
</select>
</div>
<app-login-bar (userChange)="onUserChange($event)" />
@if (user() && !isAdmin()) {
<p class="alert alert-warning">{{ 'FORM.ADMIN_ONLY' | translate }}</p>
}
@if (isAdmin()) {
<div class="row g-4">
<div class="col-lg-6">
<table class="table table-sm align-middle">
<tbody>
@for (c of clients(); track c.id) {
<tr>
<td>{{ c.title }} {{ c.firstName }} {{ c.lastName }}</td>
<td><code>{{ c.login }}</code></td>
<td class="text-end text-nowrap">
<button class="btn btn-sm btn-outline-primary me-1" (click)="edit(c)">{{ 'FORM.EDIT' | translate }}</button>
<button class="btn btn-sm btn-outline-danger" (click)="remove(c)">{{ 'FORM.DELETE' | translate }}</button>
</td>
</tr>
}
</tbody>
</table>
</div>
<div class="col-lg-6">
<form class="card p-3" novalidate (submit)="save($event)">
<h2 class="h5">{{ (editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') | translate }}</h2>
<div class="mb-2">
<label class="form-label" for="title">{{ 'FORM.TITLE' | translate }}</label>
<!-- 服务器会拒绝的 "Dr" 选项:用来观察 ERRORS.INVALID_TITLE -->
<select id="title" class="form-select" [formField]="f.title">
<option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
</select>
<!-- 服务器错误的消息是一个 KEY:我们对它进行翻译 -->
<div class="invalid-feedback">{{ f.title().errors()[0]?.message ?? '' | translate }}</div>
</div>
<div class="row g-2 mb-2">
<div class="col-sm-6">
<label class="form-label" for="firstName">{{ 'FORM.FIRSTNAME' | translate }}</label>
<input id="firstName" class="form-control" [formField]="f.firstName">
<div class="invalid-feedback">{{ f.firstName().errors()[0]?.message ?? '' | translate }}</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="lastName">{{ 'FORM.LASTNAME' | translate }}</label>
<input id="lastName" class="form-control" [formField]="f.lastName">
<div class="invalid-feedback">{{ f.lastName().errors()[0]?.message ?? '' | translate }}</div>
</div>
</div>
<div class="row g-2 mb-3">
<div class="col-sm-6">
<label class="form-label" for="login">{{ 'FORM.LOGIN' | translate }}</label>
<input id="login" class="form-control" [formField]="f.login">
<div class="invalid-feedback">{{ f.login().errors()[0]?.message ?? '' | translate }}</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="password">{{ 'FORM.PASSWORD' | translate }}</label>
<input id="password" type="password" class="form-control" autocomplete="new-password" [formField]="f.password">
<div class="invalid-feedback">{{ f.password().errors()[0]?.message ?? '' | translate }}</div>
</div>
</div>
<div class="d-flex gap-2">
<!-- submitting():submit() 的 action 运行期间为 true -->
<button class="btn btn-primary" [disabled]="f().submitting()">{{ 'FORM.SAVE' | translate }}</button>
<button type="button" class="btn btn-secondary" (click)="newForm()">{{ 'FORM.CANCEL' | translate }}</button>
</div>
@if (success(); as s) {
<div class="alert alert-success mt-3 mb-0">{{ s.key | translate: s.params }}</div>
}
<!-- 通用消息和 HTTP 状态码,便于理解 -->
@if (pageError(); as e) {
<div class="alert alert-danger mt-3 mb-0">
{{ e.key | translate: e.params }} <span class="small text-muted">({{ e.statusCode }} {{ e.key }})</span>
</div>
}
</form>
</div>
</div>
}
</div>
<app-confirm-dialog />
|
- 第 4 行:语言选择;
- 第 40 行:服务器将拒绝的“Dr.”称谓;参见[ERRORS.INVALID_TITLE];
- 第 43 行及后续:在每个字段下方显示第一个错误;其消息是一个键,由管道[translate] 进行翻译。[?? '']:没有错误,就没有文本;
- 第 71 行:提交期间按钮被禁用;
- 第 80 行:通用消息,使用当前语言并带有其参数,后面跟着 HTTP 状态和键,以便说明;
- 第 88 行:确认窗口。
切换语言也会重新翻译已显示的错误消息:我们只保留了键。
[npm start 25-server-errors];以 admin 身份登录后,我们提交称谓“Dr,”、过长的名、空的姓以及无效的用户名:

我们从一个空白表单开始:称谓为“Dr,”,名为“Jean,”,姓为空。服务器拒绝了称谓和姓;随后我们更正称谓并填写姓:这两个字段的错误立即消失,无需重新提交。通用消息会一直显示,直到下一次提交:

同名同姓的情况(Alice DURAND 已存在):服务器返回 409 响应,并标记名和姓字段。已被占用的用户名“martin,”没有被标记:服务器在遇到第一条被违反的验证规则时就停止了。随后我们切换到法语:已显示的消息被重新翻译(页面标题和登录栏是用英语写的,因此不会被翻译):

也可以尝试在两个标签页中编辑同一条记录:第二次保存会收到 [ERRORS.CONCURRENT_UPDATE]。