2. 第 1 章 - 搭建工作环境
2.1. 安装工具
- Node.js:从 nodejs.org 下载并安装 22 版本(或更高版本)。在终端中使用命令 [node --version] 和 [npm --version] 验证安装。Node.js 只对 [NestJS] 服务器有用。
- [MySQL] 8:在第 2 章中使用 Laragon 工具安装,Laragon 还提供管理工具 HeidiSQL。
- Postman:可在 postman.com 免费下载;第 2 章中用它来测试服务器。
- Visual Studio Code:可选,用于查看 [NestJS] 服务器代码。
对于客户端,只需要一个工具:[Android Studio]。无需单独安装 JDK(Java Development Kit):Android Studio 自带 JDK,即 JetBrains Runtime([JBR]),用于运行 [Gradle],即 Android 项目的构建工具。也无需安装 Kotlin 编译器:它是一个 Gradle 插件,在首次构建项目时会自动下载。
2.1.1. Android Studio 和 Android SDK
[Android Studio] 可在 [https://developer.android.com/studio] 免费下载。首次启动时,向导会提供标准安装:接受即可。随后它会下载 Android SDK(平台库、编译工具和模拟器)。

本文档已在 Android Studio Quail 4(2026.1.4)上测试。通过主屏幕上的 [More Actions] 链接可以进入 [SDK Manager] 和 [Virtual Device Manager],它们将在后面用到:

- [SDK Manager] 用于安装和更新 Android SDK 的组件。[SDK Platforms] 选项卡:确认已安装较新的 Android 平台——本文档中的项目针对 API 37(Android 17)编译。如果缺少,Gradle 会在首次构建时自动下载;
- [SDK Tools] 选项卡:确认已勾选 [Android SDK Build-Tools]、[Android SDK Platform-Tools](其中包含 [adb] 工具)和 [Android Emulator]。

SDK 默认安装在 [%LOCALAPPDATA%\Android\Sdk] 文件夹中(在 Windows 上)。它的两个子文件夹包含本文档用到的命令行工具:[platform-tools] ([adb] 工具,用于从计算机控制手机或模拟器)和 [emulator]。您可以把这两个文件夹添加到系统的 [PATH] 中,这样只需在终端中输入 [adb] 即可。
2.2. 使用 Android Studio 创建 Android 项目
客户端代码随本文档一起提供(文件夹 [rdvmedecins-kotlin-client])。它由 Android Studio 项目模板 [Empty Activity] 创建,然后扩展而成。我们先来看看这个起始项目是如何创建的:它相当于 Flutter 课程中的 [flutter create] 命令。在 Android Studio 主屏幕上,点击 [New Project]:

- 在 [Phone and large screens] 类别中,选择 [Empty Activity] 模板。这是“Jetpack Compose”模板:一个单屏应用,其 UI 在 Kotlin 中定义。相反,[Empty Views Activity] 模板使用以 XML 描述的旧视图系统,本文档不使用它;
- 点击 [Next]。

- [Name]:应用名称,显示在手机上其图标下方。本文档中为:[RdvMedecins];
- [Package name]:应用的唯一标识符,采用反向域名的形式。本文档中为:[fr.rdvmedecins.client]。它同时也是源代码的 Kotlin 基础包;
- [Save location]:项目文件夹;
- [Minimum SDK]:支持的最旧 Android 版本。本文档中的客户端要求 API 26(Android 8.0),几乎涵盖所有在用的手机;
- [Build configuration language]:Gradle 配置文件所用的语言。推荐选择 [Kotlin DSL (build.gradle.kts)]:构建配置同样用 Kotlin 编写;
- [Finish] 创建项目。随后 Android Studio 会启动首次“Gradle sync”:下载 Gradle 本身、Android 插件、Kotlin 编译器以及项目声明的库。首次可能需要几分钟。
创建出的项目具有如下目录结构(本文档读者修改或新增的文件将在第 4 章讨论):
[Gradle] 在这里的作用,与 [npm] 之于 Node.js 项目、或 [flutter]/[pub] 之于 Flutter 项目相同:它下载依赖项、编译代码,并生成可安装的应用,即 .apk 文件。脚本 [gradlew] (Linux、macOS)和 [gradlew.bat] (Windows),即 Gradle 的“wrapper”,会按需下载项目所需的确切 Gradle 版本(在 [gradle/wrapper/gradle-wrapper.properties] 中指定):无需全局安装 Gradle。
2.3. 打开客户端项目
如果您已下载本文档的代码,客户端位于 [rdvmedecins-kotlin-client] 文件夹中。打开方法:在 Android Studio 主屏幕上点击 [Open] 按钮,然后选择该文件夹(包含 [settings.gradle.kts] 的那个文件夹)。Android Studio 将开始上述的 Gradle 同步。随后项目会出现在(左侧的)[Project] 视图中;默认的 [Android] 视图按类型(清单、Kotlin+Java、assets、res)而不是按文件夹对文件分组。
也可以不打开 Android Studio,直接使用命令行构建项目。在 [rdvmedecins-kotlin-client] 文件夹中打开的终端里:
- 第一行(PowerShell)告诉 Gradle 使用哪个 JDK:Android Studio 自带的那个。如果机器上已经定义了 [JAVA_HOME] 变量,则无需这一行;
- 第二行运行 Gradle 任务 [assembleDebug],它编译项目并生成可安装到模拟器或手机上的“debug”应用。
首次构建时,Gradle 会下载所需的一切,然后显示它正在运行的任务列表:
- [compileDebugKotlin]:将 Kotlin 代码编译为 Java 字节码;
- [dexBuilderDebug]:将该字节码转换为 DEX 格式,这是 Android 虚拟机([ART],Android Runtime)执行的格式;
- [packageDebug]:组装 [app/build/outputs/apk/debug/app-debug.apk] 文件,即可安装的应用。
2.4. 设置 Android 模拟器
如果您没有手机,可以在 Android 模拟器上测试应用:这是一个在计算机窗口中运行的虚拟手机。本节与 Flutter 课程中的相应部分相同。
[Prerequisites]:必须在计算机的 [BIOS] 中启用虚拟化;在 Windows 上,还必须勾选 [Windows Hypervisor Platform] 功能([Control Panel / Programs / Turn Windows features on or off]),这需要重启。否则模拟器将无法启动或运行得非常慢。
在 Android Studio 中打开 [Device Manager]:在主屏幕上选择 [More Actions / Virtual Device Manager],或在打开项目时选择 [Tools / Device Manager]。

点击 [Create Device],选择一个型号(例如 [Pixel 8]),然后点击 [Next]。为 [x86_64] 处理器选择较新的 Android 系统镜像,并通过其旁边的 [Download] 链接下载,然后点击 [Next] 和 [Finish]。


使用 [Device Manager] 上的 [Play] 按钮启动模拟器:

也可以从终端启动。第一条命令列出已创建的模拟器;第二条启动其中一个:
等待 Android 主屏幕出现在模拟器窗口中(首次启动可能需要几分钟),然后验证 [adb] 工具能否检测到它:
[Note]:如果 [adb devices] 显示 [offline] 而不是 [device],说明模拟器尚未启动完毕,或者 [adb] 处于不一致的状态。请等待欢迎界面出现,然后在必要时重新启动 [adb] ,使用命令 [adb kill-server] ,再执行 [adb start-server]。如果问题依旧,请使用 [where.exe adb] 确认 [PATH] 中没有其他 [adb](例如来自旧版 SDK 的不同版本)。
2.4.1. 准备 Android 手机
要在真实的 Android 手机上运行应用,必须将手机设置为允许从计算机控制:
- 启用开发者选项:打开 [Settings / About phone],然后多次点按 [Build number](通常为 7 次),直到手机提示您已成为开发者。具体标签因厂商而异;
- 在 [Developer options] 菜单中启用 [USB debugging](该菜单在上一步中已出现);
- 使用能传输数据(而不仅仅是充电)的 USB 线将手机连接到计算机,并在手机上接受 USB 调试授权请求。在 Windows 上,如果手机未被识别,请安装厂商的 USB 驱动程序(“OEM USB drivers”,参见 [https://developer.android.com/studio/run/oem-usb]);
- 检查手机是否出现在 [adb devices] 显示的列表中。
手机将通过计算机在本地网络中的 IP 地址来访问 [NestJS] 服务器,或通过 USB 线使用 [adb reverse] 命令来访问:这些设置将在第 5 章中介绍。