Skip to content

8. RdvMedecins 服务器,一个黑盒

示例 22 到 25 以及案例研究都要与服务器交互:即 [RdvMedecins] 应用的 JSON 服务器。它就是 [NestJS] 服务器,用于课程 [React]、[Vue.js]、[Angular] 和 [Flutter]:即 [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])服务器:它们的安装在附录中说明。

  1. 数据库。[database/dbrdvmedecins2.sql] 脚本会创建 [dbrdvmedecins2] 数据库、它的表以及示例数据。使用 [Laragon] 时,在 [HeidiSQL] 中运行它(File 菜单 / Run a SQL file);在命令行中:
mysql -u root -p < database/dbrdvmedecins2.sql

该脚本总是从一个空数据库开始:你可以重新运行它来恢复初始数据。

  1. 库。在打开到 [rdvmedecins-nestjs-json] 文件夹的控制台窗口中:
npm install
  1. 配置。将文件 [.env.example] 复制为 [.env] (在 [Windows] 下:[copy .env.example .env]),然后修改它:
# -----------------------------------------------------------------------
# 示例配置文件。
# 将此文件复制为 [.env],然后根据你的机器调整其中的值。
# [.env] 文件绝不能被共享或提交(其中有密码)。
# -----------------------------------------------------------------------

# JSON 服务器的监听端口
PORT=8080

# MySQL 数据库 [dbrdvmedecins2] 的连接参数
# (脚本:database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# true:在控制台中显示发送给 MySQL 的 SQL 查询
DB_LOGGING=false

# -----------------------------------------------------------------------
# 身份验证
# -----------------------------------------------------------------------
# 用于签署/验证 JWT 令牌的密钥:必须更改
# 在生产环境中(一个长的随机字符串,绝不提交)。
JWT_SECRET=change-me-to-a-long-random-string
# JWT 令牌的有效期,以秒为单位(7200 秒 = 2 小时)。携带令牌的
# Cookie 具有相同的生存期。
JWT_EXPIRES_IN_SECONDS=7200
# 在生产环境中设为 true(站点通过 HTTPS 提供服务):这样身份验证
# Cookie 就永远不会通过未加密的连接发送。
COOKIE_SECURE=false

# -----------------------------------------------------------------------
# 防范机器人
# -----------------------------------------------------------------------
# 登录:允许的失败次数(验证码或密码错误),针对
# 来自同一 IP 地址的同一登录名,超过后这一对组合就会被封锁……
LOGIN_MAX_FAILURES=5
# ……持续这么长时间(如果一个 IP 地址累计的失败次数达到其 5 倍,
# 也会被封锁,所有登录名合并计算)
LOGIN_BLOCK_MINUTES=15
# 客户账户创建:每小时最多创建的账户数量,
# 来自同一 IP 地址。在教室里,所有电脑往往通过
# 同一个地址出去:如有需要请增大。
REGISTRATION_MAX_PER_HOUR=10

# 验证码测试模式:如果该变量有值,那么该值会被
# 接受为任何验证码的答案。便于使用 curl 查询
# API(你无法在控制台中“读取”图像)。
# 在生产环境中请留空。
CAPTCHA_TEST=

# -----------------------------------------------------------------------
# 生产环境
# -----------------------------------------------------------------------
# 已编译 Web 客户端的文件夹,由本服务器提供服务(默认:client/)
# CLIENT_DIR=client
# 如果服务器位于代理之后(nginx 等),则设为 true
TRUST_PROXY=false
  • 第 8 行:服务器监听 8080 端口;
  • 第 12–16 行:到 [MySQL] 的连接。使用 [Laragon] 时,用户 [root] 没有密码:默认值即可;
  • 第 25 行:用于签署身份验证令牌的密钥;
  • 第 38–45 行:反机器人保护(多次登录失败后锁定、每小时创建账户的数量);
  • 第 51 行:验证码(CAPTCHA)测试模式。登录页面要求用户重新输入图像中的字符,这在控制台中是不可能做到的。如果该变量有值,那么该值会被接受为任何验证码的答案,就像 [Google] 为其 [reCAPTCHA] 提供的“测试密钥”一样。对于本章中使用 [curl] 进行的测试,请输入 [CAPTCHA_TEST=test]。生成本课程截图的自动化测试也使用这个值。在生产环境中请将其留空;
  • 第 57–59 行:用于生产环境的两项设置(见“部署”一章)。

  • 启动。

npm run start:dev

控制台显示(节选):

1
2
3
4
5
6
7
8
[Nest] LOG [NestFactory] Starting Nest application...
[Nest] WARN [RdvMedecins] captcha TEST MODE active (CAPTCHA_TEST in .env): never use it in production
[Nest] LOG [RoutesResolver] ScheduleController {/api/schedule}:
[Nest] LOG [RouterExplorer] Mapped {/api/schedule, GET} route
[Nest] LOG [RoutesResolver] AppointmentsController {/api/appointments}:
...
[Nest] LOG [NestApplication] Nest application successfully started
[Nest] LOG [RdvMedecins] JSON server started: http://localhost:8080/api

如果数据库无法访问([MySQL] 服务器已停止、密码不正确),服务器会立即停止,并显示连接错误消息。

8.3. 响应格式

所有 URL 都以 [/api] 开头。成功的请求会收到 2xx 状态码,并在响应体中收到 JSON 格式的所请求数据。被拒绝的请求会收到 4xx 或 5xx 状态码,并在响应体中收到一个始终遵循相同格式的错误:

1
2
3
4
5
6
{
  "statusCode": 400,
  "key": "ERRORS.INVALID_FORM",
  "params": { "min": "6" },
  "fields": { "lastName": "ERRORS.LASTNAME_REQUIRED", "password": "ERRORS.PASSWORD_TOO_SHORT" }
}
  • [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
请求体不是 JSON 的 POST
[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 令牌:

Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; HttpOnly; SameSite=Strict

此后,客户端必须在每个发往 [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 或将其发回。应用将承担这个角色:[OkHttp] 库被委托持有一个“Cookie 罐”([CookieJar]),它从响应中读取 [Set-Cookie] 头,并在请求中写入 [Cookie] 头(示例 23)。[HttpOnly] 和 [SameSite] 这两个属性只适用于浏览器:它们对应用没有任何影响,就像对 [curl] 没有影响一样。

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 带有 login)
GET
[/api/clients]
ADMIN、DOCTOR
列表(对 ADMIN 带有 login)
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])描述一个时间段,以及已登录用户被授权对它执行的操作:

1
2
3
4
{ "id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0,
  "free": false,
  "patient": { "title": "Mme", "firstName": "Alice", "lastName": "DURAND" },
  "mine": false, "bookable": false, "appointmentId": 2 }
  • [free]:该时间段在当天是否可预约?
  • [patient]:该预约的患者。对于已登录的患者,除了他自己的预约之外,这个值都等于 [null] :其他患者的姓名从不会被发送;
  • [mine]:这是已登录患者自己的预约;
  • [bookable]:用户能否预约该时间段(可预约、不在过去,并且对于患者而言没有未来的预约)?
  • [appointmentId]:如果用户可以取消该预约,则会填入。

由服务器做决定;客户端负责显示。即使客户端作弊(在不该显示时显示了“预约”按钮),服务器在预约时也会再次核对一切。

8.6. 使用 curl 查询 API

服务器目录 [curl] 包含本章各个请求的 JSON 请求体,每个请求一个文件。例如 [curl/login-admin.json]:

{ "login": "admin", "password": "admin", "captchaId": "-", "captcha": "test" }

命令在 [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. 登录

首先是验证码(图像已裁剪):

1
2
3
4
5
6
7
$ curl -i http://localhost:8080/api/captcha
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json; charset=utf-8
Content-Length: 11081

{"id": "e347ae38-79ff-4dea-8d6e-19610a7d69a7", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}

没有令牌时,受保护的 URL 会返回 401 响应:

1
2
3
4
5
6
$ curl -i http://localhost:8080/api/doctors
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47

{"statusCode": 401, "key": "ERRORS.AUTH_REQUIRED"}

验证码错误,接着是密码错误:

1
2
3
4
5
6
$ curl -i --json @curl/login-wrong-captcha.json http://localhost:8080/api/auth/login
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 91

{"statusCode": 400, "key": "ERRORS.WRONG_CAPTCHA", "fields": {"captcha": "ERRORS.WRONG_CAPTCHA"}}
1
2
3
4
5
6
$ curl -i --json @curl/login-wrong-password.json http://localhost:8080/api/auth/login
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 38

{"statusCode": 401, "key": "LOGIN.ERROR"}

登录成功会设置 Cookie,[curl] 将其存入 [cookies.txt]:

1
2
3
4
5
6
7
$ curl -i -c cookies.txt --json @curl/login-admin.json http://localhost:8080/api/auth/login
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Mon, 28 Sep 2026 12:49:12 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 55

{"login": "admin", "name": "Administrator", "role": "ADMIN"}

有了这个 Cookie,服务器就知道我们是谁:

1
2
3
4
5
6
$ curl -i -b cookies.txt http://localhost:8080/api/auth/me
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 55

{"login": "admin", "name": "Administrator", "role": "ADMIN"}

伪造的(或已过期的)令牌会导致会话过期,服务器会指示浏览器删除该 Cookie:

1
2
3
4
5
6
7
$ curl -i -b "rdvmedecins_jwt=abc.def.ghi" http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 49

{"statusCode": 401, "key": "ERRORS.SESSION_EXPIRED"}

8.6.2. 医生、客户、日程

ADMIN 看到的医生列表(带登录名):

$ curl -i -b cookies.txt http://localhost:8080/api/doctors
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 282

[
  {"id": 3, "version": 0, "title": "Melle", "firstName": "Sophie", "lastName": "DUPONT", "login": "dupont"},
  {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER", "login": "pelissier"},
  {"id": 2, "version": 0, "title": "Mr", "firstName": "Paul", "lastName": "TATOU", "login": "tatou"}
]

PELISSIER 医生在 2030 年 1 月 15 日的日程:

$ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

一个不存在的日期:

1
2
3
4
5
6
$ curl -i -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-02-30"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 46

{"statusCode": 400, "key": "ERRORS.INVALID_DATE"}

8.6.3. 预约

ADMIN 为 2 号患者(Alice DURAND)预订 3 号时间段。请求体:

{ "day": "2030-01-15", "slotId": 3, "clientId": 2 }
1
2
3
4
5
6
$ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51

{"id": 2, "day": "2030-01-15", "slotId": 3, "clientId": 2}

现在日程中显示了这个预约,以及患者的姓名和取消它的方法([appointmentId]):

$ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": {"title": "Mme", "firstName": "Alice", "lastName": "DURAND"}, "mine": false, "bookable": false, "appointmentId": 2},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

再试一次:该患者已经有一个未来的预约。过去的预约同样会被拒绝:

1
2
3
4
5
6
$ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 66

{"statusCode": 409, "key": "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT"}
1
2
3
4
5
6
$ curl -i -b cookies.txt --json @curl/appointment-past.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 43

{"statusCode": 409, "key": "ERRORS.PAST_DATE"}

标准的 HTML 表单(这里用 [-d] 模拟,它发送 [application/x-www-form-urlencoded])会被拒绝:

1
2
3
4
5
6
$ curl -i -b cookies.txt -d "day=2030-01-15&slotId=4&clientId=2" http://localhost:8080/api/appointments
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json; charset=utf-8
Content-Length: 47

{"statusCode": 415, "key": "ERRORS.JSON_REQUIRED"}

8.6.4. 患者的视角

你先退出登录,然后以 [martin] 身份登录:

1
2
3
4
5
6
7
$ curl -i -b cookies.txt -c cookies.txt --json @curl/empty.json http://localhost:8080/api/auth/logout
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}
$ curl -s -c cookies-martin.txt --json @curl/login-martin.json http://localhost:8080/api/auth/login
{"login": "martin", "name": "Jean MARTIN", "role": "USER"}

患者看到的同一份日程:3 号时间段已被占用(["free": false]),但 ["patient"] 等于 [null]:Alice 的姓 DURAND 并没有被发送:

$ curl -s -b cookies-martin.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": null, "mine": false, "bookable": false, "appointmentId": null},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

患者无权访问客户列表:

1
2
3
4
5
6
$ curl -i -b cookies-martin.txt http://localhost:8080/api/clients
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43

{"statusCode": 403, "key": "ERRORS.FORBIDDEN"}

他为自己预订该时间段(请求体中不含 [clientId]),只能预订一次,不能预订两次:

{ "day": "2030-01-15", "slotId": 5 }
1
2
3
4
5
6
$ curl -i -b cookies-martin.txt --json @curl/appointment-martin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51

{"id": 3, "day": "2030-01-15", "slotId": 5, "clientId": 1}
1
2
3
4
5
6
$ curl -i -b cookies-martin.txt --json @curl/appointment-martin-2.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 55

{"statusCode": 409, "key": "SCHEDULE.ALREADY_BOOKED_INFO"}

他的个人区域:

$ curl -s -b cookies-martin.txt http://localhost:8080/api/my-area
{
  "patient": {"title": "Mr", "firstName": "Jean", "lastName": "MARTIN"},
  "appointments": [
    {
      "id": 3,
      "day": "2030-01-15",
      "slot": {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40},
      "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"}
    }
  ]
}

他不能取消另一位患者的预约。服务器返回“未找到”,就像对一个不存在的预约一样:它不会泄露任何关于其他患者预约的信息:

1
2
3
4
5
6
$ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/2
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 55

{"statusCode": 404, "key": "ERRORS.APPOINTMENT_NOT_FOUND"}

他自己的预约则可以:

1
2
3
4
5
6
$ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}

8.6.5. 医生的视角

不带 [doctorId] 时,已登录的医生会收到他自己的日程,其中包含所有姓名:

$ curl -s -b cookies-pelissier.txt "http://localhost:8080/api/schedule?day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": {"title": "Mme", "firstName": "Alice", "lastName": "DURAND"}, "mine": false, "bookable": false, "appointmentId": 2},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": false, "patient": {"title": "Mr", "firstName": "Jean", "lastName": "MARTIN"}, "mine": false, "bookable": false, "appointmentId": 3},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

他不能管理医生:

1
2
3
4
5
6
$ curl -i -b cookies-pelissier.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43

{"statusCode": 403, "key": "ERRORS.FORBIDDEN"}

8.6.6. 管理医生和客户(ADMIN)

添加。如果缺少登录名,默认使用小写的姓名;密码即登录名:

{ "title": "Mme", "firstName": "Claire", "lastName": "LEROY" }
1
2
3
4
5
6
$ curl -i -b cookies.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 90

{"id": 4, "version": 1, "title": "Mme", "firstName": "Claire", "lastName": "LEROY", "login": "leroy"}

无效的请求体:响应会列出每个字段的错误:

{ "title": "Dr", "firstName": "", "lastName": "A-LAST-NAME-FAR-TOO-LONG-FOR-THE-DB", "login": "Claire L" }
$ curl -i -b cookies.txt --json @curl/doctor-invalid.json http://localhost:8080/api/doctors
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 218

{
  "statusCode": 400,
  "key": "ERRORS.INVALID_FORM",
  "params": {"min": "6"},
  "fields": {"login": "ERRORS.INVALID_LOGIN", "title": "ERRORS.INVALID_TITLE", "firstName": "ERRORS.FIRSTNAME_REQUIRED", "lastName": "ERRORS.LASTNAME_TOO_LONG"}
}

同名者:两个受影响的字段都会被标出:

1
2
3
4
5
6
$ curl -i -b cookies.txt --json @curl/doctor-duplicate.json http://localhost:8080/api/doctors
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 151

{"statusCode": 409, "key": "ERRORS.DOCTOR_ALREADY_EXISTS", "fields": {"firstName": "ERRORS.DOCTOR_ALREADY_EXISTS", "lastName": "ERRORS.DOCTOR_ALREADY_EXISTS"}}

修改。[version] 是从记录中读到的版本(此处为 1):

{ "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "version": 1 }
1
2
3
4
5
6
$ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 97

{"id": 4, "version": 2, "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "login": "leroy"}

该记录现在是版本 2。再次提交同样的修改(带 version 1)会覆盖一条此后已被他人修改过的记录:这正是乐观锁所要防止的:

1
2
3
4
5
6
$ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 51

{"statusCode": 409, "key": "ERRORS.CONCURRENT_UPDATE"}

有预约的医生不能被删除;其他医生可以:

1
2
3
4
5
6
$ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/1
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"statusCode": 409, "key": "ERRORS.DOCTOR_HAS_APPOINTMENTS"}
1
2
3
4
5
6
$ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}

8.6.7. 创建账户

没有通行证,就不可能:

1
2
3
4
5
6
$ curl -i --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56

{"statusCode": 403, "key": "ERRORS.CAPTCHA_BEFORE_ACCOUNT"}

首先,你解决一个验证码;服务器签发一个有效期为 15 分钟的令牌,放在 Cookie 中:

1
2
3
4
5
6
7
$ curl -i -c cookies-registration.txt --json @curl/captcha-test.json http://localhost:8080/api/register/access
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_registration=f71fa11a-e899-4d06-a35c-42d203dce17d; Max-Age=900; Path=/api/register; Expires=Mon, 28 Sep 2026 11:04:14 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}
$ curl -s -b cookies-registration.txt http://localhost:8080/api/register/access
{"valid": true}

确认密码必须与密码一致:

1
2
3
4
5
6
$ curl -i -b cookies-registration.txt --json @curl/registration-confirmation.json http://localhost:8080/api/register
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 98

{"statusCode": 400, "key": "ERRORS.INVALID_FORM", "fields": {"confirmation": "ERRORS.PASSWORDS_DIFFER"}}
{ "title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "password": "secret1", "confirmation": "secret1" }
1
2
3
4
5
6
7
$ curl -i -b cookies-registration.txt -c cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 201 Created
Set-Cookie: rdvmedecins_registration=; Path=/api/register; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 20

{"login": "jbernard"}

通行证已被使用:它不能用来创建第二个账户:

1
2
3
4
5
6
$ curl -i -b cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56

{"statusCode": 403, "key": "ERRORS.CAPTCHA_BEFORE_ACCOUNT"}

8.6.8. 管理你的账户

新患者登录并读取她的病历:

$ curl -s -b cookies-jbernard.txt http://localhost:8080/api/my-account
{"title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "version": 1}

任何修改都需要当前密码。服务器会签发一个新令牌,其中包含新的姓名:

{ "title": "Mme", "firstName": "Julie", "lastName": "BERNARD-DUVAL", "login": "jbernard", "currentPassword": "secret1", "version": 1 }
1
2
3
4
5
6
7
$ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X PUT --json @curl/my-account.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Mon, 28 Sep 2026 12:49:15 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 63

{"login": "jbernard", "name": "Julie BERNARD-DUVAL", "role": "USER"}

删除账户的同时也会删除 Cookie:

1
2
3
4
5
6
7
$ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X DELETE --json @curl/my-account-delete.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}
1
2
3
4
5
6
$ curl -i -b cookies-jbernard.txt http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47

{"statusCode": 401, "key": "ERRORS.AUTH_REQUIRED"}

8.6.9. 一些错误

一个未知的路由,一个不是有效 JSON 的请求体:

1
2
3
4
5
6
$ curl -i -b cookies-martin.txt http://localhost:8080/api/does-not-exist
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 43

{"statusCode": 404, "key": "ERRORS.NOT_FOUND"}
1
2
3
4
5
6
$ curl -i -b cookies.txt -H "Content-Type: application/json" -d "{not json" http://localhost:8080/api/appointments
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 45

{"statusCode": 400, "key": "ERRORS.BAD_REQUEST"}

现在,我们已经了解了编写客户端所需要知道的关于服务器的一切。