Skip to content

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]。在命令行中,在项目文件夹里:

1
2
3
adb devices                                        # 模拟器必须出现
.\gradlew.bat installDebug                          # 构建并安装应用
adb shell am start -n fr.rdvmedecins.client/.MainActivity   # 启动应用

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] 命令):

1
2
3
4
5
6
W RdvMedecins: login failed
W RdvMedecins: java.net.SocketTimeoutException: failed to connect to /10.0.2.2 (port 8080)
from /10.0.2.16 (port 56580) after 10000ms
W RdvMedecins:   at okhttp3.internal.connection.RealConnection.connectSocket(RealConnection.kt:295)
...
W RdvMedecins:   at fr.rdvmedecins.client.core.services.AuthService$logIn$result$1.invokeSuspend(AuthService.kt:114)

[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:

1
2
3
4
5
6
7
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">10.0.2.2</domain>
        <domain includeSubdomains="false">localhost</domain>
    </domain-config>
</network-security-config>

该文件通过 [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] 中。

以下截图是在预订对话框打开的情况下截取的:先是横屏模式,然后回到竖屏模式。对话框、日程以及所选的医生和日期都还在:

Image

Image

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

Image

要评估这些选择的价值,可以尝试相反的做法:在 [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”:

Image

Image

修正方法(右侧截图;见第 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 商店。若要实际分发:

.\gradlew.bat assembleRelease    # 生产环境 APK:app/build/outputs/apk/release/
.\gradlew.bat bundleRelease      # Android App Bundle(.aab),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 商店),并使用个人签名密钥。