11. 案例研究:RdvMedecins 应用程序
11.1. 问题描述
RdvMedecins 应用程序用于管理一家医疗诊所的预约。每位医生都有若干时间段(例如,从上午 8:00 到中午 12:00,每 20 分钟一个);一次预约由日期、时间段和客户(患者)组成。这是上一课中 [NestJS] 应用程序在 [ASP.NET Core MVC] 中的精确实现:相同的数据库、相同的业务规则、相同的页面、相同的翻译字典。HTML 页面由服务器使用 [Razor] 视图生成。
三种用户角色共用该应用程序:
角色 | 对象 | 可执行的操作 |
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. 安装与运行
安装步骤已在本文档开头给出(在引言的“运行案例研究”一节中):使用 SQL 脚本创建数据库,通过 [appsettings.json] 检查连接字符串,然后在应用程序文件夹中运行 [dotnet run] 。应用程序文件夹:
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 | |
每个文件夹都包含一个名为 [README.md] 的文件,列出其中的文件。启动时的控制台:
在开发模式下(见 [Properties/launchSettings.json]),控制台还会显示 EF Core 发送到数据库的每条 SQL 命令。你还可以:
- 使用 [dotnet watch] 启动应用程序:每当文件被修改时,它会被重新编译并重新启动;
- 在 [Visual Studio Code] 中单步调试:安装 [C# Dev Kit] 扩展后,按 F5 键即可在调试器的控制下启动应用程序;在代码行的边栏中单击一下即可设置断点。
11.4. 应用程序架构

- [Program.cs] 配置应用程序:服务(依赖注入)、中间件(静态文件、错误页面、语言、身份验证)、控制器;
- [Auth]:登录、JWT 令牌、角色、验证码和尝试次数限制;
- [Controllers]:Web 层的控制器。它们都经由同一个服务 [ApplicationModel] (文件夹 [Web]),该服务将医生和客户列表保存在内存中,并把其他请求转发给业务层;
- [Web]:Web 层的公共元素:翻译、闪现消息、验证、视图父类、异常过滤器;[Models]:表单模型和视图模型;
- [Business]:业务规则;
- [Repositories]:DAO 层,每个表一个类;[Data]:EF Core 的 [DbContext] 层;
- [Entities]:EF Core 实体;[Domain]:日历对象,由业务层计算得出;
- [Views]:[Razor] 视图;[i18n]:字典;[wwwroot]:样式表、页面脚本以及 [Bootstrap]。
后续内容将逐一说明所有文件,从底层(数据库)到上层(视图)。
11.5. 数据库
数据库 [dbrdvmedecins2] 由脚本 [database/dbrdvmedecins2.sql] 创建,其运行方式与示例 28 相同([Laragon] 中的 [HeidiSQL] 工具,或命令 [mysql -u root < database/dbrdvmedecins2.sql])。它与 [NestJS] 应用程序的脚本一字不差:两个应用程序可以使用同一个数据库,并且可以互相替换而无需做任何修改。
11.5.1. 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 行:如果数据库尚不存在则创建,使用字符集 [utf8mb4] 和排序规则 [utf8mb4_unicode_ci],与示例 28 相同:字符串比较不区分大小写并忽略重音。这同样适用于唯一性约束:[Hélène DUPONT] 和 [helene dupont] 对 [MySQL] 而言是同一个人的两个实例;
- 第 34–38 行:脚本每次执行都从空数据库开始。表按从“子”表到“父”表的顺序删除:被外键引用的表(例如 [users],被 [doctors] and [clients]引用)只要还有其他表引用它,就无法删除。创建表时则按相反的顺序;
- 第 43–52 行:用户账户。每个表都以主键 [id](由数据库分配,[AUTO_INCREMENT])和列 [version] 开头,该列在创建行时设为 0;
- 第 46–49 行:登录名、密码、登录后的显示名称和角色([ADMIN]、[DOCTOR], 或 [USER])。[password] 列从不包含密码本身,而是包含其 [bcrypt] 哈希(见示例 25):60 个字符,列宽由此而来;
- 第 51 行:一个登录名只属于一个账户。与示例 28 一样,该约束是具名的:当 [MySQL] 拒绝某次写入操作时,其错误消息会指明被违反的约束的名称,业务层据此选择要显示的消息(见 [Business/BusinessService.cs]);
- 第 57–69 行:医生:头衔、姓、名;
- 第 59 行:列 [version] 用于乐观锁 (见示例 28):每次修改该行时它都会递增,这样就能检测另一个用户是否在该行被读取与被写入之间修改了它。与示例 28 一样,应用程序负责递增该值(见下文的 [DbContext]);
- 第 63–64 行:每位医生都有一个账户:列 [user] 是引用 外键 [users(id)] 的列。数据库会拒绝不指向任何账户的值,并拒绝删除仍被医生引用的账户。由于 [user] 是 [MySQL] 中的保留字,列名用反引号括起来;
- 第 66 行:一个账户只属于一位医生:[doctors] 与 [users] 之间是“一对一”关系;
- 第 68 行:两位医生不能具有相同的姓和名。该约束作用于这一对列:如果名不同,两位医生可以姓相同;
- 第 74–86 行:客户(患者),遵循同样的模式:每个客户一个账户(外键 [fk_clients_user],唯一性约束 [unq_clients_user]);任何两个客户不能具有相同的姓和名;
- 第 91–100 行:每位医生的时间段(外键 [doctor_id]):开始的小时和分钟、结束的小时和分钟。时间段没有日期;它每天重复;
- 第 105–115 行:预约:一个日期(类型 [DATE],不含时间)、一个时间段,以及一个客户,由两个外键标识;
- 第 114 行:同一个时间段每天只能被预约一次。数据库本身强制执行这条规则:如果两个用户同时预约同一个时间段,无论应用程序刚才验证了什么,第二条 [INSERT] 语句都会被拒绝;
- 第 127–137 行:演示账户:管理员、三位医生(角色 [DOCTOR])和四位客户(角色 [USER])。每个用户的密码就是其登录名([admin] / [admin]、[pelissier] / [pelissier]……)。哈希以 [$2b$10$] 开头:算法为 [bcrypt],成本为 10(见示例 25);应用程序的库 [BCrypt.Net-Next] 知道如何验证它们;
- 第 141–144 行:每位医生的 [user] 列通过基于登录名的子查询 获取,而不是假定数据库分配给账户的标识符;
- 第 146–150 行:客户以同样的方式处理;
- 第 153–157 行:为 PELISSIER 医生提供十二个 20 分钟的时间段,从上午 8:00 到中午 12:00。这里医生的 ID(1)是硬编码的:表 [doctors] 刚刚创建,因此其 ID 从 1 开始;
- 第 160–164 行:为 TATOU 医生提供十二个时间段,从下午 2:00 到下午 6:00。DUPONT 医生没有时间段:他的日程是空的;
- 第 167–168 行:已经为 Brigitte BISTROU(客户 3 号)在 PELISSIER 医生的第二个时间段(上午 8:20)安排了一次预约。[CURDATE()] 是运行脚本的日期:因此首次登录时,今天的日历会显示一个已被预约的时间段。
11.6. 项目配置
11.6.1. RdvMedecins.csproj
让我们逐段看看这个文件:
- 第 12 行:Web 应用程序的 SDK,与所有示例相同(见引言);
- 第 14–23 行:示例中位于共享文件 [examples/Directory.Build.props] 里的设置:[.NET] 10、“可为 null”的引用类型、隐式 [using]。案例研究是一个独立的项目:这些设置由它自己写出。[RootNamespace] 是项目的根命名空间,即 [Visual Studio Code] 为新文件建议使用的命名空间;
- 第 29 行:EF Core 的 [MySQL] 提供程序,它包含 EF Core 和 [MySqlConnector] 驱动程序(见示例 28);
- 第 31–34 行:两个身份验证包,已在第 8 章中使用过:JWT 令牌验证和密码哈希;
- 第 41 行:翻译字典 [i18n/*.json] 在启动时从磁盘读取。为生产服务器准备应用程序时(命令 [dotnet publish]),必须将它们一并复制:这正是 [CopyToPublishDirectory] 所做的;
- 第 43–44 行:SQL 脚本不是应用程序文件;它被排除在发布的文件之外,如示例 28 所示。
11.6.2. appsettings.json
文件 [appsettings.json] 的作用与 [.env] 文件在 [NestJS] 应用程序中的作用相同。有一个重要差别:[.env] 文件从不共享,而名为 [.env.example] 的文件充当它的模板。这里,[appsettings.json] 是项目的一部分;与具体机器相关的值(例如密码)可以通过其他方式提供,而无需修改它(见下文)。
让我们逐段看看这个文件:
- 第 1–9 行:与标准 JSON 不同,[ASP.NET Core] 允许在其配置文件中使用注释;
- 第 13 行:监听的地址和端口。示例监听 5000 端口,即默认端口;应用程序监听 8081 端口,与 [NestJS] 版本相同;
- 第 16–18 行:到 [dbrdvmedecins2] 数据库的连接字符串,使用 [Laragon] 的默认值(用户名 [root],无密码);见示例 28;
- 第 19–23 行:服务器版本,它告诉提供程序 [Pomelo] 应生成哪种 SQL 方言(见示例 28);
- 第 26–36 行:身份验证节:为令牌签名的密钥(至少 32 个字符;在生产环境中必须替换)、令牌的生存期(两小时),以及携带令牌的 Cookie 的 [Secure] 选项。在生产环境中,站点通过 HTTPS 提供服务,Cookie 绝不能通过未加密的连接传输:该选项设为 [true];
- 第 39–49 行:机器人防护阈值(见示例 27):允许的登录失败次数以及由此产生的封锁时长;同一 IP 地址每小时创建客户账户的数量;
- 第 51–57 行:日志级别(见引言)。EF Core 的消息仅从 [Warning] 级别开始显示:属于 [Information] 级别的 SQL 命令不会出现(见示例 28);
- 第 58 行:接受所有域名。
节 [Auth] 和 [Protection] 被解释为带类型的类(见下文的 [Config/AuthOptions.cs])。每个值由其路径指定,层级之间以 [:] 分隔:[Auth:JwtSecret]、[ConnectionStrings:RdvMedecins]、[MySql:ServerVersion]。[ASP.NET Core] 从多个依次排列的来源读取配置,后面的来源可以覆盖前面来源的值:[appsettings.json],然后是 [appsettings.{environment}.json] (见下一个文件),然后在开发环境中是“用户机密”(存储在项目之外、用户配置文件中的值),再然后是环境变量,最后是命令行参数。因此,密码可以通过环境变量提供,其中 [:] 写成 [__]:
应用程序的 [README.md] 文件详细说明了这些选项。
11.6.3. appsettings.Development.json
- 第 10 行:[ASP.NET Core] 知道应用程序运行所处的环境 :[Development]、[Production]……它从环境变量 [ASPNETCORE_ENVIRONMENT] 中读取该信息(见下一个文件);否则使用 [Production]。在 [appsettings.json] 之后,它读取文件 [appsettings.{environment}.json](如果存在),并将两者合并:第二个文件中存在的键会替换第一个文件中的键,其余的键予以保留。因此在开发期间,我们为类别 [Information] 添加级别 [Microsoft.EntityFrameworkCore.Database.Command]:更具体的规则优先于 [appsettings.json] 中更一般的规则([Warning] ,适用于任何 [Microsoft.EntityFrameworkCore]),于是发送到数据库的每条 SQL 命令都会显示在控制台中。这相当于 [logging] 选项在 [TypeORM] 中的对应项,[NestJS] 版本在非生产环境中启用了它。所有其他值(连接、身份验证等)与 [appsettings.json] 中的保持一致。
11.6.4. Properties/launchSettings.json
此文件仅在开发期间由 [dotnet run]、[dotnet watch] 和 [Visual Studio Code] 使用,不会被发布。下面逐项说明:
- 第 3–4 行:启动配置文件 描述启动应用程序的一种方式。这里只有一个;[dotnet run] 使用第一个;
- 第 5 行:应用程序直接启动,使用其自带的 Web 服务器;
- 第 6–7 行:[dotnet run] 显示其编译消息,应用程序就绪后浏览器会打开该应用程序;
- 第 8 行:监听地址,与 [Urls] 键(来自 [appsettings.json])相同。通过此配置文件启动时,应用程序使用该地址;在配置文件之外启动时(例如发布之后),则使用 [appsettings.json] 中的地址;
- 第 9–10 行:传递给应用程序的环境变量。[ASPNETCORE_ENVIRONMENT=Development] 设置环境:[appsettings.Development.json] 会被读取,并显示 SQL 命令。在生产服务器上,如果没有此文件或此变量,环境为 [Production]。
11.6.5. Config/AuthOptions.cs
下面对这段代码进行说明:
- 第 15 行:[Auth] 节,来自 [appsettings.json],以普通类的形式表示:每个键对应一个同名属性。这就是 选项模式 ([options pattern]),用于 [ASP.NET Core]。在 [Program.cs] 中,[Configure<AuthOptions>(...)] 将 该节与该类关联:框架创建一个 [AuthOptions] 对象,并用该节的值填充其属性,同时将它们转换为正确的类型(["7200"] 变为整数 7200,[false] 变为 布尔值 [false])。需要它的类通过依赖注入以
***[IOptions<AuthOptions>]的形式接收它,其***[Value]属性就是已填充的对象:[Auth/AuthService.cs] 正是这样做的,它有参数 [IOptions<AuthOptions> options] 和字段 [auth = options.Value]。这样就避免了到处读取字符串,就像 [process.env.JWT_SECRET] 在 [NestJS] 版本中所做的那样:键名由编译器验证,值也已完成转换; - 第 17 行:节名称,只写一次;
- 第 21–29 行:该节的三个值。默认值([7200],布尔值为 [false])是配置中缺少该键时所使用的值。
11.6.6. Config/ProtectionOptions.cs
- 第 10–25 行:[Protection] 节,来自 [appsettings.json],遵循相同的模式。它以 [IOptions<ProtectionOptions>] 的形式被注入到 [Auth/AttemptLimiterService.cs] 中,后者从中读取其阈值。
11.7. 应用程序启动
11.7.1. Program.cs
文件 [Program.cs] 同时承担了 [main.ts] (启动、中间件)和 [app.module.ts] (由哪个服务提供什么)在 [NestJS] 版本中的角色。它遵循所有示例的结构:先注册服务,再构建中间件管道。我们将其分段讲解。
11.7.1.1. 配置
- 第 21–31 行:所使用的命名空间,除隐式的 [using] 之外:包括框架的命名空间(本地化、EF Core、HTML 编码)以及应用程序的命名空间(每个文件夹一个);
- 第 33 行:应用程序构建器,与所有示例相同。它已读取配置([appsettings.json]、[appsettings.Development.json]、环境变量等),可通过 [builder.Configuration] 访问;
- 第 40–41 行:选项模式(参见 [Config/AuthOptions.cs]):每个节与其类关联。[GetSection("Auth")] 指定该节;[Configure<T>] 注册相应的服务 [IOptions<T>],身份验证服务将通过注入接收它;
- 第 42 行:同一个节,这次直接读取为对象([Get<AuthOptions>()]),如果该节缺失,则得到带默认值的对象。[JwtBearer] (见下文)的配置在服务注册期间就立即需要密钥:此时依赖注入容器尚未构建,因此无法注入任何 [IOptions<AuthOptions>]。
11.7.1.2. 数据库、DAO 层和业务层
- 第 4–5 行:连接字符串,与示例 28 中相同。运算符 [??] 在左侧的值不为 [null] 时返回左侧的值,否则返回右侧的值:如果缺少该键,应用程序会立即停止并显示说明缺少什么的消息,而不是在第一个请求时返回一个晦涩的错误;
- 第 6 行:[MySQL] 服务器版本,如果缺少该键则使用默认值;
- 第 7 行:应用程序的 [DbContext] (参见 [Data/RdvMedecinsDbContext.cs]),每个请求一个([Scoped]),使用 [MySQL] 提供程序(参见示例 28);
- 第 11–15 行:DAO 层:每个表一个类([users] 除外,其仓库用于身份验证)。它是 [Scoped],与它所使用的 [DbContext] 一样。服务的生命周期绝不能超过它的依赖项:[Singleton] 的 DAO 会无限期地保留第一个请求的 [DbContext] ,尽管它在该请求结束时已被销毁(参见第 6 章);
- 第 19 行:业务层。[AddScoped<IBusiness, BusinessService>()] 的含义是:“当某个服务请求 [IBusiness] 时,向它提供一个 [BusinessService]”。使用业务层的类依赖于接口,而不是类:我们可以替换实现(例如换成测试版本),只需 修改这一行。[NestJS] 版本为此需要一个令牌([BUSINESS_TOKEN]),因为 [TypeScript] 接口在编译时会消失;而在 [C#] 中,接口本身就充当令牌;
- 第 22–23 行:Web 层缓存(医生列表和客户列表)具有应用程序级作用域:[Singleton],即由所有请求共享的单个实例(参见示例 23)。所有控制器都经由其外观 [ApplicationModel],它使用业务层,因此是 [Scoped]。缓存本身不依赖任何其他内容,可以比外观存活更久。
11.7.1.3. 身份验证、翻译和编码:HTML
- 第 2 行:登录服务(验证用户名和密码,生成令牌;参见示例 25)。它使用账户仓库,因此是 [Scoped];
- 第 3–5 行:待处理的验证码(CAPTCHA)、失败计数器和账户创建口令(参见示例 27)。这些数据保存在内存中,且对所有请求必须相同:这三个服务都是 [Singleton]。缺点是:每次服务器重启时它们都会丢失;
- 第 6 行:[JwtBearer] 的配置(从 Cookie 中读取令牌、重定向到登录页等),如示例 25 所示。它存放在 扩展方法 中,该方法扩展 [IServiceCollection] (参见 [Auth/JwtAuthentication.cs]),其调用方式与框架方法相同,从而减轻了 [Program.cs] 的负担;
- 第 7 行:授权服务,由 [[Authorize]] 和中间件 [UseAuthorization] 使用;
- 第 10 行:翻译服务,它一次性读取全部字典(参见示例 22);
- 第 16 行:来自 [Razor] 的 HTML 编码器允许所有语言的字符通过,与示例 15 相同。
11.7.1.4. MVC 及其选项
- 第 2 行:[Razor] 控制器和视图。作为参数传递的函数用于设置 MVC 的选项;
- 第 5 行:一个全局异常过滤器(参见示例 24),适用于所有操作。它只处理一种情况:[InvalidSessionException] (令牌有效,但它所指向的账户此后已被删除)会导向登录页。其他异常继续沿其路径传递到 [UseExceptionHandler] 中间件(见下文);
- 第 10 行:“可为空”类型的一个陷阱。启用后,MVC 会将模型的(不可为空的)[string] 属性视为必填,就如同它带有 [[Required]] 特性一样,并给出我们看不懂的英文错误消息。此选项取消了这一默认行为:只有显式带有 [[Required]] 特性时,字段才是必填的,并使用我们自己的消息(参见 [Models/Forms.cs]);
- 第 14–25 行:绑定错误消息(参见示例 19):期望数字的地方出现了文本([version=abc])、缺少值等。示例 19 只重新定义了其中两条,且是英文的;本案例研究重新定义了全部消息,并且每条都返回同一个翻译键,即 [ERRORS.INVALID_FORM],而不是文本:消息在显示时按用户的语言翻译。字符 [_] 表示未使用的参数(字段名、输入的值):无论哪个字段,消息都相同。应用程序自己的表单绝不应出现这些错误:它们表明请求是手工构造的。
11.7.1.5. 加载缓存
- 第 1 行:应用程序构建完成。依赖注入容器现已创建:不能再注册服务,但可以获取服务;
- 第 9–12 行:在服务器开始监听之前,医生列表和客户列表被加载到缓存中。[ApplicationModel] 是一个 [Scoped] 服务:它只能在 作用域内创建,而在请求之外没有作用域。[CreateScope()] 创建一个作用域;[GetRequiredService<ApplicationModel>()] 从中获取该服务(连同它所依赖的业务层、仓库和 [DbContext] ),而 [LoadAsync()] 填充缓存,缓存是 [Singleton] ,因此在作用域结束后依然存在。[using] 语句在代码块结束时销毁作用域,连同其中的 [DbContext] 一起销毁。如果数据库无法访问,EF Core 异常不会被捕获:应用程序终止,并在控制台中显示错误消息。这是连接字符串有误或 [MySQL] 服务器已停止的第一个征兆。
11.7.1.6. 中间件管道
每个请求按照中间件声明的顺序依次经过各个中间件组件(参见第 7 章):因此这个顺序很重要。
- 第 8 行:第一个中间件包裹所有其他中间件。如果某个异常没有被任何人处理(编程错误、数据库变得不可访问等),它会记录该异常,并以地址 [/error/500] 重新执行请求:用户看到的是应用程序错误页面,而不是技术性消息(参见第 7 章);
- 第 9 行:空的错误响应(400、403、404)以同样的方式转换为页面,通过 [/error/{code}] 操作,该操作属于 [ErrorController] 控制器(参见示例 24 和 26)。重新执行的请求会再次经过后面的中间件:因此错误页面会被渲染,并能识别已登录的用户;
- 第 12 行:[wwwroot] 文件夹中的静态文件(参见示例 15):样式表、页面脚本和 [Bootstrap],它存放在 [wwwroot/lib/bootstrap] 中。由于放在管道的前面,该中间件响应文件请求时无需经过本地化或身份验证;
- 第 17–23 行:本地化配置,与示例 22 相同。支持的语言和默认语言来自翻译服务([Translator.Languages], [Translator.DefaultLanguage]):它们只在一处定义;
- 第 25 行:只有由 [LanguageController] 设置的 Cookie 决定语言(参见示例 22)。语法 [[...]] 是一个集合表达式:这里是只含一个元素的列表;
- 第 26 行:本地化中间件,为每个请求设置语言;
- 第 30–32 行:路由,然后是身份验证,再然后是授权。路由根据通过特性声明的路由选择将处理请求的操作。示例中没有调用它:[WebApplication] 因此会自动将其添加到管道的开头。显式调用它可以让顺序一目了然:授权必须在路由之后,因为被选中的操作才带有需要验证的 [[Authorize]] 特性;也必须在身份验证之后,身份验证根据令牌确定用户是谁(参见示例 25);
- 第 35 行:控制器及其路由,通过特性声明([[Route("schedule")]] 等);
- 第 37 行:服务器启动,并在 8081 端口等待请求。
11.8. 实体
EF Core 实体对应于数据库表和 [C#] 类(参见示例 28)。它们一一复刻了 [TypeORM] 实体(来自 [NestJS] 版本):特性 [[Table]]、[[Column]]、[[Key]]、[[ForeignKey]] 相当于装饰器 [@Entity]、[@Column]、[@PrimaryGeneratedColumn] 和 [@JoinColumn]。数据库不是由 EF Core 创建的,而是由 SQL 脚本 [database/dbrdvmedecins2.sql] 创建:实体只需准确描述已存在的表即可。
11.8.1. Entities/AbstractEntity.cs
- 第 23 行:一个抽象类,没有 [[Table]] 特性:它不对应任何表,但其属性会添加到其子类对应的表中。应用程序中的所有实体都继承自它,因此都有标识符和版本;
- 第 28–30 行:主键([[Key]]),列 [id]。按照 EF Core 的约定,整数键由数据库生成([AUTO_INCREMENT]):EF Core 在每次 [INSERT] 之后重新读取其值;
- 第 40–42 行:用于乐观锁的行版本(参见示例 28)。[[ConcurrencyCheck]] 会在每条 [UPDATE] 中添加条件 [AND version = <value read>]。与 [@VersionColumn] (来自 [TypeORM])不同,EF Core 不会自行递增版本:由 [DbContext] 负责(见下文)。
11.8.2. Entities/Person.cs
- 第 17 行:[Doctor] 和 [Client] 的父类(它同样是抽象的),本身是 [AbstractEntity] 的子类。医生和客户具有相同的列:它们只定义一次;
- 第 19–29 行:称谓(Mme、Mr、Melle)、姓和名。[[MaxLength]] 指定列宽。这些属性的类型为 [string] (而不是 [string?]):它们绝不能被设为 [null],因此编译器要求一个初始值,这里是空字符串 [""];
- 第 42–43 行:指向用户账户的外键,列 [user]。无需加载账户本身即可读取账户标识符:这就是 [@RelationId] 在 [NestJS] 版本中所起的作用;
- 第 47–48 行:导航属性:即 [User] 对象本身。[[ForeignKey(nameof(UserId))]] 指明哪个属性包含外键([nameof(UserId)] 等于字符串 ["UserId"],但编译器会验证该属性确实存在)。只有当查询要求时,导航属性才会被填充([Include];参见 DAO 层);否则它被设为 [null]。写法 [= null!] 会抑制编译器警告:它保证该属性只会在加载之后才被读取。“一对一”关系在 [DbContext] 中指定。在父类中声明的关系会像列一样被继承:表 [doctors] 和 [clients] 各自都有与 [users] 的关系。
11.8.3. Entities/Doctor.cs
- 第 15 行:类 [Doctor] 对应表 [doctors]。它从 [Person] 继承其全部属性。注释中提到的唯一性约束 [unq_doctors_first_name_last_name] 由 SQL 脚本创建;业务层通过其名称识别它(参见示例 28);
- 第 21 行:[Slot] 到其医生的关系的反向关系:该医生的预约时段。EF Core 会自动将这两个导航关联起来([Doctor.Slots] 和 [Slot.Doctor]),它们从各自一侧描述同一个“一个医生,多个时段”的关系。与任何导航一样,它只在请求时才会被填充;应用程序实际上并不 使用它:它通过 DAO 层读取预约时段。[[]] 是一个 集合表达式:这里是一个空列表。
11.8.4. Entities/Client.cs
客户,即诊所的患者(而不是 HTTP 客户端):来自 [Person] 的 [clients] 表(第 15 行),没有额外的属性。
11.8.5. Entities/Slot.cs
- 第 14–17 行:时段开始和结束的小时与分钟。特性和属性写在同一行:这是允许的,对于这四个相似的列来说更为紧凑;
- 第 21–25 行:指向医生的“多对一”关系:一个医生对应多个时段。技术与 [Person] 中相同:外键 [DoctorId] (列 [doctor_id]) 和导航属性 [Doctor],通过 [[ForeignKey]] 关联。EF Core 不需要进一步说明:一侧是引用,另一侧是列表,这就是“一对多”关系。
11.8.6. Entities/Appointment.cs
- 第 15 行:预约表。其唯一性约束 [unq1_appointments (day, slot_id)] 确保一个时段每天只能被预订一次;
- 第 22–23 行:预约的日期。类型 [DateOnly] (不带时间的日期)与 SQL 类型 [DATE] 完全对应:没有时间,因此没有时区问题。[NestJS] 版本处理的是 [yyyy-mm-dd] 类型的字符串,因为 [JavaScript] 中没有这样的类型。两个 [DateOnly] 值可以直接用 [<]、[>=] 等进行比较,无论是在 [C#] 中还是在 [LINQ] 查询中;
- 第 25–35 行:客户和预约时段:两个“多对一”关系,每个都通过外键和导航属性定义。要创建预约,只需填充外键 [ClientId] 和 [SlotId]:业务层正是这样做的。
11.8.7. Entities/Role.cs
- 第 17–21 行:三个角色,以 枚举 ([enum])的形式表示:[Role] 类型的变量只能取值 [Role.ADMIN]、[Role.DOCTOR] 或 [Role.USER],编译器会拒绝任何其他值。这等价于 [NestJS] 版本中的字符串联合类型 ['ADMIN' | 'DOCTOR' | 'USER']。默认情况下,EF Core 会将枚举存储为数字(0、1、2);[role] 列包含文本:转换是在 [DbContext] 中请求的。
11.8.8. Entities/User.cs
- 第 18 行:获准登录的用户账户:管理员、每位医生和每位客户。约束 [unq_users_login] 禁止两个账户使用相同的登录名;
- 第 21–23 行:用户名;
- 第 26–28 行:密码的 哈希 [bcrypt] ,绝不是密码本身(参见示例 25);
- 第 32–34 行:登录后显示在导航栏中的名称(“Marie PELISSIER”);
- 第 37–38 行:角色,类型为 [Role]。由于类 [User] 没有声明指向拥有它的医生或客户的导航,因此该关系只在 [Person] 一侧可知。
11.9. DbContext
应用程序中的 [DbContext] 以示例 28 中的 DbContext 为基础,包含五个表而不是一个,并对特性无法表达的模型细节作了一些补充说明。
11.9.1. Data/RdvMedecinsDbContext.cs
下面对这段代码进行说明:
- 第 29 行:与示例 28 中一样,[DbContext] 通过 [MySQL] 提供程序和连接字符串等选项,由 [AddDbContext] 在 [Program.cs] 中提供。它以 [Scoped] 生命周期注册:每个请求一个 [DbContext] ,由该请求的所有仓库共享,也就是说只有一个连接,必要时也只有一个事务。因此它同时承担了 [DataSource] 和 [Repository<T>] 在 [TypeORM] 中的角色;
- 第 33–37 行:每个表一个 [DbSet]。[AbstractEntity] 和 [Person] 都没有对应的 DbSet:这些抽象类没有表。EF Core 不会将它们作为实体纳入模型;它只是把它们的属性添加到子类的属性中;
- 第 39 行:[OnModelCreating] 在 EF Core 构建其 模型 (对表和关系的描述)时调用一次。它通过 流式 API(即一连串的方法调用)来补充实体特性;
- 第 47–48 行:医生(客户同理)与其账户之间的关系是“一对一”:[HasOne(d => d.User)] (一个医生有一个账户)、[WithOne()](一个账户至多对应一个医生;空括号表示 [User] 没有反向导航)、[HasForeignKey<Doctor>(d => d.UserId)] (外键位于表 [doctors] 中)。如果没有 这几行,EF Core 会假定为“多对一”关系(多个医生对应同一个账户),这样同样能运行,但对模型的描述并不准确:在数据库中,[user] 列是唯一的;
- 第 52 行:[HasConversion<string>()] 将角色以文本形式(['ADMIN'] 等)存储在数据库中,并在读取时将其转换回 [Role] ;
- 第 68–77 行:每个被修改的实体的版本号在保存前递增,与示例 28 中一样。[ChangeTracker.Entries<AbstractEntity>()] 遍历所有其类派生自 [AbstractEntity] 的被跟踪实体:得益于共同的父类,这一个循环适用于全部五个表。[SaveChangesAsync] 的这个重载被重新定义为带两个参数,因为最终调用不带参数的 [SaveChangesAsync()] 的正是这个重载。EF Core 在 旧 版本的 [WHERE] 子句中与 [UPDATE] 比较并写入新版本:如果该行在此期间已被更改,则不会修改任何行,EF Core 会引发 [DbUpdateConcurrencyException]。
11.10. 领域:日程
[Domain] 文件夹包含两个不对应任何表的类:它们描述医生某一天的日程,由业务层计算([BusinessService.GetDoctorDayScheduleAsync]),并由日程控制器显示。
11.10.1. Domain/DoctorDaySlot.cs
- 第 17 行:一个时段,以及该日该时段所安排的预约,如果该时段可用则为 [null] (因此类型为 [Appointment?])。以这种方式编写的 [record] ,其参数写在括号中(位置记录),只用一行就声明了一个类、它的构造函数及其属性 [Slot] 和 [Appointment],这些属性在构造之后不能修改:这等价于 [constructor(public slot: Slot, ...)] 语法在 [NestJS] 版本中的用法。我们之前已经遇到过用于向业务层传递数据的记录(参见示例 28)。
11.10.2. Domain/DoctorDaySchedule.cs
日程(第 14 行):一个医生、一天,以及其可用或已预订时段的列表,按时间顺序排列。
11.11. DAO 层
每个表一个类,与示例 28 中相同:方法简短,没有业务逻辑,只负责查询或修改数据库。这里它们被称为“仓库”,与 [NestJS] 版本一致。与该版本有两点不同:
- 查询用 [LINQ] 编写,由 EF Core 将其翻译为 SQL:通过导航属性从一个实体导航到另一个实体,连接由 EF Core 自行编写;
- 这些方法没有用于事务的 [manager] 参数:一次请求中的所有仓库共享同一个 [DbContext],业务层在此 [DbContext] 上开启的事务会自动涵盖它们的所有查询。
所有方法都是异步的,并返回 [Task]:调用方使用 [await] 等待它。许多方法采用 [=> expression] 的形式编写:它们直接返回请求的 [Task] ,不使用 [async] 或 [await],因为之后没有其他事情要做。
11.11.1. Repositories/PersonRepository.cs
在 [NestJS] 版本中,医生和客户的仓库除了一行代码之外完全相同。在 [C#] 中,泛型类 只需编写一次。
下面对这段代码进行说明:
- 第 24 行:[PersonRepository<T>] 是一个 泛型类;[T] 是一个 类型参数,在使用该类时被替换为实际类型([Doctor] 或 [Client]),就像 [T] 在 [List<T>] 中那样。约束 [where T : Person] 只接受 [Person] 或其子类作为 [T]:这样编译器就知道 [T] 包含 [Id], [LastName], [FirstName], [UserId], [User] 等,并在查询中接受 [p.LastName] 。该类是抽象的:只使用下面列出的它的两个子类;
- 第 26 行:主构造函数的 [db] 参数仅在该类内部可见。它被复制到一个 [protected] 字段中 ,以便子类([ClientRepository])可以访问它;
- 第 29 行:类型为 [T] 的人员表。[db.Set<T>()] 将 [DbSet] 映射到此类型:[db.Doctors] 对应 [T = Doctor],[db.Clients] 对应 [T = Client];
- 第 38–39 行:所有人员,按姓再按名排序([OrderBy],然后用 [ThenBy] 处理姓相同时的排序)。[Include(p => p.User)] 还通过连接加载每个人的账户([INNER JOIN users]):没有它,[p.User] 就等同于 [null]。账户用于在列表中显示登录名。[AsNoTracking()] (参见示例 28):这些列表在查询结束很久之后仍由 [ApplicationModel] 保存在内存中;无需 [DbContext] 对其进行处理。诸如 [p => p.LastName] 之类的表达式不会在 [C#] 中执行:EF Core 会解析它们并将其翻译为 SQL([ORDER BY last_name, first_name]);
- 第 41–42 行:某个人员及其账户,或 [null]。这里没有 [AsNoTracking()]:业务层会修改检索到的人员(及其账户),然后调用 [SaveAsync];跟踪这两个对象的 [DbContext] 知道哪些内容发生了变化;
- 第 45–46 行:账户为 [userId] 的人员。已登录的患者(其令牌中包含账户标识符)就是这样检索到自己的客户记录的。过滤条件针对外键本身([WHERE clients.user = ...]);与 [users] 的连接仅用于加载账户([Include]);
- 第 52–53 行:可能存在的同名者。运算符 [==] 被转换为 SQL 的 [=] :比较由 [MySQL] 按数据库的排序规则执行,不区分大写字母和重音符号,与唯一性约束完全一样(参见示例 28)。使用 [C#] 进行比较则会区分大写字母;
- 第 57–64 行:创建或修改,与示例 28 中相同:新的人员([Id] 设为 0)被添加到 [DbSet];已在系统中的人员则无需任何操作。注意:[SaveChangesAsync] 会保存 所有挂起的 [DbContext] 更改,而不仅仅是来自 [person] 的更改:同时被修改的账户也包含在同一次调用中;
- 第 69 行:通过 [ExecuteDeleteAsync] 删除(参见示例 28):一条 [DELETE] 直接发送到数据库,无需事先读取。它不经过更改跟踪,因此也不经过乐观锁;
- 第 73 行:医生仓库:[PersonRepository<Doctor>],没有其他内容。它将收到的 [DbContext] 转发给其父类的构造函数;末尾的分号取代了空的类体;
- 第 75 行:客户仓库,带有一个额外的方法;
- 第 89–92 行:带 锁读取客户:[SELECT ... FOR UPDATE] 会在该行上加锁,直到当前事务结束;请求同一把锁的另一个事务会等待,直到第一个事务完成。预约方法([BusinessService.AddAppointmentAsync])利用这一点,把同一位患者的两个同时发生的预订依次处理:第二个预订会看到第一个预订创建的预约,从而遵守“只能有一个即将到来的预约”这一规则。[LINQ] 无法表达 [FOR UPDATE]:必须使用 [FromSqlInterpolated] 自己编写 SQL 查询。字符串 [$"..."] 是一个 内插字符串;[FromSqlInterpolated] 不会原样复制它:花括号中的每个值([{id}])都会变成一个 SQL 参数。因此没有字符串拼接,也不可能发生 SQL 注入。查询按原样执行([ToListAsync]),然后取结果列表中的第一个客户([FirstOrDefault],在内存中):如果在 [LINQ] 运算符之后再添加 [FromSqlInterpolated] ,EF Core 就会把我们的 SQL 包装在一个子查询中。
11.11.2. Repositories/SlotRepository.cs
- 第 15–16 行:一个预约时段及其医生([Include]);
- 第 19–24 行:某个医生的时段,按时间顺序排列:[Where] 过滤,[OrderBy] 和 [ThenBy] 排序(先按小时,再按开始分钟)。查询是逐个方法构建的,就像 [TypeORM] 的 QueryBuilder 一样,并且只有在调用 [ToListAsync] 时才会执行:[SELECT ... FROM slots WHERE doctor_id = @p ORDER BY start_hour, start_minute]。值 [doctorId] 同样作为 SQL 参数传递;
- 第 28–29 行:使用单个 [DELETE] 删除某个医生的预约时段。业务层在删除医生之前调用它;否则外键 [slots.doctor_id] 会阻止删除。
11.11.3. Repositories/AppointmentRepository.cs
下面对这段代码进行说明:
- 第 19–20 行:一个带有客户及其时段的预约:两条 [Include] 记录,因此有两个连接;
- 第 22–29 行:与人员相同的模式。实际上,它只用于创建:业务层生成一个 [Appointment],其中只填充了外键;在 [SaveChangesAsync] 之后,[appointment.Id] 包含数据库分配的标识符;
- 第 32 行:取消预约;
- 第 37–42 行:某个医生在指定日期的预约,每个预约都带有其患者和时段(相当于 [leftJoinAndSelect] 在 [NestJS] 版本中的用法)。[appointments] 表并不直接引用医生:[a.Slot.DoctorId == doctorId] 过滤条件通过 [Slot] 导航,EF Core 会添加与 [slots] 的连接。区分导航的两种用法很重要:在 [Where] 中,它用于过滤;只有 [Include] 才会把对象加载到结果中;
- 第 47–54 行:某个客户从 [fromDay] 这一天起的预约,连同其时段 以及该时段的医生:[Include(a => a.Slot)] 加载时段,然后 [ThenInclude(s => s.Doctor)] 加载该时段的医生(两个级联连接)。排序先按日期,再按时段的时间。这就是“我的空间”中显示的内容;
- 第 57–58 行:这些预约的数量([SELECT COUNT(*)]),用于“只能有一个即将到来的预约”规则。[CountAsync] 可以直接接受条件,[FirstOrDefaultAsync] 也是如此;
- 第 62–63 行:删除某个客户的所有预约,包括过去和将来的:业务层在删除客户之前调用它,否则外键 [appointments.client_id] 会阻止删除;
- 第 67–68 行:某个医生的预约数量,用于阻止删除有预约的医生。同样,[a.Slot] 导航生成一个连接([INNER JOIN slots]),而不加载任何内容:这就是 [innerJoin] 在 [NestJS] 版本中的对应用法。
11.11.4. Repositories/UserRepository.cs
- 第 17 行:与此登录名关联的账户,或 [null]。它用于登录([AuthService]),以及在分配登录名之前验证其是否可用;
- 第 19–26 行:创建或修改账户。要创建医生或客户,必须先创建其账户:该人员的外键需要账户标识符;
- 第 29 行:删除账户。顺序与创建过程相反:业务层先删除引用该账户的人员,然后再删除账户。
11.12. 业务层
业务层包含应用程序的业务规则:不得预约过去的时间、每位患者只能有一个即将到来的预约、用户名和人员唯一,以及医生或客户的删除。它依靠 DAO 层(文件夹 [Repositories])进行读写,对 HTML 和界面语言一无所知。更确切地说,这就是示例 28 中的 [PersonsBusiness] 层。
11.12.1. Business/Dates.cs
- 第 11 行:[static] 类不会被实例化;它只是将方法组织在一起,通过类名调用([Dates.Today()]);
- 第 14 行:今天的日期,使用服务器的时区。[DateTime.Now] 同时返回日期和时间;[DateOnly.FromDateTime] 只返回日期(类型 [DateOnly] 已在示例 12 中介绍;这是 [appointments.day] 列的格式)。两个 [DateOnly] 值可以直接用 [<] 或 [>=] 比较;而处理 [NestJS] 版本中 [yyyy-mm-dd] 字符串时,必须自己生成这种格式。当前日期用于业务规则,因此位于业务层;Web 层会复用它(例如在 [ScheduleController] 中,用来判断某一天是否仍可预订)。
11.12.2. Business/BusinessException.cs
- 第 18 行:当业务规则拒绝某个事务时抛出的异常(参见示例 28)。该类使用 主构造函数 (参数 [key] 和 [messageParams] 列在类名之后);[: Exception(key)] 将键传递给父类 [Exception] 的构造函数,后者将其设置为属性 [Message] (在错误日志中很有用)。与示例 28 的区别:该异常携带的不是英文文本,而是一个 翻译键 ([ERRORS.LOGIN_TAKEN])。因此业务层不了解界面语言:由 Web 层使用字典 [i18n/fr.json] 和 [i18n/en.json] 翻译该键(参见第 5 章);
- 第 21 行:翻译键,只读(只有 [get] 而没有 [set]);
- 第 24 行:任何消息参数,它们将替换翻译文本中形如 [{minutes}] 的占位符。[IReadOnlyDictionary] 是只读字典。[??] 运算符在未提供参数时返回空字典:Web 层永远不需要检查 [null]。[BusinessService] 抛出的异常实际上只使用不带参数的键。
[BusinessException] 不是错误:它是一种正常的响应(“此登录名已被占用”),控制器会拦截它并显示给用户,显示在页面上或弹出消息中。任何其他异常才是真正的错误,会导致 500 错误页面。
11.12.3. Business/IBusiness.cs
- 第 17–33 行:要创建或修改的医生或客户的数据,由 Web 层传递(参见示例 28)。[required] 要求提供称谓、姓和名;[init] 防止它们之后被修改(参见示例 18)。用户名和密码是可选的([string?]):创建时,它们默认为小写的姓名;修改时,只有输入了才会更改。[Version] 是显示编辑表单时所读取记录的版本:它用于乐观锁(见下文);
- 第 36 行:业务层的 契约:其他层可以向它请求什么,而不指明如何完成(接口已在示例 06 中讨论)。按照 [.NET] 的惯例,异步方法返回 [Task<T>](相当于 [Promise<T>] 在 [JavaScript] 中的对应物),其名称以 [Async] 结尾;
- 第 39–53 行:读取操作。类型后面跟着 [?] ([Task<Client?>])表示该方法可以返回 [null]:没有人拥有这个标识符。[/// <summary>] 注释是文档注释:当鼠标悬停在方法上时,[Visual Studio Code] 会显示它们;
- 第 57–64 行:预约。[AddAppointmentAsync] 的注释列出了可能的错误代码:这是测试人员必须了解的契约的一部分;
- 第 68–74 行:医生管理(仅限 ADMIN)。每位医生与其用户账户一起被创建、修改和删除;
- 第 80–88 行:客户管理,逻辑相同。[AddClientAsync] 也用于注册患者,而 [EditClientAsync] 和 [DeleteClientAsync] 则用于管理自己账户的患者。
实现通过 [Program.cs] 中的这一行 [builder.Services.AddScoped<IBusiness, BusinessService>()] 注册:“当构造函数请求 [IBusiness] 时,为其提供一个 [BusinessService]”,每个请求一个([Scoped]),就像 [DbContext] 以及它所使用的 DAO 条目一样(参见示例 28 和第 6 章)。在 [NestJS] 中,[TypeScript] 接口在编译时消失:需要一个令牌([BUSINESS_TOKEN])和 [@Inject(BUSINESS_TOKEN)] 。在 [C#] 中,接口在运行时是存在的:接口本身就充当令牌。唯一接收 [IBusiness] 的服务是 [ApplicationModel] (文件夹 [Web]),它同时也实现了 [IBusiness]:因此控制器看到的是同一份契约,并额外增加了医生和客户列表的缓存。
11.12.4. Business/BusinessService.cs
这是应用程序中内容最全面的文件。我们将分五个连续的片段来展示它。
11.12.4.1. 描述符
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 | |
- 第 6–29 行:头部注释概述了该类所应用的五条业务规则;
- 第 34 行:[MySQL] 驱动程序(参见第 9 章):该类使用其 [MySqlException] 异常来检测对唯一性约束的违反;
- 第 42 行:该类实现了接口;它必须提供接口的所有方法;
- 第 45 行:[bcrypt] 的成本因子(参见示例 25),与 SQL 脚本中密码的成本因子相同(前缀 [$2b$10$]);
- 第 49–60 行:在业务规则方面区分医生与客户的一切内容:它们的 DAO、账户角色([DOCTOR] 或 [USER])、错误消息,以及删除时发生的事情。由于医生和客户遵循相同的规则,这些规则的代码只在 泛型方法(由类型 [T] 参数化)中编写一次,这些方法接受一个描述符。约束 [where T : Person, new()] 要求 [T] 继承自 [Person](因此可以读取 [LastName]、[FirstName]、[User] 等),并且具有无参数构造函数(因此可以编写 [new T()])。[Func<int, Task<int>>] 是接受一个 [int] 并返回 [Task<int>] 的函数的类型;[Func<int, Task>] 是不返回任何内容的异步函数的类型。这些参数有默认值([= null]):它们是可选的;
- 第 62–69 行:类的字段:[DbContext]、五个 DAO 和两个描述符。[readonly] 防止它们在构造函数之后被修改;
- 第 74–87 行:所有依赖项都由依赖注入提供。这里的 [DbContext] 仅用于开启事务:请求仍保留在 DAO 层。与示例 28 中一样,在一次请求期间,DAO 和业务层接收的是 同一个 [DbContext] ,因此使用同一个连接和同一个事务;
- 第 89–99 行:医生描述符。命名参数 ([CountAppointments:], [HasAppointmentsKey:] 等)通过名称引用参数,这样可以跳过可选参数(因此下面的客户描述符省略了 [CountAppointments] 和 [HasAppointmentsKey])。[appointmentRepository.CountByDoctorAsync] 在这里并没有被调用:传递的是方法本身,它将在稍后被调用(因此方法可以用作类型为 [Func] 的值)。只要医生还有预约,就拒绝删除;不过,他们的时段会在删除医生之前被删除;
- 第 101–109 行:客户描述符。没有 [CountAppointments]:删除客户永远不会被拒绝,其预约(过去和将来的)会在客户本身之前被删除;否则外键 [appointments.client_id] 会阻止删除。
11.12.4.2. 读取操作和日程
- 第 5–22 行:读取操作只是委托给 DAO 层。[=> expression] 语法(即 表达式主体)取代了 [{ return expression; }] 代码块。这些方法不是 [async]:它们直接返回来自 DAO 的 [Task] ,而不等待它;
- 第 24–25 行:患者即将到来的预约:业务层向 DAO 提供当前日期;
- 第 28–42 行:计算医生某一天的日程,使用与 [NestJS] 版本相同的算法。未知的医生返回 [null];否则,读取该医生的时段和当天的预约;
- 第 38 行:[ToDictionary] 将预约存储在以时段标识符为键的字典中(相当于 [Map] 在 [NestJS] 版本中的用法)。有了字典,就无需为每个时段扫描预约列表;
- 第 39–41 行:每个时段与其预约相关联,或与 [null] 相关联([GetValueOrDefault] 在键不存在时返回默认值 [null])。[Select] 转换列表中的每个元素(参见 [LINQ],第 9 章)。结果是 [DoctorDaySchedule] 对象,位于 [Domain] 文件夹中,日历视图将显示它。
11.12.4.3. 预约
- 第 17–18 行:整个预订过程在一个事务中进行:该方法将一个异步 匿名函数([async () => { ... }])传递给 [TransactionAsync] (见下文),由它执行该任务;
- 第 20–23 行:不得预约过去的时间。无论进行预订的人是什么角色(ADMIN、DOCTOR 或患者),这里都会验证该规则,即使 Web 层已经隐藏了过去日期的“预订”按钮:请求可以被手工构造;
- 第 25–27 行:患者的记录被锁定:[LockAsync] 执行 [SELECT * FROM clients WHERE id = ... FOR UPDATE] (参见 [Repositories/PersonRepository.cs])。这是一种 悲观锁:它在处理开始之前获取,假定可能发生冲突,并一直保持到事务结束。如果没有它,同一患者同时发出的两个预订(两个标签页、双击)可能都会通过下面的测试,而此时两者都还没有把各自的预约写入数据库。有了这把锁,第二个事务会等待第一个事务完成,然后看到它创建的预约。找不到的患者(在此期间被删除)会被拒绝;
- 第 29–31 行:每位患者只能有一个即将到来的预约;
- 第 35–36 行:插入。只指定外键 [SlotId] 和 [ClientId] :无需关联 [Slot] 和 [Client] 对象即可写入 [appointments] 行。如果 另一位患者刚刚预订了同一时段,锁并不能阻止它(锁作用于该患者的行):拒绝该插入的是数据库的 [unq1_appointments (day, slot_id)] 唯一性约束,并且 [TransactionAsync] 会将该错误转换为带有键 [BusinessException] 的 [ERRORS.SLOT_ALREADY_BOOKED];
- 第 39 行:取消预约:一条简单的 [DELETE],没有特定规则。
11.12.4.4. 管理医生和客户
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 | |
- 第 6–20 行:六个公共方法委托给三个私有泛型方法,并使用正确的描述符。编译器从描述符推断出 [T] :[doctorDescriptor] 对应 [Doctor],[clientDescriptor] 对应 [Client];
- 第 26–50 行:创建人员及其账户;
- 第 28–33 行:数据准备,在事务之外。[Trim] 去除字符串首尾的空格;姓名首字母大写。默认情况下,登录名与姓名相同,并且始终为小写;默认情况下,密码与登录名相同:这些是 SQL 脚本中的账户规则;
- 第 37–38 行:在事务内部,两条唯一性规则:不允许重名,以及可自由选择的登录名。这些检查在写入数据库之前进行,以便给出清晰的消息(参见示例 28);
- 第 40–47 行:先创建用户账户,因为人员引用它(外键)。密码绝不以明文存储:[BCrypt.Net.BCrypt.HashPassword] 计算其哈希(参见示例 25)。[$"{firstName} {lastName}"] 是一个内插字符串:账户的显示名称;
- 第 49–50 行:然后,根据约束 [new()],使用 [new T] 来生成 [Doctor] 或 [Client] 人员。如果第二次写入操作失败,事务也会回滚第一次写入:账户绝不会在没有人员的情况下单独存在;
- 第 59–95 行:在一个事务中修改人员及其账户;
- 第 63 行:找不到人员会引发 [BusinessException],并带有描述符的键。[?? throw] 已在示例 28 中见过;
- 第 70–72 行:乐观锁 (参见示例 28):表单在显示时带上了所读取记录的版本;如果数据库中的版本不同,说明有人在此期间修改了该记录,系统会拒绝更新,而不是悄无声息地覆盖他们的工作。与预订时使用的悲观锁不同,这里不会阻塞任何操作:我们假定冲突很少发生,只是检测冲突。如果并发修改发生在这次读取之后,则由 [WHERE version = ...] 条件(属于 [UPDATE] )来检测它(参见 [TranslateDatabaseError],见下文);
- 第 77–80 行:只需修改读取到的对象:随后 [DbContext] 会在下一次 [SaveChangesAsync] 时发送必要的 [UPDATE]。姓名检查会传递该人员的标识符:他们当然有权保留自己的姓和名;
- 第 82–88 行:账户随人员而变(导航属性 [User],由 DAO 加载):重新计算其显示名称。只有在输入了登录名且与当前登录名不同时才会更改登录名;这种情况下,它必须是可用的;
- 第 90–92 行:只有在输入了密码时才会更改密码;随后对其进行哈希;
- 第 94–95 行:保存账户和人员。我们的 [DbContext] 会递增每个被修改实体的版本号(参见 [Data/RdvMedecinsDbContext.cs]);
- 第 107–121 行:在一个事务中,按外键所要求的顺序进行删除;
- 第 111–113 行:可能的拒绝:有已安排预约的医生不能被删除(其患者会在不知情的情况下失去预约)。[d.CountAppointments(id)] 调用存储在描述符中的函数;
- 第 115–117 行:删除引用该人员的内容:医生的时段、客户的预约;
- 第 119–120 行:先删除人员,再删除该人员所引用的账户;
- 第 121 行:[TransactionAsync] 需要一个返回结果的函数:这里返回了一个结果,但没有人会使用它;
- 第 127–133 行:同名者会被拒绝,除非就是当前正在编辑的人员([currentId],新建时为 [null] )。该方法是 [static]:它不使用对象的任何字段;
- 第 137–141 行:已被使用的登录名(无论被医生、客户还是管理员使用)会被拒绝。
11.12.4.5. 事务和唯一性约束
- 第 15 行:所有多步骤的写入都经过这个泛型方法:[R] 是操作结果的类型([Appointment]、[Doctor]、[Client]、[bool]),而 [Func<Task<R>>] 是 返回 [R] 的无参数异步函数的类型。这就是示例 28 中的 [TransactionAsync] 方法的扩展版本;
- 第 17 行:[BeginTransactionAsync] 开启一个事务([START TRANSACTION])。[await using var] 声明一个变量,无论发生什么(正常结束或异常),它都会在退出包含它的代码块时自动关闭;[await] 版本允许异步关闭。未提交就关闭的事务会被回滚([ROLLBACK]);
- 第 20–22 行:执行任务;如果成功,[CommitAsync] 提交事务([COMMIT])。如果抛出异常(包括 [BusinessException]),则[CommitAsync] 永远不会被执行:所有已写入的内容都会被回滚;
- 第 24 行:示例 28 捕获了两种特定类型的异常;这里我们捕获所有异常,以便在重新抛出之前进行清理;
- 第 29 行:清理。数据库已经回滚了所有内容,但 [DbContext] 仍在跟踪已不再对应任何内容的实体:例如,插入失败的医生仍处于 [Added] 状态。由于 [DbContext] 在整个请求期间一直存在,它会在该请求的下一次 [SaveChangesAsync] 时被再次发送到数据库。[ChangeTracker.Clear()] 会让 [DbContext] 忘记它所跟踪的所有实体;
- 第 30–32 行:如果错误是已知的数据库错误,则改为引发相应的 [BusinessException]。[is { } businessError] 是一个模式过滤器:它检查该值不为 [null] ,并将其存储在变量 [businessError] 中;
- 第 34 行:否则,原始异常将原样重新抛出。在 [throw;] 单独出现于 [catch] 中时,会保持其调用堆栈(指明错误发生位置的那个堆栈)完好无损,而 [throw e;] 则会将其重置。因此,由任务引发的 [BusinessException] 会原封不动地传回控制器;任何其他错误都是异常情况,会生成 500 错误页面;
- 第 51–56 行:对于 SQL 脚本中每个具名的唯一性约束,给出其翻译键。这就是 SQL 脚本为其所有约束命名的原因。当左侧已指定类型时,允许使用不带类型名的 [new()];[["key"] = value] 填充字典;
- 第 59–77 行:将数据库错误转换为 [BusinessException],如果无法识别该错误,则为 [null] ;
- 第 62–64 行:[UPDATE ... WHERE id = ... AND version = ...] 没有修改任何行:EF Core 会引发 [DbUpdateConcurrencyException] (乐观锁;参见示例 28)。这个测试放在最前面,因为 [DbUpdateConcurrencyException] 继承自 [DbUpdateException]:如果放在后面,下面的测试就会先拦截它;
- 第 68 行:违反唯一性约束。[MySQL] 错误(代码 [DuplicateKeyEntry],编号 1062)嵌套在 [DbUpdateException] 中,位于其属性 [InnerException] 里。模式过滤只用一个表达式就在两个层级上完成所有检查:[e] 是一个 [DbUpdateException],其 [InnerException] 是一个 [MySqlException],其 [ErrorCode] 等于 [DuplicateKeyEntry];这个 [MySqlException] 被包含在 [sqlError] 中。[NestJS] 版本还测试了 [ER_DUP_ENTRY] 代码,它属于 [QueryFailedError];
- 第 71 行:错误消息列出了约束名称,例如 [Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name']。正则表达式将其提取出来:[(?:[^'.]*\.)?] 跳过可选的前缀 [doctors.] (由 [MySQL] 8 写入,而不是由 [MariaDB] 写入),而分组 [([^']+)] 捕获直到撇号为止的名称。字符串开头的 [@] 使其成为 逐字字符串,其中 [\] 不是转义字符;
- 第 72–74 行:如果找到了该名称且它列在字典中,[TryGetValue] 会将翻译键存入 [key],错误随之变为 [BusinessException]。任何其他错误,包括对字典中没有的约束的违反,都不会被翻译:这才是真正的异常情况。
11.13. 身份验证
[Auth] 文件夹以更完整的形式包含了示例 25 至 27:Cookie 中的 JWT 令牌、角色、验证码(CAPTCHA)和尝试次数限制。它还包含用于创建客户账户的“通行码”。本节末尾讨论的 [AuthController] 控制器将这些组件整合到登录页面中。
11.13.1. Auth/ConnectedUser.cs
- 第 24–29 行:令牌声明(claim)的名称,归为常量:[JwtClaims.Name] 中的拼写错误会被编译器标出,而字符串 ["name"] 中的错误则只会在运行时才被发现;
- 第 33 行:已登录的用户,以带类型的形式表示:整数标识符、类型为 [Role] 的角色(来自 [Entities] 文件夹中的枚举 ADMIN、DOCTOR、USER),而不是构成声明的字符串对列表。这等价于 [req.user] 对象,它由 [Passport] 策略在 [NestJS] 项目中创建;
- 第 39–42 行:
***[ClaimsPrincipal]上的扩展方法(参见示例 06),它是控制器和视图的***[User]属性的类型(参见示例 25)。页面只需编写 [User.CurrentUser()]; - 第 44–48 行:如果请求未经身份验证,或者声明不符合预期,该方法返回 [null] 。如果 [Identity?.IsAuthenticated] 缺少 [Identity],则 [Identity] 等于 null:[!= true] 比较将这种情况视为“未经身份验证”。[int.TryParse] 和 [Enum.TryParse<Role>] 尝试进行转换,如果转换失败则返回 [false] ,而不是抛出异常;结果存储在由 [out var] 声明的变量中;
- 第 50–54 行:[FindFirstValue] 返回所请求类型的第一个声明的值,或 [null];然后运算符 [??] 将其替换为空字符串。
11.13.2. Auth/AuthService.cs
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 | |
下面对这段代码进行说明:
- 第 38 行:该服务通过注入接收包含用户账户的 DAO([UserRepository],在讲解 DAO 层时已讨论)以及身份验证配置。[IOptions<AuthOptions>] 以 [Auth] 节的形式提供 [appsettings.json] 中的内容,类型为 [AuthOptions] 对象([Config] 文件夹):其 [Value] 属性包含密钥、令牌有效期以及 [CookieSecure] 选项。该服务在 [Scoped] 中注册于 [Program.cs],与它所使用的 DAO 一样(参见第 6 章);
- 第 41 行:承载令牌的 Cookie 的名称;
- 第 47–56 行:签名密钥(参见示例 25)。新特性:过短的密钥会被拒绝并抛出清晰的异常。该方法是 静态的:它只依赖其参数,并且在应用程序启动时由 [JwtAuthentication] (下一个文件)调用,此时还不存在任何服务。由于长度检查发生在这一时刻,错误的配置会阻止应用程序启动,而不是导致第一次登录失败;
- 第 62–69 行:如果用户名和密码正确则返回账户;否则返回 [null] (参见示例 25)。该方法是异步的:账户查找是一次数据库查询(参见第 9 章);
- 第 78–92 行:令牌,按示例 25 的方式生成。它包含账户标识符、用户名、导航栏中显示的名称以及角色;其有效期由配置决定(默认两小时);
- 第 94–100 行:Cookie,使用示例 25 中的选项([HttpOnly]、[SameSite = Lax])以及另外两个选项:[Secure]在生产环境中启用(站点通过 [HTTPS] 提供服务),防止浏览器通过未加密的连接发送该 Cookie;[Path = "/"] 确保它随对站点的每个请求一起发送。[MaxAge] 会在令牌过期时删除该 Cookie;
- 第 104–105 行:注销会删除 Cookie。为了让浏览器识别要删除的 Cookie,路径([Path])必须与存储位置的路径一致。该方法是静态的:处理程序 [JwtBearer](下一个文件)和异常过滤器 [HtmlExceptionFilter] (文件夹 [Web])也会用到它,它们没有可用的 [AuthService] 实例。
11.13.3. Auth/JwtAuthentication.cs
在示例 25 中,[JwtBearer] 的配置写在 [Program.cs] 中。这里,它存放在一个扩展方法中,[Program.cs] 只用一行调用它:[builder.Services.AddJwtAuthentication(authOptions)]。下面对这段代码进行说明:
- 第 32–34 行:扩展方法(参见示例 06)。它直接接收一个 [AuthOptions] 对象,该对象由 [Program.cs] 从配置中读取:注册服务时,依赖注入尚不可用,因此我们无法请求 [IOptions<AuthOptions>];
- 第 37–42 行:身份验证方案 [JwtBearer],其中存储了令牌的声明名称(参见示例 25);
- 第 44–54 行:对每个令牌执行的检查:使用由 [AuthService.SigningKey] 生成的密钥验证签名,以及过期时间。相对于示例 25 的新特性:[ClockSkew = TimeSpan.Zero]。默认情况下,[JwtBearer] 在令牌过期后的五分钟内仍然接受它,以兼顾生成令牌的服务器与验证令牌的服务器之间时钟的轻微差异。这里是同一台服务器:过期的令牌会被立即拒绝;
- 第 57–58 行:声明 [name] 对应 [User.Identity.Name],声明 [role] 是由 [[Authorize(Roles = "ADMIN")]] 和 [User.IsInRole] 验证的那一个(参见示例 26);
- 第 64–67 行:令牌是从 Cookie 中读取的,而不是从 [Authorization] 标头中读取(参见示例 25);
- 第 71–82 行:在没有有效令牌的情况下请求受保护的页面,会重定向到登录页面(参见示例 25)。新特性(第 77–80 行):如果请求中包含令牌 Cookie,就意味着用户曾经登录过,但其令牌已过期(或被篡改)。我们删除这个已经无用的 Cookie,并显示一条闪现消息(参见示例 20;[Flash] 类将在讲解 [Web] 文件夹时讨论):登录页面会显示“您的会话已过期”,而不是让用户疑惑自己为什么会来到这里。该消息是一个翻译键(参见示例 22)。
403 Forbidden 响应(角色不足)不需要事件:与示例 26 中一样,空响应会由 [UseStatusCodePagesWithReExecute] 转换为错误页面。在 [NestJS] 项目中,这项任务由 [Passport] 和 [jwt] 策略(读取并验证令牌)、守卫 [JwtAuthGuard] (要求令牌)和异常过滤器(将拒绝转换为重定向)分担;而在这里,处理程序 [JwtBearer]、它的事件以及特性 [[Authorize]] 就足够了。
11.13.4. Auth/InvalidSessionException.cs
- 第 13 行:令牌可能是有效的(签名正确、未过期),即使它所指向的账户在登录之后已被删除。患者的页面通过查找与该账户关联的客户(文件 [ConnectedPatientAsync] 中的方法 [Web/Utils.cs])来检测这种情况,然后抛出此异常;异常过滤器 [HtmlExceptionFilter] (过滤器参见示例 24)会拦截它,删除 Cookie,并重定向到登录页面,同时显示“会话已过期”消息。该类有一个无参数的主构造函数,它将其消息传递给父类 [Exception] 的构造函数。
11.13.5. Auth/CaptchaService.cs
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 | |
该文件包含两个类:服务类,除了一项保护措施之外与示例 27 中的完全相同;以及生成图像的 [CaptchaDrawing] 类,它已在示例 27 中讨论过(文件 [Auth/CaptchaDrawing.cs])。我们来看这段代码:
- 第 44 行:页面所接收到的验证码(CAPTCHA):标识符(放置在隐藏的表单字段中)和 [SVG] 图像;
- 第 49–52 行:图像的有效期为十分钟,并且对待处理验证码的数量设有上限。每次显示登录页面时,都会在内存中添加一个验证码;如果没有上限,一个数百万次请求该页面却从不作答的机器人最终会耗尽服务器的内存;
- 第 55 行:id → (预期答案,过期时间)。这一对是一个 元组 ,其元素带有名称([Text]、[Expires])。该服务是单例,被并发请求使用:因此使用 [ConcurrentDictionary] (参见示例 27);
- 第 57–63 行:先清理,然后生成随机的五个字符的文本字符串,以随机标识符([Guid.NewGuid()],无法猜测)存储,并显示出来;
- 第 70–77 行:验证,与示例 27 中相同:验证码在任何情况下都会被消耗([TryRemove]),然后系统验证它是否未过期,以及输入的文本(去掉空格后)是否正确,不区分大小写。[TryRemove] 是 原子的:如果两个请求同时提交同一个验证码,只有一个能将其移除;
- 第 80–87 行:过期的验证码被丢弃;如果达到上限,有效的验证码也会被移除,直到数量降到上限以下。[ConcurrentDictionary] 可以在遍历的同时被修改,而标准的 [Dictionary] 不允许这样做(参见下文的 [AttemptLimiterService])。然而,它不保留插入顺序:以这种方式移除的验证码不一定是最旧的,而 [NestJS] 项目中的 [Map] 则可以先移除最旧的。这种情况只会在遭受攻击时出现:近似处理就足够了;
- 第 96 行:绘制图像。[internal]:该类仅在应用程序内部可见;
- 第 104–136 行:“字体”:对每个字符,给出一组笔画,每个笔画是 4 × 6 网格中的一系列 (x, y) 坐标。方括号 [[...]] 是 集合表达式 ([C#] 12),一种紧凑的数组表示法;
- 第 139 行:可用的字符,即字体的键。[..] 将 一个集合展开到另一个集合中;
- 第 146–147 行和第 149–150 行:随机化使用 [RandomNumberGenerator],这是一个密码学生成器,其输出不可预测;
- 第 152–194 行:图像是一段 [SVG] 文本,由 [StringBuilder] (一种在添加元素时无需每次重写而可以不断扩展的字符串)组装而成。每个字符(第 160–181 行)变成一条 [<path>] 路径:网格上的每个点都会被轻微偏移、放大、旋转,并放置到图像中的相应位置,同时随机选择颜色和线条粗细。这些字符是线条,而不是文本:机器人无法在图像的代码中读取它们。随后有三条干扰曲线穿过图像(第 185–190 行);
- 第 199 行:[SVG] 中的数字使用小数点书写。[CultureInfo.InvariantCulture] 无论服务器使用何种语言都强制采用这种写法:在法语中,[ToString()] 会使用逗号(参见第 5 章)。
11.13.6. Auth/AttemptLimiterService.cs
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 | |
与示例 27 相比,限制器保护两个操作(登录和账户创建);登录封锁作用于(IP 地址,登录名)这一对,并且阈值可在 [appsettings.json] 中配置。我们来分析这段代码:
- 第 31 行:[IOptions<ProtectionOptions>] 指定 [Protection] 节,来自 [appsettings.json] (文件夹 [Config]):允许的登录失败次数(默认 5 次)、锁定时长(15 分钟)以及每小时创建的账户数(10 个);
- 第 33–37 行:计数器:尝试次数、计数窗口的起点,以及锁定的结束时间(如果没有锁定,则为 [DateTime.MinValue],即最早的可能日期)。这是一个 嵌套的私有类:它只为这个服务而存在。它是类,而不是 [record] 或结构:从字典中读取的计数器会被原地修改;
- 第 42–43 行:一个普通的 [Dictionary],由锁保护(参见示例 27)。[ConcurrentDictionary] 是不够的:统计一次尝试需要读取计数器、修改它,并可能替换它,而这整个操作序列必须在不被其他请求打断的情况下执行。因此,每个公共方法都在 [lock (syncLock)] 块中执行其任务;
- 第 45–47 行:阈值,一次性读取。主构造函数的参数可以用来初始化字段;
- 第 52–56 行:连接尝试的剩余锁定时间:两种可能的锁定时长中较长的一个,即(IP 地址,登录名)这一对的锁定时长与单独 IP 地址的锁定时长;
- 第 60–65 行:一次失败的尝试会被计两次。对于(IP 地址,登录名)这一对:使用同一登录名连续失败五次,会封锁该登录名,但仅限于该地址。对于单独的 IP 地址,阈值提高到五倍:尝试大量不同登录名的机器人也会被封锁。在教室里,所有计算机通常通过同一个 IP 地址连接互联网:输错密码的学生不应该封锁他们的邻座,因此才按“对”进行封锁;
- 第 70–74 行:成功登录会重置该特定登录名的计数器(而不是 IP 地址的计数器);
- 第 80–84 行和第 89–93 行:对于账户创建,只统计成功的尝试:同一个 IP 地址每小时最多创建十个账户。达到配额后,该地址被封锁一小时;
- 第 100–107 行:封锁的剩余分钟数,向上取整([Math.Ceiling]):当还剩 20 秒时,显示“1 分钟”而不是“0 分钟”。这些私有方法不获取锁:它们总是由已经持有锁的公共方法调用;
- 第 111–125 行:计数。未知的键,或其计数窗口已过期的键,从新的计数器开始。达到阈值时,该键被锁定,并在锁定结束时从零重新开始计数;
- 第 130–140 行:清理不再需要的计数器(既未被锁定也不是最近的),仅在字典超过 1000 个条目时执行。我们遍历条目的一个副本([ToList()]):[Dictionary] 在被遍历时不能被修改;
- 第 145–147 行:生成字典的键。去掉登录名中的空格并将其转换为小写:[Admin] 和 [admin] 共用同一个计数器;机器人无法通过改变大小写来绕过锁定。
11.13.7. Auth/RegistrationPassService.cs
只要解决了验证码,就可以从登录页面创建客户账户。注册表单通过后续请求来显示和提交:这些请求必须知道之前的某个请求已成功解决了验证码。这就是通行码的作用,它由 [RegistrationController] (在控制器部分说明)签发和验证:
- 第 29 行:承载通行码的 Cookie 的名称;
- 第 31–35 行:通行码的有效期为十五分钟;待处理的通行码与验证码一样保存在内存中,并具有相同的时间限制;
- 第 38–43 行:通行码是一个随机标识符,与其过期时间一起存储;控制器将它放入 Cookie 中;
- 第 47–48 行:只有持有有效的通行码,才会显示并接受注册表单。验证不会消耗通行码(使用 [TryGetValue],而不是 [TryRemove]):如果用户输入有误,可以多次重新提交表单;
- 第 51–55 行:创建账户会消耗通行码:解决一次验证码只有权创建一个账户,不能更多;
- 第 60–65 行:Cookie 选项。[new()] 创建方法所声明类型([CookieOptions])的对象。选项 [Path = "/register"] 将 Cookie 的发送限制在以 [/register] 开头的 URL:其他请求不会无谓地携带它;
- 第 68–75 行:清理过程,与验证码的清理过程相同。
11.13.8. Controllers/AuthController.cs
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 | |
下面对这段代码进行说明:
- 第 31–34 行:控制器接收它所需的三个服务。没有 [[Authorize]] 特性:其页面无需登录即可访问;
- 第 37 行:主页取决于角色:患者为“我的空间”,其他人为日历;
- 第 39–45 行:站点根路径会重定向到与角色对应的主页或登录页面。身份验证中间件对 所有 请求都会运行,无论请求是否受保护:如果 Cookie 中包含有效的令牌,则 [User] 会被填充,即使在这里也是如此。相比之下,[NestJS] 项目必须自己验证令牌(方法 [readToken]),因为此路由不应用令牌检查;
- 第 50–59 行:已登录的用户会被重定向到其主页。可选参数 [login] 来自 URL(参见示例 07),在创建账户后用于预填该字段。[login[..n]] (范围运算符)保留前 [n] 个字符:其长度被限制为 30,因为来自请求的数据绝不能不加防范地使用;
- 第 65–70 行:登录表单的字段(参见示例 11),包括通过隐藏字段传递的验证码标识符,以及用户的输入。它们都声明为 [string?]:缺失的字段得到 [null],由操作来决定如何处理它;
- 第 72–74 行:缺失的登录名变为空字符串;[password ??= ""] 只有在 [password] 为 [null] 时才会影响空字符串;
- 第 77–80 行:1. 被封锁的“对”根本不会被处理:既不检查验证码,也不检查密码。错误是一个带有一个参数的翻译键:需要等待的分钟数;
- 第 84–87 行:2. 验证码。验证码错误算作一次失败(参见示例 27);
- 第 91–95 行:3. 然后才检查密码。空的用户名或密码不会进行计算开销很大的 [bcrypt] 计算。用户名未知或密码错误:给出同样刻意含糊的消息(参见示例 25),并再记一次失败;
- 第 98–100 行:成功:计数器清零,令牌存入 Cookie,重定向到该角色的主页;
- 第 105–109 行:注销,使用 POST(参见示例 25);
- 第 115 行:客户端的 IP 地址,由网络连接提供([RemoteIpAddress],它可能为 [null],因此使用 [?.] 和 [??])。该方法是公共静态的:[RegistrationController] 和 [PatientAreaController] 也将它用于限制器。在中间服务器(例如 [nginx] 这样的反向代理)之后,该地址会是代理的地址:注释中指明了这种情况下需要启用的中间件;
- 第 118–125 行:登录页面,始终带有 新的 验证码:每张图像只使用一次。它的模型 [LoginModel] (文件夹 [Models])包含页面标题(翻译键)、输入的用户名(绝不包含密码)、验证码,以及任何错误消息及其翻译键和参数。[error] 和 [errorParams] 是 可选参数:当调用未提供它们时,默认为 [null] 。
11.14. Web 层:共享服务
在讲解控制器和视图之前,先看看它们的共同点:翻译、视图的父类、闪现消息、异常过滤器、医生和客户列表的缓存、为重新显示而准备的表单,以及一些实用函数。所有这些文件都在 [Web] 文件夹中。它汇集了示例 16 至 24 中的大部分技术。
11.14.1. Web/Translator.cs
这就是示例 22 中的翻译服务,在 [Program.cs] 中注册为单例:字典 [i18n/fr.json] 和 [i18n/en.json] 与 [NestJS] 版本中的文件相同,只在启动时读取一次。只有一处不同:
- 第 65–67 行:法语字典中缺失的键会到英语字典([DefaultLanguage])中查找;如果各处都缺失,则显示键本身。两个 [??] 运算符串联在一起:取第一个不为 [null] 的值。
11.14.2. Web/ViewPage.cs
我们来分析这段代码:
- 第 25 行:所有视图的父类,由 [@inherits] 指令指定,位于 [Views/_ViewImports.cshtml] 中,与示例 22 相同。它的作用与 [res.locals] 在 [NestJS] 版本中相同:为每个视图提供所有页面都需要的内容;
- 第 29–30 行:翻译服务,被注入到属性中(参见示例 22);
- 第 39–40 行:示例 22 中的 [T] 方法:[@T("KEY", ("name", value))]。渲染的文本由 [Razor] 转义:用户输入的名称无法向页面注入 HTML;
- 第 43 行:[T] 的第二个版本,它直接接受字典:闪现消息或 [BusinessException] 的参数正是以这种形式传递的。两个名称相同、参数不同的方法称为 重载方法:编译器根据实参选择正确的那一个;
- 第 45 行:当前语言([fr] 或 [en]),用于页面的 [lang] 属性以及 FR / EN;
- 第 47 行:已登录的用户,用于导航栏,如果没有则为 [null] 。[Context.User] 是请求的用户,由身份验证中间件根据 JWT 令牌重建(参见第 8 章);方法 [CurrentUser()] (文件 [Auth/ConnectedUser.cs])从中提取账户。在 [NestJS] 版本中,需要一个拦截器在守卫之后将 [req.user] 复制到 [res.locals] 中;而在这里,该属性是在视图读取它时才计算的,那时身份验证早已完成;
- 第 49 行:请求的闪现消息(参见下文的 [Web/Flash.cs]);
- 第 51–54 行:所请求 URL 的路径,以及一个方法,如果当前页面位于给定路径之下,该方法就返回 [active] :导航栏就是这样高亮当前菜单项的,例如 [@Active("/my-")] (参见示例 16)。[StringComparison.Ordinal] 逐个字符地比较,与语言无关;
- 第 60–70 行:视图所看到的已登录用户:登录名、姓名、角色,以及两个布尔值 [IsAdmin] 和 [IsPatient],它们使视图无需自行比较角色。静态方法 [Of] 根据已登录的账户创建此对象,或返回 [null];运算符 [? :] 在两者之间进行选择。实参 [IsAdmin:] 和 [IsPatient:] 是 命名的:参数名写在值之前,使调用更易读。
11.14.3. Web/Flash.cs
下面对这段代码进行说明:
- 第 23–26 行:两种类型的消息:成功消息,显示在页面顶部(分部视图 [_Flash.cshtml]),以及错误消息,显示在页面底部(分部视图 [_Errors.cshtml]);
- 第 30 行:闪现消息由翻译键及其参数组成,而不是预先翻译好的文本;它将在下一个页面中按该页面的语言进行翻译;
- 第 32 行:只包含函数的静态类(参见 [Web/Utils.cs])。[TempData] (参见示例 20)完成了大部分工作:它将值存储在加密的 Cookie 中,直到下一个请求,并在读取后将其删除。在 [NestJS] 版本中,这个短期 Cookie 是手工编程实现的;
- 第 43–51 行:设置消息。[TempData] 只能存储简单的值(文本、数字):消息被存储为文本 JSON([JsonSerializer.Serialize])。该方法接收 [HttpContext] ,而不是控制器的 [TempData] 属性:因此它可以在 MVC 之外被调用,例如在会话过期时由 JWT 身份验证调用(参见 [Auth/JwtAuthentication.cs])。在 MVC 之外,没有人会在请求结束时保存 [TempData] :[Save()] 会立即写入 Cookie;
- 第 60–79 行:读取请求的消息。读取 [TempData] 会将其标记为已消耗;然而页面要读取它两次(顶部用于成功消息,底部用于错误消息)。因此第一次调用将结果存储在 [HttpContext.Items] 这个请求范围的字典中(参见第 6 章),第二次调用从那里取回它(第 62 行);
- 第 71–73 行:[Deserialize] 从 JSON 重建 [FlashMessage] 对象。无法读取的文本不应导致页面失败:异常会被捕获,消息被忽略;
- 第 82–83 行:请求的 [TempData] ,从 [ITempDataDictionaryFactory] 服务获得。[RequestServices] 使静态类能够访问依赖注入,因为静态类不能通过构造函数接收服务。
11.14.4. Web/HtmlExceptionFilter.cs
下面对这段代码进行说明:
- 第 25 行:一个异常过滤器,与示例 24 中相同,作为全局过滤器添加到 [Program.cs] 中。在 [NestJS] 版本中,单个过滤器就将所有错误转换为 HTML 页面。在这里,工作由框架的两个中间件组件分担,它们在 [Program.cs] 中配置:[UseStatusCodePagesWithReExecute] 将没有内容的 400、403 和 404 响应替换为相应的错误页面(参见示例 24),而 [UseExceptionHandler("/error/500")] 拦截所有其他异常:错误连同其调用堆栈会记录在服务器日志中,但用户只会看到 500 错误页面,因为这些细节可能会帮助攻击者;
- 第 29–34 行:该过滤器只处理一种情形:已登录用户的账户在其登录后被删除,而其令牌仍然有效(参见下文的 [Web/Utils.cs])。此时会清除令牌 Cookie,显示“会话已过期”的闪存消息,并将用户重定向到登录页面。其他异常不会被标记为已处理:它们会继续传递给 [UseExceptionHandler]。
11.14.5. Web/ApplicationModel.cs
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 | |
医生和客户的列表几乎出现在每个页面中(日历下拉列表、管理页面)。我们不在每次请求时都从数据库中检索它们,而是将其保存在内存中:这是应用程序范围的数据(参见第 6 章)。[NestJS] 版本把这个角色交给了一个单独的服务,它与所有 [NestJS] 服务一样是单例。在 [ASP.NET Core] 中这是行不通的:业务层使用 [DbContext],它只在一次请求期间存在([Scoped] 服务;参见第 9 章),而单例不能接收 [Scoped] 服务。因此我们把这两个角色拆分到两个类中。
我们来逐段说明这段代码:
- 第 39 行:缓存本身,注册为单例([AddSingleton<ListCache>()] 位于 [Program.cs] 中)。它只包含两个列表;
- 第 41–42 行:[ASP.NET Core] 通过多个线程([threads])并行处理请求,而 [Node.js] 只有一个线程。因此,当另一个请求正在遍历共享列表时,绝不能修改它。我们选择的规则很简单:从不修改列表,而是用新列表替换它。替换引用只需一次操作即可完成,关键字 [volatile] 确保所有线程都能立即看到新列表。[IReadOnlyList] 只允许读取:编译器禁止添加或删除元素;
- 第 60 行:外观,注册为 [Scoped] 服务([AddScoped<ApplicationModel>()])。它接收当前请求的业务层和共享缓存。它实现了与业务层相同的 [IBusiness] 接口:对控制器而言,它就是业务层,并且是控制器收到的唯一一个;
- 第 65–68 行:两个列表的初始加载。它由 [Program.cs] 在服务器启动前调用一次。[Scoped] 服务只存在于某个作用域内:[Program.cs] 为此创建了一个作用域([CreateScope])。如果数据库无法访问,异常会带着明确的消息终止应用程序,这比用空列表启动服务器要好;
- 第 71–73 行:重新加载列表:从数据库读取整个列表并替换缓存中的列表;
- 第 77–79 行:列表从内存中提供。[IBusiness] 接口声明了一个异步方法:[Task.FromResult] 创建一个已完成的任务,并携带结果。[ToList()] 返回列表的副本:调用方可以修改它而不影响缓存;
- 第 83 行:与某个账户关联的医生,从缓存中获取:已登录的医生可以立即看到自己的日程;
- 第 87–110 行:其他请求原样转发给业务层;
- 第 104 行:与某个账户关联的客户有意不从缓存中查找;刚修改或删除了自己账户的患者,必须按其在数据库中的实际状态显示;
- 第 114–151 行:任何涉及医生或客户的写操作之后,都会刷新相应的列表。由于该服务是控制器访问业务层的唯一入口,“写入 = 刷新缓存”这条规则只在这里实现,缓存就不会变得陈旧。如果业务层拒绝该操作([BusinessException]),异常会在缓存重新加载之前终止该方法,因为此时已无需这一步。
11.14.6. Web/Validation.cs
我们来逐段说明这段代码:
- 第 20–31 行:将 [ModelState] (参见示例 07 和 19)转换为简单的“字段 → 消息键”字典。每个字段只保留第一条消息:字段下方只显示一条消息。该字典忽略大小写(第 22 行):[ModelState] 根据属性([LastName]、[Login])为字段命名,而视图则根据 HTML 字段([lastName]、[login])来请求它们;
- 第 27–28 行:作为预防措施,没有消息的错误(例如由异常引起的错误)会被赋予通用消息 [ERRORS.INVALID_FORM];
- 第 38–42 行:业务层的某些错误与特定字段有关:已被占用的用户名,或姓名相同的医生或客户。这些字段将以红色高亮显示,消息显示在页面底部。语法 [["key"] = value] 在字典创建时即完成填充;
- 第 53–64 行:准备用于显示或重新显示的表单模型:字段下方的消息([Errors])、需要用红框标出的字段([InvalidFields]:带有消息的字段,加上 [otherFields] 字段,第 61 行)、页面底部的消息及其参数。在没有明确消息时,字段错误会产生“表单包含错误”这条消息(第 62 行)。该方法是泛型的:约束 [where T : FormView] (第 58 行)接受任何派生自 [FormView] 的模型(参见 [Models/ViewModels.cs]),并以其确切类型返回该模型,可直接传给 [View]。这些参数都有默认值([= null]):调用方只需提供它需要的参数。
11.14.7. Web/Utils.cs
我们来逐段分析这段代码:
- 第 24 行:医生或客户的姓名:“Mme Alice DURAND”。该参数的类型为 [Person],即实体 [Doctor] 和 [Client] 的父类:两者使用同一个函数;
- 第 30 行:URL 中以及 [<input type="date">] 字段中使用的日期格式;
- 第 34–35 行:如果文本是 [yyyy-MM-dd] 格式且确实存在的日期,则返回 true;[2026-02-30] 会被拒绝(参见示例 12)。结果通过参数 [out day] 返回。[CultureInfo.InvariantCulture] 使解析与请求的语言无关;
- 第 37 行:反向操作:把日期转换为文本 [yyyy-MM-dd];
- 第 40–42 行:格式为 [8:05] 的时间([00] 格式要求分钟为两位数字),以及时间段的时间:[8:00 - 8:20];
- 第 47–48 行:根据请求的区域设置(由本地化中间件确定,参见示例 22)完整写出的日期:“mercredi 23 septembre 2026”或“Wednesday 23 September 2026”;
- 第 54–55 行:浏览器发送的标识符(在 URL 或表单字段中):严格正整数,或 [null]。[NumberStyles.None] 只接受数字:不接受符号、空格或千位分隔符。控制器只需测试 [null] 即可;
- 第 70–73 行:与已登录用户关联的患者(实体 [Client])。JWT 令牌只包含账户 ID;我们据此查找与该账户关联的客户。如果该客户已不存在,则说明账户在用户登录后被删除:[InvalidSessionException] 将由上文所述的 [HtmlExceptionFilter] 过滤器处理,并重定向到登录页面。[?? throw] 在左侧的值为 [null] 时抛出异常(参见第 9 章)。
11.15. 表单模型与视图模型
有两类类在浏览器、控制器和视图之间传输数据:表单,由模型绑定根据浏览器发送的内容填充;以及视图模型,由控制器为视图准备。前者对应 [NestJS] 版本中的 DTO 对象,后者对应传给 [res.render] 的对象。
11.15.1. Models/Forms.cs
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 | |
我们来讨论这段代码:
- 第 43 行:可选的称谓;
- 第 46 行:用户名的格式,由正则表达式描述:1 到 30 个字符,由小写字母、数字、句点、连字符和下划线组成;
- 第 49 行:患者所选密码的最小长度。这是一个常量([const]),因此可以用作特性的参数,例如下面的 [[MinLength(InputRules.PasswordMin)]] ;
- 第 52 行:清理输入:去除首尾空格,仅由空格组成的字段变为 [null],即视为无效;
- 第 59–62 行:我们编写的验证特性:值必须出现在某个列表中。我们只需从 [ValidationAttribute] 派生并重写 [IsValid] 即可。[null] 会被接受:拒绝缺失字段是 [[Required]] 的职责。我们以 [[OneOf]] 这个名称使用它:按照约定,后缀 [Attribute] 可以省略;
- 第 66 行:身份字段,三个表单共用。所有属性的类型都是 [string?]:浏览器发送的数据中,字段始终可能缺失,要求其必须存在的是 [[Required]]。错误消息是翻译键(参见示例 22);
- 第 68–70 行:称谓,必填,并从列表中选择。这些值在 [[OneOf(...)]] 中重复出现:特性的参数必须在编译时已知,而数组 [InputRules.Titles] (一个 [static readonly] 字段,在运行时创建)并非如此;
- 第 73–80 行和第 83–90 行:名和姓,必填,最多 20 个字符(SQL 列的宽度)。这些属性带有方法体:它们的值存储在私有字段中,并由 [set] 在赋值时进行清理。由于模型绑定在验证之前就给属性赋值,因此验证的是清理后的值。这相当于 [@Transform] 在 [NestJS] 版本中的作用;[ASP.NET Core MVC] 已经会自动把空字段转换为 [null];
- 第 95 行:ADMIN 表单,用于添加或编辑医生或客户。该类继承了身份字段及其验证特性;
- 第 97–104 行:登录名,在此处可选,但如果存在则必须符合正确的格式(第 100 行);它会被清理并转换为小写。[?.] 仅当值不是 [null] 时才调用 [ToLowerInvariant];
- 第 108–109 行:密码,同样可选,最多 72 个字符:对其加密的 [bcrypt] 算法会忽略其后的所有字符。密码不会被清理:空格也算作密码的一部分;
- 第 114 行:记录的版本,位于更新表单的隐藏字段中(乐观锁;参见示例 28)。字段缺失或为空会得到 [null];不是数字的文本会产生绑定错误,其消息在 [Program.cs] 中配置(参见示例 19);
- 第 118 行:患者创建账户:用户名、密码(6 到 72 个字符,第 131 行)和确认密码(第 135–136 行)均为必填。验证密码与其确认是否一致涉及两个字段:这由验证器检查([Controllers/RegistrationController.cs]);
- 第 140 行:患者修改自己的账户。新密码是可选的(第 153 行):如果留空,密码保持不变;因此这里不要求确认密码(第 157 行)。但任何修改都必须提供当前密码(第 160–161 行),记录版本则存储在隐藏字段中(第 163 行)。
11.15.2. Models/ViewModels.cs
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 | |
视图模板遵循我们在 [Handlebars] 中已经应用过的规则:视图中不含逻辑。控制器准备好已格式化的数据(“Mme Marie PELISSIER”、“8:00 – 8:20”),并已根据用户角色过滤;视图只是把这些数据放入 HTML 中。每个视图都声明其模板的类型([@model ScheduleModel],参见示例 13):编译器会检查每一个 [@Model.Xxx],拼写错误会导致编译错误。
我们来逐段说明这段代码:
- 第 22–31 行:所有页面的共同部分,由 [_Layout.cshtml] 模板读取:页面标题的翻译键(第 25 行),以及显示在底部的页面错误消息及其参数。该类是抽象类:每个页面都有自己的模板,并派生自它;
- 第 35 行:下拉列表中的一个选项(医生、患者),已标记为选中或未选中(参见示例 18);
- 第 38–41 行:登录页面:已输入的用户名和要显示的验证码(CAPTCHA)。关键字 [required] 要求创建对象的人必须为该属性赋值;否则会导致编译错误;
- 第 45–54 行:日历条目,即一个时间段。控制器已经确定了一切:是否显示患者姓名(患者看不到其他人的姓名)、是否显示“预约”按钮,以及是否显示“取消”按钮([AppointmentId] 已设置时)。[init] 属性只能在创建对象时赋值;
- 第 57 行:医生某一天的日程:医生姓名、完整写出的日期,以及各行;
- 第 59–66 行:预约窗口:ADMIN 和医生看到的是患者列表,患者则只看到已登录患者的姓名;
- 第 69–79 行:日历页面:医生列表、所选的医生和日期、日历(在未选择医生时为 [null] )、预约窗口(如果存在)、不带该窗口的日历 URL(第 76 行),以及向患者说明其为何无法预约的消息;
- 第 85–91 行:“人员”表单字段中显示的值,绝不包括密码:密码不会回传给浏览器;
- 第 95 行:三个“人员”表单的模板的父类,即 [Validation.Prepare] 所要求的类:字段值、字段下方的消息(第 100 行),以及要以红色高亮的字段(第 104 行)。[HashSet] 是一个集合:每个元素只出现一次,成员测试速度很快;
- 第 106–108 行:供视图使用的两个方法:字段的消息(或 [null]),以及用红框标出字段的 [Bootstrap] [is-invalid] 类。视图中的用法例如 [@Model.InvalidClass("login")];
- 第 110–111 行:称谓列表中的选项,并标出被选中的选项(参见示例 18)。每个选项是一个元组 [(Value, Selected)];
- 第 114–118 行:ADMIN 表单,用于添加和修改(参见示例 28):模式、表单提交 URL,以及返回按钮使用的列表 URL;
- 第 121–128 行:注册和账户管理表单;它们向视图传递密码的最小长度,该长度用作字段错误消息的 [{min}] 参数,对于注册表单还用于帮助文本;
- 第 134–142 行:医生和客户管理页面使用相同的视图;只是文本不同。这个 [record] 包含每种人员类型特有的翻译键;
- 第 144–150 行:医生或客户列表中的一行,带有其“编辑”和“删除”按钮的地址,以及列表页面的模板;
- 第 154–159 行:患者区域:其姓名和即将到来的预约,每个预约都带有指向当日日历的链接;
- 第 163–166 行:错误页面:HTTP 代码和消息键,默认是服务器错误的消息键。
11.16. Web 层:控制器
控制器是 Web 层的可见部分:每个控制器接收一组页面的请求,读取其参数,查询业务层(始终通过 [ApplicationModel] 服务),然后选择一个视图并向其传递类型化的模型,或者重定向请求。所有 POST 表单都遵循 Post/Redirect/Get 模式(参见示例 20);所有消息都是翻译键,由视图翻译。登录控制器 [AuthController] 已在身份验证部分讨论过。
11.16.1. Controllers/LanguageController.cs
除了一行之外,这就是示例 22 中的控制器:相同的路由 [/language/{language}],相同的本地化中间件 Cookie,并同样通过标头 [Referer] 返回原页面。两点说明:
- 第 34 行:选项 [Path = "/"] 使该 Cookie 对站点的所有地址都有效,无论是从哪个页面切换的语言;
- 第 49 行:如果原页面本身就是 [/language/...] 页面,用户会被重定向到站点根目录,而不是返回该页面,否则会导致浏览器陷入循环。
11.16.2. Controllers/ScheduleController.cs
应用程序的主页面,也是功能最丰富的控制器。我们逐段进行分析。
11.16.2.1. 页面的 URL
- 第 7–12 行:页面的路由。请注意,预约窗口不是由 [JavaScript] 打开的:它是 URL 的一个参数([book=7]),指示服务器在渲染页面时打开该窗口。因此,“预约”按钮只是一个链接。整个页面由其 URL 描述:可以重新加载、加入书签,或使用浏览器的“后退”按钮;
- 第 18–28 行:每个角色能看到什么、能做什么。这张表是页面的“规格说明”:控制器的其余部分负责实现它;
- 第 30–33 行:隐私规则,我们稍后会再讨论:其他患者的姓名不是由视图隐藏的,而是根本不会发送到浏览器;
- 第 55–57 行:类上的 [[Authorize]] 表示所有操作都要求用户已登录,无论其角色如何(参见示例 25)。[[Route("schedule")]] 是该控制器所有路由的前缀(参见示例 02)。控制器通过注入(参见示例 06)经由其[ApplicationModel]主构造函数接收该服务:写在类名后括号中的参数可在其所有方法中访问;
- 第 60–63 行:控制器对已登录用户的了解,每次请求计算一次(参见下文的 [RightsAsync])。这是一个私有的 [record],声明在类内部:只有该类使用它。[Manager] 对 ADMIN 或 DOCTOR 为 true; [Patient] 仅对客户(角色 USER)填充。
11.16.2.2. GET /schedule
- 第 6–7 行:路由 [GET /schedule] (控制器前缀,后跟空字符串)。该操作没有参数:它自动把 URL 作为 [Request.Query] 读取(参见示例 05)。模型绑定会把 [int? doctorId] 参数在缺失或为空时都转换为 [null];然而这两种情况必须加以区分(见下文);
- 第 10–11 行:已登录的用户及其权限。[CurrentUser()] 是定义在 [Auth/ConnectedUser.cs] 中的扩展方法(参见示例 06):它读取令牌的声明并将其转换为类型化对象。[!] 告知编译器结果不是 [null]:这是确定的,因为 [[Authorize]] 已经过滤掉了未经身份验证的请求;
- 第 14–26 行:所请求的日期(如果有效);否则为今天。如果参数 [TryGetValue] 缺失,[false] 就会返回 [day]:此时返回今天,不产生消息。如果存在但无效([day=2026-02-30]),则会生成错误消息。预约只能从今天开始进行([dayBookable]);
- 第 29–32 行:所请求的医生。[Input.PositiveInteger](文件夹 [Web])返回严格正整数,如果值缺失、为空或无效,则返回 [null] 。如果 URL 中[doctorId] 参数缺失,已登录的医生会看到自己的日程:这是其主页。如果它为空([doctorId=],即列表中的“-- choose a doctor --”选项),则不显示任何日程;
- 第 35–37 行:医生下拉列表中的选项,从 [ApplicationModel] 的缓存中读取;所请求医生对应的选项被选中(参见文件末尾的 [Option] 函数和示例 18);
- 第 40–46 行:只有在选择了医生且日期有效时才计算日程。[doctorId is int id] 检查该值(类型为 [int?])不是 [null],并把它的值存入新变量 [id],其类型为 [int]。未知的医生 ID 会触发一条消息,而不是错误页面。
- 第 50–56 行:业务层计算出的日程(来自 [Domain] 文件夹的 [DoctorDaySchedule] 对象)被转换为数组元素,每个时间段一个。[var (slot, appointment) = ...] 把一对值分解为两个变量。[mine] 决定该预约是否属于已登录的患者;
- 第 58–59 行:视图只接收已经格式化的数据([8:00 - 8:20]);它不再需要计算任何东西;
- 第 63 行:应用程序的隐私控制。只有对管理员,或对于预约所属的患者,患者姓名才会放入模型中。对其他所有人,模型中包含 [null],视图显示“已预约”。姓名并不是简单地由视图隐藏:它从未发送到浏览器,“查看页面源代码”也无法暴露它;
- 第 65–67 行:视图必须显示的内容,由控制器决定:“预约”按钮(时间段可用、日期未过期,并且用户有权预约)、其链接(页面的 URL,带有 [book]),以及“取消”按钮([AppointmentId] 仅对管理员填充)。视图不做任何决定:它只遵循这些指令;
- 第 70 行:完整的日程:医生、日期和各行。
11.16.2.3. 预约窗口与视图模板
- 第 3–5 行:URL 请求预约的时间段([book=7])。它必须出现在所显示的日程中,并且能被该用户预约:手工构造的 URL(过去的时间段、已被预约的时间段,或属于其他医生的时间段)不会打开该窗口。[schedule?.Rows] 在 [schedule] 为 [null] 时等于 [null] (运算符 [?.]);
- 第 6–15 行:窗口模板。管理员从列表中选择患者(所有客户,从缓存中读取);患者为自己预约:窗口只显示其姓名。[[]] 是一个空列表;
- 第 19–29 行:页面模板。它的类([ScheduleModel], [ScheduleView], [ScheduleRowView], [BookingView], [OptionView])定义在 [Models/ViewModels.cs] 中;[PageTitle] 和 [Error] 派生自它们共同的父类 [ViewModel]。[PageTitle] 与所有文本一样,是一个翻译键;
- 第 27 行:所显示日历的地址,不带预约窗口——这是关闭窗口的按钮的地址;
- 第 28 行:给已有即将到来的预约的患者的提示消息:它说明了为什么他们看不到“预约”按钮。
11.16.2.4. POST /schedule/book
- 第 12–13 行:操作上的 [[Authorize(Roles = ...)]] 会叠加到类的 [[Authorize]] 之上:三种角色都可以预约(参见示例 26)。在这里,该特性不施加更多限制;它记录了这条规则,并且在出现第四种角色时能保护该操作;
- 第 15–18 行:预约窗口表单中的字段(参见示例 11)。它们以字符串形式接收,然后被小心地转换;
- 第 20–23 行:医生和日期是表单中的隐藏字段;它们使用户能够返回所显示的日历。如果它们无效,说明请求并非来自我们的页面:而是手工构造的。[BadRequest()] 返回没有内容的 400 响应,由 [UseStatusCodePagesWithReExecute] 中间件将其转换为错误页面(参见示例 24)。[is not int sltId] 与 [is int] 相反:如果值为 [null],则为 true;否则,[sltId] 接收该值;
- 第 27–29 行:对于患者,[clientId] 字段会被忽略——系统始终为患者本人预约。如果依赖浏览器发送的这个字段,恶意患者就可以以他人的名义预约。[Patient.ConnectedPatientAsync](文件夹 [Web])使用令牌识别客户;[nameof(Role.USER)] 就是字符串 ["USER"],由编译器验证;
- 第 33–39 行:没有选择患者的管理者会被重定向到预约窗口(带有 [book] 的 URL),并附带一条弹出的错误消息。[Flash.Put](文件夹 [Web])把消息存储在 [TempData] 中(参见示例 20);
- 第 42–49 行:患者必须存在,时间段也必须存在,并且属于日历中的医生:不能把属于某位医生的时间段预约给另一位医生;
- 第 57–58 行:业务规则(不在过去、时间段可用、每位患者只能有一个即将到来的预约)由业务逻辑层验证,被拒绝时它会抛出 [BusinessException];
- 第 63–65 行:[when] 为 [catch] 添加条件:这是 [C#] 异常过滤器。只有条件为 true 时,这个块才会捕获 [BusinessException]:对于患者,消息“该患者已有预约”会被替换为第二人称的消息。否则,异常会继续传递到下一个 [catch];
- 第 69–71 行:任何其他 [BusinessException] 都会变成闪存消息,连同其键和参数([e.Params] 是只读字典:会为它创建一个副本,类型为 [Flash.Put] 所期望的类型)。其他异常不会被捕获:这些是真正的错误,会导致 500 错误页面;
- 第 74 行:PRG 模式:无论结果如何,都会显示闪存消息,并将用户重定向到日历,由日历显示该消息。在 [NestJS] 版本中,由一个工具函数负责这种业务错误的转换;在这里,两个 [catch] 块就足够了。
11.16.2.5. POST /schedule/cancel
- 第 5–7 行:取消仅限管理员;患者从“我的区域”取消自己的预约(参见 [PatientAreaController])。发送此请求的患者会收到 403 页面;
- 第 9–12 行:与预约时相同的检查;
- 第 14–18 行:已被取消的预约(因双击或由另一位管理员取消)会触发错误消息,而不是错误页面;
- 第 22–25 行:删除,随后是 PRG 模式。
11.16.2.6. 权限与工具函数
- 第 4–12 行:管理员拥有全部权限;患者在没有即将到来的预约时可以预约。命名参数([Manager: true])使对 [record] 构造函数的调用易于阅读;
- 第 18–21 行:读取 POST 表单共有的两个隐藏字段。[out] 参数是方法的额外结果:它返回一个布尔值(字段是否有效?),并通过其 [out] 参数返回转换后的值。这正是 [int.TryParse] 的工作方式;
- 第 24–27 行:医生某一天的日程的 URL,可能带有已打开的预约窗口。所有控制器的重定向都通过此函数生成:页面的 URL 只在一个地方编写;
- 第 30 行:下拉列表选项(ID、标签、选中状态),医生和客户通用:参数的类型为 [Person],即这两个实体的父类。
11.16.3. Controllers/PersonsControllerBase.cs
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 | |
医生和客户的管理是相同的。我们不编写两个相似的控制器,而是在一个抽象的泛型父类中只编写一次它们的操作。我们来说明这段代码:
- 第 15–20 行:医生的路由;在 [/clients] 中也存在相同的路由;
- 第 22–23 行:视图也是共享的(文件夹 [Views/Persons]);
- 第 25–26 行:MVC 只接受具体类作为控制器:只有 [DoctorsController] 和 [ClientsController] 接收请求;
- 第 38–45 行:每个子类提供的配置:基础 URL、文本(翻译键,在 [record] 和 [PersonKeys] 中分组,位于 [Models/ViewModels.cs]),以及用于列出、搜索、添加、修改和删除时要调用的函数。[Func<int, Task<T?>>] 是接受一个 [int] 并返回 [Task<T?>] 的函数的类型:方法就是这样存储在属性中,供以后调用的。[where T : Person] 是对泛型类型的约束:[T] 将是 [Doctor] 或 [Client],即派生自 [Person] 的两个类;因此代码可以使用 [p.FirstName] 或 [p.User],它们对所有人员都是通用的;
- 第 47 行:父类,它是泛型的(参见示例 22 中的 [ViewPage<TModel>] 类)并且是抽象的。它通过主构造函数接收 [ApplicationModel] ,并通过受保护的属性 [Application] ([protected]:只对子类可见)将其传递给子类;
- 第 51 行:抽象属性:每个子类都必须定义它;
- 第 56–69 行:列表。设置在父类方法上的路由特性会被继承:与子类的 [[Route("doctors")]] 结合,得到 [GET /doctors]。对每个人员,模型都包含其“编辑”和“删除”按钮的 URL。[p.User?.Login ?? ""]:关联账户的登录名,如果该人员没有账户则为空字符串;
- 第 60 行:视图通过其完整路径指定。如果只使用名称,MVC 会在控制器的文件夹中查找它([Views/Doctors] 或 [Views/Clients],参见示例 13),而该视图是两者共享的;
- 第 75–76 行:空表单;
- 第 83–98 行:添加,分三步进行,与示例 28 相同。参数 [form] 在调用之前已由 MVC 填充并验证(参见示例 19):无效的输入会重新显示表单,显示已输入的值以及每个错误字段下方的消息;有效的输入会传给业务层,然后浏览器被重定向到列表,并带有闪存消息(PRG);业务层的拒绝(同名、登录名已被使用)会重新显示表单;
- 第 107–121 行:预填充的修改表单。路由约束 [:int] (参见示例 02)只接受整数标识符:[/doctors/abc/edit] 不对应任何路由,结果是 404 页面([ParseIntPipe] 在 [NestJS] 中则会得到 400 错误)。不存在的人员同样得到 404。版本号是表单中的隐藏字段,将用于乐观锁(参见示例 28);
- 第 128–143 行:更新,遵循与插入相同的模式;
- 第 152–165 行:删除。事先检索该人员,以便在确认消息中显示其姓名。业务层的拒绝(例如,医生有预约)会在列表页面上产生闪存错误消息;
- 第 171–188 行:创建时的表单([id] 等价于 [null]),与修改时一样:只有标题和提交地址([Action])不同。[Validation.Prepare](文件夹 [Web])为模板填充各字段的错误消息、页脚消息以及要以红色高亮的字段;
- 第 193–203 行:已被(另一位管理员)删除的人员会再次出现在列表中;其他业务错误会重新显示表单,并带有页脚消息,相关字段以红色高亮([Validation.BusinessErrorFields] 把每个错误代码与其对应的字段关联起来:同名时为 [firstName] 和 [lastName] )。[is "A" or "B"] 把一个值与多个常量进行比较;
- 第 207–213 行:要重新显示的值——绝不包括密码;
- 第 217–224 行:传递给业务层的数据。[!] 字段不会有风险:验证已经确认了这些字段的存在;
- 第 228–230 行:成功消息中的 [{name}] 和 [{login}] 参数:人员的名和姓,以及其登录名。
11.16.4. Controllers/DoctorsController.cs
- 第 20–22 行:仅限 ADMIN。设置在类上的特性适用于它的所有操作,包括继承的操作。该控制器继承自 [PersonsControllerBase<Doctor>]:父类的类型 [T] 变为 [Doctor]。它的主构造函数把 [application] 传递给父类的构造函数。(在 [TypeScript] 中,必须编写显式构造函数,才能让 [NestJS] 知道要注入什么;这里不需要这样做);
- 第 24–34 行:配置。[override] 重新定义父类的抽象属性;[=>] 把它变成计算属性,每次读取时都会创建对象。命名参数([Url:]、[Keys:]……)使这份列表易于阅读;
- 第 35–39 行:要调用的函数,它们是 [ApplicationModel] 的方法。[Application.GetAllDoctorsAsync] 不带括号书写,并不调用该方法:它只是引用该方法,编译器会把它转换为所需类型 [Func] 的值。
11.16.5. Controllers/ClientsController.cs
同样的控制器,用于客户:路由不同,翻译键不同,使用的 [ApplicationModel] 方法也不同。
11.16.6. Controllers/RegistrationController.cs
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 | |
我们来说明这段代码:
- 第 14–24 行:防范机器人,分四步。验证码(CAPTCHA)和尝试次数限制器已在示例 27 中介绍;
- 第 40–45 行:该控制器没有 [[Authorize]] 特性;它的页面对所有人开放。它通过注入接收四个服务;
- 第 51–52 行:登录页面上的“创建患者账户”按钮把登录表单发送到此地址(特性 [formaction];参见示例 20)。只读取验证码字段;
- 第 54 行:浏览器的 IP 地址,通过 [AuthController] 的静态方法获得;
- 第 57–61 行:最近一小时内从此地址创建的账户过多:用户被重定向到登录页面,并显示一条弹出消息,指明需要等待的分钟数。[new() { ["minutes"] = ... }] 创建消息参数字典:其类型由 [Flash.Put] 的参数推断;
- 第 66–70 行:缺失或错误的验证码(CAPTCHA)计为一次失败的登录尝试(用户名为空):机器人无法无限次地尝试。返回登录页面会显示新的图片;
- 第 74–75 行:验证码正确:一张通行证(参见 [Auth/RegistrationPassService.cs])被存储在 Cookie 中,浏览器被重定向到表单;
- 第 81–88 行:表单,只有持有效通行证时才可访问。直接输入地址 [/register] 是没有意义的;
- 第 96–97 行:创建。表单 [RegistrationForm](文件夹 [Models])已由 MVC 绑定并验证;
- 第 99–101 行:再次验证通行证:POST 请求可能是绕过表单发送的;
- 第 104–109 行:出错时要重新显示的值,不含密码。默认称谓为 [Mr];
- 第 113–116 行:时间限制,在创建时再次检查;
- 第 121–128 行:输入错误,逐字段处理(参见示例 19)。密码与其确认密码是否一致——这涉及两个字段——在这里手动验证;只有当这两个字段本身都正确时才会测试。所有错误一并报告:用户可一次性全部更正;
- 第 136–148 行:创建客户及其 USER 账户,使用 ADMIN 所用的业务层方法。如果用户名或名字与姓氏的组合已被占用,则重新显示表单,相关字段以红色高亮;通行证仍然有效;
- 第 152–154 行:通行证已被使用:它在服务器端被消耗,其 Cookie 被删除。要删除 Cookie,必须指定与创建时相同的路径([Path]):通行证 Cookie 只会发送到 [/register...] 的地址。最后,这次创建被计入每小时的限制。
- 第 157–158 行:返回登录页面,用户名已预填,并显示成功消息。[Uri.EscapeDataString] 对用户名进行编码,使其可以包含在 URL 中;
- 第 163 行:从请求的 Cookie 中读取通行证;
- 第 166–169 行:如果没有通行证,则返回登录页面并显示一条消息;
- 第 173–181 行:由 [Validation.Prepare] 准备的表单,与医生和客户的表单相同。[errorParams] 用于页脚消息的参数(分钟数)。
11.16.7. Controllers/PatientAreaController.cs
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 | |
我们来逐段分析这段代码:
- 第 14–17 行:该控制器的黄金法则:所涉及的患者始终是与令牌关联的那一位,绝不是浏览器发送的标识符;
- 第 35–39 行:仅限患者。该控制器没有 [[Route]] 特性:每个操作各自提供其完整地址,因为它们没有共同的前缀([/my-area], [/my-account]);
- 第 44–59 行:“我的区域”页面。[Patient.ConnectedPatientAsync] 根据令牌识别用户;如果其账户在登录后已被删除,则会触发 [InvalidSessionException],由 [Web/HtmlExceptionFilter.cs] 过滤器将其重定向回登录页面。日期由 [WebDates.FormatDay] 根据请求的语言(由本地化中间件设置,参见示例 22)进行格式化;每个预约都包含指向医生当天日程的链接;
- 第 66–82 行:取消患者的预约。[condition ? value1 : value2] 在这里返回该预约,如果 ID 无效则返回 [null]。不存在的预约和属于其他患者的预约(第 73 行)得到相同的响应:不会泄露任何关于其他患者预约的信息;
- 第 88–98 行:账户表单,已预填,带有版本号(乐观锁);
- 第 105–106 行:修改过程,分三步:验证、检查当前密码、业务逻辑;
- 第 109–115 行:出错时要重新显示的值,绝不包括密码;
- 第 118–125 行:输入错误。新密码是可选的(留空:保持不变);只有在输入了确认密码时才会对其进行比较;
- 第 129–138 行:当前密码。[var (key, messageParams) = ...] 解构验证所返回的一对值。错误的密码显示在其字段下方和页面底部;锁定(尝试次数过多)只显示在页面底部,并附带分钟数;
- 第 143–150 行:由业务层执行修改,它适用与 ADMIN 相同的规则(唯一性、乐观锁);
- 第 154 行:令牌包含登录名和显示名称:修改之后会签发新的令牌;否则导航栏会保留旧名称;
- 第 158–160 行:业务层的拒绝会重新显示表单,相关字段以红色高亮;
- 第 169–183 行:删除账户,同样需要当前密码。错误会通过账户页面上的弹出消息指示(PRG);
- 第 180–181 行:删除记录、账户和所有预约(ADMIN 所用的业务层方法),随后退出登录:清除令牌 Cookie;
- 第 190–191 行:验证当前密码。如果密码正确,则返回 [null] ;否则返回一个元组:一对命名值(消息键及其参数)。末尾的 [?] 使这个元组“可为 null”;
- 第 195–198 行:当前密码与登录使用同一个限制器(参见示例 27)。找到一个仍处于打开状态的会话的人,将无法修改密码、删除账户,也无法无限次地尝试密码;
- 第 200–204 行:身份验证过程本身,由 [AuthService] 处理;失败的身份验证尝试计为一次失败的登录尝试;
- 第 209–217 行:账户表单。
11.16.8. Controllers/ErrorController.cs
这是示例 24 中的控制器,消息已翻译:
- 第 23–28 行:每个错误代码的消息键。[static readonly]:只有一个字典,在类加载时创建,且从不被替换;
- 第 30–31 行:缺少 HTTP 方法的 [[Route]] 接受所有方法:重新执行的 POST 请求(例如,患者尝试执行仅限管理员的取消操作)仍然是 POST 请求;
- 第 35–37 行:非错误的 HTTP 代码(手动输入的 [/error/200] 地址)会变成 500 错误;
- 第 39 行:页面保留原始的错误代码;
- 第 40–44 行:页面模板。[GetValueOrDefault] 返回与该代码关联的键,对任何其他代码(尤其是 500)则返回 [ERRORS.SERVER_ERROR]。
11.17. 视图
视图几乎无需做任何决定:它们的模板已由控制器在 [Models/ViewModels.cs] 文件的类中准备好(显示哪些按钮、哪些 URL 元素、哪些翻译键)。每个视图都声明其模板的类型([@model],参见示例 13):[@Model.Xxx] 中的拼写错误会导致编译错误。每个视图还以 [Razor] [@* ... *@] 注释开头,描述其作用;这些注释不会出现在发送给浏览器的页面中。
与第 4 章的示例有一点不同:本案例研究不使用 Tag Helper。分部视图通过 [@await Html.PartialAsync("_Name")] 插入,它等价于示例 15 中的 [<partial name="_Name">] 标记。第二个可选参数提供分部视图的模型;如果省略,分部视图会接收页面的模型。该方法是异步的(分部视图可能需要编译或从磁盘读取):[await] 等待其结果。
11.17.1. 模板与分部视图
11.17.1.1. Views/_ViewImports.cshtml
- 第 9–11 行:视图所使用类型的命名空间:视图模板([RdvMedecins.Models])、闪存消息([RdvMedecins.Web]);
- 第 12 行:所有视图的父类 [Web/ViewPage.cs],与示例 22 中相同。它为视图提供翻译 [@T("KEY")]、语言 [Language]、已登录用户 [CurrentUser]、闪存消息 [FlashMessage]、所请求的路径 [CurrentPath],以及方法 [Active] (导航栏中当前活动的菜单项)。在 [NestJS] 版本中,这些信息是通过 [res.locals] 传递的。这里没有 [@addTagHelper] 指令:应用程序不使用 Tag Helper。
11.17.1.2. Views/_ViewStart.cshtml
- 第 9 行:所有页面都使用 [Views/Shared/_Layout.cshtml] 模板(参见示例 15)。[Handlebars] 会自动使用 [views/layout.hbs];[Razor] 则要求明确指定这一点。
11.17.1.3. Views/Shared/_Layout.cshtml
- 第 20 行:该模板共享页面模型,可通过 [ViewData.Model] 访问(类型为 [object])。所有页面模板都派生自抽象类 [ViewModel],它包含标题键([PageTitle])和页面错误([Error])。如果模板不是 [as ViewModel] ,则返回 [null] ;[ViewModel]:该模板适用于任何页面;
- 第 23 行:页面的语言(参见示例 22);
- 第 27 行:翻译后的标题,例如“Schedule - RdvMedecins”。与示例 22 不同,该键不是由视图在 [ViewData] 中设置的:它由控制器在类型化模型中提供。[page?.PageTitle] 在 [page] 为 [null] 时等于 [null],随后运算符 [??] 会把键替换为 [APP.TITLE];
- 第 28–29 行:样式表,由 [UseStaticFiles] 从 [wwwroot] 文件夹提供:[Bootstrap] ([wwwroot/lib/bootstrap])以及应用程序专用的样式表;
- 第 33–36 行:导航栏、成功消息(在顶部)、所请求的页面([@RenderBody()])和错误区域(在底部);
- 第 39–40 行:确认窗口(隐藏)及其脚本(参见示例 21),加载在页面底部。
11.17.1.4. Views/Shared/_Navbar.cshtml
- 第 12 行:已登录的用户,由 [ViewUser] 类(位于 [Web/ViewPage.cs] 中)描述(登录名、姓名、角色、[IsAdmin], [IsPatient]),由 JWT 令牌派生。在公共页面(登录、创建账户)上它被设置为 [null] ;
- 第 17–31 行:菜单取决于角色:患者看到“我的区域”,ADMIN 看到“医生”和“患者”。这只是为了方便:安全由控制器的 [[Authorize(Roles = ...)]] 特性保证(手动输入 [/doctors] 的患者会收到 403 页面)。[Active("/doctors")] 在所请求的路径以 [active] 开头时返回 [/doctors]:[Bootstrap] 随后高亮该菜单。前缀 [/my-] 涵盖两个患者页面,即 [/my-area] 和 [/my-account];
- 第 34 行:没有菜单时,由一个空块取而代之([me-auto]:自动右边距),使其余内容保持在导航栏的右侧;
- 第 40–41 行:示例 22 中的 FR / EN 链接。表达式 [@( ... )] 用括号括起来,因为其中包含空格(参见示例 14);
- 第 44–52 行:角色、姓名和退出登录按钮,位于 POST 表单中(参见示例 21)。
11.17.1.5. Views/Shared/_Flash.cshtml
- 第 9 行:上一个操作发出的闪存消息(参见示例 20 和 [Web/Flash.cs])。读取闪存消息会将其清除;由于页面读取它两次(在这里和在 [_Errors.cshtml] 中),[Flash] 类在读取后会把它存储在 [HttpContext.Items] 中(参见第 6 章);
- 第 11 行:[flash is { Type: FlashType.Success }] 是一个属性模式:当 [flash] 不是 [null] 并且其属性 [Type] 等于 [FlashType.Success] 时,条件为真。这里只显示成功消息;
- 第 14 行:消息是一个键;其可能的参数([name]、[login]、[minutes])是一个字典,传给 [T] 方法的第二种形式。[role="status"]:屏幕阅读器会在不打断用户的情况下播报该消息。
11.17.1.6. Views/Shared/_Errors.cshtml
- 第 15–18 行:错误的两个来源:所显示页面上的错误(模板的 [Error] 属性:表单被拒绝、密码错误等),以及在重定向之前显示的闪存错误消息(时间段已被预约、删除被拒绝等);
- 第 20–22 行:只要存在其中任何一个,就会显示该区域。[role="alert"]:屏幕阅读器在页面显示后会立即播报该消息,即使它位于底部。类 [error-zone] 定义在 [wwwroot/css/styles.css] 中;
- 第 25 行:运算符 [!] 告知编译器 [page] 不是 [null]:编译器自己无法推断出这一点,尽管它是确定的,因为从 [error] 读取的 [page] 不是 null。
11.17.1.7. Views/Shared/_Confirmation.cshtml
示例 21 中的窗口,其标签由服务器翻译——与页面其余部分一样——并带有无障碍属性:
- 第 16 行:整个页面只有一个窗口,初始时隐藏([d-none]);
- 第 18–19 行:[role="alertdialog"] 表示等待响应的窗口;[aria-modal="true"] 表示页面的其余部分处于非活动状态;[aria-labelledby] 和 [aria-describedby] 指定屏幕阅读器朗读的标题和消息;
- 第 24 行:关闭按钮,表示“否”([data-action="no"])。它没有文本:[aria-label] 为屏幕阅读器提供名称;
- 第 32–33 行:用“否,返回”而不是“取消”:有时问题是“取消此预约?”,在这种情况下“取消”按钮会有歧义。
11.17.1.8. Views/Auth/_Captcha.cshtml
- 第 15 行:该分部视图有自己的模板,即由 [Auth/CaptchaService.cs] 生成的验证码(CAPTCHA)(参见示例 27):其 ID 和图像;
- 第 19 行:SVG 图像原样插入(参见示例 14):它由服务器生成,不含用户的任何输入。[role="img"] 和 [aria-label] 使屏幕阅读器把它当作图像;
- 第 20 行:“换一张图片”只是重新加载当前页面:会生成新的验证码(CAPTCHA);
- 第 22 行:验证码 ID,位于隐藏字段中:它告诉服务器要验证哪个验证码。而正确答案则绝不会离开服务器;
- 第 23–24 行:输入框。[autocomplete="off"]、[autocapitalize="off"] 和 [spellcheck="false"] 可防止浏览器对抄写的字符进行建议、自动大写或纠正。
11.17.1.9. Views/Shared/_PersonFields.cshtml
身份字段(称谓、名、姓),三个表单共用:ADMIN 的医生或客户表单、账户创建表单和患者账户管理表单。
- 第 11 行:[FormView] 是这三个表单模板的(抽象)父类。它包含已输入的值([Values])、每个被拒绝字段的错误消息([Errors])以及要以红色高亮的字段([InvalidFields])。因此该分部视图可以接受这三个页面中每一个的模板;
- 第 14–19 行:称谓列表。[Model.Titles] 返回元组(值,是否选中);[var (value, selected)] 把每个元组分解为两个变量。[selected="@selected"] 是布尔属性,仅当值为 true 时才会写出(参见示例 17)。[InvalidClass("title")] 在字段要以红框标出时返回 [is-invalid] (参见示例 19);
- 第 20–23 行:字段的错误消息(如果有)。[ErrorOf] 返回该消息,或 [null];条件 [is { } titleError] 在值不是 [null] 时为真,然后把它存储在新变量 [titleError] 中;
- 第 26–45 行:名和姓,格式相同,在足够宽的屏幕上并排显示([Bootstrap] 网格:[col-sm-6])。属性 [maxlength] 和 [required] 只是为了方便:插入此分部视图的表单带有属性 [novalidate],验证由服务器处理。
11.17.1.10. Views/Schedule/_Booking.cshtml
- 第 11 行:该分部视图接收日历页面的模板。[Model.Booking!]:只有当 [Booking] 不是 [null] 时,页面才会插入它,运算符 [!] 向编译器断言了这一点;
- 第 15–16 行:模态窗口及其灰色背景所用的 [Bootstrap] 类,被“硬编码”为可见([show d-block]):当 URL 包含参数 [book] 时,服务器决定显示该窗口。[Bootstrap] 的 [JavaScript] 并未被使用(甚至没有加载);
- 第 18 行:窗口的内容就是预约表单本身;
- 第 21 行:关闭窗口会跳转到同一日历的链接,不带 [book] 参数([BackUrl],由控制器准备);
- 第 25 行:“时间段 8:00 - 8:20”:一个翻译参数;
- 第 28–30 行:隐藏字段:除所选患者之外,服务器还需要的附加信息;
- 第 32–48 行:患者看到自己的姓名;管理者(ADMIN、DOCTOR)从列表中选择患者。第一个选项的值为空:配合 [required],浏览器要求必须选择一位真正的患者。[autofocus] 把光标放在列表中;
- 第 52–53 行:“取消”是一个链接,X 也是;“确认”提交表单。
11.17.2. 页面
11.17.2.1. Views/Auth/Login.cshtml
- 第 13 行:失败之后,控制器返回此页面,并带有已输入的用户名;
- 第 20 行:标准的 HTML 表单:浏览器自行提交用户名、密码和验证码(CAPTCHA)答案;
- 第 23–29 行:[autofocus] 是布尔属性:两个字段中只有一个会带有它。光标放在用户名字段中;如果已经知道用户名,则放在密码字段中。[autocomplete] 的值([username]、[current-password])有助于浏览器的密码管理器;
- 第 32 行:验证码(CAPTCHA);第二个参数提供分部视图的模板;
- 第 45–46 行:第二个按钮把同一个表单提交到 [/register/access] (特性 [formaction],参见示例 20):服务器在那里验证验证码(CAPTCHA),然后才打开创建账户页面。[formnovalidate]:浏览器不要求填写用户名和密码,因为创建账户并不需要它们。在字段中按 Enter 键总是会触发表单上的第一个按钮:“登录”;
- 第 51–56 行:演示账户(密码 = 用户名)。
11.17.2.2. Views/Schedule/Schedule.cshtml
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 | |
我们来逐段说明这段代码:
- 第 14–34 行:选择医生和日期:一个 GET 表单(参见示例 17),它会在 URL 中带上 [?doctorId=...&day=...] 重新加载页面。每位医生是一个 [OptionView] ,它指明该医生是否被选中。[type="date"] 字段以 [yyyy-mm-dd] 格式发送日期(参见示例 18);
- 第 37–42 行:给已有即将到来的预约的患者的消息:它说明了为什么没有“预约”按钮;
- 第 45 行:日历(如果被请求)。条件 [is { } schedule] 检查该属性不是 [null] ,并把它的值存储在变量 [schedule] 中;
- 第 48 行:标题:“Schedule for 2026-09-25 – Mme Marie PELISSIER”;
- 第 63 行:可预约的时间段在鼠标悬停时变色(类 [free-slot],参见 [styles.css])。当属性的值为 [null] 时,[Razor] 根本不会写出该属性:其他行没有 [class] 属性;
- 第 69–80 行:三种情形:可预约;已预约,并显示患者姓名(如果是已登录患者的预约则显示为蓝色,[Mine]);已预约但看不到姓名,显示“已预约”。只有在用户有权查看该姓名时,控制器才会填充 [Patient] ;
- 第 85–90 行:“预约”是一个链接:它重新打开此页面,并显示该时间段的预约窗口([BookUrl],由控制器准备);
- 第 91–101 行:“取消”会修改数据:它是带有确认的 POST 表单([data-confirmation],参见示例 21)。隐藏字段 [doctorId] 和 [day] 使控制器能够重定向到同一日历。在循环中,[Model] 始终指向页面模板:不需要 [@root] 或 [Handlebars] 中的对应物;
- 第 110 行和第 116 行:没有可用时间段的医生,或者尚未请求任何日历;
- 第 120–123 行:预约窗口(如果控制器已准备好它)。
11.17.2.3. Views/Persons/List.cshtml
医生和客户共用一个视图:
- 第 8–9 行:每类用户特有的文本以键的形式出现([Model.Keys],类型为 [PersonKeys]),由 [DoctorsController] 或 [ClientsController] 提供:[DOCTORS.TITLE] 或 [CLIENTS.TITLE] 等;
- 第 26–45 行:每人一行,带有两个按钮;
- 第 35 行:“编辑”是指向表单的链接;
- 第 38–41 行:“删除”是带有确认的 POST 表单;
- 第 51 行:“没有医生。”或“没有患者。”
11.17.2.4. Views/Persons/Form.cshtml
我们来逐段说明这段代码:
- 第 17 行:标题(“添加医生”、“编辑患者”等)是页面标题键,由控制器提供;
- 第 22 行:URL 由控制器提供:同一个视图既用于添加也用于编辑医生和客户。[novalidate]:由服务器处理验证(参见示例 19);
- 第 23–25 行:对于编辑,记录版本位于隐藏字段中:这就是示例 28 中的乐观锁;
- 第 29 行:身份字段;
- 第 34–44 行:登录名,带有错误消息,如果没有错误则带有帮助文本。帮助文本因是添加还是编辑而不同(“可选:默认为小写的姓氏。”);
- 第 48–59 行:密码,从不预填;它绝不会回传给浏览器。[autocomplete="new-password"]:浏览器不会建议管理员已保存的密码。长度限制为 72 个字符,因为 [bcrypt] 算法会忽略其后的字符;
- 第 64 行:返回列表的链接是一个超链接。
11.17.2.5. Views/Registration/Registration.cshtml
创建客户账户,公共页面。这里没有验证码(CAPTCHA):只有在登录页面输入了验证码之后才能到达此页面。
- 第 17 行:与 ADMIN 表单相同的身份字段;
- 第 22–32 行:用户名,这次是必填的;
- 第 37–47 行:帮助文本和“太短”消息带有参数 [{min}],即由模板提供的密码最小长度([PasswordMin])。不带参数 [{min}] 的消息会直接忽略所提供的值;
- 第 50–56 行:确认密码;
- 第 62 行:返回登录页面。
11.17.2.6. Views/PatientArea/Area.cshtml
- 第 8 行:“Hello Mr Jean MARTIN”;
- 第 12–21 行:两个选项都是链接,显示为卡片(类 [option-card],参见 [styles.css]);
- 第 31–46 行:即将到来的预约(通常只有一个)。在 [@if] 块内,格式是 [C#]:[for] 循环不带 [@] 书写。边框([border-bottom])把各个预约隔开,最后一个之后除外;
- 第 40–44 行:取消,带有确认的 POST 表单。
11.17.2.7. Views/PatientArea/Account.cshtml
- 第 16–76 行:账户修改:身份、登录名、新密码(可选)及其确认;
- 第 17 行:客户记录的版本(乐观锁);
- 第 59–69 行:当前密码,任何修改都需要它;
- 第 83–91 行:删除,带有确认。同一页面上有两个相互独立的表单:每个表单只提交自己的字段。因此密码字段在这里有不同的名称([deletePassword])和不同的标识符。这个表单没有 [novalidate] 属性:浏览器甚至在触发 [required] 之前,即在询问确认问题之前,就要求填写密码([submit] 事件)。
11.17.2.8. Views/Shared/Error.cshtml
- 第 9–10 行:由 [ErrorController] 生成的错误页面(400、403、404、500):HTTP 代码和翻译后的消息。它存放在 [Views/Shared] 中,无论哪个控制器请求它,都能找到它。
11.18. 字典
字典与 [NestJS] 版本中的相同,没有任何改动:它们由 [Translator] 服务读取(参见示例 22)。
11.18.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])对文本进行分组。有些名称([DOCTOR_DAY_PICKER]、[BOOKING_DIALOG])对应 [Angular] 客户端的组件,其字典由 [NestJS] 版本继承而来;
- 第 80 行:带有两个参数的文本,[{name}] 和 [{login}],它们在翻译时被替换;
- 第 98–136 行:错误消息。这些是业务层中的 [BusinessException] 组件、表单验证特性([ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED"])、控制器和异常过滤器所使用的键。其中三个带有参数:[{minutes}] 和 [{min}]。
11.18.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.19. 静态文件
[wwwroot] 文件夹由 [UseStaticFiles] 提供(参见示例 15)。[wwwroot/lib/bootstrap] 文件夹包含 [Bootstrap] (其样式表 [css/bootstrap.min.css] 及其许可证),这些内容不予展示。
11.19.1. wwwroot/css/styles.css
- 第 10–12 行:可预约的时间段在鼠标悬停时变色;
- 第 23–33 行:错误区域,背景为浅粉色。[position: sticky] 和 [bottom: 1rem]:如果页面比窗口高,该区域会保持在窗口底部,而不是滚出屏幕;[z-index] 把它置于预约窗口的灰色背景之上;
- 第 36–43 行:“我的区域”的两个选项会对鼠标悬停作出响应;
- 第 46–50 行:验证码(CAPTCHA)图像的边框。
11.19.2. wwwroot/js/app.js
示例 21 中确认窗口的脚本,增加了键盘处理。它遵循同样的渐进增强原则:没有 [JavaScript] 时,表单会不经确认直接提交,应用程序仍然可以正常工作。
- 第 16–19 行:没有确认窗口的页面无事可做;
- 第 24 行:窗口打开之前拥有键盘焦点(接收按键的元素)的元素:窗口关闭时,焦点会返回到它;
- 第 26–35 行:焦点放在“否,返回”上;意外按下 Enter 键不会删除任何内容;
- 第 37–43 行:窗口被隐藏,焦点被恢复;
- 第 46–51 行:我们拦截带有属性 [data-confirmation] 的表单的提交,与示例 21 中一样;
- 第 54–67 行:“是”、“否”、关闭按钮,以及点击窗口外部。[closest('[data-action]')] 会找到包含该属性的元素,即使点击的是其内部的元素。当找不到元素时,运算符 [?.] 返回 [undefined] 而不是失败;
- 第 71–86 行:Esc 键关闭窗口;Tab 键(以及 Shift+Tab)使焦点在窗口内的按钮之间循环,而不是移到其后变灰的页面上。