Android on 方糖猫Blog

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

Thu, 10 Aug 2023 09:10:00 +0800

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

目标读者：想进入 Android 开发的新人，或者写过一阵 Java/旧版 XML 布局、想切换到现代技术栈（Kotlin + Compose）的同学。
知识骨架参考《Android 编程权威指南》（Big Nerd Ranch Guide），结合 2026 年的技术现状做了取舍，按「由浅入深」重新编排。
姊妹篇：《前端 UI 开发从入门到精通（Vue 技术栈）》——写 UI 的心法，两端是相通的。

全文共八篇，顺序就是学习的顺序——每一篇都依赖前一篇打下的基础：

flowchart LR
    A["一 环境搭建<br/>能跑起 Hello World"] --> B["二 Kotlin 基础<br/>语法 + 协程"]
    B --> C["三 Compose 界面<br/>写出第一个页面"]
    C --> D["四 架构与生命周期<br/>从写页面到写应用"]
    D --> E["五 网络与存储<br/>数据从哪来 存到哪去"]
    E --> F["六 系统能力<br/>定位 通知 唤醒 适配"]
    F --> G["七 质量与发布<br/>测试 调试 签名上线"]
    G --> H["八 AI 时代<br/>让 AI 写 80% 的代码"]
    style H fill:#e8f4e8

为什么是这个顺序？前三篇解决「能不能写出来」；第四篇解决「代码多了以后会不会散架」；第五、六篇解决「能不能和服务器、和操作系统打交道」；第七篇解决「敢不敢发给真实用户」；第八篇解决「如何持续快下去」。

第一篇环境搭建：90% 的新人倒在这一关

先泼一盆冷水再给你信心：Android 开发的门槛不在写代码，而在环境。新人放弃 Android 的第一大原因不是学不会语法，而是装了三天 Android Studio 跑不起来一个 Hello World。所以环境放在最前面，并且写得足够细。

1.1 你需要安装的三样东西

flowchart TD
    A["JDK 17+<br/>编译 Kotlin/Java 的底座"] --> D["Android Studio"]
    B["Android SDK<br/>系统 API + 平台工具 adb"] --> D
    C["Android Emulator<br/>或一台真机"] --> D
    D --> E["能跑起 Hello World<br/>= 入门完成一半"]

好消息是 2026 年的 Android Studio 已经是「全家桶」安装：下载安装包一路 Next，JDK（内嵌 JBR）、SDK、模拟器全都有了。真正需要你动手的只有三件事：

下载地址认准官方：developer.android.google.cn（国内可直连）。别去下载站，装到捆绑了全家桶的旧版本是新人常见悲剧。
第一次启动时让它下载 SDK，默认勾选 Android SDK Platform、SDK Build-Tools、Android Emulator 即可。
配环境变量（命令行构建和 AI 工具都会用到）：

# Windows: 系统环境变量里添加
ANDROID_HOME=C:\Users\你的用户名\AppData\Local\Android\Sdk
# Path 里追加
%ANDROID_HOME%\platform-tools   # adb 在这里
%ANDROID_HOME%\cmdline-tools\latest\bin

验证：新开一个终端跑 adb version，有输出即成功。

1.2 第一个项目：别折腾，用模板

New Project → Empty Activity（注意选 Empty Activity，这是 Compose 模板；不要选带 “Views” 后缀的，那是旧 XML 布局）。点 Run，等模拟器起来，看到 “Hello Android” 就算通关。

1.3 踩坑故事一：Gradle 同步转了一小时的圈

现象：新建项目后底部状态栏 “Gradle Sync” 转圈一小时不动，或者报 Could not resolve com.android.tools.build:gradle:x.x.x。

原因：Gradle 要从国外 Maven 仓库下载几百 MB 的构建工具和依赖，国内直连极慢。这是国内 Android 新人的「成人礼」。

解法：给项目根目录的 settings.gradle.kts 换上国内镜像（阿里源）：

// settings.gradle.kts
pluginManagement {
    repositories {
        maven("https://maven.aliyun.com/repository/gradle-plugin")
        maven("https://maven.aliyun.com/repository/google")
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        maven("https://maven.aliyun.com/repository/google")
        maven("https://maven.aliyun.com/repository/central")
        google()
        mavenCentral()
    }
}

教训：镜像要放在 google() 前面，Gradle 按顺序找，先命中镜像就不用走官方源了。同样的思路适用于一切包管理器（npm、pip、Maven）——「换源」是国内开发者的通用生存技能。

1.4 踩坑故事二：AGP、Gradle、JDK 的三角恋情

现象：拉下同事的项目，构建报错 Unsupported class file major version 65 或 Minimum supported Gradle version is x.x。

原因：Android 开发有三个版本必须互相匹配，这是新人最懵的地方：

flowchart TD
    A["Android Gradle Plugin (AGP)<br/>项目级 build.gradle 里声明"] -->|"要求"| B["Gradle 版本<br/>gradle-wrapper.properties"]
    A -->|"要求"| C["JDK 版本<br/>Android Studio 内嵌或系统"]
    B -.->|"版本对照表<br/>查官方文档"| C
    style A fill:#fff3cd

AGP 8.x 要求 Gradle 8.x + JDK 17。
报错时不要瞎改，打开 Google 官方的「Android Gradle 插件版本说明」对照表，三者对齐。

教训：项目里 gradle-wrapper.properties 锁定了 Gradle 版本是有深意的——它保证任何同事、任何 CI 机器拉下代码构建结果一致。新人最容易犯的错就是全局升级 Gradle 然后所有老项目全炸。

第二篇 Kotlin 基础：写给会别的语言的人

环境通了，接下来是语言。如果你会 Java 或 JavaScript，这一篇很快；如果是零基础，建议搭配《Kotlin 核心编程》或官方教程把例子都敲一遍。

2.1 十分钟速览：和 Java/JS 的核心差异

// 1. val / var：不可变优先
val name = "方糖猫"        // 不可变，类似 const
var age = 3               // 可变
// age = "三"             // ❌ 类型推导为 Int，改 String 编译报错

// 2. 空安全：类型系统层面消灭 NPE
var nickname: String? = null
// nickname.length        // ❌ 编译不过，必须处理 null
val len = nickname?.length ?: 0   // ?. 安全调用 + ?: 默认值

// 3. when 表达式：加强版 switch
val desc = when (age) {
    in 0..2 -> "幼猫"
    3 -> "壮年"
    else -> "老猫"
}

// 4. data class：一行顶 Java 五十行
data class User(val id: Long, val name: String, val email: String = "")
// 自动生成 equals/hashCode/toString/copy

// 5. 函数式：lambda 和集合操作
val names = users.filter { it.name.isNotBlank() }
                 .map { it.name }

// 6. 扩展函数：给别人的类加方法
fun String.isEmail(): Boolean = this.contains("@")
"ftmao@example.com".isEmail()   // true

空安全是 Kotlin 最值得吹的设计。Java 程序员的一生之敌 NullPointerException，在 Kotlin 里被类型系统提前拦下——String? 和 String 是两个不同的类型，编译器强迫你处理 null。

2.2 协程：异步代码同步写

App 开发的核心动作是「发起网络请求 → 更新界面」，而且网络请求绝不能跑在主线程（否则界面卡死，系统直接弹 ANR 杀掉你的 App）。协程让这件事写得像同步代码：

// viewModelScope 是 ViewModel 自带的协程作用域，页面销毁自动取消
fun loadUsers() {
    viewModelScope.launch {
        _uiState.value = UiState.Loading
        try {
            // withContext(Dispatchers.IO) 切到 IO 线程执行耗时操作
            val users = withContext(Dispatchers.IO) {
                api.getUsers()        // 挂起函数：等结果，但不阻塞线程
            }
            _uiState.value = UiState.Success(users)   // 回到主线程更新 UI
        } catch (e: Exception) {
            _uiState.value = UiState.Error(e.message ?: "未知错误")
        }
    }
}

sequenceDiagram
    participant UI as 主线程(UI)
    participant CO as 协程
    participant IO as IO 线程池
    UI->>CO: viewModelScope.launch
    CO->>IO: withContext(IO) 发起网络请求
    Note over UI: 主线程不阻塞<br/>界面照常响应触摸
    IO-->>CO: 请求返回
    CO-->>UI: 切回主线程更新状态
    UI->>UI: Compose 自动重组界面

思考：协程最难的不是语法，是「作用域」的概念——协程挂在谁的 scope 上，决定了它什么时候被取消。用 viewModelScope 而不是裸 GlobalScope.launch，你的协程就会随页面销毁自动取消，不会内存泄漏。这是面试高频题，更是线上事故高频源。现在只需要记住结论，第四篇讲完生命周期后你会真正理解为什么。

第三篇用 Compose 写出第一个界面

语言有了，马上写界面——学习正反馈来得越早越好。

3.1 从 XML 到 Compose：一次范式革命

旧时代的 Android UI 是「XML 写布局 + Java/Kotlin 找控件 + 手动 setText」，命令式的，状态和视图靠人肉同步。Compose 是声明式的：UI 是状态的函数。

flowchart LR
    subgraph old["旧时代：命令式"]
        A1["XML 布局"] --> B1["findViewById"] --> C1["手动 setText/setVisibility"]
        C1 --> D1["状态变了？<br/>记得手动再 set 一遍<br/>(漏了就出 bug)"]
    end
    subgraph new["Compose：声明式"]
        A2["状态 State"] -->|"状态变化自动触发重组"| B2["@Composable 函数<br/>UI = f(state)"]
    end
    style new fill:#e8f4e8

写过 Vue/React 的人会秒懂——这和前端框架的响应式是同一种思想，只是语法换成了 Kotlin。

3.2 主流 UI 组件「库」：答案比前端简单

前端有 Element Plus / Ant Design / Naive UI 群雄割据，Android 的答案简单得多：

flowchart TD
    Q{"做什么样的 App？"}
    Q -->|"绝大多数情况"| A["Material 3 (material3)<br/>官方出品 随 SDK 维护"]
    Q -->|"要高度自定义设计"| B["Compose Foundation 无样式组件<br/>+ 自建 Design System"]
    Q -->|"跨端 iOS + Android"| C["Compose Multiplatform<br/>或 Flutter(另一条技术栈)"]

Material 3（androidx.compose.material3）：官方组件库，Button、Card、TextField、Dialog、Scaffold、NavigationBar 一应俱全，且深度适配系统特性（深色主题、动态取色）。先用它，用到不够用再谈别的。这和前端「别和组件库对着干」是同一个道理——对抗官方设计体系的自定义，维护成本极高。
accompanist 已成历史：早年 Compose 功能不全，靠 accompanist 库补（下拉刷新、权限等），2026 年这些能力已全部并入官方库，新项目不要再引入。
第三方生态里值得一提的：Coil（图片加载，事实标准）、Compose Destinations（类型安全导航）。

3.3 Demo：一个五脏俱全的登录页

把 Kotlin、协程、Compose、Material 3 串起来——这是每个 App 都有的页面：

@Composable
fun LoginScreen(viewModel: LoginViewModel = viewModel()) {
    val state by viewModel.uiState.collectAsState()

    Scaffold { padding ->
        Column(
            modifier = Modifier
                .padding(padding)
                .fillMaxSize()
                .padding(24.dp),
            verticalArrangement = Arrangement.Center,
        ) {
            OutlinedTextField(
                value = state.email,
                onValueChange = viewModel::onEmailChange,
                label = { Text("邮箱") },
                isError = state.emailError != null,
                supportingText = { state.emailError?.let { Text(it) } },
                modifier = Modifier.fillMaxWidth(),
            )
            Spacer(Modifier.height(16.dp))
            OutlinedTextField(
                value = state.password,
                onValueChange = viewModel::onPasswordChange,
                label = { Text("密码") },
                visualTransformation = PasswordVisualTransformation(),
                modifier = Modifier.fillMaxWidth(),
            )
            Spacer(Modifier.height(24.dp))
            Button(
                onClick = viewModel::login,
                enabled = !state.loading,
                modifier = Modifier.fillMaxWidth(),
            ) {
                if (state.loading) {
                    CircularProgressIndicator(Modifier.size(20.dp))
                } else {
                    Text("登录")
                }
            }
        }
    }
}

对应的 ViewModel，注意状态管理的写法：

data class LoginUiState(
    val email: String = "",
    val password: String = "",
    val emailError: String? = null,
    val loading: Boolean = false,
)

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(LoginUiState())
    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()

    fun onEmailChange(v: String) {
        _uiState.update { it.copy(email = v, emailError = null) }
    }

    fun login() {
        val s = _uiState.value
        if (!s.email.contains("@")) {
            _uiState.update { it.copy(emailError = "邮箱格式不对") }
            return
        }
        viewModelScope.launch {
            _uiState.update { it.copy(loading = true) }
            try {
                delay(1500)  // 假装发请求
                // api.login(s.email, s.password)
                _uiState.update { it.copy(loading = false) }
            } catch (e: Exception) {
                _uiState.update { it.copy(loading = false) }
            }
        }
    }
}

设计要点（这些比语法值钱）：

单一数据源：整个页面的所有状态装进一个 UiState data class，UI 只读它。改状态用 update { it.copy(...) } 不可变更新，和前端 Redux/Pinia 一个思想。
UI 状态的状态机：登录按钮有「正常 / 加载中 / 禁用」形态，错误有「无错 / 有错」形态——「UI 本质是状态机」，在任何平台都成立。

3.4 踩坑故事三：列表滑动卡成 PPT

现象：LazyColumn 展示 500 条消息，滑动掉帧明显。

排查与解法，按出现频率排序：

flowchart TD
    A["LazyColumn 卡顿"] --> B{"Composable 里<br/>有耗时计算吗？"}
    B -->|"有，最常见"| C["用 remember 缓存计算结果<br/>remember(list) { expensive(list) }"]
    B -->|"没有"| D{"item 有稳定的 key 吗？"}
    D -->|"没写 key"| E["items(list, key = { it.id })<br/>没 key 时位置变动全量重组"]
    D -->|"写了"| F{"在 Debug 包测的？"}
    F -->|"是，冤枉了"| G["换 Release 包测！<br/>Debug 包 Compose 性能差数倍"]
    style G fill:#ffe4e1

教训：第三条最坑——Compose 的 Debug 包性能不代表线上。无数新人在 Debug 包测出「卡顿」，花两天优化，打完 Release 包发现根本不卡。性能问题永远以 Release 包为准。

3.5 踩坑故事四：旋转屏幕，数据全没了

现象：页面填了一半表单，用户一转屏幕，输入全没了。

原因：旋转屏幕默认会销毁并重建 Activity。存在 Composable 局部变量里的状态随重建灰飞烟灭。

解法分三层，按持久程度选：

// 1. remember：只管重组不丢，不管重建 —— 最弱
var text by remember { mutableStateOf("") }

// 2. rememberSaveable：重建也能恢复（进 Bundle，有大小限制）
var text by rememberSaveable { mutableStateOf("") }

// 3. ViewModel + StateFlow：配置变更（旋转、深浅色切换）都不丢 —— 正道
//    状态放 ViewModel 里，Activity 重建 ViewModel 不重建

感悟：Android 的「生命周期地狱」本质上是系统在告诉你：UI 是廉价的，随时会被销毁；状态是珍贵的，要放在比 UI 活得久的地方。这个坑也是下一篇的入口——旋转只是「销毁」的一种，更狠的还在后面。

第四篇架构与生命周期：从「写页面」到「写应用」

前三篇你能写出一个页面了。但真实 App 是几十个页面、在几亿台不可控的设备上被随意切换、随时被杀。这一篇建立组织代码的地基——《Android 编程权威指南》全书真正想教的就是这一篇的东西。

4.1 Activity 生命周期：不是八股，是保命符

生命周期回调几乎每个教程都有，但多数人只背了图没理解「什么时候会走哪条边」：

stateDiagram-v2
    [*] --> onCreate: 启动
    onCreate --> onStart
    onStart --> onResume: 获得焦点，可交互
    onResume --> onPause: 被半透明遮挡(弹窗)
    onPause --> onResume: 回到前台
    onPause --> onStop: 完全不可见(跳别的页面/按Home)
    onStop --> onRestart: 从后台回来
    onRestart --> onStart
    onStop --> onDestroy: 用户退出或系统回收
    onDestroy --> [*]

真正值钱的是这两条规则：

可见性配对：onStart/onStop 管「看不看得见」（注册/注销广播监听放这里），onResume/onPause 管「能不能交互」（相机、传感器这类独占资源放这里）。放错层级是资源泄漏的常见来源。
onDestroy 不保证被调用：进程被系统直接杀死时，什么回调都不会来。重要数据不能指望「退出时再保存」。

踩坑故事五：切后台半小时，回来从头再来

现象：用户在表单页填到一半，切出去回了个微信，半小时后切回来，App 重新从启动页加载，填的内容全没了。

原因：这不是 3.5 节旋转屏幕那种配置变更，而是进程死亡（Process Death）——App 在后台久了，系统内存不足时直接杀掉整个进程。ViewModel 也跟着进程一起死了，3.5 节的三层方案全部失效。

解法：ViewModel 里的关键状态用 SavedStateHandle，它会把数据写入进程死亡也能存活的 Bundle：

class FormViewModel(private val state: SavedStateHandle) : ViewModel() {
    // 进程被杀再恢复，draft 还在
    var draft: String
        get() = state["draft"] ?: ""
        set(value) { state["draft"] = value }
}

怎么测试：开发者选项里打开「不保留活动（Don’t keep activities）」，或者在 App 切后台后执行 adb shell am kill <包名> 模拟进程死亡。不测这一关，你永远不知道自己的状态恢复写对了没有——这是权威指南反复强调而多数教程略过的点。

4.2 四大组件与 Intent：Android 的「宪法」

flowchart TD
    A["Activity<br/>一页界面"] --- E["Intent 把它们串起来"]
    B["Service<br/>无界面的后台工作<br/>(今天多由 WorkManager/前台服务承担)"] --- E
    C["BroadcastReceiver<br/>监听系统/应用事件<br/>开机完成 网络变化"] --- E
    D["ContentProvider<br/>跨进程共享结构化数据<br/>联系人 媒体库"] --- E

应知应会的点不在概念，而在分寸：

Intent 分显式/隐式：显式指定类名跳自己 App 的页面；隐式声明「我想看一张图片 / 打开一个网页」，系统找能干的 App 来接。隐式 Intent 配合 intent-filter，就是 Android 应用间协作的全部基础——第六篇的 App 唤醒全靠它。
Task 与返回栈：启动的 Activity 层层叠在一个任务栈里，返回键出栈。第六篇的 launchMode 就是在控制这个栈的行为。
今天的比重：新项目里 Service 大多被 WorkManager 和协程替代，BroadcastReceiver 的系统广播被限制得越来越严，ContentProvider 多数时候你只是「使用者」（读联系人、读相册）。概念要懂，但别再像十年前的教程那样上来先写三个 Service。

4.3 Fragment：Compose 时代怎么看它

权威指南的老版本用了大量篇幅讲 Fragment——它是 View 时代组织页面的核心。2026 年的答案：

新项目：单 Activity + Compose + Navigation 库，页面就是 Composable，不需要 Fragment。
绕不开的场景：维护老项目、集成只有 View 版本的第三方 SDK（某些地图、支付 SDK），以及系统级 UI（如 PreferenceFragmentCompat）。

所以对待 Fragment 的正确姿势是：看懂生命周期比 Activity 多一层（view 的生命周期和 Fragment 本身分离），够用即可，不必深入。把省下的时间投给 Compose。

4.4 架构：MVVM + Repository + 单向数据流

权威指南从 MVC 讲到 MVVM 的演进，核心思想收敛成今天 Google 官方推荐的这张图：

flowchart TD
    subgraph UI层
        A["Composable<br/>只负责渲染和上报事件"]
    end
    subgraph 状态层
        B["ViewModel<br/>持有 UiState(StateFlow)<br/>暴露事件处理函数"]
    end
    subgraph 数据层
        C["Repository<br/>数据的唯一入口<br/>决定走网络还是缓存"]
        D["Retrofit<br/>远程数据"]
        E["Room / DataStore<br/>本地数据"]
    end
    A -->|"用户事件"| B
    B -->|"StateFlow 数据流"| A
    B --> C
    C --> D
    C --> E

三条铁律，比记住「MVVM」三个字母重要得多：

UI 不直接碰网络和数据库——Composable 里出现 Retrofit 调用，就是架构腐烂的开始。
数据向下流，事件向上流（UDF）：UI 只读状态、只发事件，ViewModel 改状态。3.3 节的登录 Demo 就是这个模式。
Repository 是数据的唯一入口：ViewModel 不关心数据来自网络还是 Room 缓存，这让「离线优先」的 App 成为可能——先展示 Room 里的旧数据，网络回来再刷新。

注意这张图里数据层的两个角色——Retrofit 和 Room。它们就是下一篇的主角。

第五篇网络与存储：数据从哪来，存到哪去

架构定了，现在填数据层的肉。这一篇学完，你就能写出「联网 CRUD + 离线缓存」的完整 App 了。

5.1 联网的第一步：权限与明文拦截

踩坑故事六：请求发出去了，App 里却报 CLEARTEXT 错误

现象：Retrofit 请求发出去了，模拟器浏览器也能打开接口地址，App 里却报 CLEARTEXT communication not permitted。

原因，两个新手必踩的组合拳：

AndroidManifest.xml 忘了声明网络权限（Android 不像前端，联网要申请）：

<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Android 9+ 默认禁止 HTTP 明文请求，测试环境是 http:// 就会撞上。开发期放行：

<application
    android:usesCleartextTraffic="true"   <!-- 仅限 debug 包这么干 -->
    ...>

教训：上线前把明文流量关掉，让后端上 HTTPS。安全这类事情，「先放行以后再收」基本等于永远不收。

5.2 Retrofit：网络层的事实标准

移动端网络层的标准组合：Retrofit（定义接口）+ OkHttp（发请求）+ 协程（写异步）。

// 1. 接口定义：挂起函数 + 注解，Kotlin 协程原生支持
interface ApiService {
    @GET("users")
    suspend fun getUsers(@Query("page") page: Int): ApiResponse<List<User>>

    @POST("login")
    suspend fun login(@Body body: LoginRequest): ApiResponse<LoginData>
}

// 2. OkHttp：拦截器统一带 token、打日志、配超时
val okHttp = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .addInterceptor { chain ->
        val req = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer ${TokenHolder.token}")
            .build()
        chain.proceed(req)
    }
    .addInterceptor(HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
    .build()

// 3. Retrofit 组装
val api = Retrofit.Builder()
    .baseUrl("https://api.example.com/")   // ⚠️ 必须以 / 结尾，见踩坑故事七
    .client(okHttp)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
    .create(ApiService::class.java)

踩坑故事七：baseUrl 结尾少了一个斜杠

现象：Retrofit 初始化直接 crash：IllegalArgumentException: baseUrl must end in /。

教训：几乎每个 Android 开发者都撞过一次。顺手记住另一个相关坑：@GET 里的相对路径如果以 / 开头，会丢弃 baseUrl 的路径段——baseUrl("https://x.com/api/") 配 @GET("/users") 实际请求的是 https://x.com/users，/api 没了。

踩坑故事八：拦截器里打印了 body，业务层就拿不到数据了

现象：在自定义拦截器里写了 response.body()!!.string() 打日志，结果业务层解析永远失败。

原因：OkHttp 的响应体是流，只能消费一次。

解法：打日志用官方 HttpLoggingInterceptor（上面 Demo 里已带）；自定义拦截器里要读内容，用 peekBody：

val bodyText = response.peekBody(1024 * 1024).string()  // ✅ 复制一份读，不影响原流

移动端特有的提醒：手机用户会进电梯、进地铁、切 Wi-Fi 和流量，弱网和断线是常态而不是异常。超时必须配、失败要给重试入口、一次抖动失败别急着弹「网络异常」的全屏错误——静默重试一次，体验天差地别。

5.3 本地存储：四个层级，各管各的

「存东西」在 Android 里不是一件事，先想清楚存什么：

flowchart TD
    Q{"要存什么？"}
    Q -->|"键值对<br/>设置项 / token"| A["DataStore<br/>(SharedPreferences 的接班人)"]
    Q -->|"结构化数据<br/>离线缓存 / 消息列表"| B["Room 数据库<br/>(下一节详解)"]
    Q -->|"图片 / 日志 / 大文件"| C["App 私有目录<br/>context.filesDir"]
    Q -->|"要存进相册 / 共享给用户"| D["MediaStore API<br/>(不要直接写 /sdcard)"]

键值存储的 Demo，协程化的 DataStore 用法：

val Context.dataStore by preferencesDataStore(name = "settings")
val KEY_TOKEN = stringPreferencesKey("token")

suspend fun saveToken(context: Context, token: String) {
    context.dataStore.edit { it[KEY_TOKEN] = token }
}

// 读取是 Flow，可以在 ViewModel 里直接 collect
val tokenFlow: Flow<String?> = context.dataStore.data.map { it[KEY_TOKEN] }

踩坑故事九：SharedPreferences 引发的 ANR

现象：老项目用户反馈「切换页面偶尔卡死」，ANR 日志里堆栈停在 QueuedWork.waitToFinish()。

原因：SharedPreferences.apply() 号称异步，但系统会在 Activity 停顿时把磁盘写入队列 flush 完才放行——数据多了，主线程就在这等着。另外首次 getSharedPreferences() 的读盘也发生在主线程。

解法：新项目一律 DataStore（协程挂起，天然不阻塞主线程）；老项目遇到这类 ANR，迁移 DataStore 是治本方案。

踩坑故事十：targetSdk 升到 30，读不到文件了

现象：原来「把文件存到 /sdcard/Download」的代码，升级 targetSdk 后全部失败。

原因：Android 10 引入分区存储（Scoped Storage），App 再也不能随意读写公共目录了。

解法分级：

App 自己的文件 → 用 context.filesDir / cacheDir，不需要任何权限，卸载自动清理。
图片视频要进相册 → 走 MediaStore API。
让用户选文档 → 走 SAF（系统文件选择器）。
想申请 MANAGE_EXTERNAL_STORAGE 一把梭？Google Play 会拒审，除非你是文件管理器类 App。

感悟：分区存储当年被骂得很惨，但回头看是对的——它终结了「每个 App 都在 SD 卡根目录拉一坨文件夹」的蛮荒时代。适配它的正确姿势不是对抗（到处找绕过方案），而是按数据的归属选 API：属于自己的放私有目录，属于用户的走 MediaStore。

5.4 Room：编译期检查 SQL 的数据库

结构化数据（消息列表、账单、离线缓存）的答案。完整三件套 Demo：

// 1. Entity：一张表
@Entity(tableName = "expenses")
data class Expense(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val title: String,
    val amount: Double,
    val createdAt: Long,
)

// 2. DAO：操作表的方法，SQL 在编译期校验
@Dao
interface ExpenseDao {
    @Query("SELECT * FROM expenses ORDER BY createdAt DESC")
    fun observeAll(): Flow<List<Expense>>   // 返回 Flow：数据变了 UI 自动更新

    @Insert
    suspend fun insert(expense: Expense)

    @Delete
    suspend fun delete(expense: Expense)
}

// 3. Database：单例持有
@Database(entities = [Expense::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun expenseDao(): ExpenseDao
}

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app.db").build()

@Query 返回 Flow 是 Room 最优雅的用法——数据库一变，Flow 发射新值，Compose 自动重组，「增删改 → 界面刷新」这条链路不用写一行通知代码。

踩坑故事十一：加了个字段，老用户升级就闪退

现象：新版给 Expense 加了一个 category 字段，自己测没问题，上线后老用户打开就崩：IllegalStateException: A migration from 1 to 2 was required。

原因：Room 用 version 管理表结构。老用户手机里的库还是 version 1 的结构，新代码按 version 2 读，Room 要求你提供 Migration（怎么从 1 迁移到 2），你没有提供。

解法：

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE expenses ADD COLUMN category TEXT NOT NULL DEFAULT ''")
    }
}
Room.databaseBuilder(...)
    .addMigrations(MIGRATION_1_2)
    // 开发期偷懒可以用 .fallbackToDestructiveMigration()（清库重建）
    // 上线前必须删掉 —— 那是拿用户数据开玩笑
    .build()

教训：数据库字段变更和接口变更一样，是对存量用户的承诺。每次改 Entity，先想「老用户的库里有什么」。

第六篇系统能力：定位、通知、唤醒与平台适配

到这里，你的 App 已经「自成一体」了。这一篇让它和操作系统、和其他 App、和真实世界的几亿台设备打交道。系统能力的坑有一个共同特征：Demo 里都好好的，一到用户手机上就出事。

6.1 定位：别再用 LocationManager 了

官方推荐的是 Google Play 服务里的 FusedLocationProviderClient——它自动在 GPS、基站、Wi-Fi 之间选最优来源，比你手写 LocationManager 监听省心得多。

权限申请的关键流程（Android 12 之后有变化）：

flowchart TD
    A["请求定位权限<br/>ACCESS_FINE + ACCESS_COARSE"] --> B{"用户怎么选的？"}
    B -->|"精确授权"| C["高精度定位<br/>米级"]
    B -->|"Android 12+ 只给『大致位置』"| D["只有约 3km 精度<br/>⚠️ 代码必须兼容这种情况"]
    B -->|"拒绝"| E["优雅降级<br/>引导手动选择城市"]
    B -->|"需要后台定位"| F["必须再单独申请<br/>ACCESS_BACKGROUND_LOCATION<br/>且只能跳设置页让用户手动开"]

获取定位的 Demo（配合 kotlinx-coroutines-play-services 的 await()）：

val fused = LocationServices.getFusedLocationProviderClient(context)

suspend fun getCurrentLocation(): Location? {
    return try {
        fused.getCurrentLocation(
            Priority.PRIORITY_HIGH_ACCURACY,
            CancellationTokenSource().token,
        ).await()
    } catch (e: SecurityException) {
        null   // 权限被收回
    }
}

踩坑故事十二：定位永远是 null，或者位置是三天前的

现象：getLastLocation() 一会儿返回 null，一会儿返回几个小时前的旧坐标。

原因：这个方法只是读系统缓存——最近有别的 App 定位过才有值，它自己不会发起定位。

解法：像上面 Demo 那样用 getCurrentLocation() 主动请求一次新定位。需要持续追踪（跑步轨迹这类）再用 requestLocationUpdates()。

踩坑故事十三：坐标偏了五百米，人都站到河里了

现象：GPS 拿到的经纬度画到高德地图上，位置偏移了几百米，用户「站在」马路对面的河里。

原因：国内坐标系的经典天坑——世界上同时存在三种坐标：

flowchart LR
    A["GPS 芯片原始坐标<br/>WGS-84"] -->|"国测局加密算法"| B["GCJ-02 火星坐标<br/>高德/腾讯/Google 国内用"]
    B -->|"百度再加密一次"| C["BD-09<br/>百度地图专用"]
    A -.->|"直接画到高德地图<br/>❌ 偏移 300-600 米"| D["线上事故"]
    style D fill:#ffe4e1

教训：用什么地图 SDK 就转成什么坐标。FusedLocationProviderClient 返回的是 WGS-84，上高德地图前先用高德 SDK 的 CoordinateConverter 转 GCJ-02；接百度地图就转 BD-09。永远不要自己写转换算法，加密参数不公开，网上的「破解版公式」精度堪忧。

6.2 消息通知：两段历史决定了今天的写法

通知 API 看着简单，但它是 Android 版本行为变更的重灾区。先记住这两个分水岭：

flowchart LR
    A["Android 8 (API 26)<br/>通知必须归属<br/>NotificationChannel"] --> B["Android 13 (API 33)<br/>通知变成运行时权限<br/>POST_NOTIFICATIONS"]
    B --> C["今天的完整姿势<br/>建渠道 + 申请权限<br/>缺一不可"]

完整 Demo：

// 第 1 步：建渠道（App 启动时建，重复调用无副作用）
val channel = NotificationChannel(
    "order",                          // 渠道 id
    "订单消息",                        // 用户在系统设置里看到的名字
    NotificationManager.IMPORTANCE_HIGH,
)
context.getSystemService(NotificationManager::class.java)
    .createNotificationChannel(channel)

// 第 2 步：Android 13+ 运行时申请权限
val launcher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { granted -> /* 记录用户选择，别循环弹 */ }
launcher.launch(Manifest.permission.POST_NOTIFICATIONS)

// 第 3 步：发通知
val notification = NotificationCompat.Builder(context, "order")
    .setSmallIcon(R.drawable.ic_notification)   // 必须，否则直接抛异常
    .setContentTitle("订单已发货")
    .setContentText("您的包裹正在派送")
    .setAutoCancel(true)                        // 点击后自动消失
    .build()
NotificationManagerCompat.from(context).notify(1, notification)

踩坑故事十四：通知死活不显示

按出现概率排查：

flowchart TD
    A["通知不显示"] --> B{"建 Channel 了吗？"}
    B -->|"没建（Android 8+ 直接静默丢弃）"| C["补上 createNotificationChannel"]
    B -->|"建了"| D{"Channel 的 importance<br/>是不是 LOW/MIN？"}
    D -->|"是"| E["⚠️ 渠道等级一旦创建<br/>代码里改不了！<br/>只能换渠道 id 或引导用户去设置"]
    D -->|"否"| F{"Android 13+ 申请<br/>POST_NOTIFICATIONS 了吗？"}
    F -->|"没申请"| G["补运行时权限申请"]
    style E fill:#ffe4e1

第二个分支最阴：渠道等级创建后被系统记住，你在代码里把 IMPORTANCE_LOW 改成 IMPORTANCE_HIGH 毫无作用，要么换一个新的渠道 id，要么引导用户去系统设置里改。

关于推送（Push）多说两句：本地通知只是通知的一半，另一半是服务器推消息下来。这里国内生态是割裂的：

FCM（Google 推送）在国内不可用。
国内正道是厂商通道：华为、小米、OPPO、vivo、荣耀各自的推送 SDK。它们是系统级通道，App 被杀也能收到。
第三方聚合（个推、极光）可以一套代码接多家厂商通道，小团队首选。
只靠自己的长连接保活推消息？国产 ROM 杀后台从不手软，重要消息（订单、支付）务必走厂商通道。

6.3 App 唤醒：Deep Link、拉起与被拉起

4.2 节讲了隐式 Intent 和 intent-filter 的原理，这一节把它用起来。「唤醒」分两个方向：别人拉起你，你拉起别人。

flowchart TD
    Q{"从哪拉起你的 App？"}
    Q -->|"网页/短信里的 https 链接"| A["App Links<br/>需域名资产验证 体验最好"]
    Q -->|"其他 App / 二维码"| B["自定义 Scheme<br/>myapp://detail/123<br/>简单但可被抢注"]
    Q -->|"通知点击"| C["PendingIntent<br/>配 FLAG_IMMUTABLE"]

Manifest 里声明可唤起入口（Android 12+ 必须显式 android:exported）：

<activity
    android:name=".DetailActivity"
    android:exported="true"
    android:launchMode="singleTask">   <!-- ⚠️ 见踩坑故事十五 -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="ftmao.com"
            android:pathPrefix="/app" />
    </intent-filter>
</activity>

踩坑故事十五：从链接唤起后，页面参数是旧的，或者叠了三四层

现象：App 已在后台时点击链接，打开的还是上次的旧内容；多点几次链接，返回键要按四下才退出去。

原因：默认 launchMode="standard" 每次唤醒都新建一个 Activity 实例，叠在任务栈顶（4.2 节的返回栈）；而且热启动时新参数走 onNewIntent() 回调，不走 onCreate()——只在 onCreate 里读 intent 的代码自然漏掉。

解法：singleTask + 两个入口都处理：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    handleDeepLink(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handleDeepLink(intent)   // 热启动的参数在这里
}

private fun handleDeepLink(intent: Intent?) {
    val id = intent?.data?.lastPathSegment ?: return
    // 跳详情页
}

反方向（你拉起别的 App）的版本坑：Android 11 引入包可见性限制，packageManager.getPackageInfo("com.tencent.mm") 会抛 NameNotFoundException——不是你代码错了，是系统假装微信不存在。需要在 Manifest 里声明 <queries>：

<queries>
    <package android:name="com.tencent.mm" />
</queries>

6.4 平台适配 tips：碎片化才是 Android 的本体

前端适配的是几个浏览器，Android 适配的是「几十种 ROM × 十几个活跃系统版本 × 无数种屏幕」。以下是我项目里反复用到的适配清单：

屏幕与手势

尺寸单位永远 dp/sp，别碰 px；字号用 sp 才能跟随用户的系统字体设置。
Android 15 起强制 edge-to-edge：内容会画到状态栏和手势导航条下面。用 Compose 的 Scaffold + Modifier.padding(paddingValues) 或 WindowInsets 处理，别自己猜状态栏高度。
折叠屏和平板：用 WindowSizeClass 判断屏幕档位切换单栏/双栏布局，别写死「宽度大于 600dp 就是平板」。

深色模式

颜色全部走 MaterialTheme.colorScheme，一个 Color.White 都不要写死。写死颜色的页面在深色模式下就是一块刺眼白斑，而且这种 bug 只在用户半夜打开 App 时才暴露。

版本策略

flowchart LR
    A["minSdk 26<br/>覆盖 95%+ 活跃设备"] --> B["targetSdk 跟着<br/>Google Play 年度要求走"]
    B --> C["行为变更按版本处理<br/>Build.VERSION.SDK_INT 分支"]
    C --> D["能力检测优于版本判断<br/>能查权限就查权限"]

踩坑故事十六：小米上好好的，华为上定时任务就是不执行

现象：提醒功能在小米、Pixel 上正常，部分华为、OPPO 用户反馈「到点不提醒」。

原因：国产 ROM 的后台管控比原生 Android 激进得多——自启动权限、电池优化白名单、后台弹出界面权限，每家厂商的名称、入口、默认策略都不一样。原生 API 层的 AlarmManager、前台服务，到了这些 ROM 上随时可能被「省电策略」干掉。

解法：

周期性、可延迟的任务用 WorkManager——它是 Google 专门为解决各厂商后台差异做的兼容层，会根据系统能力自动选底层实现。
必须精确到点的（闹钟类），检测并引导用户跳转对应设置页（Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS 等），文案讲清楚「不开会怎样」。
重要消息走 6.2 节说的厂商推送通道，别指望自己保活。

感悟：适配的终极心法只有一句——不要假设环境，永远做能力检测。if (Build.VERSION.SDK_INT >= 33)、if (checkSelfPermission(...) == GRANTED)、if (packageManager.resolveActivity(intent) != null) 这些防御性代码写多了，你就从「在我手机上能跑」毕业到「在所有人手机上能跑」。这也是 Android 开发和前端开发气质上最大的不同：前端的环境是相对可控的浏览器，Android 的环境是几亿台你从没见过的手机。

第七篇质量与发布：从「能跑」到「敢上线」

功能做完只是上半场。这一篇是把 App 交给真实用户之前的最后一道关。

7.1 测试：少但要有

测试金字塔在移动端同样成立，按性价比排：

flowchart LR
    A["单元测试 多写<br/>ViewModel / 工具函数<br/>毫秒级 不依赖设备"] --> B["Compose UI 测试 精选<br/>核心页面渲染与交互"]
    B --> C["端到端 极少<br/>发版前跑主流程"]

单元测试 Demo（ViewModel + 协程，kotlinx-coroutines-test）：

class LoginViewModelTest {
    @Test
    fun `邮箱格式错误时不发起登录`() = runTest {
        val vm = LoginViewModel()
        vm.onEmailChange("not-an-email")
        vm.login()
        assertEquals("邮箱格式不对", vm.uiState.value.emailError)
        assertFalse(vm.uiState.value.loading)
    }
}

Compose UI 测试 Demo：

class LoginScreenTest {
    @get:Rule
    val rule = createComposeRule()

    @Test
    fun 点击登录按钮触发校验提示() {
        rule.setContent { LoginScreen() }
        rule.onNodeWithText("登录").performClick()
        rule.onNodeWithText("邮箱格式不对").assertIsDisplayed()
    }
}

务实建议：别追求覆盖率数字。给「钱相关的计算、状态机的转移、数据解析」这三类写单元测试，给「登录、主列表、下单」这三条主链路写 UI 测试，投入产出比最高。

7.2 调试三板斧：Logcat、adb 与 Layout Inspector

遇到问题时的三板斧，按使用频率排：

Logcat：分级日志 Log.d/e/w，配上明确的 TAG。经验：TAG 用类名，日志里带上关键 id（订单号、用户 id），半年后排查线上问题你会感谢自己。
adb 命令行，高频就这几条：

adb devices                          # 设备列表
adb install app-debug.apk            # 安装
adb shell am start -n 包名/.MainActivity   # 拉起页面
adb shell am kill 包名                # 模拟进程死亡（4.1 节测试用）
adb logcat -s 你的TAG                 # 只看自己的日志

Layout Inspector：Compose 时代的「布局透视镜」，实时看每个 Composable 的重组次数——重组次数异常飙升，就是 3.4 节性能问题的第一现场。

7.3 国际化与无障碍：专业完成度的分水岭

这两件事区分了「能用的 App」和「专业的 App」：

国际化（i18n）

所有文案进 res/values/strings.xml，代码里用 stringResource(R.string.xxx)，一个中文字符串都不要硬编码——今天不国际化，明天产品说「做个英文版」你就要全文搜索替换。
复数用 <plurals>（英文的 1 item / 2 items 规则不同），别用字符串拼接数字。

无障碍（a11y）

图片和图标按钮加 contentDescription（视障用户的屏幕阅读器 TalkBack 靠它朗读）：

IconButton(onClick = onBack) {
    Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "返回")
}

可点击区域不小于 48dp——Material 组件默认满足，自定义 Canvas 绘制按钮时最容易违规。
最后打开 TalkBack 把自己的 App 主流程走一遍，十分钟，胜过读十篇规范。

7.4 发布：签名、混淆与 AAB

1. 签名（Keystore）：Android 用签名识别「同一开发者」。生成 release keystore 后立刻备份到至少两个安全的地方——丢了它，你的 App 永远无法更新，只能换包名重新上架，用户和评分清零。这不是理论风险，是每个公司都流传过的真实事故。

2. 混淆（R8）：Release 包默认开启，压缩、优化、混淆代码。

踩坑故事十七：Debug 包好好的，Release 包登录一直失败

现象：Debug 一切正常，打完 Release 包，接口返回的 JSON 解析出来所有字段都是 null。

原因：R8 把 data class 的字段名混淆成了 a、b、c，而 Gson 默认靠字段名反射匹配 JSON 的 key——名字没了，匹配全落空。

解法，二选一：

// 方案 A：给序列化模型加 keep 规则（proguard-rules.pro）
-keep class com.example.app.data.model.** { *; }

// 方案 B：换 Moshi/kotlinx-serialization，编译期生成适配器，不靠反射

教训：所有验证都必须用 Release 包做最后一遍。Debug 和 Release 的差异（混淆、压缩、日志）大到足以让「我测过了」变成一句空话——3.4 节的性能测量如此，7.4 节的功能验证同样如此。

3. 打包 AAB：Google Play 要求上传 Android App Bundle（.aab）而非 APK，由 Play 按用户设备分发精简后的安装包。versionCode 单调递增（系统靠它判断更新），versionName 给人看。

第八篇 AI 时代：怎么少写一半代码把 App 做出来

前七篇是「内功」，这一篇是「兵器」。我的结论先放在这：AI 没有让 Android 开发变简单，它让「懂行的人」快了 3-5 倍，让「不懂行的人」更快地写出能跑但烂尾的代码。区别在于你怎么用它。

8.1 AI 在 Android 开发各环节的胜任度

flowchart LR
    subgraph good["AI 做得极好 放心交出去"]
        A1["样板代码<br/>ViewModel / data class / Repository"]
        A2["单页面 UI<br/>给我画一个设置页"]
        A3["单元测试"]
        A4["解释报错信息"]
    end
    subgraph mid["AI 能做 但你要盯着"]
        B1["跨页面架构改造"]
        B2["性能优化"]
        B3["依赖升级适配"]
    end
    subgraph bad["AI 做不好 还得靠人"]
        C1["环境/构建问题<br/>(它看不到你的机器)"]
        C2["真机/特定 ROM 才出现的 bug"]
        C3["产品取舍<br/>这个交互要不要做"]
    end

8.2 实战工作流：需求 → App 的 AI 协作五步法

这是我自己做一个新 App 时的真实流程：

第一步：先写「项目宪法」，再让 AI 写代码。 在项目里放一个 AGENTS.md / .cursorrules，写明技术栈和约定：

# 项目约定
- Kotlin + Jetpack Compose + Material 3，不用 XML 布局
- 架构：MVVM + Repository，单向数据流，状态全部走 ViewModel + StateFlow + UiState
- 网络：Retrofit + OkHttp + 协程，挂起函数返回 ApiResponse<T>
- 本地：Room 存结构化数据，DataStore 存键值，定时/后台任务用 WorkManager
- 图片加载用 Coil，导航用 Navigation Compose
- 禁止 GlobalScope；禁止硬编码颜色和文案，一律走 MaterialTheme 和 strings.xml
- Room 改 Entity 必须同步提供 Migration 并升 version

没有这份文件，AI 每次生成代码的风格都随机漂移；有了它，AI 的输出稳定得像团队里最守规矩的那个工程师。注意这份清单里的每一条，都对应着前面某一篇的某个坑——项目宪法本质上是踩坑笔记的浓缩。

第二步：页面级生成，而不是 App 级生成。 不要对 AI 说「给我写一个记账 App」，要说「按项目约定写一个记账首页：顶部本月支出汇总卡片，下面是 LazyColumn 账单列表，每条显示分类图标、备注、金额」。一次一个页面、一个模块，AI 的输出质量和你的可控性都最高。

第三步：让它先写数据层和状态，再写 UI。 先生成 Entity/DAO/Repository + UiState + ViewModel，review 通过后再让它写 Composable——这正是第四、五篇的架构顺序。状态设计错了，UI 写得再漂亮也是白写。

第四步：编译错误直接喂回去。 Android Studio 现在集成了 Gemini，编译报错选中 → 问 AI → 应用修复，循环两三次大部分构建问题都能解决。但 1.3、1.4 那种环境级问题 AI 帮不了你——它看不到你本地的 SDK 装在哪个盘；6.4 那种「只在华为手机上复现」的问题它更帮不了——它没有真机。这就是为什么 AI 篇必须排在最后：它是放大器，放大的是你前七篇的水平。

第五步：人工 review 的四个必查点。 AI 生成的 Android 代码，我每次都只细查四处：① 协程作用域是否用了 viewModelScope（内存泄漏重灾区）；② 状态是否放进了 ViewModel 而不是 remember 在深层 Composable 里（旋转和进程死亡丢数据）；③ 网络/IO 是否切了 Dispatchers.IO（ANR 来源）；④ 权限和版本分支有没有做能力检测（AI 爱写「假设权限已授予」的代码）。其他代码粗看即可——review 的精力要花在 AI 的已知短板上。

8.3 一个真实对比：Demo App 的工时变化

3.3 节那个登录页 + 一个用户列表页的小 Demo，三年前我要写一整天（查 API、调布局、处理状态）。2026 年用 AI 的实际耗时：

pie title 一个双页面 Demo 的 2 小时去哪了
    "写 AGENTS.md 和提示词" : 20
    "AI 生成 + 我 review 修改" : 60
    "环境构建问题排查(AI帮不上)" : 25
    "真机测试与细节打磨" : 15

注意那张饼图里最大的启示：省下来的时间没有消失，它转移到了「描述需求」和「审查代码」上。AI 时代的核心能力从「打字速度」变成了两样：

把模糊需求拆成精确技术任务的能力——你对第四篇架构的理解越深，给 AI 的指令就越准。
快速判断代码对错的能力——这恰恰要求你懂前七篇讲的所有基本功。看不懂协程作用域的人，review 不了 AI 写的 Android 代码。

8.4 思考：AI 是放大器，不是替代品

每次技术圈出现「AI 能不能取代程序员」的争论，我都想起一个类比：计算器没有取代会计，它淘汰了「只会打算盘的会计」，成就了「用计算器做财务分析的会计」。AI 对 Android 开发者的影响一样：

它消灭了记忆型知识的价值（某个 API 的参数顺序，查得再快也不如 AI 直接生成）。
它放大了判断型知识的价值（这个状态该放 ViewModel 还是 Composable？这个版本冲突该升 AGP 还是降 Gradle？这个定时任务该用 WorkManager 还是 AlarmManager？这次 Room 改表要不要写 Migration？）。

所以这篇文章前七篇的内容，在 AI 时代不但没有过时，反而更重要了——它们是你在 AI 写完代码后，能说「对」或者「不对」的全部依据。

结语：学习路线收个尾

flowchart LR
    A["第 1 周<br/>环境搭建 + 跑通模板<br/>+ Kotlin 语法"] --> B["第 2-4 周<br/>Compose 基础<br/>写 5 个静态页面"]
    B --> C["第 2-3 个月<br/>架构 + 网络 + Room<br/>写一个完整的<br/>联网 CRUD App"]
    C --> D["第 3-6 个月<br/>定位/通知/唤醒/适配<br/>测试 签名 发布上架"]
    D --> E["持续<br/>把 AI 变成<br/>你的初级工程师"]

三条反直觉的建议作为结尾：

第一周死磕环境不丢人。每个 Android 老兵都经历过 Gradle 转圈的下午，这不是你笨，是这个生态的真实成本。
用真机开发，而且要用不止一台。模拟器掩盖了低端机的性能问题，单品牌真机掩盖了 ROM 碎片化问题——你的用户分布在十几种厂商的手机上。
让 AI 写代码，让自己写笔记。每踩一个坑记下「现象、根因、下次怎么一眼认出」，这些笔记是 AI 时代你不可被替代的资产——因为 AI 知道所有答案，但它不知道你的项目昨天为什么炸。

祝你的 Gradle 永远秒同步，keystore 永远有备份，App 在华为和小米上都一样坚挺。

基于 UDP 通信的洋葱网络设计：服务器、Android 客户端与 P2P 控制总结

Tue, 19 Dec 2017 10:00:00 +0800

基于 UDP 通信的洋葱网络设计：服务器、Android 客户端与 P2P 控制总结

最近要实现端到端的加密通信，现在把设计方案记录下来。目标读者：刚接触洋葱网络、P2P 或 UDP 信令设计，想了解「怎么用 UDP 搭一个匿名转发网络，再基于它做 P2P」的同学。
阅读目标：建立整体架构图、理解关键模块职责、记住常见踩坑点。

0. 写在前面：为什么用 UDP 做洋葱网络 + P2P 信令？

洋葱网络（Onion Network）的核心思想是：数据像剥洋葱一样，一层一层加密转发。每一跳节点只知道上一跳和下一跳，不知道完整路径，从而保护通信双方的隐私。

传统洋葱路由（如 Tor）多跑在 TCP 上，因为 TCP 可靠、有序。但在移动场景或 P2P 场景里，UDP 有几个独特优势：

开销小：UDP 头只有 8 字节，没有连接建立/拆除开销，适合移动弱网。
NAT 友好：UDP 是 NAT 打洞（Hole Punching）最常用的传输层协议，STUN/TURN/ICE 都优先用 UDP。
适合信令：P2P 建立连接前的「打招呼」消息很短，UDP 足够用；真正的大数据再切到 P2P 直连或中继。
抗审查更灵活：无连接特性让流量更像普通 DNS/QUIC/游戏报文，便于混淆。

但 UDP 也带来问题：

不保证可靠、不保证顺序，需要自己在应用层做重传、去重、拥塞控制。
报文可能被分片、被防火墙限制、被运营商 QoS。

这篇文章会带你从「一个 UDP 报文怎么进洋葱网络」开始，逐步拆解：

洋葱网络的层次结构与加密过程。
服务器（目录服务 + 中继 + 信令服务）应该怎么设计。
Android 客户端的结构与关键代码思路。
怎么用这套 UDP 信令网络做 P2P 控制（NAT 穿透、打洞、直连、中继回退）。
新人最容易踩的坑与规避方法。

1. 洋葱网络核心概念：先建立「知识地图」

1.1 洋葱路由 vs 普通代理的区别

对比项	普通代理	洋葱网络
路径	单跳	多跳（通常 3 跳）
加密	端到端一次加密	每跳一层加密
节点知情范围	代理知道你是谁、你访问哪	每跳只知道上一跳和下一跳
代表	HTTP/SOCKS 代理	Tor、I2P、自定义洋葱网络

1.2 一次洋葱转发的过程

假设 Alice 要给 Bob 发消息，路径为：

flowchart LR
    A[Alice] --> E["入口节点 (Entry)"] --> M["中间节点 (Middle)"] --> X["出口节点 (Exit)"] --> B[Bob]

Alice 会先把报文从后往前逐层加密：

用 Exit 的公钥加密「Exit → Bob 的真实数据」，得到 C3。
用 Middle 的公钥加密「下一站是 Exit + C3」，得到 C2。
用 Entry 的公钥加密「下一站是 Middle + C2」，得到 C1。

然后 Alice 把 C1 发给 Entry。Entry 用自己的私钥解密后，看到「下一站是 Middle」，把 C2 转发给 Middle。Middle 解密后转发 C3 给 Exit。Exit 解密后拿到真实数据，发给 Bob。

flowchart LR
    A[Alice] -->|C1| E[Entry<br/>解密: 下一站 Middle] -->|C2| M[Middle<br/>解密: 下一站 Exit] -->|C3| X[Exit<br/>解密: 真实数据] -->|明文| B[Bob]

新人记忆点：洋葱网络的数据是「加密好的俄罗斯套娃」，每到一个节点就剥掉一层外衣。

1.3 UDP 洋葱报文的基本结构

一个 UDP 洋葱报文可以简单设计为：

+----------------+----------------+----------------+----------------+
|  版本 (1B)     |  命令 (1B)     |    跳数 (1B)   |   预留 (1B)    |
+----------------+----------------+----------------+----------------+
|                        会话 ID / 电路 ID (4B)                       |
+----------------+----------------+----------------+----------------+
|                         下一跳洋葱层数据 ...                       |
+------------------------------------------------------------------+

版本：协议版本，方便后续升级。
命令：路由、数据、建立、销毁、心跳等。
跳数 / TTL：防止报文无限循环，每经过一跳减 1。
会话 ID / 电路 ID：标识一条逻辑链路，让节点知道该用哪把密钥解密。
下一跳洋葱层数据：被当前节点私钥解密后，才能得到真正的下一跳地址和载荷。

新人容易混淆的点：洋葱网络里的「加密」不是端到端 TLS，而是逐跳加密。每一跳都能解密自己最外层，但看不到内层。

2. 系统整体架构

flowchart TB
    subgraph 公网服务层
        DS[Directory Server<br/>目录服务：发布可信节点]
        SS[Signaling Server<br/>信令服务：NAT 信息交换]
        RS[Relay Server<br/>中继服务：UDP 洋葱转发]
    end

    subgraph Android 客户端
        AC[App 业务层]
        CM[Connection Manager<br/>管理 Circuits / Peers]
        OC[Onion Core<br/>分层加密 / 解密]
        NC[Network Core<br/>UDP Socket / NAT / ICE]
    end

    subgraph 对端
        P2P[Peer B<br/>Android / Server / IoT]
    end

    AC --> CM
    CM --> OC
    CM --> NC
    OC --> NC
    NC -->|UDP| RS
    NC -->|UDP| SS
    NC -.->|查询节点列表| DS
    NC -.->|P2P 直连或中继| P2P

2.1 三类服务器职责

服务	职责	协议
Directory Server（目录服务）	维护可信中继节点列表、公钥、负载、版本	HTTPS / UDP 查询
Signaling Server（信令服务）	帮助两个 Peer 交换公网 IP:Port、NAT 类型、候选地址	UDP + 可靠信令协议
Relay Server（中继服务）	当 P2P 打洞失败时，转发 UDP 洋葱流量	UDP 洋葱路由

实际部署中，目录服务可以用 HTTPS 更稳；信令和中继为了速度和 NAT 友好，优先用 UDP。

3. 服务器端设计

3.1 目录服务（Directory Server）

目录服务就像「黄页」，让客户端知道哪些中继节点在线、可信、负载低。

核心数据模型

Node {
    node_id:        节点唯一 ID
    public_key:     Ed25519/X25519 公钥
    endpoint:       公网 IP:UDP 端口
    bandwidth:      声明带宽（Mbps）
    load:           当前负载（连接数 / 带宽占用）
    version:        协议版本
    flags:          入口 / 中间 / 出口 / 中继 标志位
    last_seen:      最后一次心跳时间
    signature:      节点用私钥对以上字段签名
}

客户端获取节点列表的流程

sequenceDiagram
    participant C as Android Client
    participant D as Directory Server
    participant N1 as Node Entry
    participant N2 as Node Middle
    participant N3 as Node Exit

    C->>D: HTTPS GET /nodes?count=3&flags=entry|middle|exit
    D-->>C: 返回节点列表 + 签名
    C->>C: 验证签名、选择路径
    C->>N1: UDP 建立 Circuit 请求
    N1-->>C: 返回 Circuit ID
    C->>N1: 经过 N1 转发到 N2 建立
    N2-->>C: 返回确认
    C->>N2: 经过 N1→N2 转发到 N3 建立
    N3-->>C: 返回确认

新人避坑：目录服务返回的节点列表必须带签名，客户端要校验，否则会被恶意节点钓鱼。

3.2 中继服务（Relay Server）

中继服务是洋葱网络里的「快递员」：收到一个 UDP 报文，解密最外层，转发给下一跳。

核心状态

Circuit {
    circuit_id:     本节点分配的 32 位 ID
    prev_node:      上一跳地址（IP:Port）
    next_node:      下一跳地址（IP:Port）
    shared_key:     与创建者协商的共享密钥
    created_at:     创建时间
    last_active:    最后活跃时间
    bytes_forward:  转发字节数
}

转发流程

flowchart TD
    A[收到 UDP 报文] --> B{报文格式合法?}
    B -->|否| C[直接丢弃]
    B -->|是| D[查找 circuit_id]
    D --> E{存在?}
    E -->|否| C
    E -->|是| F[用 shared_key 解密洋葱层]
    F --> G{解密成功?}
    G -->|否| C
    G -->|是| H[读取下一跳地址 + 内层数据]
    H --> I[TTL - 1]
    I --> J{TTL > 0?}
    J -->|否| K[发送销毁通知]
    J -->|是| L[转发给下一跳]

关键设计点

限速与防滥用：单 Circuit 限制带宽，防止被当免费代理滥用。
TTL 与环检测：每跳 TTL 减 1，到 0 丢弃，防止恶意构造环路。
密钥派生：每个 Circuit 用 X25519 ECDH 协商出共享密钥，再用 HKDF 派出发送/接收两个方向的对称密钥。
无日志策略：中继节点不记录明文内容、不记录完整路径（实际上也看不到）。

3.3 信令服务（Signaling Server）

信令服务是 P2P 的「媒人」：两个 Peer 无法直接找到对方公网地址时，通过信令服务交换信息。

数据模型

PeerInfo {
    peer_id:        用户/设备唯一 ID
    public_key:     用于加密信令的公钥
    nat_type:       全锥型 / 限制型 / 端口限制型 / 对称型
    local_candidates: [局域网 IP:Port, ...]
    srflx_candidates: [STUN 映射后的公网 IP:Port, ...]
    relay_candidates: [TURN 中继地址, ...]
    timestamp:      更新时间
    signature:      防止伪造
}

典型信令流程

sequenceDiagram
    participant A as Peer A
    participant S as Signaling Server
    participant B as Peer B

    A->>S: 注册/上报 PeerInfo（UDP 心跳包）
    B->>S: 注册/上报 PeerInfo

    A->>S: 请求连接 peer_B
    S->>S: 检查 A、B 是否在线
    S-->>A: 返回 B 的候选地址列表
    S-->>B: 转发 A 的连接请求 + A 的候选地址

    A->>A: 按优先级尝试直连 / 打洞
    B->>B: 同时尝试直连 / 打洞
    A-->>B: UDP 打洞成功，建立 P2P
    B-->>A: 业务数据互通

    alt 打洞失败
        A->>S: 请求中继
        S-->>A: 分配 Relay 地址
        S-->>B: 通知 B 通过 Relay 通信
        A->>R: 经中继与 B 通信
    end

新人避坑：信令服务本身不传输业务数据，只传「怎么找到对方」。不要把它当成聊天服务器用。

4. Android 客户端设计

Android 客户端需要同时处理：业务逻辑、洋葱路由、UDP 网络、NAT 穿透、后台保活。建议按层拆分。

4.1 客户端分层架构

flowchart TB
    subgraph 应用层
        UI[UI / ViewModel]
        API[业务 API]
    end

    subgraph 网络中间层
        CM[ConnectionManager<br/>管理多 Circuit / 多 Peer]
        P2P[P2PController<br/>打洞 / 直连 / 中继决策]
        SM[SignalingClient<br/>与信令服务通信]
    end

    subgraph 核心引擎层
        OC[OnionCore<br/>加密 / 解密 / 报文封装]
        NC[NetworkCore<br/>UDP Socket / ICE / STUN]
        CR[CircuitStore<br/>持久化 Circuit 状态]
    end

    UI --> API
    API --> CM
    CM --> P2P
    CM --> SM
    CM --> OC
    P2P --> OC
    P2P --> NC
    SM --> NC
    OC --> NC
    CM --> CR

4.2 关键模块说明

模块	职责	技术要点
`ConnectionManager`	管理所有活跃 Circuit 和 Peer 连接	连接池、复用、超时清理
`P2PController`	决定是否直连、打洞、还是走中继	ICE 候选排序、NAT 类型判断
`SignalingClient`	与信令服务器通信	UDP 心跳、请求/响应匹配、重传
`OnionCore`	分层加密/解密、报文打包	X25519、ChaCha20-Poly1305、HKDF
`NetworkCore`	UDP Socket、STUN/ICE、NAT 类型探测	DatagramChannel、线程模型、电池优化
`CircuitStore`	本地缓存 Circuit 信息	SQLite / MMKV、加密存储

4.3 NetworkCore 线程模型

UDP 网络层要避免在主线程做 IO，也避免一个线程处理所有事导致卡顿。

flowchart LR
    subgraph 网络线程
        RT[ReceiveThread<br/>阻塞 recvFrom]
        RT -->|Raw Packet| DP[DecoderPipeline<br/>STUN / 洋葱 / 业务]
        DP -->|业务消息| MQ[MessageQueue]
        DP -->|信令响应| SR[SignalingResponseMap]
    end

    subgraph 发送线程
        SQ[SendQueue<br/>优先级队列]
        ST[SendThread<br/>定时 flush]
        SQ --> ST -->|sendTo| Socket
    end

    subgraph 业务线程
        BH[BusinessHandler]
        MQ --> BH
    end

    Socket --> RT

4.4 Android 端 NAT 类型探测

客户端启动时，先用 STUN 服务器探测自己的 NAT 类型：

1. 向 STUN Server A 发 Binding Request，得到映射地址 M1。
2. 向 STUN Server B 发 Binding Request，得到映射地址 M2。
3. 比较 M1 和 M2：
   - 相同 → 可能全锥型 / 限制型
   - 不同 → 对称型 NAT（打洞困难）
4. 再测试其他 IP/Port 是否能把包送进本机，判断是限制型还是端口限制型。

flowchart TD
    A[开始探测] --> B[STUN A 请求]
    B --> C[得到 M1]
    C --> D[STUN B 请求]
    D --> E[得到 M2]
    E --> F{M1 == M2?}
    F -->|是| G[全锥 / 限制 / 端口限制]
    F -->|否| H[对称型 NAT]
    G --> I[进一步测试过滤规则]
    H --> J[P2P 大概率失败<br/>优先准备 Relay]

4.5 Android 后台保活与省电

P2P 需要客户端能被找到，但 Android 对后台限制越来越严。

方案	适用场景	注意事项
Foreground Service	需要长期在线	必须显示通知，用户可能反感
WorkManager 周期性心跳	非实时场景	最小间隔 15 分钟，无法保证即时
FCM / 厂商推送	唤醒 App 建立连接	国内厂商通道需要适配
保活 socket + 心跳	与信令服务维持 NAT 映射	心跳间隔建议 15-30s， balancing 电量

新人避坑：不要试图用「双进程守护」「1 像素 Activity」等旧保活手段，Android 高版本会被杀，且应用商店可能下架。

5. 通过 UDP 信令网络实现 P2P 控制

5.1 P2P 连接的三种结果

flowchart TD
    A[Peer A 想连 Peer B] --> B[通过信令服务获取 B 的候选地址]
    B --> C{尝试直连}
    C -->|成功| D[UDP P2P 直连]
    C -->|失败| E{尝试 NAT 打洞}
    E -->|成功| D
    E -->|失败| F[通过 Relay 中继]
    D --> G[业务通信]
    F --> G

5.2 ICE-like 候选地址优先级

graph LR
    A[直连候选<br/>局域网 IP] -->|优先级最高| B[srflx 候选<br/>STUN 映射公网地址]
    B -->|次高| C[prflx 候选<br/>对端看到的地址]
    C -->|再次| D[relay 候选<br/>TURN/中继服务器]

优先级规则：

host 候选：同一局域网直接连，延迟最低。
server reflexive（srflx）：STUN 映射后的公网地址，适合普通 NAT。
peer reflexive（prflx）：对端实际看到的地址，可能在打洞过程中发现。
relay 候选：最后兜底，走服务器转发。

5.3 NAT 打洞详细流程

假设 A 和 B 都在普通家用路由器后，NAT 类型为「端口限制锥型」。

sequenceDiagram
    participant A as Peer A
    participant SA as STUN/Signaling Server
    participant B as Peer B

    A->>SA: 注册：我的 srflx 是 1.1.1.1:10000
    B->>SA: 注册：我的 srflx 是 2.2.2.2:20000

    A->>SA: 请求连接 B
    SA-->>A: 返回 B 的地址 2.2.2.2:20000
    SA-->>B: 转发 A 的地址 1.1.1.1:10000

    A->>B: 发送 UDP 打洞包（可能到达或被过滤）
    B->>A: 发送 UDP 打洞包
    Note over A,B: 双方都先发包，让各自 NAT 建立映射

    A->>B: 收到 B 的包，回确认
    B->>A: 收到 A 的包，回确认
    Note over A,B: 打洞成功，后续直接通信

新人记忆点：NAT 打洞的本质是让双方路由器先记录一条「允许对方包进来」的映射。所以必须双方同时主动发一个包到对方公网地址。

5.4 基于洋葱网络的 P2P 控制通道

除了直接 P2P，还可以把「P2P 控制信令」本身也套在洋葱网络里，增强隐私：

flowchart LR
    A[Alice] -->|洋葱隧道| X[出口节点] --> S[信令服务器]
    B[Bob] -->|洋葱隧道| X

控制消息包括：

请求连接、交换候选地址。
协商加密密钥（用于 P2P 直连后的端到端加密）。
心跳、断开通知。
中继切换通知。

这样即使信令服务器被监控，攻击者也只能看到「某个洋葱出口在发信令」，不知道 Alice 和 Bob 的真实身份。

5.5 P2P 直连后的加密

P2P 直连本身不保证安全，还需要端到端加密：

sequenceDiagram
    participant A as Peer A
    participant S as Signaling Server（洋葱保护下）
    participant B as Peer B

    A->>S: 发送 X25519 公钥 PA
    S->>B: 转发 PA
    B->>S: 发送 X25519 公钥 PB
    S->>A: 转发 PB

    A->>A: ECDH 计算共享密钥 K
    B->>B: ECDH 计算共享密钥 K

    A->>B: 用 K 加密业务数据，UDP P2P 直连发送
    B->>A: 用 K 加密业务数据，UDP P2P 直连发送

新人避坑：洋葱网络的逐跳加密 ≠ P2P 端到端加密。如果数据离开出口节点后是明文，出口节点仍然能看到内容。真正保密需要在 P2P 直连后再做一次端到端加密。

6. 协议报文设计示例

6.1 洋葱路由报文

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version       | Command       | TTL           | Reserved        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        Circuit ID                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+              Encrypted Onion Payload (variable)               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Command 定义示例：

值	命令	说明
0x01	CREATE	建立 Circuit
0x02	CREATED	建立成功响应
0x03	RELAY	中继数据
0x04	DESTROY	销毁 Circuit
0x05	HEARTBEAT	保活心跳

6.2 信令报文

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic (4B)    | Version (1B)  | Command (1B)  | Flags (2B)    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Sequence Number                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Timestamp                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                    Encrypted Payload                          +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

信令 Command 示例：

值	命令	说明
0x10	REGISTER	客户端注册
0x11	OFFER	发起连接请求
0x12	ANSWER	响应连接请求
0x13	CANDIDATE	交换候选地址
0x14	HEARTBEAT	保活
0x15	ERROR	错误通知

新人避坑：UDP 报文要加 Magic 数和版本号，防止收到错乱的广播/扫描包时解析出错。

7. 关键算法与数据结构

7.1 Circuit 选择算法

客户端从目录服务拿到节点列表后，选择一条路径：

def choose_path(nodes, desired_hops=3):
    # 1. 过滤在线、版本兼容、flags 符合要求的节点
    valid = [n for n in nodes if n.is_online and n.version == PROTO_VERSION]
    
    # 2. 按负载和带宽评分，负载越低、带宽越高分越高
    scored = [(n, score(n)) for n in valid]
    scored.sort(key=lambda x: x[1], reverse=True)
    
    # 3. 随机选择前 K 个中的节点，避免总是选同一批
    candidates = scored[:max(len(scored)//3, desired_hops * 2)]
    
    # 4. 确保 Entry、Middle、Exit 来自不同运营商 / 网段，增加路径多样性
    path = []
    for role in ['entry', 'middle', 'exit']:
        chosen = pick_diverse(path, candidates, role)
        path.append(chosen)
    
    return path

7.2 消息可靠性保证

UDP 不保证可靠，应用层需要自己实现：

flowchart TD
    A[发送消息] --> B[分配 Seq]
    B --> C[加入重传队列]
    C --> D[UDP 发送]
    D --> E{收到 ACK?}
    E -->|是| F[从队列移除]
    E -->|否| G{超时?}
    G -->|否| E
    G -->|是| H[重传 N 次]
    H --> I{达到最大重试?}
    I -->|否| C
    I -->|是| J[通知上层失败]

重传策略建议：

初始超时：200ms（RTT 估计）。
退避：指数退避，最多 5 次。
ACK 去重：用滑动窗口或位图记录已确认 Seq。

7.3 连接状态机

P2P 连接可以建模为状态机：

stateDiagram-v2
    [*] --> Idle: 用户发起连接
    Idle --> Gathering: 收集 ICE 候选
    Gathering --> Connecting: 开始打洞/直连
    Connecting --> Connected: 收到对端包
    Connecting --> Relaying: 打洞失败，切中继
    Relaying --> Connected: 中继链路建立
    Connected --> Disconnected: 超时未收到心跳
    Disconnected --> [*]

8. 新人避坑技巧大全

8.1 UDP 层面的坑

坑	现象	规避方法
UDP 报文丢失	部分消息收不到	应用层 ACK + 重传；关键信令走可靠通道
UDP 乱序	消息顺序错乱	按 Seq 排序或丢弃过期包；业务层幂等
UDP 分片	大报文丢失率陡增	控制报文大小 < 1200 字节；必要时分片重组
运营商 QoS	高峰丢包严重	使用常见端口（如 443/8080）或混淆成 QUIC/DNS
防火墙拦截	某些网络 UDP 不通	准备 TCP 回退或 Relay 兜底

8.2 洋葱网络层面的坑

坑	现象	规避方法
Circuit 被重用	旧连接和新连接混用	每个 Circuit 带唯一 ID，过期销毁
时序攻击	入口和出口流量时间关联	引入填充（padding）和混合延迟
恶意出口节点	出口监听或篡改明文	P2P 必须端到端加密，不依赖出口
节点列表被污染	连上恶意节点	目录服务签名 + 节点身份固定 + 信誉系统
密钥管理混乱	加密失败或性能差	一个 Circuit 一对密钥，用 HKDF 派生

8.3 Android 层面的坑

坑	现象	规避方法
主线程网络	ANR / 卡顿	所有 UDP IO 放子线程或用协程
Doze 模式心跳中断	后台连接断开	使用 JobScheduler / WorkManager 补心跳
IPv4/IPv6 双栈	一端 v4 一端 v6 连不上	同时收集 v4/v6 候选地址
端口复用失败	`BindException`	Socket 设置 `SO_REUSEADDR` / `SO_REUSEPORT`
电量消耗高	用户卸载	动态心跳间隔，网络空闲时延长

8.4 P2P / NAT 层面的坑

坑	现象	规避方法
对称型 NAT 打洞失败	两边都收不到包	提前探测 NAT 类型，准备 Relay
hairpin NAT 不支持	同一局域网却走公网	优先尝试 host 候选
NAT 映射超时	长时间没通信后连不上	定期发送心跳保活
双方不同时打洞	一方先发可能被防火墙拦	设计让 A、B 同时主动发包
信令与数据通道混淆	安全边界不清	信令用短期密钥，数据用长期会话密钥

8.5 安全与隐私层面的坑

坑	现象	规避方法
只做了洋葱加密，没做端到端加密	出口节点可读明文	P2P 直连后再做一次 ECDH
时间戳不校验	重放攻击	每个报文带时间戳 + 滑动窗口
随机数可预测	Circuit ID 被猜中	用 SecureRandom / crypto.random
元数据泄露	包大小暴露内容类型	固定包长或随机填充
证书/公钥不校验	中间人攻击	目录服务签名 + 证书锁定

9. 一个最小可运行流程串起来

为了让新人有整体感，下面把一次「Alice 通过 UDP 洋葱网络控制 P2P 连接 Bob」的完整流程串起来。

sequenceDiagram
    participant A as Android Alice
    participant D as Directory Server
    participant S as Signaling Server
    participant R as Relay Server
    participant B as Android Bob

    %% 阶段 1：准备节点
    A->>D: HTTPS 获取节点列表
    D-->>A: 返回 Entry/Middle/Exit + 签名
    A->>A: 校验签名，选择路径
    A->>Entry: UDP CREATE Circuit
    Entry-->>A: CREATED
    A->>Middle: 经 Entry 转发 CREATE
    Middle-->>A: CREATED
    A->>Exit: 经 Entry→Middle 转发 CREATE
    Exit-->>A: CREATED

    %% 阶段 2：注册信令
    A->>S: 经洋葱隧道 REGISTER Alice
    B->>S: 经洋葱隧道 REGISTER Bob

    %% 阶段 3：发起 P2P
    A->>S: OFFER（请求连接 Bob）
    S->>B: 转发 OFFER + Alice 候选地址
    B->>S: ANSWER + Bob 候选地址
    S->>A: 转发 ANSWER

    %% 阶段 4：打洞
    A->>B: UDP 打洞包
    B->>A: UDP 打洞包
    A-->>B: 直连成功

    %% 阶段 5：业务通信
    A->>B: 端到端加密业务数据
    B->>A: 端到端加密业务数据

    %% 阶段 6：失败兜底
    alt 打洞失败
        A->>S: 请求 Relay
        S-->>A: 分配 Relay 地址
        S-->>B: 通知走 Relay
        A->>R: 经洋葱→Relay→Bob
    end

10. 总结：一张图记住全文

flowchart TB
    A[UDP 洋葱网络 + P2P] --> B[目录服务<br/>给节点]
    A --> C[信令服务<br/>撮合 Peer]
    A --> D[中继服务<br/>兜底转发]
    A --> E[Android 客户端<br/>洋葱 + NAT + P2P]
    E --> F[OnionCore<br/>逐跳加密]
    E --> G[NetworkCore<br/>UDP / STUN / ICE]
    E --> H[P2PController<br/>直连 / 打洞 / 中继]
    F --> I[隐私保护]
    G --> J[NAT 穿透]
    H --> K[去中心化通信]
    A --> L[避坑：可靠传输 / 端到端加密 / 后台保活]

核心要点回顾：

洋葱网络用 UDP 是为了轻量、NAT 友好、适合信令；但可靠性和顺序要自己补。
服务器分三类：目录服务（给节点）、信令服务（撮合 P2P）、中继服务（兜底转发）。
Android 客户端分层：业务层、连接管理层、核心引擎层、网络层，不要混在一处。
P2P 控制靠 UDP 信令交换地址，再用 ICE 候选优先级尝试直连、打洞、中继。
隐私不等于安全：洋葱网络保护路径隐私，P2P 业务数据还要端到端加密。
新人最容易踩的坑：UDP 当 TCP 用、忽略 NAT 类型、不做端到端加密、Android 主线程 IO。

参考与延伸阅读

Tor Project: https://www.torproject.org/
ICE / STUN / TURN RFCs: RFC 5245, RFC 5389, RFC 5766
WebRTC NAT Traversal 实践
Android DatagramSocket、WorkManager、Foreground Service 官方文档

如果你正在动手实现，建议先做一个「最小闭环」：一个目录服务 + 一个中继节点 + 两个 Android 客户端，先跑通「Alice 经洋葱网络发一条消息给 Bob」，再逐步加入 P2P 直连和 NAT 打洞。先跑通，再优化。

Android on 方糖猫Blog

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

第一篇 环境搭建：90% 的新人倒在这一关

1.1 你需要安装的三样东西

1.2 第一个项目：别折腾，用模板

1.3 踩坑故事一：Gradle 同步转了一小时的圈

1.4 踩坑故事二：AGP、Gradle、JDK 的三角恋情

第二篇 Kotlin 基础：写给会别的语言的人

2.1 十分钟速览：和 Java/JS 的核心差异

2.2 协程：异步代码同步写

第三篇 用 Compose 写出第一个界面

3.1 从 XML 到 Compose：一次范式革命

3.2 主流 UI 组件「库」：答案比前端简单

3.3 Demo：一个五脏俱全的登录页

3.4 踩坑故事三：列表滑动卡成 PPT

3.5 踩坑故事四：旋转屏幕，数据全没了

第四篇 架构与生命周期：从「写页面」到「写应用」

4.1 Activity 生命周期：不是八股，是保命符

4.2 四大组件与 Intent：Android 的「宪法」

4.3 Fragment：Compose 时代怎么看它

4.4 架构：MVVM + Repository + 单向数据流

第五篇 网络与存储：数据从哪来，存到哪去

5.1 联网的第一步：权限与明文拦截

5.2 Retrofit：网络层的事实标准

5.3 本地存储：四个层级，各管各的

5.4 Room：编译期检查 SQL 的数据库

第六篇 系统能力：定位、通知、唤醒与平台适配

6.1 定位：别再用 LocationManager 了

6.2 消息通知：两段历史决定了今天的写法

6.3 App 唤醒：Deep Link、拉起与被拉起

6.4 平台适配 tips：碎片化才是 Android 的本体

第七篇 质量与发布：从「能跑」到「敢上线」

7.1 测试：少但要有

7.2 调试三板斧：Logcat、adb 与 Layout Inspector

7.3 国际化与无障碍：专业完成度的分水岭

7.4 发布：签名、混淆与 AAB

第八篇 AI 时代：怎么少写一半代码把 App 做出来

8.1 AI 在 Android 开发各环节的胜任度

8.2 实战工作流：需求 → App 的 AI 协作五步法

8.3 一个真实对比：Demo App 的工时变化

8.4 思考：AI 是放大器，不是替代品

结语：学习路线收个尾

基于 UDP 通信的洋葱网络设计：服务器、Android 客户端与 P2P 控制总结

基于 UDP 通信的洋葱网络设计：服务器、Android 客户端与 P2P 控制总结

0. 写在前面：为什么用 UDP 做洋葱网络 + P2P 信令？

1. 洋葱网络核心概念：先建立「知识地图」

1.1 洋葱路由 vs 普通代理的区别

1.2 一次洋葱转发的过程

1.3 UDP 洋葱报文的基本结构

2. 系统整体架构

2.1 三类服务器职责

3. 服务器端设计

3.1 目录服务（Directory Server）

核心数据模型

客户端获取节点列表的流程

3.2 中继服务（Relay Server）

核心状态

转发流程

关键设计点

3.3 信令服务（Signaling Server）

数据模型

典型信令流程

4. Android 客户端设计

4.1 客户端分层架构

4.2 关键模块说明

4.3 NetworkCore 线程模型

4.4 Android 端 NAT 类型探测

4.5 Android 后台保活与省电

5. 通过 UDP 信令网络实现 P2P 控制

5.1 P2P 连接的三种结果

5.2 ICE-like 候选地址优先级

5.3 NAT 打洞详细流程

5.4 基于洋葱网络的 P2P 控制通道

5.5 P2P 直连后的加密

6. 协议报文设计示例

6.1 洋葱路由报文

6.2 信令报文

7. 关键算法与数据结构

7.1 Circuit 选择算法

第一篇环境搭建：90% 的新人倒在这一关

第三篇用 Compose 写出第一个界面

第四篇架构与生命周期：从「写页面」到「写应用」

第五篇网络与存储：数据从哪来，存到哪去

第六篇系统能力：定位、通知、唤醒与平台适配

第七篇质量与发布：从「能跑」到「敢上线」