Skip to content

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]:

1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}
  • 第 2 行:路径以 /api 开头的请求……
  • 第 3 行:……会被转发到 JSON 服务器。

对于每个示例,该文件都在 [ng serve] 命令的选项中指定,位于 [angular.json] 文件里:

1
2
3
4
5
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          },

浏览器发送 [GET http://localhost:4200/api/captcha];开发服务器将请求转发到 [http://localhost:8080/api/captcha],然后把响应返回给浏览器。对浏览器来说,页面和 API 具有同一个源:

Image

在生产环境中,将不再有开发服务器: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]:

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]):

Image

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

Image

8.3. 示例 24:API 的访问层

在示例 23 中,每个请求都重复相同的步骤:/api 前缀、[firstValueFrom]、读取错误响应体,以及选择消息。本示例把它们归并到几个文件中,这些文件位于工作区的 [common] 文件夹 中,因为示例 25 也会用到它们:

1
2
3
4
5
6
examples-angular/common/
├── types.ts                API 的 JSON 对象
├── api-error.ts            所有 API 错误的类
├── errors.interceptor.ts   HTTP 拦截器
├── api.service.ts          单行请求
└── login-bar.ts            栏中的登录

示例中的 [tsconfig.app.json] 文件把该文件夹加入要编译的文件中:

1
2
3
4
{
  "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 的时间段:

Image

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

Image

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

本示例演示管理员对客户的管理。表单在浏览器中不做任何验证:所有内容都发送给服务器,服务器在拒绝时会以错误作出响应:

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

然后必须显示总体消息,并以用户的语言,把每个字段的错误显示在该字段下方。

字典包含服务器的错误代码:

{
  "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,”、过长的名、空的姓以及无效的用户名:

Image

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

Image

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

Image

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