6. 第 5 章 - 运行应用:模拟器、手机、APK
6.1. 单一目标:Android
Flutter 课程的第 5 章展示了同一份源代码如何编译为三类目标:移动端、桌面端和 Web。这里并非如此:本文档中的客户端是一个 Android 应用——而且只是 Android。相反,它直接使用该平台的工具和库([Gradle]、[Android Studio]、[ViewModel]、[SharedPreferences]……),没有抽象层。本章最后一节说明若还要面向 iOS、桌面端和 Web,需要做些什么。
本章中的命令使用 [adb] 工具和 Gradle wrapper。在 Windows 上,如果 SDK 的 [platform-tools] 和 [emulator] 文件夹不在 [PATH] 中,请把 [adb] 替换为 [& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"] (见第 1 章)。
6.2. 模拟器目标
这是第 4 章全程使用的目标。在 Android Studio 中:从设备列表中选择模拟器,然后选择 [Run]。在命令行中,在项目文件夹里:
6.2.1. 网络陷阱:localhost 不再指向开发用的 PC
这是移动开发中需要了解的重要细节(THE important detail),与 Kotlin 或 Compose 无关:在“Server URL”字段中,[localhost] (或 [127.0.0.1])指向运行代码的那台机器。然而,模拟器是一台虚拟机,不同于运行 [NestJS] 服务器的开发 PC,尽管两者看起来“在同一台计算机上”。有两种解决办法:
- 特殊地址 [http://10.0.2.2:8080]:它是官方 Android 模拟器特有的,会被重定向到宿主机的 [localhost]。这是“Server URL”字段的默认值(见 [SettingsService.kt]);
- 命令 [adb reverse tcp:8080 tcp:8080],然后使用 URL [http://localhost:8080]。[adb reverse] 会创建一条隧道:设备上任何发往其自身(ITS)8080 端口的连接,都会由 [adb] 转发到计算机的 8080 端口。模拟器停止时(或 [adb] 服务器重启时),隧道就会消失:此时必须重新运行该命令。
第一种方案最简单。但在编写本文档所用的计算机上它行不通:到 [10.0.2.2:8080] 的连接在 10 秒超时后失败,而服务器在 [localhost] 上却响应正常。这类问题取决于 PC 的网络配置(防火墙、VPN、虚拟化软件):[adb reverse] 绕过了这个问题,因为此时流量经过的是 [adb] ,而不是模拟器的虚拟网络。应用显示的消息(“Incorrect login or password.”)提供不了多少线索;确切原因可以在 Android 日志中找到,这要归功于客户端对 [Log.w(...)] 的调用(Android Studio 中的 [Logcat] 选项卡,按 [RdvMedecins] 过滤,或使用 [adb logcat -s RdvMedecins] 命令):
[adb reverse] 命令和 URL [http://localhost:8080](由 [SettingsService] 保存)解决了这个问题:第 4 章中的所有截图使用的都是这种配置。
6.3. 目标:手机
在第 1 章中设置好的手机(开发者选项、USB 调试)会出现在 [adb devices] 的输出中,也会出现在 Android Studio 的设备列表中:它的工作方式与模拟器完全相同([Run] 或 [gradlew installDebug])。只有服务器的 URL 不同:
- 通过 USB 线连接的手机:命令 [adb reverse tcp:8080 tcp:8080] 同样适用于真实手机,URL [http://localhost:8080] 随后即可通过线缆访问 PC 上的服务器。这是最简单的方案;
- 手机与 PC 处于同一 Wi-Fi 网络:使用 PC 在该网络中的本地(LOCAL)IP 地址(例如 [http://192.168.1.48:8080];在 Windows 中,[ipconfig] 命令会显示它),绝不要使用 [localhost] 或 [10.0.2.2],因为在这种情况下两者都指向手机本身。PC 上的防火墙此时必须允许 8080 端口的传入连接(首次启动 Node.js 时,Windows 会提示您这样做)。
[NestJS] 服务器监听 PC 的所有网络接口([0.0.0.0]):服务器一侧无需任何更改。
6.4. 移动端特有的两项限制
6.4.1. 未加密的 HTTP 流量
从 Android 9(API 28)开始,默认情况下应用不能再使用“明文”HTTP([http://],未加密)通信:只允许 [https://] 。由于本课程的服务器监听的是普通 HTTP,客户端的清单声明了 [android:usesCleartextTraffic="true"] 这一例外(见第 4 章)。没有它,任何请求都会失败,并抛出 [CLEARTEXT communication to 10.0.2.2 not permitted by network security policy] 异常。
这个授权适用于所有(ALL)服务器。也可以使用 [res/xml/network_security_config.xml] 文件进行更细粒度的配置,只允许对特定主机名使用明文 HTTP:
该文件通过 [android:networkSecurityConfig="@xml/network_security_config"] 属性在清单的 [<application>] 标签中声明。本文档没有使用它:Wi-Fi 网络中 PC 的 IP 地址事先并不知道。无论哪种情况,这些设置都只适用于开发阶段:在生产环境中,服务器会以 [https://] 对外提供(例如放在 Nginx 之类的“反向代理”之后),这会使任何例外都变得不必要。
6.4.2. 网络访问权限
如果清单中没有 [<uses-permission android:name="android.permission.INTERNET" />] 这一行,第一个请求就会失败,并抛出 [SocketException: socket failed: EPERM (Operation not permitted)] 异常(当 URL 包含主机名时,则抛出 [SecurityException: Permission denied (missing INTERNET permission?)] 异常)。这是一个常见的疏忽:Android Studio 的项目模板并不包含它。
6.5. 屏幕旋转
旋转手机(或使用模拟器侧边栏上的旋转按钮旋转模拟器)会销毁并重新创建 Activity(见第 3 章)。客户端凭借第 4 章中做出的三个选择来处理这一问题:
- 服务由 [RdvMedecinsApplication] 构建,它不会被重新创建;
- 屏幕状态(医生、患者、日程、当前正在预订的时段)存储在 [AppViewModel] 中,由 Android 保留;
- 次要的界面状态(正在输入的登录信息、所选的医生和日期、在对话框中选择的患者)存储在 [rememberSaveable] 中。
以下截图是在预订对话框打开的情况下截取的:先是横屏模式,然后回到竖屏模式。对话框、日程以及所选的医生和日期都还在:


在横屏模式下,屏幕宽度超过 600 dp:标题栏显示完整的标题和用户名,并且 [DoctorDayPicker] 把它的三个元素排成一行:

要评估这些选择的价值,可以尝试相反的做法:在 [App.kt] 中,把 [val vm = viewModel { AppViewModel(auth, api) }] 替换为 [val vm = remember { AppViewModel(auth, api) }]。旋转之后,日程消失,必须重新执行搜索:[remember] 无法在 Activity 重建后保留下来。
6.6. 窄屏幕:布局陷阱
竖屏的手机宽度只有大约 400 dp。[ScheduleView.kt] 的第一个版本与 Flutter 客户端的一样,被这个宽度绊倒了。日程的每一行都按固定权重把可用宽度分给三列——时间占 30%,状态占 45%,按钮占 25%([Modifier.weight(0.25f)])。在手机上的法语界面中,行宽的 25% 不足以容纳标签“Réserver”,它被截断成了“Rése”:


修正方法(右侧截图;见第 4 章的 [ScheduleView.kt] ):按钮不再有权重,占据其文本的宽度;时间使用固定宽度;状态占据剩余宽度([Modifier.weight(1f)])。由此得出两条规则,与 Flutter 客户端相同:
- 永远不要假定宽度:要么让元素按其内容确定大小,要么检查实际可用宽度([BoxWithConstraints]、[LocalConfiguration.current.screenWidthDp])来选择布局;
- 尽早在窄屏幕上、并使用两种语言进行测试:英语标签(“Book”、“Cancel”)比法语标签短,某个缺陷可能只在两种语言之一中出现。
6.7. 生成 APK
[gradlew assembleDebug] (第 1 章)会生成 [app/build/outputs/apk/debug/app-debug.apk],这是一个“debug”应用:它使用 Android Studio 自动生成的开发密钥签名,可以安装到模拟器或手机上([adb install app-debug.apk]),但不能发布到 Play 商店。若要实际分发:
发布版本必须使用个人密钥签名,该密钥只需创建一次并妥善保管:Android Studio 为此提供了 [Build / Generate Signed App Bundle or APK...] 菜单。Play 商店还要求提供图标、隐私政策……以及位于 [https://] 的服务器。
6.8. 那么 iOS、桌面和 Web 应用呢?Kotlin Multiplatform
课程中的 Flutter 客户端可以由同一份代码库生成移动、桌面和 Web 应用。Kotlin 生态中也有对应的方案:[Kotlin Multiplatform] (KMP)允许您在 Android、iOS、桌面(JVM)和 Web 之间共享 Kotlin 代码,而 JetBrains 的 [Compose Multiplatform] 则把 Jetpack Compose 扩展到这些相同的目标平台。移植本文档中的客户端,主要是把 Android 专用的库替换为跨平台的等价库:
- [OkHttp] → [Ktor Client],JetBrains 的跨平台 HTTP 客户端;
- [SharedPreferences] → 一个跨平台的键值存储库(例如 [DataStore],它现在已支持跨平台);
- Android 文件夹 [assets/] → Compose Multiplatform 资源;
- [android.util.Log]、[Handler] → 它们的跨平台等价物(或 [Dispatchers.Main] 上的协程);
- Application 类和 Activity 仍然保留,但只用于 Android 目标:每个目标平台都有自己的入口点。
@Composable 函数、[@Serializable] 类、协程,甚至 ViewModel(在多平台上可用)几乎都可以原样保留。这项移植不在本文档的范围之内。
6.9. 汇总表
- Android 模拟器 - [Run] 或 [gradlew installDebug] - Server URL:[http://10.0.2.2:8080],或 [adb reverse tcp:8080 tcp:8080] 后接 [http://localhost:8080];
- USB 手机 - [Run] 或 [gradlew installDebug] - URL:[adb reverse tcp:8080 tcp:8080],然后是 [http://localhost:8080];
- Wi-Fi 手机 - [Run] 或 [gradlew installDebug] - URL:PC 的本地 IP 地址,防火墙中开放 8080 端口;
- 所有情况下:清单中都需要 [INTERNET] 权限和对明文 HTTP 的授权;
- 分发:[gradlew assembleRelease] (APK)或 [bundleRelease] (Play 商店),并使用个人签名密钥。