9. 与服务器通信
现在必须启动 JSON 版 [RdvMedecins] 服务器(端口 8080),如上一章所述。
9.1. 示例 22:第一个 HTTP 请求
9.1.1. 服务器在哪里?
对于由服务器自身提供的 Web 客户端,这个问题并不存在:请求使用相对地址([/api/captcha])发往与页面相同的源。移动应用没有源:你必须向它提供服务器的完整地址。而这个地址取决于应用运行在哪里:
- 第 24 行:应用启动时通过选项 [--dart-define] 提供的地址:[flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...]。[String.fromEnvironment] 在编译时求值:如果没有提供该选项,它是一个常量,即“”;
- 第 29–35 行:否则,使用默认地址,取决于平台。[kIsWeb] 在应用运行于浏览器中时为 true;[defaultTargetPlatform] 指示它运行在哪个系统上([TargetPlatform.android]、[TargetPlatform.windows]……):
- 在 Web 上:相对地址(''),与应用同源;
- 在 [Android] 模拟器上:[http://10.0.2.2:8080]。模拟器是一台独立的机器,有自己的网络:对模拟器而言,[localhost] 指的是模拟器自身。特殊地址 [10.0.2.2] 指的是运行模拟器的那台电脑;
- 在电脑上([Windows]……):[http://localhost:8080]。
一部真实手机,如果与服务器所在的电脑连接在同一个 Wi-Fi 网络上,就必须使用该电脑在这个网络中的地址([ipconfig] 命令在 [Windows] 下可以得到它):这个地址通过 [--dart-define] 传入。电脑的防火墙还必须允许 8080 端口的入站连接。
在 [Android] 项目中需要两项设置,位于 [android/app/src/main/AndroidManifest.xml] 文件中:
- 第 3 行:使用网络的权限。在开发期间,[Flutter] 会自动添加它(用于热重载);对于发布的应用,必须显式声明;
- 第 8 行:从 [Android] 9 版本开始,应用默认只允许通过 HTTPS 通信。我们的开发服务器使用 HTTP(“未加密”):我们对此予以允许。在生产环境中,服务器会使用 HTTPS,这一行就要删除。
至于 Web:[Flutter] ([flutter run -d chrome])的开发服务器在它自己的端口上提供应用;而 JSON 服务器则在 8080 端口。这是两个不同的源:浏览器会拒绝在请求中包含 Cookie,甚至拒绝在响应中读取它(服务器不允许来自不同源的请求,即所谓的“CORS”)。[web_dev_config.yaml] 文件用来配置 [Flutter] 的 Web 开发服务器(自 3.38 版本起):
- 第 12 行:Web 应用在 5173 端口上提供;
- 第 13–15 行:一个代理:任何发往以 [/api/] 开头的地址的请求,都会被转发到 JSON 服务器(8080 端口),其响应再被送回浏览器。对浏览器而言,应用和 API 同源。这正是 [Vite] 代理在 [React] 课程中所起的作用。
9.1.2. 请求
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 | |
- 第 21 行:[http] 包,即 [Dart] 团队的 HTTP 客户端。[as http]:它的函数带前缀使用([http.get]、[http.Response]),这样可避免它们的名称与其他名称混淆;
- 第 44–48 行:状态:收到的验证码(一个记录,或 [null])、请求的三种状态(进行中、错误、成功)、成功请求的数量;
- 第 51–53 行:屏幕一出现就发出第一个请求;
- 第 56–84 行:请求:
- 第 63 行:[http.get] 发送一个 GET 请求,稍后返回 [Future<http.Response>]:即响应。[Uri.parse] 根据字符串构造地址;
- 第 66–67 行:对于错误响应(4xx、5xx),[http.get] 不会抛出异常:它只是另一个响应。我们要检查它的状态码;
- 第 69 行:[response.body] 是响应体,即文本;[jsonDecode] 把它转换为 [Dart] 对象:这里得到的是一个 [Map];
- 第 72 行:对过期请求(其间又请求了一张图片)的响应,或在屏幕关闭之后才到达的响应,会被忽略(见示例 19);
- 第 74 行:JSON 的类型是 [dynamic]:每个值都要转换为相应的类型,因此使用 [as];
- 第 78–82 行:根本没有响应(服务器宕机、地址错误、网络断开):[http.get] 会抛出异常,该异常被捕获并显示;
- 第 102 行:请求期间显示进度条;
- 第 122 行:验证码图片是文本形式的 SVG:[SvgPicture.string] (包 [flutter_svg])负责渲染它。它由我们自己的服务器生成,不包含任何用户提供的内容;
- 第 130 行:“换一张图片”,请求期间禁用。
在 [Android] 模拟器上;然后,在关闭 JSON 服务器的情况下:
![]() | ![]() |
该 [Flutter DevTools] 工具(由 [VS Code] 启动,或通过 [flutter run] 提供的地址打开)有一个 Network 选项卡,它显示应用发出的每个 HTTP 请求及其头和主体,类似于浏览器的开发者工具。
9.2. 示例 23:登录、Cookie 与会话
9.2.1. 处理 Cookie 的 HTTP 客户端
服务器把 JWT 令牌存放在 Cookie 中。在浏览器里,存储和发送 Cookie 都由浏览器处理;应用代码不需要做任何事。而在手机上没有浏览器——需要由应用自己来处理。
- 第 25 行:[http] 包允许你包装自己的客户端:继承 [http.BaseClient],只需实现 [send] 方法,所有请求([get]、[post]……)都要经过它;
- 第 28–31 行:被包装的客户端、设备的存储(可选:[?]),以及各个 Cookie(名称 → 值);
- 第 33–37 行:创建时,读取在应用上一次使用期间存储的 Cookie。这样,关闭再重新打开应用时仍保持登录状态:在手机上,这相当于浏览器在两次访问之间保留它的 Cookie;
- 第 42–52 行:每个请求都带上头 [Cookie] (“rdvmedecins_jwt=eyJhbGci...; other=value”),然后读取响应中的 [Set-Cookie] 头。[kIsWeb]:在 Web 上,应用什么也不多做,只相当于一个普通客户端,因为浏览器不允许应用读取或写入这些头(它自己处理它们);
- 第 58–69 行:解析 [Set-Cookie] 头。多个 Cookie 以逗号分隔,但日期 [Expires] 本身就含有逗号(“Tue, 29 Sep 2026”):正则表达式只匹配后面跟着 [=] 的名称,且该名称位于头的开头或逗号之后。每个 Cookie 只保留名称和值;值为空(退出登录时:服务器发送 [rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970...])就会删除该 Cookie。[_storage?.setString(...)]:只有当 [_storage] 不是 [null] 时才执行该调用。
更完善的 Cookie 管理(域、路径、过期时间)可以在一些包中找到([cookie_jar],与客户端 [dio] 搭配);我们只有几行的实现,对于一台服务器来说已经足够。安全提示:这里令牌以明文存储在设备上。生产环境的应用应使用 [flutter_secure_storage] 包(见示例 20)。
9.2.2. 命令
异步操作(登录、保存等)有一个状态,屏幕必须把它显示出来:它是否进行中(按钮被禁用)?它是否以错误结束(显示消息)?这就是 [Flutter] 架构指南中的“Command”模型,已精简到只剩要点。[React] 课程为此使用了 [React] 19 的“actions”([useActionState])。
- 第 27–39 行:执行一个操作:如果另一个操作正在进行,就什么也不做(防止按钮被按两次而重复发送);否则,命令切换为“进行中”并通知它的监听者;如果发生异常,错误会被记录下来用于显示;无论哪种情况([finally]),命令都不再处于进行中。
9.2.3. 屏幕
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 | |
- 第 36–41 行:把 Cookie 存储在设备上的 HTTP 客户端在启动时创建,并传给屏幕;
- 第 47–49 行:一个把响应作为错误捕获的异常(可以从中读取其状态码)。[implements Exception]:一个可以被抛出的对象([throw]);
- 第 90–93 行:一个我们想要获取响应体(JSON)的请求(GET),如果状态码不是 2xx 则抛出异常。[widget.client.get(...)]:带 Cookie 的客户端。[utf8.decode(response.bodyBytes)]:响应体按 UTF-8 解码(带重音的字符),而不论响应头怎么说;
- 第 97–101 行:一个 POST:头是 [content-type: application/json] ,请求体为 JSON(服务器会拒绝不是 JSON 的 POST);
- 第 117–132 行:1. 启动时:谁已连接?[GET /api/auth/me]:200,表示有用户;401,表示没有人。[on ErrorResponse catch (e)] 只捕获这一类异常;下一个 [catch] 捕获所有其他异常(根本没有响应);
- 第 136–152 行:2. 连接:[POST /api/auth/login]。如果请求被拒绝,错误响应的响应体会给出消息键;加载一张新图片(每张只使用一次),然后抛出该消息:在 [Dart] 中,任何对象都可以被抛出——这里抛出的是一个字符串。由命令来捕获并存储它;
- 第 156–162 行:4. 退出登录:[POST /api/auth/logout];服务器删除 Cookie(客户端也删除它的 Cookie);
- 第 193–197 行:3. 已登录:医生列表([GET /api/doctors],一个受保护的请求:Cookie 随它一起发送);
- 第 225–226 行:验证码及其按钮;
- 第 236–248 行:按钮反映请求的状态:请求发送期间被禁用并显示“Logging in...”;任何错误消息都显示在其下方。
登录屏幕;密码错误;登录成功:
![]() | ![]() | ![]() |
关闭后重新启动应用:它会以已登录状态启动。存储在设备上的 Cookie 被提交给 [GET /api/auth/me],服务器返回用户的身份信息。令牌在两小时后过期:此后 [GET /api/auth/me] 将返回 401 响应,登录屏幕会重新出现。
9.3. 示例 24:API 访问层
在示例 23 中,每个请求都重复了相同的步骤。本示例把它们组织成三层,案例研究将再次用到这三层。
9.3.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 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 | |
解码后的 JSON 是无类型的:[Map]、[List]、[dynamic]。每个类都有一个工厂构造函数 [fromJson] ,用来验证收到的 JSON 的格式。[factory] 构造函数不一定创建新对象:它是一个返回该类对象的函数。
- 第 33–39 行:[Dart] 3 的模式匹配应用于 JSON。模式 [{'login': final String login, 'name': final String name, 'role': final String role}] 验证 [json] 是一个 [Map],这三个键都存在,它们的值是字符串,并把这些值存入三个变量。如果 JSON 的格式不同,例如 [_] 的情况,就按异常处理。这样,意外的响应在收到时就被检测出来,而不是稍后在显示过程中才发现;
- 第 23 行:“ADMIN” -> [Role.admin]:[byName] 按名称取回一个枚举值;
- 第 67–76 行:模式检查必需的键;可选的键 [login] 单独读取;
- 第 81 行:一个列表形式的 JSON -> 一个人员列表;
- 第 133–144 行:[final Object? patient] 接受任何值,包括 [null];[final int? appointmentId],是一个整数,或 [null];
- 第 162–164 行:一个格式化的 getter。
9.3.2. 错误
服务器的所有错误响应都具有相同的格式。但是,请求也可能以其他方式失败:根本没有响应,或者响应并非来自我们的服务器。我们把这一切都转换为同一个类 [ApiError]。
- 第 19–23 行:一个状态(0:没有响应)、一个翻译键、它的参数,以及每个字段的错误;
- 第 28–44 行:一个错误响应 → 一个 [ApiError]。[if (body case {'key': final String key})]:在 [if] 中进行过滤(“if-case”):如果响应体有一个字符串类型的 [key] 键,它就被存入 [key] 变量。 否则,说明响应的不是我们的服务器;
- 第 53 行:“401 LOGIN.ERROR”,用于快速显示。
9.3.3. 请求
- 第 31–49 行:所有请求都经过这个方法:服务器地址和前缀 [/api]、JSON 格式的请求体、发送([_client.send],随后是 [http.Response.fromStream],它会等待完整的响应体)、被转换为 [ApiError] 的错误,以及解码后的响应体。我们可以在这里处理所有请求共有的问题(见案例研究和 401 响应);
- 第 52–56 行:四个快捷方法。POST 总是带有 JSON 请求体:默认为 [{}] 。
9.3.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 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | |
示例 23 中的表单,精简为一个单独的栏,并使用 [Api] 重写。每当已登录用户发生变化(包括启动时),它都会调用 [onUserChange]。
- 第 30 行:对象 [Api] 在更上层提供(由 [provider]);[late]:它只在首次使用时才读取,即在 [initState] 中;
- 第 64–72 行:启动时,谁已连接?[User.fromJson(await _api.get('/auth/me'))]:只有一行。任何 [ApiError] 都表示“没有人”;
- 第 77–92 行:连接,只需几行:错误以 [ApiError] 的形式出现。
9.3.5. API 访问层
每条 API 路由对应一个带类型的方法。屏幕不知道地址、[http] 包或 JSON 的格式:它们调用的是返回 [Dart] 对象的方法。如果 API 发生变化(地址、字段名),只需修改这一个文件。[Flutter] 架构指南把这一层称为“仓库(repository)”。
- 第 26 行:[Uri] 构造出字符串“doctorId=1&day=2030-01-15”,并对必要的数据进行编码;
- 第 33 行:['clientId': ?clientId] 位于 [Map] 字面量中:键被放入 [Map] 中,仅当 [clientId] 不是 [null] 时(这是 [Dart] 3.8 的“可选元素”)。
9.3.6. 视图模型
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 | |
在 [Flutter] 架构指南中,建议把视图 (组件,负责显示并传递用户的操作)和视图模型 (一个 [ChangeNotifier] ,包含屏幕的状态及其操作,并调用 API 访问层)分开。视图不再包含任何逻辑;视图模型不含组件:无需屏幕就可以测试它。
- 第 35–43 行:屏幕状态;
- 第 45–46 行:一个缓存:每个已读取过的(医生,日期)对应的日程都会被存储;再次回到它时会立即显示,同时重新读取。还有最近一次读取的编号,用来忽略过期的响应(见示例 19)。这几行代码所做的,就是 [TanStack Query] 库在 [React] 课程中所做的事;
- 第 49–50 行:计算值;
- 第 53–64 行:一个新用户:我们清除一切(权限已经改变),然后读取医生,并且对于 ADMIN 和 DOCTOR,还读取客户(USER 会收到 403);
- 第 91–98 行:一个操作(预约、取消),然后始终重新读取日程:以服务器的响应为准;
- 第 101–120 行:获取日程:先从缓存(或什么也没有)获取,然后是服务器的响应,除非期间发起了更新的获取。
9.3.7. 屏幕
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 | |
- 第 28–34 行:在启动时组装的三层:[Api] (请求)、[RdvMedecins] (路由)、[ScheduleModel] (屏幕)。[Provider.value] 返回一个普通对象,它不会触发任何通知;
- 第 50 行:视图订阅视图模型;
- 第 58 行:登录栏通知模型;
- 其余只是显示:每个组件读取模型的状态,并在用户执行操作时调用它的某个方法([model.chooseDoctor(id!)], [model.book(c)]……);
- 第 120–153 行:日程中的一行。按钮遵循由服务器 计算出的权限([bookable]、[appointmentId])。
以 [admin] 身份登录,PELISSIER 女士的日程;一个时间段被预约给一位患者;以 [martin] (角色 USER)身份登录,同一份日程:
![]() | ![]() | ![]() |
患者 [martin] 看不到已预约时间段的患者姓名:服务器没有把它发给他。
9.4. 示例 25:服务器返回的错误
9.4.1. 字典
服务器的错误消息是键 (“ERRORS.LASTNAME_REQUIRED”):由字典来翻译它们。
9.4.2. 屏幕
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | |
患者管理(admin 账户)。这个表单在手机上不做任何验证:一切都发送给服务器,服务器在拒绝时会返回错误 JSON,并被转换为 [ApiError]。
- 第 37–43 行:示例 21 中的翻译,使用该示例中的字典;
- 第 77 行:每个字段的错误:由服务器返回的一个翻译键;
- 第 79–82 行:最近一次错误的通用消息、成功消息,以及发送给服务器的 [Command](示例 23);
- 第 126–131 行:从记录中读取的版本 会随修改一同更新:如果其间有人修改了该记录,服务器会返回 409 [CONCURRENT_UPDATE] (乐观锁);
- 第 141–162 行:保存操作:[POST /api/clients] (创建)或 [PUT /api/clients/:id] (更新)。如果操作被拒绝,[ApiError] 会返回一条通用错误消息和每个字段的具体错误;
- 第 188–198 行:一个输入字段:它的错误(一个服务器键)会被翻译并显示在字段下方([errorText]);编辑该字段会清除它的错误;
- 第 209–212 行:顶部栏中用于选择语言的菜单;
- 第 257 行:一个“Dr”称谓,服务器会拒绝它:见 [ERRORS.INVALID_TITLE];
- 第 291–302 行:翻译后的通用消息,以及为了说明上下文而显示的 HTTP 状态和键。
一个空表单;一个同名者(“Alice DURAND”);同样的情形,用法语显示:
![]() | ![]() | ![]() |
还可以试试:一个已被占用的登录名([martin])、一个无效的登录名(“Jean M”),以及在两台设备上编辑同一条记录(或在应用中和用 [curl] 同时编辑)。
其原理与案例研究中的所有表单相同:规则只存在于一个地方——服务器;应用用用户的语言显示结果。










