8. RdvMedecins 服务器,一个黑盒
示例 22 至 25 以及随后的案例研究都要与一台服务器交互:即 [RdvMedecins] 应用的 JSON 服务器。它就是 [NestJS] 服务器,供 [React]、[Vue.js] 和 [Angular] 课程使用:这是 [NestJS] 课程的服务器,它的控制器不再生成 HTML 页面,而是生成 JSON 响应。这些课程的读者已经熟悉本章内容,本章在此几乎原样重现;他们只需关注身份验证一节,其中说明了移动应用有哪些不同。
在本课程中,这台服务器是一个黑盒:你不需要知道它是怎么写的。重要的只是它的 API——也就是它接受的 HTTP 请求列表及其返回的响应。这是客户端开发者的典型处境:API 是一份契约,服务器团队可以在契约背后随意更改。为好奇的读者提供了它的源代码([rdvmedecins-nestjs-json] 文件夹),并附有大量注释。
本章说明如何安装服务器,描述它的 API,并用 [curl] 来查询它。
8.1. RdvMedecins 应用
该应用用于管理一家医疗诊所的预约。它有三种角色:
角色 | 身份 | 可执行的操作 |
[ADMIN] | 管理员([admin]) | 为所有患者安排和取消预约;管理医生和客户 |
[DOCTOR] | 医生([pelissier]、[tatou]、[dupont]) | 为所有患者安排和取消预约;在日程中查看所有姓名 |
[USER] | 患者([martin]、[durand]、[bistrou]、[german]) | 为自己预约;取消自己的预约;管理自己的账户。在日程中,他们看不到其他患者的姓名 |
演示账户以其登录名作为密码。管理规则由服务器验证,与客户端无关:
- 不能预约过去的时间;
- 每位患者只能有一个即将到来的预约;
- 同一天内,一个时间段只能被预约一次;
- 两位医生(或两位客户)不能有相同的名和姓;一个登录名只属于一个账户;
- 有预约的医生不能被删除;
- 如果某条记录在此期间已被其他人修改,则不能覆盖它(乐观锁);
- 患者绝不会被分配到另一位患者的姓名。
8.2. 安装
你需要 [Node.js] 和一台 [MySQL] (或 [MariaDB])服务器:它们的安装方法见附录。
- 数据库。脚本 [database/dbrdvmedecins2.sql] 会创建数据库 [dbrdvmedecins2]、它的表以及示例数据。使用 [Laragon] 时,在 [HeidiSQL] 中运行它(File 菜单 / Run a SQL file);在命令行中:
该脚本总是从空数据库开始:你可以重新运行它来恢复初始数据。
- 库。在打开到 [rdvmedecins-nestjs-json] 文件夹的控制台窗口中:
- 配置。把文件 [.env.example] 复制为 [.env] (在 [Windows] 下:[copy .env.example .env]),然后修改它:
- 第 8 行:服务器监听 8080 端口;
- 第 12–16 行:到 [MySQL] 的连接。使用 [Laragon] 时,用户 [root] 没有密码:默认值即可;
- 第 25 行:为身份验证令牌签名的密钥;
- 第 38–45 行:反机器人措施(多次登录失败后锁定、每小时创建的账户数量);
- 第 51 行:验证码测试模式。登录页面要求你输入图片中的字符,而这在控制台中是不可能的。如果这个变量有值,那么该值会被接受为任何验证码的答案,类似于 [Google] 为其 [reCAPTCHA] 提供的“测试密钥”。在本章中使用 [curl] 进行测试时,请填入 [CAPTCHA_TEST=test]。生成本课程截图的自动化测试也使用这个值。在生产环境中务必让它为空;
- 第 57–59 行:生产环境的两项设置(见“部署”一章)。
- 启动。
控制台显示(节选):
如果数据库无法访问([MySQL] 服务器已停止、密码错误),服务器会立即停止,并显示连接错误消息。
8.3. 响应格式
所有 URL 都以 [/api] 开头。成功的请求会收到 2xx 状态码,并在响应体中得到 JSON 格式的所请求数据。被拒绝的请求会收到 4xx 或 5xx 状态码,并在响应体中得到一个始终具有相同格式的对象:
- [statusCode]:HTTP 状态码,在响应体中重复一遍;
- [key]:消息的翻译键。服务器从不返回要显示的文本:它不再知道用户的语言。由客户端使用其字典来翻译这个键(见示例 21);
- [params] (可选):消息的参数([At least {min} characters], [Try again in {minutes} minute(s)]);
- [fields] (可选):对于被拒绝的表单,给出每个字段的错误。
使用的状态码:
状态码 | 含义 | 键的示例 |
400 | 无效请求 | [ERRORS.INVALID_FORM] (+ fields),[ERRORS.INVALID_DATE]、[ERRORS.WRONG_CAPTCHA]、[ERRORS.CHOOSE_PATIENT]、[ERRORS.WRONG_CURRENT_PASSWORD]、[ERRORS.BAD_REQUEST]…… |
401 | 未通过身份验证 | [ERRORS.AUTH_REQUIRED] (无令牌),[ERRORS.SESSION_EXPIRED] (令牌无效或已过期),[LOGIN.ERROR] |
403 | 拒绝访问 | [ERRORS.FORBIDDEN] (角色权限不足),[ERRORS.CAPTCHA_BEFORE_ACCOUNT] (没有通行证) |
404 | 未找到 | [ERRORS.NOT_FOUND]、[ERRORS.DOCTOR_NOT_FOUND]、[ERRORS.APPOINTMENT_NOT_FOUND]…… |
409 | 违反业务规则 | [ERRORS.PAST_DATE]、[ERRORS.SLOT_ALREADY_BOOKED]、[ERRORS.LOGIN_TAKEN]、[ERRORS.CONCURRENT_UPDATE]…… |
415 | POST 请求的内容不是 JSON | [ERRORS.JSON_REQUIRED] |
429 | 尝试次数过多 | [ERRORS.TOO_MANY_ATTEMPTS]、[ERRORS.TOO_MANY_ACCOUNTS] (+ params.minutes) |
500 | 服务器错误 | [ERRORS.SERVER_ERROR] |
8.4. 身份验证
客户端使用 [POST /api/auth/login] 进行身份验证,提交用户名、密码和验证码答案。作为回应,服务器在其响应的 [Set-Cookie] 头中发送一个 Cookie,其中包含一个已签名的 JWT 令牌:
此后,客户端必须在发往 [Cookie] 头的每个 [/api] 请求中都带上这个 Cookie:服务器正是以此得知是谁在发出请求。
这台服务器是为 Web 客户端设计的,其设计选择受 Web 浏览器特有风险的驱动:
- [HttpOnly]:页面的代码([JavaScript])无法读取这个 Cookie。因此,注入页面中的恶意脚本无法窃取令牌。对客户端的影响:它无法自行判断自己是否已登录。它要询问服务器([GET /api/auth/me]);
- [Path=/api]:Cookie 只会包含在发往 API 的请求中;
- [SameSite=Strict]:浏览器只会把 Cookie 附加到发往本站页面的请求上。另一个站点上的恶意页面无法让浏览器代表用户执行操作(即所谓的 CSRF 攻击);
- [Max-Age=7200]:它在两小时后过期,与令牌过期的时间相同。
针对 CSRF 攻击的第二重保障:服务器会拒绝(415)任何请求体不是 JSON 的 POST 请求。另一个站点上被入侵的 HTML 表单无法发送 JSON。
那么移动应用呢?这里没有浏览器:没有谁会自行存储 Cookie 或把它发回去。应用将承担这一角色:读取响应中的 [Set-Cookie] 头,并在请求中写入 [Cookie] 头(示例 23)。属性 [HttpOnly] 和 [SameSite] 只适用于浏览器:它们对应用没有影响,就像对 [curl] 没有影响一样。不过,同一个 [Flutter] 应用在编译为 Web 版本时,其工作方式会和浏览器一样:Cookie 由浏览器管理,前提是应用和 API 同源(见示例 22 和“部署”一章)。
8.5. API
方法 | 地址 | 角色 | 发送的内容/响应体 |
GET | [/api/captcha] | 公开 | 响应:[{ id, svg }] |
POST | [/api/auth/login] | 公开 | [{ login, password, captchaId, captcha }];响应:[{ login, name, role }] + Cookie |
POST | [/api/auth/logout] | 公开 | [{}] ;删除 Cookie |
GET | [/api/auth/me] | 已登录 | 响应:[{ login, name, role }] |
GET | [/api/schedule?doctorId=&day=] | 所有角色 | 响应:日程(未提供 doctorId 时:对于 DOCTOR,是他自己的日程) |
POST | [/api/appointments] | 所有角色 | [{ day, slotId, clientId }](对于 USER,clientId 被忽略);201 |
DELETE | [/api/appointments/:id] | 所有角色 | USER 只能取消自己的预约 |
GET | [/api/doctors] | 所有角色 | 列表(对于 ADMIN,包含登录名) |
GET | [/api/clients] | ADMIN, DOCTOR | 列表(对于 ADMIN,包含登录名) |
GET | [/api/doctors/:id]、[/api/clients/:id] | ADMIN | 一条记录 |
POST | [/api/doctors]、[/api/clients] | ADMIN | [{ title, firstName, lastName, login?, password? }];201 |
PUT | [/api/doctors/:id]、[/api/clients/:id] | ADMIN | [{ title, firstName, lastName, login?, password?, version }] |
DELETE | [/api/doctors/:id]、[/api/clients/:id] | ADMIN | 响应:[{}] |
POST | [/api/register/access] | 公开 | [{ captchaId, captcha }];签发一个令牌(Cookie) |
GET | [/api/register/access] | 公开 | 响应:[{ valid }] |
POST | [/api/register] | 公开 + 通行证 | [{ title, firstName, lastName, login, password, confirmation }];201 |
GET | [/api/my-area] | USER | 响应:[{ patient, appointments }] |
GET | [/api/my-account] | USER | 响应:[{ title, firstName, lastName, login, version }] |
PUT | [/api/my-account] | USER | [{ title, firstName, lastName, login, password?, confirmation?, currentPassword, version }] |
DELETE | [/api/my-account] | USER | [{ currentPassword }];删除账户及其预约 |
日程条目([GET /api/schedule])描述一个时间段,以及已登录用户被授权对它执行的操作:
- [free]:该时间段在当天是否可预约?
- [patient]:预约所属的患者。对于已登录的患者,除了他自己的预约之外,这个值都等于 [null]:其他患者的姓名绝不会被发送;
- [mine]:这是已登录患者自己的预约;
- [bookable]:用户能否预约这个时间段(可预约、不在过去,并且对于患者而言没有即将到来的预约)?
- [appointmentId]:如果用户可以取消这个预约,就会填写。
服务器负责决定;客户端负责显示。即使客户端作弊(在不该显示时显示“预约”按钮),服务器在预约时也会再次核查一切。
8.6. 使用 curl 查询 API
服务器上的 [curl] 文件夹包含本章的 JSON 请求体,每个请求一个文件。例如 [curl/login-admin.json]:
命令在打开到 [rdvmedecins-nestjs-json] 目录的控制台中输入。[curl] 的一些选项:
- [-i]:同时显示响应头;[-s]:不显示进度条;
- [--json @file]:用 POST 发送文件的内容,并带上头 [Content-Type: application/json] (curl 7.82 及更高版本;对于较旧的版本,请使用 [-H "Content-Type: application/json" -d @file]);
- [-X PUT]、[-X DELETE]:HTTP 方法;
- [-c cookies.txt]:把收到的 Cookie 保存到这个文件中;[-b cookies.txt]:把它们再发回去。[curl] 就是这样像浏览器一样在命令之间“保持登录”的。
在 [PowerShell] 下,必须输入 [curl.exe] 而不是 [curl] (在那里它指的是另一个命令)。JSON 的响应有些冗长,已在本文档中格式化,并且 [Date]、[ETag]、[Connection],和 [Keep-Alive] 这些头已被删除。
8.6.1. 登录
首先是验证码(图片已裁剪):
没有令牌时,受保护的 URL 会返回 401 响应:
先输入错误的验证码,再输入错误的密码:
登录成功后会设置 Cookie,[curl] 把它存储在 [cookies.txt] 中:
有了这个 Cookie,服务器就知道我们是谁:
伪造的(或已过期的)令牌会导致会话过期,服务器会指示浏览器删除该 Cookie:
8.6.2. 医生、客户、日程
ADMIN 看到的医生列表(包含登录名):
PELISSIER 医生 2030 年 1 月 15 日的日程:
一个不存在的日期:
8.6.3. 预约
ADMIN 为 2 号患者(Alice DURAND)预约 3 号时间段。请求体:
日程现在显示了这个预约,以及患者的姓名和取消它的方法([appointmentId]):
再试一次:该患者已经有一个即将到来的预约。过去的预约也会被拒绝:
标准的 HTML 表单(这里用 [-d] 模拟,它发送 [application/x-www-form-urlencoded])会被拒绝:
8.6.4. 患者视角
你先退出登录,然后以 [martin] 身份登录:
同一份日程,在患者看来是这样的:3 号时间段被占用(["free": false]),但 ["patient"] 等于 [null]:Alice 的姓 DURAND 没有被发送:
患者无权访问客户列表:
他为自己预约(请求体中不包含 [clientId]),预约一次,而不是两次:
他的个人区域:
他不能取消另一位患者的预约。服务器的响应是“未找到”,就像对待一个不存在的预约一样:它不会透露任何关于其他患者预约的信息:
取消他自己的预约则可以:
8.6.5. 医生视角
不带 [doctorId] 时,已登录的医生会收到他自己的日程,其中包含所有姓名:
他不能管理医生:
8.6.6. 管理医生和客户(ADMIN)
添加。如果缺少登录名,则默认使用小写形式的名字;密码与登录名相同:
无效的请求体:响应列出每个字段的错误:
同名者:受影响的两个字段都会被标出:
修改。[version] 是从记录中读取的值(这里是 1):
该记录现在是版本 2。再次提交相同的修改(带版本 1)会覆盖一条此后已被其他人修改过的记录:乐观锁会阻止这种情况:
有预约的医生不能被删除;其他医生可以:
8.6.7. 创建账户
没有通行证,就无法创建:
首先,你要解答一个验证码;服务器会在 Cookie 中签发一个有效期为 15 分钟的令牌:
确认密码必须与密码相同:
通行证已被使用:它不能用来创建第二个账户:
8.6.8. 管理你的账户
新患者登录并读取她的账户记录:
进行修改需要当前密码。服务器会签发一个新令牌,其中包含新的姓名:
删除账户的同时也会删除 Cookie:
8.6.9. 一些错误
一个未知的路由,一个不是有效 JSON 的请求体:
现在,我们已经了解了编写客户端所需知道的关于服务器的一切。