6. 第 5 章 - [RdvMedecins] 应用程序的 [Vue.js] 客户端
本章逐个文件详述本文档附带的 [rdvmedecins-vuejs-client] 文件夹的内容,采用本课程通篇使用的格式:先给出逐行编号的源代码,然后是标题为“我们来解读这段代码:”的部分。每个项目文件夹还包含其自己的 [README.md]。
6.1. 架构概览
与原始文档一样,也与本课程的 [Angular] 和 [React] 变体一样,客户端采用分层架构,我们在这里称之为 V-Services (视图-服务)。
值得注意的是术语上的一处差异:在 AngularJS 1.x 中,视图(HTML 模板)和控制器(关联的 JavaScript 类)是两个不同的实体,通过 $scope 连接。在 [Vue.js] 中,它们合并为单个实体,即 [.vue] 组件(参见上一章)——与 [Angular] 和 [React] 中完全一样,尽管形式不同(是一个包含三个块的文件,而不是一个类或一个函数)——因此,在下文中,凡是原始文档区分视图和控制器的地方,我们都简单地称为“组件”。
与原始文档一样,组件绝不直接通过 HTTP 通信:这个角色专属于服务层(在这里是组合式函数 [useAppointmentService()] 和组合式函数 [useAuth()])。这是一条设计原则,同样适用于 AngularJS 1.x、[Angular]、[React]、或 [Vue.js]——它没有改变。
6.2. 项目结构
这一结构直接遵循原始文档的流程(登录、选择医生/日期、查看日程表、预约),只是在这里组织成 [Vue.js] 组件,而不是 AngularJS 1.x 的独立控制器/视图、独立组件([Angular])或函数组件([React])。与本课程中的另外两个变体相比:
- 根组件只需一个文件(App.vue,外加 README.md),而不是三个文件([Angular]:app.ts/app.html/app.css),在 [React] 一侧也是三个文件(App.tsx/App.css/README.md):[<template>] 和 [<script setup>] 在同一个文件中合并了 [JSX] 此前在 [React] 一侧已经合并的内容——并且 App.vue 与 App.tsx 一样,没有相当于 app.config.ts 的应用程序配置文件;
- 出现了 `core/composables/` 文件夹,取代 [React] 一侧的 `core/context/` (后者在 [Angular] 一侧本身并不存在):它包含充当可注入服务的组合式函数([SettingsService]、[AuthService]、[LanguageService]),对应于 [Angular] 变体——这一机制(组合式函数 + [provide]/[inject])已在上一章连同一个通用示例一起介绍(参见上一章“共享逻辑”)。
[Bootstrap] 5 用于所有视图(在 main.ts 中导入;见下文)——它是原始文档已使用的 Bootstrap 3 的直接演进,与本课程的 [Angular] 和 [React] 变体保持一致。
6.3. 项目配置文件
6.3.1. package.json
我们来解读这段代码:
- 第 5–8 行:["scripts": { … }] ——可用的 [npm run <name>] 命令。[start] (同 dev)启动 [Vite] 开发服务器,每当源文件被修改时自动重新加载,端口为 4200(见下文的 vite.config.ts)——与本课程的 [Angular] 和 [React] 变体端口相同;
- 第 7 行:["build": "vue-tsc -b && vite build",] ——与 [React] ([tsc -b && vite build])的显著区别:[vue-tsc] 用一个变体取代标准的 TypeScript 编译器,该变体还能检查 [<template>] 内部的类型(例如,作用于不存在的属性的 [v-model] ,或与 [:doctors] 不匹配 [defineProps]所期望类型的情形)——很像 [Angular] 通过其 strictTemplates 选项所做的那样,而 [React] 只是像对待其他任何 TypeScript 一样检查 [JSX] ;
- 第 12–16 行:["dependencies": { … }] ——在浏览器中运行所需的包:[vue] (框架的核心)、[vue-i18n] (FR/EN 翻译;见下文)、[bootstrap] (仅样式表)。与本课程的 [Angular] 和 [React] 变体不同,这里既没有单独对应于 [@angular/router]/[react-i18next] 的包(vue-i18n 直接内嵌其引擎;见 i18n.ts),也没有 RxJS;
- 第 17–23 行:["devDependencies": { … }] ——仅在开发期间需要的包:[@vitejs/plugin-vue] (将 [.vue] 文件转换为 JavaScript,以及热重载)、TypeScript、[vue-tsc] (见上文),以及 [Vite] 本身。与 [React] ([@types/react]、[@types/react-dom])不同,[Vue.js] 不需要单独的类型包:该库本身就是用 TypeScript 编写的。
与 [NestJS] 服务器([commonjs] 模块,参见第 3 章)不同,这个项目以原生 ECMAScript 模块(import/export)运行——与本课程的 [Angular] 和 [React] 变体完全一样。
6.3.2. vite.config.ts
我们来解读这段代码:
- 第 5 行:[plugins: [vue()],] ——启用对 [.vue] 文件的转换(拆分三个块,根据渲染模式编译 [<template>] )和热重载——对 [Vue.js] 而言,相当于 [@vitejs/plugin-react]() 在 [JSX] 方面于 [React] 一侧所做的事情(参见上一章),也相当于 [@angular/build:dev-server] 在幕后为 [Angular] 所做的事情;
- 第 6–8 行:[server: { port: 4200, },] ——把开发服务器的端口设为 4200,与 [ng serve] 在 [Angular] 一侧的端口相同,也与本课程中的 [React] 客户端相同——这纯粹是出于教学考虑的选择,使本课程的三个变体可以互换,而无需改变你的工作流程。
这个文件在原始的 AngularJS 1.x 项目中没有对应物;在本课程的 [Angular] 一侧,起这个作用的是 [angular.json] ;在 [NestJS] 一侧(第 3 章),则是 [nest-cli.json]。
6.3.3. tsconfig.json
我们来解读这段代码:
- 第 15 行:["strict": true,] ——与本课程 [tsconfig.json] 中的 [Angular] 和 [React] 变体一样,TypeScript 的完整严格模式处于启用状态:每个变量都必须有可确定的类型,每个 null 或 undefined 值都必须被显式处理;
- 第 18–19 行:["noUnusedLocals": true, "noUnusedParameters": true,] ——在编译期间标记任何已声明但从未使用的变量或参数——与 [React] 的设置相同;
- 第 13 行:["noEmit": true] ——这里使用 TypeScript 只是为了类型检查([npm run build] 首先运行 [vue-tsc -b],如果出现类型错误,它就会失败,包括在 [<template>] 中;参见上文的 package.json):真正生成浏览器所执行的 JavaScript 的是 [Vite] (通过 esbuild)。
与 [tsconfig.json] 文件(由 [React] 项目生成,其中有 [jsx: ‘react-jsx’])不同,这个文件不包含任何特定于框架的设置:[vue-tsc] (而不是标准的 TypeScript 编译器)会预先确定如何解析 [.vue] 文件——这是与此配置文件分开的机制,不同于 [React],后者对 [JSX] 的支持直接在这里配置。
6.4. 启动应用程序
6.4.1. index.html
我们来解读这段代码:
- 第 2 行:[<html lang="en">] ——与 [Angular] 和 [React] 一样,由于这个 HTML 页面是静态的(在 [Vue.js] 应用程序启动之前由浏览器加载),它无法立即反映用户之后所做的语言选择;
- 第 10 行:[<div id="app"></div>] ——这个页面最初包含的唯一元素,一旦挂载,[Vue.js] 就会将其完全填充(见下文的 main.ts)——完全相当于 [Angular] 一侧的 <app-root></app-root>、[React] 一侧的 <div id="root"></div>,以及原始文档(AngularJS 1.x,2014 年)中 <html> 标签上的 [ng-app="rdvmedecinsApp"] ;只有标识符不同([Vue.js] 的惯例:"app");
- 第 11 行:[<script type="module" src="/src/main.ts"></script>] ——与 [React] 一样,是 index.html 直接引用 main.ts(这是 [Vite] 特有的约定),而不是反过来。在开发环境中,[Vite] 会即时转换并提供这个文件;在生产环境中([npm run build]),它当然是事先编译好的。
与另外两个变体一样,整个应用程序只有一个入口点:这正是单页 Web 应用程序(SPA)的定义,原始文档中已经描述过。
6.4.2. src/main.ts
我们来解读这段代码:
- 第 12 行:[const app = createApp(App);] ——直接相当于 [bootstrapApplication(App, appConfig)] 在 [Angular] 一侧的写法,以及 [createRoot(...).render(...)] 在 [React] 一侧的写法:[createApp(...)] 创建一个应用实例(但尚未挂载它;见第 30 行);
- 第 14 行:[app.use(i18n);] ——安装 [vue-i18n] 插件:从此以后,任何组件的 [useI18n()] 都可以在 [<script setup>] 中使用;
- 第 16–23 行:[const settingsStore = createSettingsStore(); app.provide(SettingsKey, settingsStore); …] ——来自 core/composables/(见下文)的三个 [createXxxStore()] + [app.provide(...)] 组合,使 [useSettings()]、[useAuth()]和 [useLanguage()] 可以在任何后代组件中使用——相当于 [provideXxx()] 的三个调用,来自 [app.config.ts] ,位于 [Angular] ([providers: [...]])一侧,但这里表现为一个函数调用的序列,而不是提供者数组,也不是像 [React] 一侧那样,围绕根组件对 [Provider] 组件进行嵌套——这里不需要视觉上的嵌套,不同于 [React] (可与本课程 React 客户端的 main.tsx 对比:<SettingsProvider><AuthProvider>...);
- 第 16、19 行:[const settingsStore = … const authStore = createAuthStore(settingsStore);] ——调用的顺序很重要:[createAuthStore(...)] 要求 [settingsStore] 已经存在(以读取 [apiBaseUrl])——因此它是作为参数直接传入的,而不是通过 [Vue.js] 注入:在这个阶段,还不存在任何组件,所以 [inject()] 帮不上忙;
- 第 22 行:[const languageStore = createLanguageStore();] ——在 [app.use(i18n)] (第 14 行)之后调用:这个组合式函数要求 [vue-i18n] 插件已经安装;
- 第 30 行:[app.mount(container);] ——真正把应用程序挂载到 index.html 的 #app 元素中——与 [createApp(App)](第 12 行)分开,恰恰是为了在应用程序显示之前,留出时间让中间几行(app.use、app.provide)对其进行配置。
与本课程的 [Angular] 和 [React] 客户端一样(单页,没有路由表),这个 [Vue.js] 客户端不使用任何路由器:App.vue 根据 [useAuth().isLoggedIn]显示登录界面或应用程序的其余部分——一个简单的 [v-if] 就足够了;路由器([vue-router] 或其他)对单页应用不会增加任何价值。
6.4.3. src/i18n.ts
我们来解读这段代码:
- 第 8 行:[legacy: false,] ——启用 [vue-i18n] 的“组合式 API”模式:在组件中使用 [useI18n()] (就像 [useTranslation()] 在 [React] 一侧那样),而不是 [this.$t](旧模式,面向 [Vue.js] 2 的选项式 API);
- 第 9–11 行:[locale: navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en', fallbackLocale: 'en', messages: {},] ——启动语言(如果浏览器语言以 'fr' 开头则为法语,否则为英语)、当前字典中缺少某个键时的回退语言(英语),以及启动时为空的字典——[language.composable.ts] (见下文)会立即用 localStorage 中存储的选择(如果有的话)替换 [locale] ;
- 第 14–22 行:[export async function loadDictionary(language: Language): Promise<void> { …] ——不同于 [i18next-http-backend] (React)或 [TranslateHttpLoader] (Angular),[vue-i18n] 原生并不提供“加载器”:它只是等待通过 [setLocaleMessage(...)] 提供已加载好的字典。因此,这个函数手动重建了 [HttpBackend] 在 [React] 一侧自动完成的工作:它使用 [fetch] 获取文件 [/i18n/<language>.json](与本课程另外两个变体使用完全相同的 URL),然后把其内容保存到 [vue-i18n];
- 第 15–17 行:[if (loadedDictionaries.has(language)) { return; }] ——防止重新下载会话期间已经遇到过的语言——与 [i18next-http-backend] 在 [React] 一侧的内部缓存是同一种优化。
6.4.4. src/index.css
我们来解读这段代码:
- 第 1 行:[body { background-color: #f5f7fa; }] ——与另外两个变体相同:使用非常浅的灰色,而不是默认的纯白色,使 [Bootstrap] 卡片(白色背景,.card)从页面背景中略微凸显出来;
- 第 5–11 行:[.free-slot { cursor: pointer; } .free-slot:hover { … }] ——应用于日程表中表示可预约时间段的行(见 Schedule.vue,下文的 [:class="scheduleSlot.appointment === null ? ‘free-slot’ : undefined"] ):光标在整行上呈手形,悬停时背景略微变绿——这里与本课程的 [React] 客户端不同(在那里,“pointer”光标应用于“预约”按钮本身),整行表格都是可点击的,正如原始文档中所设计的那样。
这个文件包含全局样式,与 [Vue.js] 组件可以在其自身的 [<style scoped>] 块中定义的“局部”样式相对(本项目中没有使用:[Bootstrap] 和 index.css 已足以满足本文档实现的一切需求)——原理与 [Angular] 和 [React] 相同(每个组件有单独的样式文件)。
6.5. core/models 层
6.5.1. src/app/core/models/appointment.models.ts
我们来解读这段代码:
- 这些接口本身是对本课程 [Angular] 和 [React] 变体的严格复制粘贴(只是像整个客户端一样被重写):描述与服务器交换的数据的 TypeScript 接口不依赖于任何框架——它是“纯”TypeScript,与 [ServerResponse]<T> 类和 [TypeORM] 实体完全对应,属于 [NestJS] 服务器(第 3 章);
- [Role]/[LoginResult]——与服务器端同名类型(src/entities/user.entity.ts、auth/login-result.model.ts,第 3 章)完全相同的副本。
在 AngularJS 1.x(2014 年)中,纯 JavaScript 无法以这种方式描述所期望的数据格式。而使用 TypeScript——本课程的三个变体都使用它——字段名中的拼写错误在程序运行之前,也就是在编译时就会被标出。
6.6. core/composables 层
对于这个客户端,[Vue.js],该目录所起的作用与本课程 [React] 客户端中的 core/context/ 相同(参见上一章“共享逻辑”):它把三个组合式函数组织在一起,在这里它们充当可注入的服务(对应 [SettingsService]、[AuthService],以及 [LanguageService] 的一部分,位于 [Angular] 一侧)。
6.6.1. src/app/core/composables/settings.composable.ts
我们来解读这段代码:
- 第 8 行:[export const SettingsKey: InjectionKey<SettingsStore> = Symbol('SettingsStore');] ——注入键(参见上一章)——一个带类型的 [Symbol],而不是简单的字符串;
- 第 10–18 行:[export function createSettingsStore(): SettingsStore { …] ——完全取代 [readonly apiBaseUrl = signal(‘http://localhost:8080’);] ,即 [SettingsService] 在 [Angular] 一侧的写法:默认值相同,也同样可以通过原始文档主视图上的“服务器 URL”字段来修改它;这里选择 [reactive(...)] (而不是 [ref()])是因为该存储包含多个属性(apiBaseUrl 及其更新函数)——[store.apiBaseUrl] 直接读取和写入,无需 [.value];
- 第 20–26 行:[export function useSettings(): SettingsStore { …] ——组件调用的组合式函数([const settings = useSettings();]),直接相当于 [inject(SettingsService)] 在 [Angular] 一侧的写法,以及 [useSettings()] 在 [React] 一侧的写法。
6.6.2. src/app/core/composables/auth.composable.ts
移植自 [AuthService]:处理用户的登录,调用 [POST /login],存储收到的 JWT 令牌(以及随附的身份/角色),并通过 [localStorage] 确保它在页面重新加载后依然保留。这是应用程序中唯一使用 HTTP 与服务器通信的地方,另一处是 [core/services/appointment.service.ts] (见下文)。
我们来解读这段代码:
- 第 14–21 行:[function readStoredSession(): StoredSession | null { …] ——用 try/catch 块保护,与 [Angular] 和 [React] 中一样:[localStorage] 可能不可用(限制非常严格的隐私浏览模式),或者包含已损坏的值——这种情况下,我们直接认为没有会话;
- 第 37 行:[const initialSession = readStoredSession();] ——只在构造存储时调用一次(在 src/main.ts 中)——所起的作用与 [useState(readStoredSession)] 在 [React] 一侧的初始化函数,或 [signal(readStoredSession())] 在 [Angular] 一侧的作用完全相同。如果用户在登录后重新加载页面,他们仍保持登录状态;
- 第 39–51 行:[function applySession(session: StoredSession | null): void { …] ——提取出 [logIn()] 和 [logOut()] 的共同之处:一步完成更新存储的响应式属性并同步 [localStorage] ——这是一个小型内部函数,在对应的 [React] 版本中没有(由于缺少同样自然的统一写入点,它在两个函数中各重复了这一逻辑);
- 第 53–79 行:[const store = reactive<AuthStore>({ … });] ——原理与 settings.composable.ts 相同:单个 [reactive] 对象,它的每个属性(isLoggedIn、login、accessToken……)由 [applySession()] 就地修改,而不是替换为新对象——不同于 [AuthContext] 在 [React] 一侧,那里每次变化都必须使用 [value] 通过 [useMemo]() 重建一个新对象(参见上一章),而 [Vue.js] 在这里无需这样做:只有读取了确实发生变化的属性的组件才会被自动重绘;
- 第 61–74 行:[async logIn(login: string, password: string): Promise<LoginResult> { …] ——相当于:POST /login,JSON 请求体 { login, password };与 [React] 一侧一样(fetch/async-await),各个步骤自上而下自然地依次进行,无需专门的 RxJS 操作符(不同于 [AuthService.logIn()] 在 [Angular] 一侧,后者返回一个 Observable,并在单独的 tap() 操作符中保存会话);
- 第 76–78 行:[logOut(): void { applySession(null); },] ——纯本地操作(不调用服务器):在本次移植中,JWT 令牌不会在服务器端被“撤销”;它会在 JWT_EXPIRES_IN 之后自行过期(参见服务器的 .env,第 3 章)。
6.6.3. src/app/core/composables/language.composable.ts
移植自 [LanguageService] 的一部分:在 [vue-i18n] 之上集中处理界面语言(法语/英语)的切换(参见上文的 i18n.ts)。
我们来解读这段代码:
- 第 15 行:[currentLanguage: i18n.global.locale.value as Language,] ——[vue-i18n] 已经把其当前语言暴露为响应式 [ref] ([i18n.global.locale]):[LanguageStore] 并不创建单独的状态;它只是以稳定的名称(currentLanguage)重新发布它——概念上与 [Angular] 中完全相同,在那里 [LanguageService] 只是把 [this.translate.currentLang] 以不同的名称重新发布;
- 第 22–27 行:[function applyLanguage(language: Language): void { …] ——[loadDictionary(language)] (参见 i18n.ts)在必要时获取相应的字典,然后,一旦完成,我们就切换到 [i18n.global.locale.value]——不同于 [i18n.changeLanguage(...)] 在 [React] 一侧(它同时完成这两件事);在这里,由于 [vue-i18n] 没有内置的“加载器”(参见 i18n.ts),这个组合式函数自己编排这两个步骤;
- 第 29–31 行:[watch(i18n.global.locale, (newLanguage) => { store.currentLanguage = newLanguage as Language; });] ——[watch(source, callback)] 每当被观察的值变化时就重新执行回调——对于单个属性,相当于 [useEffect](..., [dep]) 在 [React] 一侧,或 [effect()] 在 [Angular] 一侧。正是这一行真正实现了本文件开头提到的“重新发布”:[store.currentLanguage] 始终保持同步,与 [i18n.global.locale] 保持一致,无论后者是如何变化的;
- 第 33–38 行:[const savedLanguage = localStorage.getItem(STORAGE_KEY) as Language | null; …] ——在最初的加载时:如果用户在之前的访问中已经选择过语言,则恢复该语言;否则,保留 i18n.ts 中设置的启动语言(英语,或法语浏览器对应的法语)——但它的字典仍然必须被加载,而 i18n.ts 自己不会加载它——这正是 [useEffect](..., []) 在 [React] 一侧 language.context.tsx 中所起的作用,它在设置期间只执行一次。
相当于原始 AngularJS 1.x 客户端中的“FR / EN”按钮,当时它依赖 [angular-translate] 库——它是 AngularJS 1.x 生态系统中 [ngx-translate]([Angular])的前身,之后有 [i18next] ([React])和 [vue-i18n] ([Vue.js])。
6.7. 翻译字典(public/i18n/)
[loadDictionary()] (参见上文的 i18n.ts)每当语言变化(或首次使用)时,都会通过 [HTTP GET /i18n/<language>.json] 请求加载这两个文件之一。[vue-i18n] 随后通过 features/ 目录中所有组件使用的 [useI18n() (function t(...))] Hook 来解析每个键("LOGIN.TITLE"、"SCHEDULE.FREE"……)(见本章后面)。
6.7.1. public/i18n/fr.json
我们来解读这段代码:
- 这个文件与本课程 [Angular] 和 [React] 变体的文件逐键一一对应(与 DOCTOR_DAY_PICKER/SCHEDULE/BOOKING_DIALOG 中相同的各个部分,出于篇幅原因此处不再重复;详见随附文件),只有两处例外:第 3 行([TITLE]),它现在指的是 [Vue.js] 而不是 [React];以及四个新键([DEMO_ACCOUNTS_*],第 14–17 行),由 Login.vue 显示(见下文),直接在登录界面上展示两个演示账户——这是一个小小的便利功能,本课程的另外两个版本中没有;
- 一个嵌套的 JSON 对象,每个组件一个部分;[vue-i18n] 把它展平为扁平字典,其中每个完整的键("LOGIN.TITLE")由路径用点号连接而成——与 [i18next] 附加到 [React]、以及 [TranslateService] 附加到 [Angular] 的方式完全一样。
6.7.2. public/i18n/en.json
我们来解读这段代码:
- 第 3 行:["TITLE": "RdvMedecins - NestJS / Vue.js port",] ——只有副标题变化:“[RdvMedecins]”在两种语言中保持不变;这是应用程序的专有名称。
两个文件在结构上必须保持一致(两者的键相同):这确保每个键在两种语言中都存在。未被翻译的部分与本课程的 [Angular] 和 [React] 变体相比保持不变:[NestJS] 服务器返回的错误消息无论客户端选择哪种语言都保持英文,而医生和患者的姓名则直接来自数据库。
6.8. core/interceptors 层
6.8.1. src/app/core/interceptors/auth.interceptor.ts
[Vue.js] 和 [React] 都没有像 [Angular] 一侧的 [HttpClient]/[withInterceptors([...])] 那样内置的 HTTP 拦截器。这个文件把同样的概念重新实现为封装 [fetch] 的组合式函数:它是原始文档(“示例 6”一章)中已经遇到过的 AngularJS 1.x $http 拦截器的现代等价物。
我们来解读这段代码:
- 第 3 行:[export function useAuthFetch(): (path: string, options?: RequestInit) => Promise<Response> {] ——不同于 [authInterceptor] 在 [Angular] 一侧(一个一次性注册在 [app.config.ts] 中的函数,随后会自动应用于对 [HttpClient] 的每次调用),[useAuthFetch()] 是一个组合式函数,每个调用方(这里是 [useAppointmentService()],见下文)必须显式调用它,并用它来代替 [fetch()]——与 [React] 一侧的方式相同;不同于 [React] ([useCallback](...)),这里无需存储所返回的函数:[<script setup>] 的主体对每个组件实例只执行一次,因此该函数也只构造一次;
- 第 8–10 行:[if (auth.accessToken) { headers.set(‘Authorization’, …); }] ——直接相当于 [request.clone({ setHeaders: { Authorization: … } })] 在 [Angular] 一侧的写法。与(不可变的)[HttpClient] 请求不同,[fetch] 的选项只是一个 JavaScript 对象:无需创建它的“克隆”副本;只要在调用之前构造好 [headers] 对象即可;
- 第 14–16 行:[if (response.status === 401) { auth.logOut(); }] ——原理与 [Angular] 中相同(catchError + HttpErrorResponse.status === 401):会话期间出现 401,意味着令牌不再有效;客户端会被平稳地断开连接;[fetch] 不会因为 HTTP 状态而把其 Promise 作为错误拒绝(不同于 Observable [HttpClient])——这就是为什么这个测试直接针对 [response.status],而不使用 try/catch 块;
- 第 18 行:[return response;] ——响应(可能是 401)仍然原样返回给调用方,由调用方负责处理其后果(参见下文的 useAppointmentService()、extract<T>())——拦截器不应向调用代码隐瞒错误。
可以手动把 [Authorization: Bearer ...] 添加到 [useAppointmentService()] 的每个方法中。共享的组合式函数避免了这种重复,带来与 [Angular] 拦截器相同的好处:“如何对请求进行身份验证?”这个问题在单一位置得到解答。
6.9. core/services 层
6.9.1. src/app/core/services/appointment.service.ts
移植 [AppointmentService]:应用程序中唯一的部分(连同负责连接本身的 [core/composables/auth.composable.ts] ),通过 HTTP 与 [NestJS] 通信。它直接相当于原始文档“示例 6:HTTP 服务”一章中介绍的 [dao] 服务(该服务使用 AngularJS 的 $http 服务)。
我们来解读这段代码:
- 第 5 行:[async function extract<T>(httpResponse: Response): Promise<T> {] ——我们不在每个公共函数中重复“如果 status !== 0,则出错”的逻辑,而是在这里只集中处理一次——这正是 [AppointmentService.extract()] 在 [Angular] 中的作用,以及 [extract<T>()] 在 [React] 中的作用;
- 第 13 行:[export function useAppointmentService() {]——一个组合式函数,其读取和使用方式与 [inject(AppointmentService)] 在 [Angular] 一侧完全一样:在组件的 [<script setup>] 顶部调用一次,然后使用它返回的函数;
- 第 17–20 行:[async function getAllDoctors(): Promise<Doctor[]> { …] ——不同于 [React] ([useCallback](..., [authFetch, apiBaseUrl])),这些函数都无需在多次渲染之间缓存:[<script setup>] [Vue.js] 对每个组件实例只执行一次(参见上文的 auth.interceptor.ts)——这个技术细节在 [React] 一侧是必需的,而在这里则完全消失了;
- 每个函数都恰好对应 [NestJS] 控制器(第 3 章)的十一个路由之一——事实上,两侧出现的名称相同(getAllDoctors、addAppointment、deleteAppointment……),这使得服务器端和客户端的比较更容易,就像 [Angular] 和 [React] 那样。
与 [AuthStore.logIn()] (上一章)不同,这个组合式函数中的方法在调用之后都无需保留任何数据:决定如何处理结果(doctors.value = result、schedule.value = result……)的是调用它的组件(App.vue)——这与 [Angular] 和 [React] 中所见的职责分离相同,在那里 [AppointmentService] 和 [useAppointmentService()] 对屏幕上显示的状态一无所知。
6.10. features 层:四个组件
6.10.1. src/app/features/login/Login.vue
移植自 [login.component.ts/.html] ([Angular])和 [Login.tsx] ([React]):登录界面,相当于原始 AngularJS 1.x 客户端的视图 [login.html] (应用程序显示的第一个视图)。这个组件对日程表或预约一无所知:它只收集一对(用户名,密码),把它转交给 [AuthStore.logIn(...)],并显示可能出现的错误。
我们来解读这段代码:
- 第 6 行:[const { t } = useI18n();] ——独立的 [Angular] 组件在其装饰器 [@Component] 中声明它所用的管道([imports: [TranslatePipe]]);而 [Vue.js] 组件和 [React] 组件一样,没有任何对应的内容需要声明:[useI18n()] 只是像其他任何函数一样被导入并调用;
- 第 9–12 行:[const login = ref(''); const password = ref(''); …] ——纯粹属于表单本地的状态(用户当前正在输入的内容)——相当于 [signal()] 本地值在 [Angular] 组件中的作用,以及 [useState()] 在 [React] 一侧的作用(这里是按值使用的 [ref] ,而不是 [value, setValue] 对);
- 第 33 行:[@submit.prevent="onSubmit"] ——与本课程的 [Angular] 变体刻意不同:这个组件不是分别监听每个字段(keyup.enter),而是使用真正的 <form> 元素及其原生事件 [submit]——回车键和点击“登录”按钮(type="submit")都会触发 [onSubmit()];[.prevent] 修饰符会自动阻止浏览器的默认行为(重新加载页面)——相当于显式的客户端 [event?.preventDefault()],但直接在 [<template>] 中表达,而不是在 TypeScript 代码中;
- 第 44–45 行:[autocomplete="username" v-model="login"] ——[v-model] 在单个属性中把字段与 [login] [ref] 双向关联起来(既读取又写入)——相比 [React] ([value={login} onChange={(e) => setLogin(e.target.value)}],两个独立的属性)和 [Angular] ([[(ngModel)]] 或 [[value]]+(input),视情况而定)的写法,这是一种简化;
- 第 23–26 行:[catch { submitting.value = false; error.value = ‘LOGIN.ERROR’; }] ——无效的用户名/密码对会使 [logIn()] 因 JavaScript 异常而失败(由 auth.composable.ts 抛出,见上文):向用户显示“LOGIN.ERROR”,而不尝试区分用户名不存在和密码错误——与 [Angular] 和 [React] 的做法完全相同。存储翻译键而不是已经解析好的文本,与另外两个变体中一样有好处:如果用户在显示此消息时切换语言,它会自动翻译自己([t(error)],第 37 行,会自动重新求值)。
这个组件把 [Angular] 拆成两个文件的内容(login.component.ts 用于逻辑,login.component.html 用于模板)合并到了单个 [.vue] 文件中:[<template>] 用于模板,[<script setup>] 用于逻辑,二者在同一个文件中——就像 [Login.tsx] 在 [React] 一侧借助其函数返回的 [JSX] 已经做到的那样。
6.10.2. src/app/features/doctor-day-picker/DoctorDayPicker.vue
移植自 [doctor-day-picker.component.ts/.html] ([Angular])和 [DoctorDayPicker.tsx] ([React]):该组件可让你选择医生和日期,然后请求查看其日程。在概念上相当于原始 AngularJS 1.x 客户端的示例 7 到示例 10。
我们来解读这段代码:
- 第 6–8 行:[defineProps<{ doctors: Doctor[]; }>();] ——[Angular] 的 [input.required<Doctor[]>()] 变成 [Vue.js] 的 prop;不同于 [React] (解构的 `props` 对象,没有单独的类型声明),[defineProps<...>()] 是在编译时被 [Vue.js] 编译器识别的函数:它在最终的 JavaScript 中甚至不再存在;
- 第 10–12 行:[const emit = defineEmits<{ search: [criteria: { … }]; }>();] ——[output<...>()] [Angular] 在这里变成声明的事件——[App.vue] 将通过 [@search="onSearchSchedule"] 监听它(见下文),就像它订阅 [Angular] 模板的 (search) 事件一样;而在 [React] 中,它是一个简单的 prop 函数([onSearch])——[Vue.js] 在这里更显式地区分输入和输出,与 [Angular] 类似;
- 第 21–26 行:[function onSearchClick(): void { … emit(‘search’, { … }); }] ——[emit(‘search’, ...)] 触发事件——直接相当于 [search.emit(...)] 在 [Angular] 一侧的写法,以及作为 prop 接收的函数调用([onSearch(...)])在 [React] 一侧的写法;
- 第 36 行:[select id="select-doctor" class="form-select" v-model="selectedDoctorId"] ——在 <select> 上使用 [v-model] 可直接把所选的值与 [selectedDoctorId.value] 关联起来——相比 [React](单独的 :value 和 @change,参见上一章)以及 [Angular] ([(ngModel)] 或 [value]+(change),视情况而定)的写法,这是一种简化;
- 第 38–40 行:[option v-for="doctor in doctors" :key="doctor.id" :value="doctor.id"] ——[v-for] + [:key] 相当于[Vue.js] 中的 [.map(...)] + [key={...}] 在 [React] 一侧(以及 [@for (doctor of doctors(); track doctor.id)] 在 [Angular] 一侧):在这三种情况下,都由一个稳定的标识符来指明,重绘时如何识别已经显示的医生。
6.10.3. src/app/features/schedule/Schedule.vue
移植自 [schedule.component.ts/.html] ([Angular])和 [Schedule.tsx] ([React]):显示某位医生在指定日期的日程。相当于原始 AngularJS 1.x 客户端的示例 8 和示例 9。由于加入了身份验证,这个组件还接收 [canEdit]:当它被设为 false(角色 USER)时,“预约”/“取消”按钮会消失——日程仍然可以查看,但处于只读模式。
我们来解读这段代码:
- 第 34、36 行:[p v-if="schedule === null" … div v-else …] ——[v-if]/[v-else] 取代了 [React] 中使用的“提前返回”([if (schedule === null) return <p>...</p>;]):只要尚未执行任何搜索(或日程为空),DOM 中就只包含空状态消息,甚至不会构造后面的表格;
- 第 7 行:[canEdit: boolean;] ——身份验证引入的新特性,与 [Angular] 和 [React] 中类似:App.vue 向它传入 [auth.isAdmin](见下文)。当它被设为 false(角色 USER)时,“预约”/“取消”按钮在 DOM 中根本不存在(第 67 行,[v-if="canEdit"])——它不只是变灰或被禁用,而是完全缺失;
- 第 58–64 行:[span v-if="scheduleSlot.appointment === null" … span v-else …] ——[v-if]/[v-else] 取代了 [React] 一侧使用的三元运算符——根据时间段的状态,显示绿色的 [Bootstrap] 徽章(“空闲”)或灰色徽章(患者姓名);
- 第 67 行:[button v-if="canEdit" type="button"] ——不同于 [React] (运算符 [&&],{canEdit && (…)}),在 [v-if] 这里单独使用 [Vue.js] 就足够了:在 [Vue.js] 中没有可用于“仅在为真时显示,否则什么都不显示”的 [&&] 等价物——[v-if] 自己就能做到这一点;
- 第 70 行:[{{ scheduleSlot.appointment === null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT') }}] ——与 [Angular] 一侧(管道可用于任何模板表达式)和 [React] 一侧一样,[t(...)] 是标准的 JavaScript 函数:可以直接用在 [{{ }}] 表达式中,无需任何特殊语法。
这个组件本身不发出任何 HTTP 调用:它显示通过 props 接收的数据,并通过 [book]/[cancel] 事件 向其父组件(App.vue)通知用户的意图——这与 [Angular] 和 [React] 之间的职责分离完全相同。
6.10.4. src/app/features/booking-dialog/BookingDialog.vue
移植自 [booking-dialog.component.ts/.html] ([Angular])和 [BookingDialog.tsx] ([React]):用于选择患者以预约可用时间段的(模态)窗口。相当于原始 AngularJS 1.x 客户端的示例 9。
我们来解读这段代码:
- 第 35 行:[template v-if="open"] ——一个 [<template>]([Vue.js] 特有的标签,其本身不生成任何元素)承载着 [v-if]:在模态窗口打开之前,DOM 中甚至什么都不会加载——完全相当于 [if (!open) return null;] 在 [React] 一侧的写法,以及 [@if(open())] 在 [Angular] 一侧的写法;
- 第 36 行:[div class="modal-backdrop fade show"] ——使页面其余部分变暗的半透明背景——这里与另外两个变体一样是硬编码的,而 [Bootstrap] 通常会在显示模态窗口时通过 JavaScript 自行插入它;
- 第 38 行:[div class="modal fade show d-block"] ——[d-block] 承担了通常由 [Bootstrap] 的 JavaScript 完成的角色(在打开时添加 [display:block] )——在这里,直接履行这一角色的是第 35 行的 [v-if];
- 第 44 行:[:aria-label="t(‘BOOKING_DIALOG.CLOSE_ARIA’)"] ——不同于 [attr.aria-label="‘BOOKING_DIALOG.CLOSE_ARIA’ | translate"] 在 [Angular] 一侧的写法(与 {{ }} 插值不同的属性绑定),而与 [JSX] 和 [React] (它们不区分属性和元素内容)颇为相似,[Vue.js] 这里使用 [:aria-label="..."]——前缀 [:] 表示属性绑定(一个 JavaScript 表达式),而不是字面字符串。
与另外两个变体一样,这个组件使用模态窗口的真实 [Bootstrap] 类,但其可见性由 [Vue.js]([v-if] 作用于 [open] 属性)控制,而不是由 [Bootstrap] 的 JavaScript([bootstrap.bundle.js, new bootstrap.Modal(...)])控制——以防止二者各自独立地管理同一条信息(模态窗口是否打开?),这是细微 bug 的常见来源。原始文档(2014 年)使用的是 angular-ui-bootstrap 库中的组件(一个“开箱即用”的模态窗口),它已经是按照同样的原则设计的。
6.11. 根 App 组件:协调者与身份验证守门人
这个组件承担着原始 AngularJS 1.x 应用程序中“主控制器”所起的作用,也相当于 [Angular] 和 [React] 两侧的 App 组件:它维护应用程序的全局状态,并响应 features/ 组件的事件,在适当的时机调用 [useAppointmentService()] 。自从加入身份验证后,它还承担了第二个角色:作为表示层上的“守门人”,决定是显示登录界面还是应用程序的其余部分。[Vue.js] 组件把 [.vue] 文件中的内容合并为单个文件,而 [Angular] 把它拆分为三个文件(app.ts、app.html、app.css)——正如 App.tsx 此前已对 [React] 所做的那样。
6.11.1. src/app/App.vue
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
我们来解读这段代码:
- 第 25–26 行:[const lastDoctorId = ref<number | null>(null); const lastDay = ref<string | null>(null);] ——我们保存最近一次搜索(医生 + 日期),以便在预约或取消之后刷新日程表。与 [React] (使用 [useRef](),而不是 [useState]())一样,这两个值从不直接用于显示(不同于日程表或错误页面)——但是,不同于 [React],[Vue.js] 不需要为一个能在多次渲染之间保留、且不触发重绘的变量使用特殊的 Hook([useRef]):因为 [<script setup>] 对每个组件实例只运行一次(不同于每次渲染都会重新执行的 [React] 组件函数),一个简单的 JavaScript 变量(let)同样可行;[ref()] 在这里使用,只是为了与文件其余部分保持一致;
- 第 28–36 行:[watch(() => auth.isLoggedIn, (isLoggedIn) => { if (isLoggedIn) { loadInitialLists(); } }, { immediate: true });] ——每当 [auth.isLoggedIn] 变化时就重新执行其函数体——直接相当于 [effect(() => { if (this.auth.isLoggedIn()) { … } })] 在 [Angular] 一侧的写法,以及 [useEffect](..., [auth.isLoggedIn]) 在 [React] 一侧的写法。[{ immediate: true }] 还会使它在第一次时立即运行,而无需等待变化——这与 [useEffect]() 在 [React] 一侧的行为完全相同(后者至少总会在初始化时运行一次):如果 [localStorage] 中已存有会话(页面重新加载),则启动时列表会立即加载,而无需等待登录;
- 第 112–133 行:[div class="btn-group btn-group-sm" … FR … EN … template v-if="auth.isLoggedIn" …] ——语言选择器始终可见(包括在登录界面上);而角色徽章 + 姓名 + 退出按钮,则仅在 [auth.isLoggedIn] 为真时才显示(第 126–132 行,[template v-if="auth.isLoggedIn"])——逻辑与 [Angular] 和 [React] 完全相同;
- 第 152 行:[Login v-if="!auth.isLoggedIn"] ——只要 [useAuth().isLoggedIn] 为 false,这个组件就只显示 <Login />;由于现在所有服务器路由都受 [JwtAuthGuard] (第 3 章)保护,在登录之前加载医生/客户/日程表无论如何都是没有意义的(还会导致 401 错误)——理由与 [Angular] 和 [React] 完全相同;
- 第 154–171 行:[template v-else … DoctorDayPicker … Schedule … BookingDialog …] ——features/ 中的三个“业务逻辑”组件在这里被组装起来,每个组件接收自己的 props(数据,以 [:] 为前缀)和自己的事件处理函数(以 [@] 为前缀)——完全相当于 [Angular] 一侧的 app.html 模板,在那里同样的三个组件以 [doctors]="doctors()" (search)="onSearchSchedule($event)"…… 的形式出现。
状态([ref])、副作用([watch])和事件处理函数(各个 onXxx 函数):这些正是上一章已经介绍过的同一批元素,在这里应用于整个根组件——这个文件中没有引入任何新内容;只是把它们组装了起来。
6.12. 应用程序使用分步指南
以下屏幕截图是按照与本课程 [Angular] 和 [React] 变体完全相同的操作序列,在这个 [Vue.js] 客户端上获得的:服务器 URL 保持默认值(http://localhost:8080),演示账户为 admin/admin 和 user/user。
6.12.1. 1. 登录界面
页面首次加载时,[useAuth().isLoggedIn] 为 false(localStorage 中没有会话):只显示 <Login />。

登录界面
使用无效的用户名/密码组合尝试登录,会显示 Login.vue 所存储的错误消息:

登录错误
仍然可见的 FR/EN 选择器也会翻译这个界面(以及所存储的错误消息,它无需额外代码即可重新翻译;参见上文的 Login.vue):

法语登录界面
6.12.2. 2. 以管理员身份登录(角色 ADMIN,完全访问)
使用 admin/admin 登录后,App.vue 不再显示 <Login />,而是加载医生/客户([loadInitialLists()],由第 28 行的 [watch(() => auth.isLoggedIn, …, { immediate: true })] 触发):

以 ADMIN 登录后的主页

以 ADMIN 登录后的主页(法语)
在 <DoctorDayPicker /> 中选择医生和日期后,会显示带有“预约”/“取消”按钮的日程表(对于角色 ADMIN,canEdit 为 true):

日程表,ADMIN 视图(“预约”/“取消”按钮可见)
点击“预约”会打开 <BookingDialog />([open] 变为 true;参见 App.vue 中的 [onBookingRequest] ):

预约窗口(Bootstrap 模态窗口)
确认后([onConfirmBooking] 调用 [api.addAppointment(...)],然后 [loadSchedule()] 刷新显示),该时间段就显示为已预约:

预约之后的日程表
点击“取消”([onCancelAppointment] 调用 [api.deleteAppointment(...)])会使该时间段重新变为可预约:

取消之后的日程表
6.12.3. 3. 以用户身份登录(角色 USER,只读)
退出登录(onLogout)后,使用 user/user 账户登录,会显示不同的“USER”徽章:

以 USER 登录后的主页
日程表仍然可以查看,但不会出现“预约”/“取消”按钮:每个时间段的操作列都是空的(参见 Schedule.vue,按钮上的 [v-if="canEdit"] )。直接向服务器发出的请求(例如,使用 Postman 并提供该用户的令牌)仍然会收到 403 Forbidden 响应——隐藏按钮只是为了显示上的便利;真正的限制由服务器端的 [RolesGuard] 强制执行(第 3 章):

日程表,USER 视图(只读,没有操作按钮)
6.13. 未纳入范围或已推迟的内容
原始 AngularJS 1.x 客户端的“调试”模式(显示当前视图的原始模板)是一项被有意从本次移植中省略的功能,与本课程的 [Angular] 和 [React] 变体一样——它不会在课程的后续阶段出现(该决定的理由见第 6 章“结论”)。不过,人为网络延迟的配置在三个变体中确实都推迟到了后续阶段。
此外,这个 [Vue.js] 移植版本还有两处特有的差异,值得在这里一提:
- 单元测试(本项目中没有,本课程的 [Angular] 和 [React] 项目中也没有)在 [Vue.js] 中会采用不同的方式:它不用 TestBed([Angular] 特有)或 [React Testing Library] ([React]),[Vue.js] 生态系统通常依赖 [Vue Test Utils]——本文档不作介绍;
- [<template>] 的类型检查在这里有特殊地位:不同于 [React](标准的 TypeScript 编译器就足够了,因为 [JSX] 只是 JavaScript 的又一种形式),[Vue.js] 专门为此提供了 [vue-tsc] (参见 package.json,第 5 章),用来检查 [<template>] 内部的类型——就这一点而言,这种情形更接近 [Angular] 和 strictTemplates,而不是 [React],尽管它是一个单独的工具,而不是编译器本身的一个选项。