跳到正文Lab学后总结 · Jimmy Huang's BlogLab学后总结
本页目录· 62 条
1. 一句话总结这个 Lab
这个 Lab 教你如何把 Google Maps 接入一个 Android Jetpack Compose App：先在 Google Cloud 端申请地图服务权限和 API Key，再在 Android 项目里配置权限、依赖和 Manifest，最后在 App 的地图上显示位置、标记点、路线、距离和范围。
2. 这个 Lab 实际做了什么
这次 Lab 可以理解成：你不是单纯“放一张地图图片”到 App 里，而是让你的 Android App 真正接入 Google Maps 服务，并且具备一些常见地图交互能力。
2.1 第一步：在 Google Cloud Console 准备地图服务
你首先需要在 Google Cloud Console 里创建或选择一个项目，然后启用 Maps SDK for Android。
这一步的作用是：
如果没有启用 Maps SDK for Android，App 里即使写了地图代码，也可能无法正常加载地图。
2.2 第二步：创建 Google Maps API Key
接下来你会创建一个 Google Maps API Key。
API Key 可以理解成 App 使用 Google Maps 服务时的“钥匙”或“通行证”。
它的作用是：
让 Google 知道是哪一个项目/哪一个 App 在调用地图服务。
让 Google Maps SDK 可以返回地图数据。
方便 Google 端做用量统计、计费、限制和安全控制。
如果没有 API Key，地图 SDK 不知道你是否有资格使用服务，地图很可能无法显示。
真实项目补充：实际开发中通常还会限制 API Key 的使用范围，例如只允许某个 Android package name 和 SHA-1 指纹使用，避免别人盗用。当前 Notion 可见内容没有展示这一步的完整操作，所以这里只作为真实项目里的安全提醒。
2.3 第三步：在 Android 项目里配置 Manifest、权限和 API Key
Google Cloud 端准备好之后，还需要在 Android 项目里告诉 App：
AndroidManifest.xml
location permission
API key metadata
Gradle dependencies
其中 AndroidManifest.xml 是 Android App 的重要配置文件。你可以把它理解成 App 的“身份证资料表”或“系统登记表”。
2.4 第四步：配置 Gradle dependencies
Gradle dependencies 可以理解成项目的“工具采购清单”。
你想在 Compose 里显示 Google Map，就不能只靠 Android 项目自带的基础库，还需要引入 Google Maps 相关的库。
可见内容只明确说需要配置 Gradle dependencies，但没有展示完整依赖名和版本号，所以具体版本 材料未显示/不确定。
如果没有加依赖，代码中使用 Google Map 相关组件时，Android Studio 通常会报错，例如找不到类、找不到 Composable、找不到 Maps 工具类等。
2.5 第五步：用 Jetpack Compose 显示 Google Map
配置完成后，Lab 的核心就进入 Android UI 层：用 Jetpack Compose 显示一张 Google 地图。
这一步相当于在 App 页面里放入一个真正可交互的地图区域。用户可以看到地图，可以拖动、缩放，也可以在地图上看到你添加的元素。
这里的重点不是“地图长什么样”，而是理解地图 App 的基本结构：
2.6 第六步：在地图上放置 Marker
比如你想标记 Monash University、餐厅、超市、用户点击的位置，都可以用 Marker。
如果只有地图没有 Marker，用户只能看到地图背景，不知道你想强调哪个地点。
2.7 第七步：获取用户当前位置并显示 My Location dot
Lab 进一步让 App 获取用户当前位置，并在地图上显示类似 Google Maps App 里的蓝色当前位置点，也就是 My Location dot。
Android 权限App 不能随便读取用户位置。
必须先请求用户授权。
用户同意后，App 才能读取当前位置。
地图显示获取到位置后，可以把地图相机移动到用户附近。
也可以显示蓝色当前位置点。
如果用户拒绝权限，那么 App 仍然可以显示普通地图，但不能可靠显示用户当前位置。
2.8 第八步：点击地图放置 Marker、清除 Marker
这说明你不只是显示固定地点，而是让用户可以参与交互。
清除 Marker 则是把这些记录清空，让地图恢复干净。
用户选择取货地点；
用户选择活动地点；
用户标注问题位置；
用户规划路线点。
2.9 第九步：使用 Polyline 画路径
它通常用于连接多个坐标点，让用户看到一条路线或一段路径。
在这个 Lab 里，可见内容提到使用 Polyline 画路径。
如果只显示 Marker，用户只能看到几个孤立的点；如果用 Polyline 连接起来，用户就能看到这些点之间的关系。
重要提醒：根据当前可见内容，这里的 Polyline 更像是“把多个点连接起来的线”。它不一定等于真实道路导航路线。真实道路导航通常还需要 Directions API 或其他路线服务；当前材料未显示这一部分，所以不能默认 Lab 做了完整导航。
2.10 第十步：计算路径总距离
这一步的意思是：当你有多个地点坐标时，可以计算它们之间的距离，并把总距离展示给用户。
估算步行距离；
估算配送距离；
估算巡检路径长度；
比较多个地点之间远近。
需要注意：如果只是基于坐标点直接计算，通常是地理直线距离或球面距离，不一定等于沿道路行驶距离。当前可见材料没有说明是否接入真实路线服务，所以不要把它理解成“自动避开道路、红绿灯、交通情况的导航距离”。
2.11 第十一步：使用 Circle 画 1km 半径范围
可见内容提到 Lab 会用 Circle 画出某个地点周围 1km 半径范围。
某个店铺周围 1km 可配送；
某个活动地点周围 1km 是服务范围；
用户当前位置周围 1km 内查找可用资源；
食物捐赠 App 中，显示附近可领取范围。
3. 每个核心组件有什么用
3.1 Google Cloud Console
用来创建/选择项目、启用 Maps SDK for Android、创建 API Key。
你没有地方管理地图服务，也无法正常申请地图 API Key。
它是 Google Maps 服务的“后台管理中心”。Android App 不是直接凭空使用地图，而是通过这里配置出来的项目和 API Key 使用 Google Maps。
3.2 Maps SDK for Android
Google 提供给 Android App 使用 Google Maps 的开发工具包。
让你的 Android App 能显示 Google 地图，并支持地图交互。
App 里无法正常嵌入 Google Map，也无法使用 Android 地图相关功能。
它需要在 Google Cloud Console 端启用，也需要 Android 项目端通过依赖引入。
3.3 Google Maps API Key
App 调用 Google Maps 服务时使用的“钥匙”。
让 Google 知道这个 App 有资格请求地图服务。
API Key 在 Google Cloud Console 创建，然后在 Android 项目的 Manifest metadata 里配置，最后由 Google Maps SDK 使用。
3.4 AndroidManifest.xml
声明 App 所需权限，并配置 Google Maps API Key metadata。
它连接 Android 系统、权限机制和 Google Maps SDK。
3.5 Location Permission
Android 系统对“读取用户位置”的权限控制。
决定 App 是否能获取用户当前位置，并显示 My Location dot。
App 可以显示普通地图，但不能随便读取用户真实位置。
它和当前位置功能、My Location dot、Camera 移动密切相关。
3.6 Gradle Dependencies
引入 Google Maps / Compose / 地图工具相关库。
项目可能无法识别 Google Map 相关代码，编译失败。
Google Cloud 端负责“服务开通”，Gradle 负责“代码里能使用相关工具”。
3.7 Jetpack Compose
用 Composable 的方式搭建地图页面和相关按钮/状态展示。
你仍然可以用传统 Android View 做地图，但就不是这个 Lab 的 Compose 练习重点了。
Compose 是 UI 层，GoogleMap 组件会嵌入到 Compose 页面中。
3.8 GoogleMap Composable
在 Compose 页面中显示 Google 地图的核心组件。
你可能已经有 API Key、权限和依赖，但页面上仍然没有地图。
它会结合 CameraPositionState、Marker、Polyline、Circle 等一起工作。
3.9 LatLng
表示一个地理坐标的数据结构，通常包含 latitude 和 longitude。
用来表示 Marker 的位置、用户当前位置、Polyline 的点、Circle 的圆心。
Marker、Polyline、Circle、Camera 都会围绕 LatLng 工作。
3.10 CameraPositionState
决定地图一开始看哪里、缩放多少、之后是否移动到用户当前位置。
地图可能能显示，但你不好控制用户进入页面时看到哪个区域。
Camera 不是用户位置本身，而是“用户屏幕正在看地图的哪个地方”。
3.11 Marker
Marker 依赖 LatLng；多个 Marker 可以被 Polyline 连接起来。
3.12 My Location dot
它依赖 location permission 和当前位置获取能力。
3.13 Polyline
用户只能看到分散的点，看不到点与点之间的路径关系。
Polyline 通常由多个 LatLng 组成，也可以配合距离计算。
3.14 Distance Calculation
计算路径总距离，让地图不仅能“看”，还能提供数值信息。
它通常基于 Polyline 的点或多个 LatLng 进行计算。
3.15 Circle
用户只能知道一个点在哪里，但不知道这个点影响或覆盖的范围有多大。
Circle 需要一个圆心 LatLng 和半径；它和 Marker 都属于地图上的视觉覆盖元素。
4. 用初学者类比解释
我们把这个 Lab 类比成：你要做一个“城市导览 App”。
4.1 Google Cloud Console = 城市地图服务中心
你想在 App 里使用城市地图，就要先去“城市地图服务中心”登记。
你是谁？
你要用什么地图服务？
你有没有资格调用？
调用量是多少？
这就是 Google Cloud Console 在做的事情。
4.2 Maps SDK for Android = 地图服务中心给 Android App 的工具包
光有服务中心还不够，你的 App 还需要工具才能把地图画出来。
Maps SDK for Android 就像地图服务中心给 Android 开发者的一套工具箱。
显示地图的能力；
控制地图视角的能力；
添加图钉、线、圆形区域的能力。
4.3 API Key = 进地图服务中心的钥匙 / 会员卡
“我是这个项目授权的 App，我要使用 Google Maps。”
4.4 AndroidManifest.xml = App 的身份证资料表
AndroidManifest.xml 就像 App 在手机系统里的“登记资料”。
如果 Manifest 没写好，手机系统和 Google Maps SDK 都可能不知道这个 App 到底要干什么。
4.5 Location Permission = 向用户借定位权限
Location Permission 就像你问用户：
用户同意，App 才能读位置。用户拒绝，App 就不能显示真实当前位置。
4.6 Gradle Dependencies = 项目的工具采购清单
Gradle dependencies 就是在告诉项目：
“请把 Google Maps 相关工具下载进来，我的代码要用。”
4.7 GoogleMap Composable = App 页面里的电子地图屏幕
GoogleMap Composable 就是 App 页面中真正显示地图的那块区域。
4.8 CameraPositionState = 你看地图时的镜头
CameraPositionState 不等于用户真实位置。
看墨尔本市中心；
放大到街道；
缩小到整个城市；
移动到用户当前位置。
用户在哪里是一回事；地图镜头正在看哪里是另一回事。
4.9 Marker = 地图上的图钉
4.10 Polyline = 连接图钉的红绳子
如果你在地图上插了多个图钉，Polyline 就像一根线，把这些图钉串起来。
4.11 Distance Calculation = 拿尺子量线长
Distance calculation 就像拿尺子量：
4.12 Circle = 以某个点为中心画服务范围
比如以某个地点为中心画 1km 半径，就可以表示：
1km 内可配送；
1km 内可领取；
1km 内属于服务范围；
1km 外暂时不覆盖。
5. 重点区分容易混淆的概念
5.1 API Key 和 Location Permission 的区别
API Key 不是定位权限；定位权限也不是 API Key。
一个是 Google 给 App 的服务钥匙，一个是用户给 App 的隐私授权。
5.2 Maps SDK for Android 和 GoogleMap Composable 的区别
SDK 是能力来源，GoogleMap Composable 是 UI 中显示地图的组件。
5.3 Gradle dependencies 和 AndroidManifest.xml 的区别
Gradle 解决“代码能不能编译、库有没有引入”。
Manifest 解决“系统和 SDK 知不知道你要用什么权限和 key”。
5.4 LatLng 和 Marker 的区别
LatLng 是“位置数据”，Marker 是“看得见的图钉”。
5.5 Marker、Polyline、Circle 的区别
Marker 是点，Polyline 是线，Circle 是范围。它们都是画在地图上的覆盖元素，但表达的含义不同。
5.6 CameraPositionState 和用户当前位置的区别
地图镜头移动到 Melbourne CBD，不代表用户本人就在 Melbourne CBD。
地图镜头可以看任何地方；用户当前位置需要定位权限和定位数据。
5.7 My Location dot 和 Marker 的区别
蓝色当前位置点不是普通 Marker。Marker 是你主动加的图钉，My Location dot 是用来显示用户位置的特殊地图功能。
5.8 Polyline 和真正导航路线的区别
当前可见材料只显示 Lab 使用 Polyline 画路径和计算总距离，没有显示接入完整导航路线服务。
所以不要默认它已经实现 Google Maps App 那种真正导航。
5.9 “显示地图” 和 “获取当前位置” 的区别
5.10 谁能访问谁？
这里没有看到数据库组件，所以不能把这个 Lab 理解成“有后端数据库的地图系统”。
如果真实项目需要保存用户添加的 Marker，才会额外引入：
Room 本地数据库；
Firebase / Firestore；
后端 API；
云数据库。
6. 这个 Lab 有什么实际用途
这个 Lab 很实用，因为地图能力是很多移动 App 的核心功能。
6.1 在 Android App 开发中的用途
显示附近地点的 App；
店铺定位 App；
活动地点展示 App；
校园地图 App；
取货点选择 App；
旅行路线规划 App；
食物捐赠/领取地点展示 App；
外卖或配送范围展示 App。
比如你之前做过的 FreshGuard 这类食品救援/过期提醒 App，如果未来要加地图功能，就可能需要：
6.2 在云架构里的用途
这个 Lab 让你看到一个真实 App 不是只写前端代码，还需要云端服务支持：
云端开通服务；
云端发放密钥；
客户端配置密钥；
客户端调用第三方服务。
Firebase；
AWS SDK；
Stripe Payment；
OpenAI API；
Mapbox；
Weather API。
6.3 在后端开发里的用途
虽然当前可见材料重点是 Android 前端地图，但真实项目中地图经常会和后端结合。
后端保存用户提交的位置；
后端返回附近地点列表；
后端根据用户位置筛选 1km 内的数据；
后端记录路线、配送距离、服务范围；
后端做权限和审计。
这个 Lab 先让你学会前端地图展示和基础交互，为后端地图功能打基础。
6.4 在 DevOps / 配置管理里的用途
这类任务很像真实项目中的 DevOps 和环境配置工作：不是代码写对就一定能跑，还要云服务、密钥、依赖、权限都配对。
6.5 在安全设计里的用途
不要随便暴露或滥用 API Key；
限制 API Key 的使用范围；
不要在用户未授权时读取位置；
清楚告诉用户为什么需要位置权限；
只收集真正需要的位置数据。
7. 最后画一张生动形象的示意图
如果你的 Markdown 查看器支持 Mermaid，就可以直接渲染成流程图；如果不支持，也可以直接看图里的文字关系。
7.1 文字版流程图
如果你不看 Mermaid，可以用下面这个文字版理解：
最后帮你记忆
这次 Lab 你最应该记住的不是某一行代码，而是下面这个整体逻辑：
API Key 让 App 能用 Google 地图服务；Location Permission 让 App 能读用户位置；LatLng 是坐标；Marker/Polyline/Circle 是画在地图上的点、线、范围；Camera 是地图镜头，不等于用户本人位置。
Android App 页面
↓
GoogleMap 组件
↓
地图相机 Camera 决定当前看哪里
↓
Marker / Polyline / Circle 作为图层画在地图上
用户点击地图某个位置
↓
App 得到这个位置的 LatLng
↓
把这个 LatLng 存进 Marker 列表
↓
地图上显示新的 Marker
Marker A → Marker B → Marker C
点 A 到点 B：300m
点 B 到点 C：500m
总距离：800m
Android App
├─ 使用 API Key 调用 Google Maps 服务
├─ 使用 Gradle 引入地图相关库
├─ 使用 Manifest 声明权限和 key
└─ 在用户授权后读取当前位置
Google Cloud Console
↓
启用 Maps SDK
↓
创建 API Key
↓
Android App 使用地图服务
flowchart TB
T["Google Map Lab：Android Compose 地图功能全流程"]:::title
U["用户\n点击、授权、查看地图"]:::user
APP["Android App\nJetpack Compose UI"]:::app
PERM{"是否获得\nLocation Permission？"}:::decision
LOC["当前位置服务\n获取用户 LatLng"]:::system
DENY["❌ 用户拒绝权限\n不能显示真实当前位置\n不能显示 My Location dot"]:::blocked
MANIFEST["AndroidManifest.xml\n声明权限 + 配置 API Key metadata"]:::config
GRADLE["Gradle dependencies\n引入 Maps / Compose / Utils 相关库"]:::config
CLOUD["Google Cloud Console\n创建/选择项目\n启用 Maps SDK for Android"]:::cloud
KEY["Google Maps API Key\nApp 使用地图服务的钥匙"]:::key
MAPS["Google Maps Platform\n返回地图服务 / 地图数据"]:::cloud
GMAP["GoogleMap Composable\nApp 页面里的地图区域"]:::map
CAMERA["CameraPositionState\n控制地图镜头看哪里"]:::map
LATLNG["LatLng\n经纬度坐标数据"]:::data
MARKER["Marker\n地图图钉：标记一个地点"]:::overlay
CLICK["点击地图\n新增 Marker"]:::overlay
CLEAR["清除 Marker\n让地图恢复干净"]:::overlay
POLYLINE["Polyline\n连接多个点形成路径"]:::overlay
DIST["Distance calculation\n计算路径总距离"]:::overlay
CIRCLE["Circle\n某地点周围 1km 范围"]:::overlay
BADKEY["没有 API Key\n或没有启用 Maps SDK"]:::bad
BADCONF["只有代码\n但 Manifest / Gradle 没配好"]:::bad
BADPERM["只有权限声明\n但用户没有同意"]:::bad
XMAP["❌ 地图可能无法正常加载"]:::blocked
XLOC["❌ 不能读取用户真实位置"]:::blocked
CORE["你要记住的核心区别：\nAPI Key = App 使用 Google 地图服务的钥匙；\nLocation Permission = 用户允许 App 读取位置；\nLatLng = 坐标数据；\nMarker / Polyline / Circle = 画在地图上的视觉元素；\nCamera = 地图镜头视角，不等于用户真实位置。"]:::summary
T --> U
U --> APP
APP --> MANIFEST
APP --> GRADLE
MANIFEST --> KEY
KEY --> CLOUD
CLOUD --> MAPS
MAPS --> GMAP
GRADLE --> GMAP
APP --> PERM
PERM -- "允许" --> LOC
PERM -- "拒绝" --> DENY
LOC --> LATLNG
LATLNG --> GMAP
GMAP --> CAMERA
GMAP --> MARKER
GMAP --> CLICK
CLICK --> MARKER
CLICK --> POLYLINE
POLYLINE --> DIST
GMAP --> CIRCLE
GMAP --> CLEAR
BADKEY -.-> XMAP
BADCONF -.-> XMAP
BADPERM -.-> XLOC
DENY --> XLOC
XMAP --> CORE
XLOC --> CORE
DIST --> CORE
CIRCLE --> CORE
classDef title fill:#1f2937,color:#ffffff,stroke:#111827,stroke-width:2px;
classDef user fill:#fef3c7,color:#111827,stroke:#f59e0b,stroke-width:1.5px;
classDef app fill:#dbeafe,color:#111827,stroke:#2563eb,stroke-width:1.5px;
classDef decision fill:#ede9fe,color:#111827,stroke:#7c3aed,stroke-width:1.5px;
classDef config fill:#e0f2fe,color:#111827,stroke:#0284c7,stroke-width:1.5px;
classDef cloud fill:#dcfce7,color:#111827,stroke:#16a34a,stroke-width:1.5px;
classDef key fill:#fef9c3,color:#111827,stroke:#ca8a04,stroke-width:1.5px;
classDef map fill:#ccfbf1,color:#111827,stroke:#0f766e,stroke-width:1.5px;
classDef data fill:#f3e8ff,color:#111827,stroke:#9333ea,stroke-width:1.5px;
classDef overlay fill:#fae8ff,color:#111827,stroke:#c026d3,stroke-width:1.5px;
classDef system fill:#e5e7eb,color:#111827,stroke:#4b5563,stroke-width:1.5px;
classDef bad fill:#fee2e2,color:#991b1b,stroke:#dc2626,stroke-width:1.5px;
classDef blocked fill:#fecaca,color:#7f1d1d,stroke:#dc2626,stroke-width:2px;
classDef summary fill:#fff7ed,color:#111827,stroke:#ea580c,stroke-width:2px;
用户打开 Android App
↓
App 页面由 Jetpack Compose 构建
↓
GoogleMap Composable 显示地图
↓
地图服务来自 Google Maps Platform
↓
App 必须用 API Key 证明自己有资格使用地图服务
↓
API Key 来自 Google Cloud Console，并且需要启用 Maps SDK for Android
同时：
如果 App 想显示用户当前位置
↓
必须在 Manifest 声明 location permission
↓
还要在运行时向用户请求授权
↓
用户同意后，才能获取当前位置 LatLng
↓
地图可以显示 My Location dot，并把 Camera 移动到用户附近
地图上可以额外画：
- Marker：一个地点
- Polyline：连接多个地点的线
- Distance：路径总距离
- Circle：某个点周围 1km 范围
Google Cloud 端：
开项目 → 启用 Maps SDK → 创建 API Key
Android 配置端：
Gradle 加依赖 → Manifest 配 API Key 和权限
App UI 端：
Compose 显示 GoogleMap → Camera 控制视角 → Marker / Polyline / Circle 画地图元素
用户隐私端：
想读取当前位置 → 必须请求 Location Permission → 用户允许后才能显示 My Location dot