11. 案例研究:RdvMedecins 应用
11.1. 问题描述
The RdvMedecins application manages appointments for a medical practice. Each doctor has time slots (from 8:00 AM to 12:00 PM in 20-minute increments, for example); an appointment consists of a day, a time slot, and a client (a patient). It uses the database and business layers from the [NestJS] server in the courses “An Example of a Flutter Client/Server / NestJS” and “An Example of an Angular Client/Server / NestJS, and displays the same pages as the [Angular] client; but instead of serving JSON to a client [JavaScript] or [Flutter], it generates its own HTML pages.
三种用户 角色 共用该应用:
角色 | 谁 | 可以做什么 |
ADMIN | 管理员([admin]) | 查看日程,为任何患者预约和取消预约;管理(列出、添加、编辑、删除)医生和客户 |
DOCTOR | 医生 | 查看日程,为任何患者预约和取消预约 |
USER | 客户(患者) | 查看日程,但看不到其他患者的姓名;为自己预约;取消自己的预约;管理自己的账户;创建账户 |
主要管理规则:
- 不能在过去的时间预约;
- 同一时段每天只能被预约一次;
- 一个患者同一时间只能有 一个 即将到来的预约;
- 两位医生(或两位客户)不能有相同的名和姓,一个登录名只属于一个账户;
- 有预约的医生不能被删除;删除客户时会连同其预约一起删除;
- 登录页面受到防机器人保护(验证码、限制尝试次数),创建客户账户需要先在该页面上通过验证码。
11.2. 使用应用
11.2.1. 登录页面

页面有两个按钮:登录和创建患者账户。两者都要求输入图像中显示的字符。按钮 FR / EN 用于切换语言:

错误(这里是验证码拼写错误)显示在页面底部,背景为浅粉色:

11.2.2. 日程,管理员和医生看到的样子
登录后,管理员会进入日程页面。他们选择一位医生和一个日期:


每个时段要么可预约(预约 按钮),要么已被占用(患者姓名,取消 按钮)。点击 预约 会打开一个窗口,要求填写患者的信息:

点击 “取消” 会弹出确认提示(这里是以 Pélissier 医生的身份,其导航栏不包含管理菜单):

11.2.3. 患者的主页
患者(USER 角色)进入“我的空间”:显示他们即将到来的预约(可以取消),以及指向其账户管理和日程的链接:

在日程中,他们能看到自己的预约,但看不到其他患者的姓名(显示“已预约”)。由于他们已经有一个即将到来的预约,所以不能再安排另一个:

没有预约的患者可以为自己预约一个可用的时段:

账户管理:编辑他们的信息、更改密码,或删除账户(以及预约)。任何更改都需要当前密码:

试图打开管理员专用页面的患者会收到一个错误页面:

11.2.4. 管理医生和客户
管理员有两个额外的菜单,“医生”和“患者”:


添加医生的表单,提交时带有错误:

与现有医生同名的姓名会被拒绝:

删除客户需要确认:

11.2.5. 创建患者账户
在登录页面上,“创建患者账户” 按钮只有在验证码输入正确时才会打开表单:


11.3. 安装与运行
应用文件夹:
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 | |
[README.md] 文件说明了每个文件夹的用途;这里不再复述。安装并运行应用的步骤:
- 通过运行 [dbrdvmedecins2] 脚本 [database/dbrdvmedecins2.sql] 创建数据库(参见附录);
- 在打开到应用文件夹的控制台窗口中,安装依赖:[npm install];
- 把文件 [.env.example] 重命名为 [.env],并在其中更新连接设置,使之与 [MySQL] 中的设置一致;
- 运行应用:[npm run start:dev],然后打开 [http://localhost:8081]。
演示账户的密码就是它们的登录名:[admin] (ADMIN)、[pelissier]、[tatou]、[dupont] (DOCTOR)、[martin]、[durand]、[bistrou]、[german] (USER)。启动时:
([TypeORM] 显示的 SQL 请求已被删除)
11.4. 应用架构

- [src/main.ts] 配置应用:视图引擎、静态文件、Cookie、异常过滤器;
- [src/auth]:身份验证、令牌(JWT)、角色、CAPTCHA 和尝试次数限制;
- [src/web]:Web 层。它的控制器([src/web/controllers])都通过同一个服务 [ApplicationModelService],该服务把医生和客户的列表保存在内存中,并把其他请求转发给业务层;
- [src/business]:业务规则;
- [src/repositories]:DAO 层,每张表一个类;
- [src/entities]:[TypeORM] 实体;[src/domain]:日程对象,由业务层计算;
- [views]:[Handlebars] 视图;[i18n]:词典;[public]:样式表和页面脚本。
接下来的内容会评述 所有 文件,从下层(数据库)到上层(视图)。
11.5. 数据库
文件 [database/dbrdvmedecins2.sql]:
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 | |
我们来逐行说明这个脚本:
- 第 30 行:与示例 28 一样,排序规则 [utf8mb4_unicode_ci] 在比较时忽略大小写和重音;
- 第 34–38 行:删除表时从“子”表到“父”表依次进行:被外键引用的表,不能在引用它的表之前被删除;
- 第 43–52 行:用户 账户。[password] 包含密码的 bcrypt 哈希(参见示例 25)。第 51 行:登录名是唯一的;
- 第 57–69 行:医生。每位医生都有一个账户(列 [user],指向 [users] 的外键,第 64 行)。名称 [user] 是 [MySQL] 的保留字:因此用反引号括起来。第 66 行:一个账户只属于一位医生;第 68 行:不能有两位医生具有相同的名和姓;
- 第 74–86 行:客户,格式相同;
- 第 91–100 行:每位医生的时段(以小时和分钟表示的开始和结束时间);
- 第 105–115 行:预约:一个日期、一个时段、一位客户。第 114 行:一个时段每天只能被预约一次;
- 第 127–137 行:演示账户;每个账户的密码就是它的登录名;
- 第 141–144 行:每位医生的 [user] 列通过基于登录名的子查询获得,而不是假定生成的凭据;
- 第 167–168 行:一个当天的预约([CURDATE()]),以便立即展示一个已被预约的时段。
11.6. 项目配置
[package.json] 文件:
- 第 7–13 行:[npm run ...] 命令。[start:dev] 以“监视”模式启动应用:每次更改后,代码都会重新编译,服务器也会重启;[--watchAssets] 选项还会监视非代码文件;
- 第 14–34 行:应用的库,示例中都已涉及。[dotenv] 读取文件 [.env];[mysql2] 是 [MySQL] 驱动程序,由 [TypeORM] 使用;[reflect-metadata] 和 [rxjs] 是 [NestJS] 所必需的;
- Lines 35–43: development tools: the [nest] tool, the [TypeScript] compiler, and the type declarations ([@types/...]) for libraries written in [JavaScript].
[tsconfig.json] 文件:
这个文件由 [nest] 工具为新项目生成。与示例相比:第 5 行,注释不会复制到编译后的代码中;第 14 行,只重新编译被修改的文件;第 17 行:接受没有显式类型或无法推断类型的变量(此时它的类型是 [any])——这使得没有类型声明的 [hbs] 包能够被导入。
文件 [nest-cli.json]:
与示例中的相同。
[.env.example] 文件:
- 名为 [.env] 的文件包含特定于机器的配置设置:它绝不共享(其中含有密码)。文件 [.env.example] 则作为供复制的模板;
- 第 9 行:应用的端口;
- 第 13–17 行:数据库连接;
- 第 24–30 行:令牌密钥、其有效期(两小时),以及 [secure] Cookie 选项(在生产环境中,站点通过 HTTPS 提供服务,Cookie 绝不能通过未加密的连接传输);
- 第 37–44 行:防机器人保护的阈值。
[src/config/database.config.ts] 文件:
数据库连接(参见示例 28)。第 46 行:除生产环境外,都会显示 SQL 请求。
[src/config/paths.ts] 文件:
- 第 12 行:编译后,此文件位于 [dist/config]:项目根目录在它上面两级;
- 第 14–18 行:未经编译的文件夹(视图、静态文件、词典),以及 [Bootstrap] 的文件夹。
11.7. 启动应用
文件 [src/main.ts]:
我们来逐行剖析这段代码:
- 第 15 行:[dotenv/config] 读取文件 [.env] 并把其中的值放入 [process.env]。这个导入必须是 第一个:其他模块一加载就会读取 [process.env] (例如 [JWT_SECRET]);
- 第 37–38 行:静态文件(参见示例 15);
- 第 43–49 行:视图引擎、辅助函数和局部视图(参见示例 15 和 16);
- 第 53–54 行:读取 Cookie,然后是为每个页面准备语言和闪现消息的中间件(参见 [web/view-context.ts]);
- 第 58–59 行:一个全局拦截器把已登录的用户暴露给视图,一个全局过滤器把异常转换为 HTML 页面(参见第 7 章);
- 第 61 行:端口,从 [.env] 读取(默认为 8081)。
[src/app.module.ts] 文件:
- 第 38 行:数据库连接;
- 第 39 行:此模块管理的四个实体的仓库([User] 的仓库由 [AuthModule] 声明);
- 第 43 行:身份验证模块,带有自己的控制器和服务;
- 第 45–52 行:Web 层控制器;
- 第 53–60 行:服务:DAO 层(四个仓库)、业务层和 Web 层缓存。第 58 行:业务层以 令牌 ([BUSINESS_TOKEN])而不是其类名注册:使用它的对象依赖的是 [IBusiness] 接口,而不是 [BusinessService] 类。只需修改这一行,就可以替换实现(例如换成测试版本)。
11.8. 实体
[TypeORM] 实体映射到数据库表和 [TypeScript] 类(参见示例 28)。它们的注释经常提到 [Java] / [Spring] 项目(本应用是它的远亲后代),以及“JSON 服务器”:即客户端/服务器课程中的 [NestJS] 服务器,其案例研究整合了 DAO 层和业务层。
11.8.1. src/entities/abstract.entity.ts
- 第 19 行:一个没有 抽象类装饰器 [@Entity] 的类:它不对应任何表,但它的列会被添加到子类的列中;
- 第 27–28 行:主键,由数据库生成;
- 第 39–40 行:行版本,每次修改时由 [TypeORM] 递增(乐观锁;参见示例 28)。
11.8.2. src/entities/person.entity.ts
- 第 17 行:[Doctor] 和 [Client] 的父类,它本身是 [AbstractEntity] 的子类;
- 第 18–25 行:称谓、姓、名;
- 第 34–36 行:与用户账户的 一对一关系。[@JoinColumn] 表示此表包含外键,位于列 [user] 中。该关系只在被请求时才加载(查询中的选项 [relations] );
- 第 40–41 行:[@RelationId] 暴露外键的值(账户 ID),而无需加载账户本身。
11.8.3. src/entities/doctor.entity.ts
- 第 18 行:该类对应于表 [doctors];
- 第 24 行:唯一性约束,写在这里只是为了文档说明;它实际上由 SQL 脚本创建([synchronize: false]);
- 第 30–31 行:与医生时段的 一对多关系,是 [@ManyToOne] 关系(来自 [Slot])的反向关系。
11.8.4. src/entities/client.entity.ts
一位客户(患者):来自 [Person] 表 [clients] 的实体,没有额外的字段。
11.8.5. src/entities/slot.entity.ts
- 第 24–27 行:开始和结束的小时与分钟;
- 第 39–41 行:与医生的 多对一关系:一位医生有多个时段。外键是 [doctor_id] 列;
- 第 51–52 行:医生的 ID,无需加载医生。
11.8.6. src/entities/appointment.entity.ts
- 第 31 行:一个预约时段每天只能被预约一次;
- 第 36–37 行:一个 [DATE] 类型的列,被当作字符串 [yyyy-mm-dd] 处理:没有时区问题,并且两个日期按字符串比较;
- 第 39–45 行:客户和预约时段;
- 第 49–53 行:它们的 ID。
11.8.7. src/entities/user.entity.ts
- 第 21 行:字符串的 联合类型:类型为 [Role] 的变量只能是这三个字符串之一;
- 第 31–32 行:密码 哈希;
- 第 36–37 行:显示在导航栏中的名称(“Marie PELISSIER”);
- 第 39–40 行:角色。这里指定了列类型:[TypeORM] 无法从联合类型推断出 SQL 类型。
11.9. 领域:日程
[domain] 文件夹包含两个类,它们不对应任何表:它们描述由业务层计算出的 一位 医生一天的 日程 。
11.9.1. src/domain/doctor-day-slot.ts
第 22–25 行:一个时段,以及该时段在当天所安排的预约(如果时段可用,则为 [null] )。构造函数参数中的 [public slot: Slot] 语法一步完成字段的声明和初始化。
11.9.2. src/domain/doctor-day-schedule.ts
日程:一位医生、一天,以及他们的时段列表,无论是可用的还是已被预约的。
11.10. DAO 层
每张表一个类。它们都遵循示例 28 中的模型:一个注入的 [Repository] [TypeORM]、一个为当前事务选择仓库的 [repo(manager)] 方法,以及不含业务逻辑的简短方法。
11.10.1. src/repositories/doctor.repository.ts
- 第 28–30 行:在事务中,当前事务的仓库([manager]);
- 第 33–35 行:所有医生,连同他们的账户([relations: { user: true }]),按姓再按名排序。账户用于在医生列表中显示登录名;
- 第 45–47 行:任何可能的同名者。比较由 [MySQL] 按数据库的排序规则执行;
- 第 49–51 行和第 53–55 行:写入和删除操作。
11.10.2. src/repositories/client.repository.ts
与医生相同的方法,另加两个:
- 第 35–37 行:指定账户所对应的客户——已登录的患者(其令牌包含其 账户 ID)就是这样取得自己的客户记录的。[TypeORM] 把过滤条件 [where: { user: { id: userId } }] 转换为 [WHERE clients.user = ?];
- 第 45–47 行:带 锁 的读取([lock: { mode: 'pessimistic_write' }],即 SQL 中的 [SELECT ... FOR UPDATE] )。在事务结束之前,任何请求同一把锁的其他事务都会 等待。预约调度模块利用这一点,把针对同一位患者的两个同时发生的预约依次处理。
11.10.3. src/repositories/slot.repository.ts
- 第 27–34 行:医生的预约时段,按时间顺序排列。该查询使用 QueryBuilder (来自 [TypeORM])编写,它逐个方法地构造一条 SQL 查询:[createQueryBuilder('s')](表,别名为 [s])、[where] (带有名为 [:doctorId] 的参数——绝不是字符串拼接,那样会为 SQL 注入敞开大门)、[orderBy],然后是 [getMany],由它执行查询;
- 第 38–41 行:删除医生的预约时段,在删除该医生时使用。
11.10.4. src/repositories/appointment.repository.ts
- 第 43–51 行:医生在某一天的预约。[leftJoinAndSelect] 执行连接 并 加载被连接的实体:每个预约都连同其患者和时段一起取回;
- 第 56–67 行:客户从某一天开始的预约,连同其时段 以及 分配给该时段的医生(两次级联连接):这就是“我的空间”中显示的内容;
- 第 70–76 行:它们的数量,用于“只能有一个即将到来的预约”这条规则;
- 第 80–82 行:删除某位客户的所有预约;
- 第 87–93 行:医生的预约数量。表 [appointments] 并不直接引用医生:必须通过时段([innerJoin],不加载的连接)。
11.10.5. src/repositories/user.repository.ts
第 26–28 行:某个登录名对应的账户,用于登录以及检查登录名是否可用。
11.11. 业务层
11.11.1. src/business/dates.ts
第 14–18 行:今天的日期,格式为 [yyyy-mm-dd];即列 [appointments.day] 中的日期。[padStart(2, '0')] 用于给数字补足两位(9 变成 [09])。在这种格式下,字母顺序就是时间顺序:两个日期用 [<] 比较。
11.11.2. src/business/business.exception.ts
- 第 17 行:[BusinessException] 携带的不是消息,而是一个 翻译键 ([ERRORS.LOGIN_TAKEN])。因此业务层不关心界面语言:由视图翻译该键(参见第 5 章);
- 第 18 行:任何消息参数;
- 第 21 行:异常名称,显示在错误日志中。
11.11.3. src/business/business.interface.ts
- 第 17–30 行:要创建或修改的医生或客户的数据。用户名和密码是可选的:创建时,默认为小写的姓名;修改时,只有在输入了新值时才会改变;
- 第 32–78 行:业务层 契约——其他层可以向它请求什么。注释 [/** ... */] 是文档注释,当你把鼠标悬停在方法上时,由 [VS Code] 显示;
- 第 80 行:实现在 [app.module.ts] 中注册时使用的令牌。[TypeScript] 接口在编译时会消失:它不能用于依赖注入。因此,注入是通过这个令牌完成的:[@Inject(BUSINESS_TOKEN)]。
11.11.4. src/business/business.service.ts
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 | |
这是应用中最全面的文件。我们逐节来剖析它。
11.11.4.1. 描述符
- 第 54 行:bcrypt 的成本,与 SQL 脚本中的相同;
- 第 59–64 行:医生和客户的 DAO 文件的共同之处。[TypeScript] 按类型的 形状来比较类型:[DoctorRepository] 和 [ClientRepository] 无需声明([implements])就满足这个接口;
- 第 67–80 行:在业务逻辑方面,区分医生和客户的一切:它的 DAO、如何创建实例、其账户的角色、其错误消息,以及删除时会发生什么。由于医生和客户遵循相同的规则,这些规则的代码只写一次,放在由描述符参数化的泛型方法中;
- 第 87–98 行:构造函数接收 [DataSource] (用于开启事务)和五个 DAO。它构造两个描述符。医生的描述符(第 99–111 行)禁止删除有预约的医生([countAppointments]),并在删除医生之前先删除其时段([beforeDelete])。客户的描述符(第 112–122 行)没有 [countAppointments]:删除客户时会连同其预约一起删除。
11.11.4.2. 读取操作与日程
- 第 129–167 行:查询委托给 DAO 层;
- 第 170–185 行:日程计算。读取医生的时段和当天的预约;预约被存入以时段 ID 为索引的 [Map] 中;然后每个时段与它的预约关联起来,或者与 [null] 关联。[Map] 避免了为每个时段扫描预约列表。
11.11.4.3. 安排预约
- 第 203–221 行:一切都在同一个事务中进行;
- 第 206–208 行:不能在过去的时间预约;
- 第 209–211 行:患者的记录被 锁定。没有这把锁,同时提交的针对同一位患者的两个预约(两个标签页、双击)可能都通过下面的检查,而此时两者都还没有把预约写入数据库。有了这把锁,第二个事务会等待第一个事务完成,然后看到它所创建的预约;
- 第 212–214 行:每位患者只能有一个即将到来的预约;
- 第 215–219 行:插入。如果 另一位患者刚刚预约了同一个时段,约束 [unq1_appointments] 会拒绝这次插入,而 [transaction] 方法会处理该错误(见下文);
- 第 223–225 行:删除预约。
11.11.4.4. 医生和客户的管理
- 第 232–256 行:六个公共方法委托给三个泛型方法,并使用正确的描述符;
- 第 262–288 行:创建。姓名首字母大写;默认情况下,用户名是小写的姓名,密码就是用户名(第 267–268 行)。在事务中:验证唯一性规则,创建 账户(密码被哈希),然后创建 人员,并将其与账户关联。如果第二次写入失败,第一次写入会被回滚:绝不会出现没有对应人员的账户;
- 第 295–299 行:更新。乐观锁(第 308–310 行)会拒绝在此期间已被修改的记录。账户的显示名称跟随名和姓变化;用户名和密码只有在输入了新值时才会改变;
- 第 341–356 行:删除,按外键所要求的顺序进行:可能的拒绝(有预约的医生)、删除对该人员的引用(医生的时段、客户的预约)、删除该人员,然后删除其账户;
- 第 361–367 行:同名的人员会被拒绝,除非就是本人(修改时);
- 第 374–378 行:已被占用的用户名会被拒绝。
11.11.4.5. 事务与唯一性约束
- 第 392–398 行:所有写操作都经过这个方法:[dataSource.transaction] 提交或回滚事务(参见示例 28),而错误由 [translateDuplicate] 转换;
- 第 411–416 行:SQL 脚本中的每个 命名的唯一性约束都有自己的错误消息;
- 第 420–432 行:带有代码 [QueryFailedError] 的 SQL 错误 [ER_DUP_ENTRY] 表示违反了唯一性约束。它的消息包含约束名称(在 [MySQL] 8 中带有表名前缀,在 [MariaDB] 中没有前缀):第 429 行的正则表达式会提取它。已知的约束会变成 [BusinessException];任何其他错误则原样报告:这是一个真正的异常情况。
11.12. 身份验证
[auth] 文件夹以更完整的形式包含了示例 25 至 27:Cookie 中的 JWT 令牌、角色、CAPTCHA 和尝试次数限制。它还包含一个用于创建账户的“通行证”。
11.12.1. src/auth/auth.constants.ts
- 第 4–21 行:注释解释了为什么令牌存放在 Cookie 中,以及它的每个选项的用途(参见示例 25);
- 第 28 行:密钥,从 [.env] 读取。默认值只应在开发期间使用;
- 第 30–32 行:令牌的有效期:默认为两小时;
- 第 34–42 行:Cookie 选项,集中在一处(用于登录和修改患者账户)。[secure] 只在生产环境中启用,因为那里的站点通过 HTTPS 提供服务;[maxAge] 的单位是毫秒。
11.12.2. src/auth/auth.service.ts
- 第 26–32 行:如果用户名和密码正确,则为该账户([bcrypt.compare]),否则为 [null] ;
- 第 34–37 行:令牌,其中包含 ID、用户名、显示名称和角色;
- 第 41–50 行:[jwtService.verify] 验证令牌的签名和过期日期,如果无效则抛出异常。这个方法由 不受保护的页面(登录页面)使用,这些页面想要确定用户是否已经登录。
11.12.3. src/auth/jwt.strategy.ts
- 第 20–25 行:令牌的内容;
- 第 28–33 行:[req.user] 将包含的内容;
- 第 38–45 行:从 Cookie 中读取令牌;如果它已过期或签名不正确,就会被拒绝;
- 第 48–50 行:令牌的内容成为 [req.user]。
11.12.4. src/auth/jwt-auth.guard.ts
要求提供有效令牌的守卫(参见示例 25)。没有令牌时,它会抛出 [UnauthorizedException],异常过滤器会把它转换为重定向到 [/login]。
11.12.5. src/auth/roles.decorator.ts
第 19 行:[@Roles(...)] 装饰器(参见示例 26)。它的参数类型为 [Role]:[@Roles('ADMIM')] (拼写错误)会被编译器拒绝。
11.12.6. src/auth/roles.guard.ts
角色映射与示例 26 中的相同。
11.12.7. src/auth/captcha.service.ts
- 第 29–31 行:与示例 27 相比,验证码有生存期(十分钟),并且内存中的验证码数量有上限:一个机器人即使请求登录页面数百万次,也无法耗尽服务器的内存;
- 第 42 行:[Map] 保留插入顺序:它最前面的条目是最旧的;
- 第 44–57 行:图像、其预期答案(小写)及其过期日期;
- 第 61–68 行:比较答案时不区分大小写;无论哪种情况,验证码都会被消耗;
- 第 70–77 行:已过期的验证码会被丢弃,达到上限时最旧的验证码也会被丢弃。
11.12.8. src/auth/attempt-limiter.service.ts
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 | |
- 第 26–30 行:一个尝试次数计数器,带有其计数窗口的起点和锁定结束日期;
- 第 34–37 行:从 [.env] 读取的阈值,带有默认值;
- 第 50–52 行:锁定作用于(IP 地址,登录名)这一对,当某个 IP 地址在所有登录名上累积了大量失败尝试时,则单独作用于该 IP 地址。在教室里,所有工作站往往通过同一个 IP 地址连接:一个输错密码的学生不应该把邻座的同学也锁在外面;
- 第 54–57 行:一次失败的尝试会同时计入两个键;
- 第 66–68 行和第 70–73 行:限制同一 IP 地址每小时创建的账户数量;
- 第 84–98 行:计数。过期的窗口会重置为零;达到阈值时,该键被封锁;
- 第 101–110 行:清除旧的计数器,以防止键在内存中无限累积;
- 第 113–118 行:为 [Map] 生成键。
11.12.9. src/auth/registration-pass.service.ts
创建患者账户可以从登录页面进行,前提是已经通过验证码。因此,一个请求(注册表单)必须知道 之前的请求已经通过了验证码。这就是通行证的作用:
- 第 38–43 行:一个随机标识符,有效期 15 分钟,存放在内存中;它会被保存在 Cookie 里;
- 第 46–52 行:只有持有有效通行证时,注册表单才会被显示和接受;
- 第 55–59 行:创建账户会消耗通行证:通过一次验证码,只能创建一个账户,不能更多;
- 第 61–63 行:选项 [path: '/register'] 把 Cookie 的发送限制在以 [/register] 开头的 URL。
11.12.10. src/auth/auth.controller.ts
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 | |
我们来逐行说明这段代码:
- 第 34–36 行:主页取决于用户的角色:患者是“我的空间”,其他所有人是日程;
- 第 46–50 行:站点根路径根据用户是否已登录进行重定向。由于该路由不受守卫保护,令牌由 [readToken] 验证;
- 第 54–62 行:已经登录的用户会被送到他们的主页。参数 [login] 预先填充该字段(在创建账户之后)。[slice(0, 30)] 限制其长度:来自请求的数据绝不能不加防范地使用;
- 第 69–73 行:登录流程,按顺序为:可能的锁定、验证码,然后是密码(参见示例 27)。[req.ip] 是客户端的 IP 地址。成功时:计数器清零,设置 Cookie,重定向到该角色的主页;
- 第 104–108 行:注销;
- 第 111–116 行:登录页面,始终带有新的验证码。错误是一个翻译键,连同它的参数(锁定的分钟数)。
11.12.11. src/auth/auth.module.ts
- 第 28 行:[User] 实体的仓库;
- 第 30–33 行:[JwtService] 的配置;
- 第 44 行:向根模块 导出 的服务(参见示例 06):[UserRepository] 供业务层使用(创建医生或客户的账户),其余的供 Web 层控制器使用(创建账户、患者管理账户)。
11.13. Web 层:公共服务
在查看控制器之前,先看它们的共同之处:翻译、每个页面的上下文、拦截器、异常过滤器、列表缓存和辅助函数。
11.13.1. src/web/i18n.ts
示例 22 中的翻译模块,只有一处补充说明(第 42 行):如果某个键在法语词典中缺失,就到英语词典(默认语言)中查找;如果两者都缺失,则显示键本身。
11.13.2. src/web/view-context.ts
我们来逐行说明这段代码:
- 第 22–23 行:语言和闪现消息 Cookie 的名称;
- 第 26–30 行:闪现消息:一个类型(成功或错误)、一个翻译键及其参数。它以 JSON 形式存放在 Cookie 中;
- 第 33–39 行:已登录的用户,即视图所看到的样子。布尔值 [isAdmin] and [isPatient] 使视图不必比较字符串;
- 第 48–64 行:在任何路由之前执行的中间件(参见示例 20 和 22):语言、路径(用于高亮当前菜单)和闪现消息,后者先读取然后清除。[JSON.parse] 由 [try] 保护:手动修改过的 Cookie 不应导致页面出错;
- 第 66–69 行:语言,基于其 Cookie;
- 第 80–82 行:显示闪现消息(参见示例 20);
- 第 89–102 行:把已登录的用户([req.user])复制到 [res.locals] 中,供导航栏使用。这个函数不是由中间件调用的:中间件在守卫 之前运行,因此在 [req.user] 存在之前运行(参见第 7 章)。它由下面的拦截器和异常过滤器调用。
11.13.3. src/web/view-user.interceptor.ts
第 22–26 行:拦截器在守卫之后、操作之前运行:这是暴露 [JwtAuthGuard] 所传递的用户的恰当时机。它在操作之后无事可做:直接返回 [next.handle()]。
11.13.4. src/web/html-exception.filter.ts
- 第 25–29 行:每个错误码对应的消息键;
- 第 42–50 行:401 会重定向到登录页面。如果存在令牌 Cookie,说明它已经过期(或者账户已被删除):该 Cookie 会被删除,并通过闪现消息通知用户;
- 第 52–56 行:真正的错误会记录在服务器控制台中,连同其调用栈,但绝不会透露给用户:这些细节会帮助攻击者;
- 第 60–65 行:错误页面,带有已登录用户的导航栏。
11.13.5. src/web/application-model.service.ts
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 | |
我们来逐行说明这段代码:
- 第 25 行:该服务与业务层具有相同的接口:对控制器来说,它 就是业务层。它位于两者之间,把医生和客户的列表保存在内存中(应用作用域,参见第 6 章),这些列表几乎在每个页面上都要显示;
- 第 29 行:业务层通过其令牌注入;
- 第 34–37 行:[onModuleInit] 在模块构建完成之后、服务器启动之前由 [NestJS] 调用:列表在启动时读取。如果数据库无法访问,应用会以一条清晰的消息终止;
- 第 49–55 行:列表从内存中提供;
- 第 59–61 行:医生的账户:已登录的医生能立即看到自己的日程;
- 第 65–109 行:其他请求原样转发;
- 第 113–145 行:任何涉及医生或客户的写操作都会 刷新 相关的列表。由于这个服务是进入业务层的唯一入口,“写入 = 刷新缓存”这条规则只在这里实现,缓存就不会过时。
11.13.6. src/web/views/handlebars-helpers.ts
- 第 31–37 行:翻译辅助函数(参见示例 22);
- 第 39 行:相等性检查(参见示例 16);
- 第 43 行:如果任一参数为真,则为真。[...args] 接收所有参数;最后一个是 [options] 对象,来自 [Handlebars],它会被丢弃;
- 第 45–47 行:当前菜单的 [active] 类(参见示例 16)。
11.13.7. src/web/models/person-form.dto.ts
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 | |
我们来逐行说明这段代码:
- 第 32 行:可能的称谓;
- 第 34–42 行:在验证之前由 [@Transform] 应用的清理函数:去除空格,空字段简化为 [undefined] (这样 [@IsOptional] 才会接受它们),登录名转为小写,版本转换为数字。密码不做清理:它的空格也是密码的一部分;
- 第 45 行:用户名的格式,由正则表达式描述;
- 第 50–64 行:身份字段,三个表单共用。最大长度与 SQL 列的相同。消息是翻译 键;
- 第 67–85 行:ADMIN 表单(医生或客户):可选的用户名和密码,以及用于乐观锁的版本。[extends]:该类从其父类继承 字段 和装饰器 。密码必须不超过 72 个字符;bcrypt 会忽略超出该限制的任何字符;
- 第 88–103 行:患者创建账户:用户名和密码必填,至少六个字符,并需确认;
- 第 106–132 行:患者修改自己的账户:新密码可选,当前密码必填。
11.13.8. src/web/helpers/form.helper.ts
- 第 27–30 行:表单验证,与示例 19 中一样。选项 [forbidUnknownValues: false] 是必需的,因为我们验证的是由 [plainToInstance] 生成的对象,而不是从 [ValidationPipe] 接收的对象;
- 第 52–56 行:某些业务错误与特定字段相关(例如已被占用的用户名):这些字段会用红色高亮显示,消息则显示在页面底部;
- 第 60–66 行:要用红色高亮显示的字段;
- 第 69–71 行:称谓列表中的选项,所选的一项高亮显示(参见示例 18)。
11.13.9. src/web/helpers/dates.helper.ts
- 第 10 行:当前日期在业务层中定义;这个模块 重新导出它:控制器从同一个位置导入所有日期函数;
- 第 14–20 行:一个真实存在的 [yyyy-mm-dd] 日期(参见示例 12);
- 第 29–34 行:根据语言完整拼写出的日期。[timeZone: 'UTC'] 选项可以避免服务器未设置为格林尼治标准时间时出现一天的偏差。
11.13.10. src/web/helpers/patient.helper.ts
- 第 23–25 行:“Mme Alice DURAND”;
- 第 27–30 行:已登录患者的记录,根据其账户获取。如果它已不存在(账户在另一个标签页中被删除,或被 ADMIN 删除,即使令牌仍然有效),则返回 401 错误:重定向到登录页面。
11.14. Web 层:控制器
11.14.1. src/web/controllers/language.controller.ts
示例 22 中的控制器。注意:如果原始页面本身就是 [/language/...] 页面(第 40 行),请求会被重定向到站点根路径,以防止无限循环。
11.14.2. src/web/controllers/schedule.controller.ts
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 | |
应用的主页面。我们逐节来梳理这段代码。
11.14.2.1. 页面的 URL 部分
第 9–14 行的注释描述了这些路由。请注意,预约窗口不是由 [JavaScript] 打开的:而是 URL 的一个参数([book=7])指示服务器显示窗口已打开的页面。因此 “预约” 按钮只是一个链接。整个页面由其 URL 描述:你可以重新加载它、把它加入书签,或使用浏览器的“后退”按钮。
11.14.2.2. 视图模型
- 第 56 行:受保护路由的请求类型:一个 [Express] 请求,其 [user] 字段由 [JwtAuthGuard] 设置;
- 第 62–106 行:视图模型是 有类型的。视图只接收已经格式化([time: "8:00 - 8:20"])并根据用户角色过滤过的数据;它不做任何决定。在 [ScheduleRowView] (第 68–77 行)中,当用户无权查看患者姓名时,[patient] 等于 [null] ;[bookable] and [appointmentId] 决定是否显示 “预约” 和 “取消” 按钮;
- 第 109–113 行:控制器对已登录用户所了解的信息。
11.14.2.3. GET /schedule
- 第 115–116 行:所有路由都需要已登录的用户。类上没有 [@Roles] 时,所有角色都可以访问该页面;
- 第 127–132 行:URL 的三个参数,都是可选的,以字符串形式接收,稍后再转换;
- 第 137–145 行:所请求的日期,如果有效;否则为今天。只能从今天开始预约;
- 第 148–151 行:所请求的医生;否则,已登录的医生看到自己的日程;
- 第 153 行:医生的下拉列表,从缓存中获取;
- 第 157–184 行:由业务层计算出的日程被转换为表格行。第 175 行是 应用的 隐私检查点:患者只会收到 自己 预约的姓名。对于其他预约,模型中包含 [null],视图显示“已预约”。姓名并不是简单地被视图隐藏:它从未发送到浏览器;
- 第 188–198 行:只有当所请求的时段 对该用户可预约时,预约窗口才会打开。管理员从列表中选择患者;患者为自己预约;
- 第 200–210 行:模型 [info] 向已有预约的患者解释,为什么他们看不到 “预约” 按钮。
11.14.2.4. POST /schedule/book
- 第 225 行:三种角色都可以预约;
- 第 231 行:[doctorId] 和 [day] 字段(在表单中是隐藏的)使用户能够返回所显示的日程;
- 第 238–239 行:对于患者,字段 [clientId] 会被 忽略:患者总是为自己预约。如果依赖浏览器发送的这个字段,狡猾的患者就可以替别人预约;
- 第 242–246 行:没有选择患者的管理员会被送回预约窗口,并附带一条消息;
- 第 251–254 行:时段必须存在,并且属于日程中的那位医生;
- 第 256–261 行:业务规则由业务层验证。对于患者,消息“该患者已有一个即将到来的预约”会被替换为直接对患者说的消息;
- 第 275 行:PRG 模式:无论结果如何,都显示闪现消息并重定向到日程。
11.14.2.5. POST /schedule/cancel
第 282–299 行:仅限管理员;患者在“我的空间”中取消自己的预约。已经被取消的预约(因双击或被另一位管理员取消)会返回错误消息,而不是错误页面。
11.14.2.6. 权限与工具函数
- 第 304–311 行:管理员拥有全部权限;患者在没有即将到来的预约时可以预约;
- 第 317–320 行:把参数安全地转换为标识符;
- 第 323–329 行:无效的隐藏字段只可能来自手工构造的请求:400 错误;
- 第 331–337 行:[URLSearchParams] 构造正确编码的查询字符串;
- 第 345–351 行:[BusinessException] 变成闪现消息;任何其他异常都会向上传播到异常过滤器。
11.14.3. src/web/controllers/persons.controller.ts
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | |
医生和客户的处理是相同的。我们不写两个相似的控制器,而是创建一个 抽象类,两个控制器都继承它。
- 第 44–53 行:每种人员特有的文本(翻译键);
- 第 55–63 行:每个子类提供的配置:基础 URL、文本,以及用于列出、搜索、添加、修改和删除的待调用函数;
- 第 75 行:一个 抽象字段:每个子类都必须定义它;
- 第 82–99 行:列表。应用于父类的路由装饰器会被继承:[NestJS] 通过遍历原型链找到它们。模型为每个人员包含其按钮所用的 URL;
- 第 104–107 行和第 112–126 行:添加,分三步,与示例 28 中一样:验证、业务层、PRG;
- 第 133–146 行和第 151–157 行:修改。[ParseIntPipe] 会拒绝非数字的标识符(400 错误);
- 第 176–189 行:删除。事先取回该人员,以便在确认消息中显示其姓名;
- 第 199–206 行:表单,既用于创建([id === null]),也用于修改;
- 第 223–235 行:在此期间已被删除的人员会被送回列表;其他业务错误会重新显示表单,并用红色高亮显示相关字段;
- 第 239–247 行:要重新显示的值(绝不包括密码)。
11.14.4. src/web/controllers/doctors.controller.ts
- 第 21–22 行:仅限 ADMIN。应用于类的 [@Roles] 适用于它的所有路由,包括继承来的路由;
- 第 25–42 行:配置:医生的翻译键,以及要调用的缓存方法;
- 第 48–50 行:一个显式的构造函数,尽管它只是调用父类的构造函数;这使编译器能够为 这个 类生成 [NestJS] 所需的类型元数据,以便知道该注入什么。
11.14.5. src/web/controllers/clients.controller.ts
同样的控制器,用于客户。
11.14.6. src/web/controllers/registration.controller.ts
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | |
我们来逐行说明这段代码:
- 第 69–91 行:登录页面上的 “创建患者账户” 按钮把登录表单发送到这个地址(属性 [formaction];参见示例 20)。页面的验证码会被验证;如果正确,通行证会存入 Cookie,浏览器被重定向到表单;
- 第 96–102 行:表单,但只在持有有效通行证时;
- 第 109–163 行:创建账户:通行证、时间限制、验证(包括验证密码与其确认一致)、由业务层创建。然后通行证被消耗,患者被重定向到登录页面,其用户名已预先填好;
- 第 168–175 行:没有通行证时,带着一条消息返回登录页面;
- 第 178–185 行:表单。[passwordMin] 用于帮助文本(“至少 6 个字符”)。
11.14.7. src/web/controllers/patient-area.controller.ts
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 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | |
我们来逐行说明这段代码:
- 第 59–60 行:仅限患者;
- 第 14–17 行:这个控制器的黄金法则:所涉及的患者 始终是与令牌关联的那一位,绝不是浏览器发送的标识符;
- 第 74–91 行:“我的空间”页面。[@Res({ passthrough: true })] 提供对响应的访问(以便读取 [res.locals] 中的语言并格式化日期),同时不放弃 [@Render] (参见示例 05);
- 第 96–101 行:取消预约。对不存在的预约和其他患者的预约,会给出 相同的 响应:不会泄露任何关于其他患者预约的信息;
- 第 118–128 行:账户表单,已预先填充;
- 第 133–139 行:更新:验证、检查当前密码,然后是业务逻辑层。令牌包含登录名和显示名称:更新之后会签发一个 新的 令牌(第 182 行);否则,导航栏会保留旧的姓名;
- 第 198–203 行:删除账户、记录和所有预约(使用与 ADMIN 相同的业务层方法),然后注销;
- 第 219–223 行:任何更改都需要当前密码:发现一个没有关闭的会话的人,将无法更改密码或删除账户。错误计为登录失败;
- 第 241–248 行:表单。
11.15. 视图
视图几乎不需要做任何决定:它们的模型已由控制器准备好。每个视图都以一条 [Handlebars] [{{!-- ... --}}] 注释开头,说明它的角色;这些注释不会出现在发送给浏览器的页面中。
11.15.1. 模板和局部模板文件
11.15.1.1. views/layout.hbs
- 第 22 行:页面的语言(参见示例 22);
- 第 26 行:标题,已翻译:键 [pageTitle] 由每个操作提供;
- 第 32–35 行:导航栏、成功消息、页面和错误区域;
- 第 38–39 行:确认窗口及其脚本(参见示例 21)。
11.15.1.2. views/partials/navbar.hbs
- 第 14–25 行:菜单取决于角色:患者是“我的空间”,ADMIN 是“医生”和“患者”。这只是为了方便;安全性由控制器的守卫来保证;
- 第 31–34 行:FR / EN 链接;
- 第 36–43 行:角色、姓名,以及位于 POST 表单中的注销按钮。
11.15.1.3. views/partials/flash.hbs
第 10 行:消息是一个键;它可能带有的参数([name]、[login]、[minutes])会传给辅助函数 [t]。
11.15.1.4. views/partials/errors.hbs
第 16 行:如果存在页面错误 或 闪现错误消息,则显示该区域:辅助函数 [or] 把两个条件结合起来,其中 [eq] 用作子表达式。
11.15.1.5. views/partials/confirmation.hbs
示例 21 中的窗口,带有翻译后的标签和无障碍属性:[role="alertdialog"],以及 [aria-labelledby] / [aria-describedby],它们指定屏幕阅读器朗读的标题和消息。
11.15.1.6. views/partials/captcha.hbs
- 第 20 行:SVG 图像,原样插入(三重花括号):它由服务器生成,不含用户输入;
- 第 21 行:“换一张图片”只是重新加载页面;
- 第 23 行:验证码标识符,位于隐藏字段中。
11.15.1.7. views/partials/personFields.hbs
身份字段,三个表单共用(参见示例 19)。不带参数插入的局部模板使用插入它的页面的模型:[values], [titles], [errors], [invalidFields]。
11.15.1.8. views/partials/booking.hbs
- 第 13–14 行:模态窗口的 [Bootstrap] 类,以“硬编码”方式使其可见:由服务器决定是否显示它;
- 第 19 行:关闭窗口就是访问指向同一页面、但不带 [book] 参数的链接;
- 第 26–28 行:表单的隐藏字段;
- 第 30–34 行:患者看到自己的姓名;管理员从列表中选择患者。
11.15.2. 页面
11.15.2.1. views/login.hbs
- 第 20 行:光标放在登录名字段中;如果已知登录名,则放在密码字段中;
- 第 28 行:验证码;
- 第 41–42 行:第二个按钮把同一个表单提交到 [/register/access] ([formaction])。[formnovalidate]:浏览器不要求填写用户名和密码,因为创建账户并不需要它们。
11.15.2.2. views/schedule.hbs
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 | |
- 第 16–35 行:选择医生和日期:一个 GET 表单(参见示例 17)。字段 [type="date"] 以 [yyyy-mm-dd] 格式发送日期;
- 第 38–42 行:已有预约的患者看到的消息;
- 第 59–96 行:每个时段一行。[{{else if patient}}] 依次列出各种状态:可预约、已预约且姓名可见、已预约但不显示姓名(“已预约”);
- 第 80 行:“预约” 是一个链接;
- 第 86–92 行:“取消” 是一个带确认的 POST 表单。在循环中,[@root.doctorId] 指的是页面模型中的字段,而不是行中的字段;
- 第 108–110 行:预约窗口,如果控制器已经准备好它。
11.15.2.3. views/persons/list.hbs
一个供医生和客户共用的视图:文本以键的形式提供([keys.title], [keys.add]……)。第 38 行:在循环中必须使用 [@root.keys] 。
11.15.2.4. views/persons/form.hbs
- 第 24 行:提交地址([action])由控制器提供。 [novalidate]:由服务器进行验证;
- 第 25–27 行:版本号,用于修改;
- 第 30 行:身份字段;
- 第 35–42 行:登录名,带有帮助文本或错误消息;
- 第 46–54 行:密码,从不预填。
11.15.2.5. views/account/registration.hbs
创建账户。第 42 行:帮助文本带有一个参数——密码的最小长度——由控制器提供。
11.15.2.6. views/patient/area.hbs
- 第 9 行:“您好,Jean MARTIN 先生”;
- 第 13–19 行:两个选项,都是链接;
- 第 31–43 行:即将到来的预约。[{{#unless @last}}]:用边框分隔各个预约,最后一个之后除外。
11.15.2.7. views/patient/account.hbs
- 第 17–65 行:账户修改;
- 第 72–80 行:删除,带确认。同一页面上有两个相互独立的表单:每个表单只发送自己的字段。
11.15.2.8. views/error.hbs
异常过滤器的错误页面:HTTP 状态码和翻译后的消息。
11.16. 词典
11.16.1. i18n/fr.json
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 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
- 各部分按页面([LOGIN]、[SCHEDULE], [AREA]……)或按主题([ERRORS]、[CONFIRMATION])对文本分组;
- 第 80 行:带有两个参数的文本,[{name}] 和 [{login}];
- 第 98–137 行:错误消息。这些是业务层中的 [BusinessException] 、表单验证装饰器和异常过滤器所使用的键。
11.16.2. i18n/en.json
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 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
英语词典的键与法语词典完全相同。
11.17. 静态文件
11.17.1. public/css/styles.css
- 第 10–12 行:可预约的时段在鼠标悬停时改变颜色;
- 第 23–33 行:错误区域,背景为浅粉色。[position: sticky] 和 [bottom: 1rem]:如果页面比窗口高,该区域会停留在窗口底部,而不是消失在屏幕之外;[z-index] 把它置于模态窗口的灰色背景之上;
- 第 36–43 行:“我的空间”的两个选项会响应鼠标悬停;
- 第 46–50 行:验证码图像的边框。
11.17.2. public/js/app.js
示例 21 中确认窗口脚本的完整版本:
- 第 17–19 行:没有确认窗口的页面无事可做;
- 第 24 行:窗口打开之前拥有键盘 焦点 的元素,窗口关闭时焦点会回到它身上;
- 第 26–35 行:焦点放在“不,返回”上;意外按下回车键不会删除任何内容;
- 第 37–43 行:窗口被隐藏,焦点被恢复;
- 第 54–67 行:“是”、“否”、关闭按钮,以及点击窗口外部。[closest('[data-action]')] 会找到带有该属性的元素,即使你点击的是它内部的某个元素;
- 第 71–86 行:Esc 键关闭窗口;Tab 键让焦点在窗口 内部循环,而不是让它移到后面变灰的页面上。