AI 编程 on 方糖猫Blog

高 bug 率的人该怎么对待：一场项目争论背后的对事、对人与系统

Mon, 19 Jan 2026 16:00:00 +0800

高 bug 率的人该怎么对待：一场项目争论背后的对事、对人与系统

引子是一次真实的项目讨论。组里有位同事，bug 率明显比其他人高——高到 QA 看见他的名字心里先咯噔一下。评审会上大家争论怎么处理，冒出来的意见很能代表一个团队的所有本能：

「对事不对人，先别急着怪他，看看是不是模块本身烂。」

「烂模块别人也在写，怎么就他 bug 多？这就是人的问题，该敲打敲打。」

「要我说这是架构问题，没测试没 CI，谁写都得出事。」

「都 2026 年了，他连 AI 辅助 review、AI 生成测试都不用，bug 多不是活该吗？」

「你们都想简单了，这模块需求天天变、接口文档是过期的，这是设计问题。」

五种说法，五种药方，互相打架。这场争论当时没有结论，但它逼我把一个问题想透了：「高 bug 率」根本不是一个问题，而是一组完全不同的问题共用的一个症状。 这篇文章就是我后来理出来的完整处理路径：先把症状变成数据，再用方法论找全病根，然后对照行业里的成熟做法，最后才轮到那个最初的问题——对事，还是对人。

一、第一步：把「高 bug 率」变成数据

「bug 率高」是一个印象，不是事实。争论对错之前，至少要回答三个数据问题：

分母是什么？ 按提交算、按功能点算，还是按代码行算？写核心复杂模块的人和写边角页面的人，天然不在一个 bug 密度量级上。不比单位产出只比绝对数量，是争论里最常见的暗坑。
分布长什么样？ 他的 bug 集中在某个模块，还是均匀散布在他写的所有代码里？同一个模块换谁写都 bug 多，是系统的问题；同一个人换什么模块都 bug 多，才轮到看人。 这一条能砍掉一半的争论。
bug 的类型是什么？ 是低级错误（空指针、边界、拼写），还是逻辑误解（需求理解错、边界场景没想到），还是集成事故（改了 A 弄坏 B）？三种 bug 指向三种完全不同的病根。

没有这三组数据，会议上的所有「我觉得」都只是立场。这也引出一个朴素的道理：对事不对人的第一步，是先把「事」看清楚——多数争论不是因为价值观不同，而是因为大家在争论一个没被测量过的东西。

二、第二步：逐条验证，五种说法归并成四种病根

拿着数据回到会上的五种说法，逐条对照，会发现它们归并完只剩四种病根：

会上的说法	数据特征	归并后的病根	正确药方
「就是人的问题」	跨模块一致偏高，明知规范仍绕过，同类错误重复犯	能力、习惯或态度	先教练，无效再惩戒
「架构问题」＋「AI 用得太少」	全组在该模块都偏高；逃逸率高（漏到线上才发现）；重复性低级错误占比高、测试覆盖率远低于组均	工程系统缺位：无测试、无 CI、高耦合、反馈慢，AI 工具链未流程化	补工程系统（含 AI 工具链默认化），不怪任何人
「设计问题」	bug 集中在「需求理解偏差」类；返工率高	需求模糊、接口契约缺失	修设计流程，不归咎执行者
「对事不对人」所暗含的一次性事故	无模式，单次事故	运气 + 单点疏忽	复盘机制，不动人

为什么「AI 用得太少」和「架构问题」并成一行？因为用要素维度分解（后文的鱼骨图），AI 工具链属于「机」这一格：团队没把 AI review、AI 生成测试、CI 静态检查做成流程默认项，这是系统缺位，不是哪个成员的问题。只有一种情况它退化回「人」：工具链已经是默认项，而个人拒绝使用——那属于习惯与技能问题，交给后文的 Just Culture 框架处理。

这个 2026 年的新变量值得多说两句，因为它有正反两面。

正面：「AI 用得不够」首先暴露的是系统问题，不是个人懒惰。 如果团队没有默认开启 AI 辅助 review、没有用 AI 生成测试基线，那么「某个成员不用 AI」暴露的是工程系统的缺失——别人不用你也发现不了，只不过他 bug 多先暴露了。正确的动作是把 AI 工具链做成流程默认项，让所有产出都过一遍机器筛子，而不是点名批评谁「不拥抱新技术」。

反面：AI 生成的代码不经 review 直接提交，是 2026 年高 bug 率的新来源。 见过不止一个案例，当事人解释「这是 AI 写的，我大意了」——这不能作为免责理由。AI 是放大器，责任心仍是人的。用 AI 放大产出可以，用 AI 稀释 review 不行。规矩要立在团队层面：AI 生成的代码，提交人负全责。

另外单独提醒「设计问题」：它是最容易被冤枉成「人的问题」的一种。需求一句话、接口靠口头、边界场景靠猜——这种环境下产出的 bug，记在程序员头上是冤案。判断方法很简单：把他的 bug 逐条归因，如果一半以上可以追溯到「需求没说清」，那该改的是需求评审流程，不是他。

三、第三步：病根怎么找全——三层归因方法论

五种说法来自一场会议的即兴发挥，够用吗？不够。它漏掉的病根我在不同团队真实遇到过：排期压垮质量、度量口径本身失真、外部依赖的脏数据、频繁切换任务导致的认知断裂……经验枚举永远有盲区，需要的是一套能生成假设、保证不重不漏的方法论。我用三把刀。

第一把刀：引入链分解——按 bug 的生命周期切

每个 bug 都有完整的生命周期：需求 → 设计 → 实现 → 验证 → 集成 → 发布 → 运行。沿链条逐环问「这一环会不会是病根」，得到一阶的病根空间：

环节	典型病根	会上的对应说法
需求	需求模糊、频繁变更、边界未定义	设计问题
设计	接口契约缺失、状态机没画清、边界场景没想	设计问题
实现	人的能力/习惯、AI 生成未审查	人的问题
验证	无测试、review 走过场、AI 工具链缺位	架构问题
集成	高耦合、改动半径不可控、无回归机制	架构问题
发布/运行	环境差异、脏数据、依赖服务不稳定	（会上没人提——这就是盲区）

会上的说法覆盖了链条的前五环，却漏了最后一环——线上 bug 里有相当比例是环境、数据、依赖造成的，把这类算在程序员头上是彻头彻尾的冤案。

第二把刀：鱼骨图 6M——按要素维度切

链条切法还有交叉项漏网，再换制造业用了半个世纪的鱼骨图（人机料法环测）做一次正交检查：

graph LR
    R["高 bug 率"] --> M1["人<br/>能力 / 习惯 / 态度 / 状态"]
    R --> M2["机<br/>工具链 / AI / 编译检查 / IDE"]
    R --> M3["料<br/>需求质量 / 文档 / 输入数据"]
    R --> M4["法<br/>流程 / 评审 / 排期 / 协作方式"]
    R --> M5["环<br/>环境 / 依赖服务 / 任务切换频率"]
    R --> M6["测<br/>测试覆盖 / 度量口径 / 统计方法"]

6M 的价值在于它逼你检查平时想不到的维度：

法里面藏着排期——连续赶工期的团队，bug 率上升是生理现象，不是态度问题；
环里面藏着任务切换——一个人同时被拉在三个项目里，认知断裂本身就是 bug 发生器；
测里面藏着最容易被忽略的一条：度量口径本身可能就是病根。bug 怎么算、谁录入、严不严格，直接扭曲「谁 bug 率高」的结论。度量一旦成为目标就不再是好的度量（古德哈特定律），拿失真的数据去惩人，是双重错误。

两把刀交叉，病根空间基本不重不漏：链条保证流程维度不漏，6M 保证要素维度不漏。

第三把刀：控制变量——把相关性变成归因

枚举出假设只是开始，归因要靠实验设计。核心思想是方差分析：bug 率是人、模块、需求、流程的多元函数，每次只动一个变量，看结果怎么变：

换人写同模块：bug 率不降 → 模块/需求的问题；降了 → 继续往下查人；
同一个人写别的模块：还是高 → 人的嫌疑上升；正常了 → 原模块的问题；
同一需求给两个人分别实现：bug 模式相似 → 需求/设计的问题；差异大 → 实现者的问题；
横向对照组：全组在同类模块上的 bug 基线是多少？没有基线，「偏高」二字本身就不成立。

这一套换组实验做完，多数「人的问题」会现出系统问题的原形，剩下真正属于人的部分，才轮到第五节处理。

最后补一个贯穿全程的视角：每个线上 bug 都是两个失败的乘积——引入失败 × 拦截失败。 只问「谁引入的」是在追责，同时问「为什么六道防线一道都没拦住」才是在建设。前者最多改变一个人，后者改变的是所有人的未来 bug 率。

四、第四步：行业里的成熟方法论与工具地图

三把刀都不是我的发明：引入链分解借自 IBM 的 ODC，鱼骨图来自石川馨，控制变量是实验设计的基本功。行业里的原版比我的速记法成熟，这一节直接对照。

归因层：ODC（正交缺陷分类）

ODC（Orthogonal Defect Classification，Chillarege 等人 1992 年提出） 的核心思想比「按环节分类」更深一层：把每个缺陷沿正交维度（缺陷类型、触发条件、影响、来源、发现阶段）打标签，然后看分布特征而不是个案——某一类缺陷在某个阶段的分布异常，直接反推哪个流程环节出了系统性问题。缺陷不是待修的孤案，而是流程的测量数据。这套方法在 IBM、电信和航空软件里跑了三十多年。小团队不必全套上 ODC，但最低限度要做到：缺陷入库时强制填「引入阶段」和「缺陷类型」两个字段——没有这两个字段，第一节要的三组数据永远凑不齐。

度量层：DORA 指标与缺陷逃逸率

「bug 率高」的行业标准度量不是我拍脑袋的三个数据问题，而是：

DORA 四键指标（《Accelerate》）：其中的变更失败率就是「高 bug 率」最权威的同行参照系——顶级团队与垫底团队的差距是数量级的，而且它和其他三项（部署频率、变更前置时间、恢复时间）联动，单独压 bug 率而不管交付节奏是缘木求鱼；
缺陷逃逸率：bug 在哪一环被发现（开发自测 / CI / 测试 / 线上），逃逸越靠后成本越高——这是「拦截失败」的标准度量；
缺陷聚集热力图：Microsoft Research 多年的实证结论——缺陷不是均匀分布的，少数模块集中了多数缺陷（与改动频率和复杂度强相关），CodeScene 这类工具可以直接画出热度图。这直接支撑了「换人写同模块」实验的必要性：热点模块的 bug 率天然高，不控变量就是在冤枉人。

防线层：shift-left 与工具链

「拦截失败 × 引入失败」的乘积视角，行业里叫 shift-left（防线左移），配套工具链已经高度成熟：

防线	方法论	工具（2026 年现网主流）
需求/设计	设计评审、ADR（架构决策记录）、契约先行	设计文档模板 + 评审清单
实现	测试金字塔（Google 的 small/medium/large 分层）、TDD、小步提交	JUnit/pytest + 覆盖率（只做参考，不做 KPI——古德哈特定律）
静态检查	静态分析、安全扫描	SonarQube、CodeQL、Semgrep、Snyk
测试有效性	变异测试（测试的测试）、模糊测试	PIT（Java）、fuzzing
代码审查	AI review 设为 CI 默认门禁	CodeRabbit（部署最广）、Greptile（全库上下文检出率最高）、Qodo（审查+测试生成）、GitHub Copilot Code Review、Cursor BugBot
测试生成	AI 生成单测基线	Diffblue Cover（Java）、Qodo
集成/发布	Trunk-Based Development、小 PR、CI 门禁、灰度	GitHub Actions / GitLab CI + 特性开关

两点强调：其一，2026 年的 AI review 工具已经过了尝鲜期——CodeRabbit 接入仓库数以百万计，Greptile 靠全代码库索引拿到最高检出率——「不配 AI 审查门禁」在今天的含义，和五年前「没有 CI」一样，属于工程系统缺位，这印证了第二节把 AI 折进工程系统的判断。其二，覆盖率、检出数这些指标一旦变成 KPI 就失效，它们只能用来找盲区，不能用来排名。

机制层：错误预算与安灯——「宽猛相济」的工程制度

第六节要讲的「宽与猛怎么配比」，行业里其实早已制度化了，两个现成机制：

Google SRE 的错误预算（error budget）：服务的可靠性目标不是 100%，预算内随你折腾（宽），预算耗尽立刻冻结发布、全员还债（猛）。什么时候该宽、什么时候该猛，不再依赖管理者的手感，而是事先约定的数字——这是「小惩大诫」最优雅的工程实现：惩戒自动触发、剂量事先封顶、对事不对人。书架上有我的《Google SRE 工作手册》笔记，错误预算一章值得细看；
丰田的安灯（andon）与防错（poka-yoke）：流水线上任何人发现异常都可以拉灯停线——「对事不对人」不是口号，是给一线员工的制度性权力；防错设计则直接把「人会犯的错」设计成「犯不了的错」，比任何惩戒都高明。bug 率治理的终极目标不是把人管得更紧，而是让低级错误在机制上不可能发生。

所以这一节的结论是：归因用 ODC 的思想，度量用 DORA 与逃逸率，防线用 shift-left 工具链，宽猛用错误预算制度化——我的「三把刀」只是这些成熟方法论的穷人版速记，团队有条件就应该直接上原版。

五、第五步：轮到「人」之后——Just Culture 三分法

排除了系统性因素，剩下的才轮到「人」——而处理人，最怕一刀切。安全科学里的 Just Culture（公正文化）把行为分成三类，每一类的正确回应完全不同：

行为类型	特征	正确回应
无心之失	认真做事，但人都会犯错	安慰 + 改系统，绝不罚——罚了以后没人再上报错误
侥幸冒险	明知规范但绕过了（侥幸没出事）	教练谈话，明确后果预期
明知故犯 / 屡教不改	重复再犯，警示无效	及时、小剂量、成比例的惩戒

用「对事不对人」处理第三类，是在纵容——恶意和惰性会学习你的宽容；用「敲打」处理第一类，是在制造恐惧文化——从此 bug 都被藏起来，团队失去学习的输入。冲突从来不在两种哲学之间，而在用错了对象。

六、更高处的统一：系辞与 Dalio

「对事不对人」和「该敲打敲打」这两种看似对立的姿态，恰好各有一部经典背书，而两部经典在更高处说的是同一件事。

《系辞传》讲「小惩而大诫，此小人之福也」。注意上下文——它的对象是「不威不惩」的小人，即内在荣辱感已经失灵、只有外部后果能触动的人；注意落点——「福」：惩罚是为受罚者本人的长远利益服务的。《系辞》下传还有一句「无有师保，如临父母」：管教的心是父母之心，不是权力之心。

Dalio《原则》讲对事不对人、极端求真（radical truth）：当面指出问题比背后留情更仁慈，这是 tough love。

两者在最高处是同一个标准：评价一次干预，不看「有没有怪罪人」，而看「它有没有让反馈回路闭合、有没有让这个人变得更好」。 惩罚如果是为了发泄、为了立威，就同时背叛了系辞和 Dalio。孔子论政说「宽以济猛，猛以济宽，政是以和」——宽（对事不对人）与猛（小惩大诫）不是二选一，是因人因事因时动态配比的阴阳两端：只宽不猛，组织失去边界；只猛不宽，组织失去真话。

而两者共同信仰的，是《系辞》最看重的那个字——几：「几者，动之微，吉之先见者也。」反馈必须早、必须真、必须被感觉到。Dalio 用真话送达信号，「小惩」用后果送达信号；信道不同，信源相同。等到 bug 率高到要开会讨论才处理，已经是「不俟终日」的反面教材了。

七、落地：一棵判断树

graph TD
    A["有人 bug 率明显偏高"] --> B{"看分布<br/>同一模块换谁写都高?"}
    B -- "是" --> C["系统问题<br/>补测试 / CI / 解耦 / AI 工具链<br/>不归咎任何人"]
    B -- "否, 集中在他" --> D{"看 bug 类型"}
    D -- "需求理解偏差类居多" --> E["设计问题<br/>修需求评审与接口契约流程"]
    D -- "低级重复错误居多" --> F["工程系统缺失<br/>AI review / 测试基线设为流程默认项"]
    D -- "集成事故类居多" --> G["架构耦合问题<br/>修边界与回归机制"]
    D -- "跨模块一致的逻辑疏忽" --> H{"看人: 无心之失<br/>还是明知故犯 / 屡教不改?"}
    H -- "无心之失" --> I["教练 + 结对 + 改系统<br/>绝不罚, 保护上报文化"]
    H -- "侥幸冒险 / 屡教不改" --> J["小惩大诫<br/>及时 / 小剂量 / 成比例<br/>动手前自问: 如临父母还是发泄立威?"]

动手惩戒之前，还有最后一道自检，三个问题按顺序问：

什么类型？ 无心之失和善意试错，绝不罚——罚了就没人上报了。
多早？ 越早代价越小，「小惩而大诫」的精髓不在「惩」而在「小」。问题在几微阶段，一次明确而克制的谈话就够；拖到「恶积而不可掩」，就只剩「何校灭耳」的选项了。
为谁？ 这一下是为了回路闭合和他的成长，还是为了我的情绪？答不出前者，就不该动。

八、收尾

回到那场争论。会后我做了归因分析，结论有点扫兴也有点解脱：那位同事 60% 的 bug 出在同一个无测试、需求三天一变的老模块——是系统问题；剩下的低级错误里，AI review 能拦掉一大半——是工程系统问题；真正属于他个人的，是重复犯同类边界错误、提醒后照旧——这部分，一次正式的、明确的、带着「这是为你好」的谈话处理了。三个月后，他的 bug 率回到了组内均值。

所以「对事还是对人」是个伪问题。完整的答案是：先对事（数据归因），再对系统（方法论找全病根），最后才对人（Just Culture 分类处理）；对事不对人是道的常态，小惩大诫是道的边界——两者的根，都是让反馈回路不失灵。

延伸阅读：书架上《原则》笔记里有 Dalio 的完整决策框架，《系统之美》讲透了为什么「人的行为来自系统结构」，《系辞传全文与白话译文》里有「小惩大诫」的原文语境。

把 Claude Code 用成工程杠杆：落地心得

Sat, 10 Jan 2026 15:00:00 +0800

把 Claude Code 用成工程杠杆：落地心得

我做软件工程 18 年了，在华为和 IBM 做过电信级系统，近四年又一头扎进 AI 工程化，主导过 AI Agent 短视频生成平台和自动化口播剪辑平台。Claude Code 是我最近半年每天都在用的主力工具。它不是替代工程师的魔法，而是一把需要正确握持的杠杆。这篇文章聊聊我怎么把它落地到工程工作流里。

一、先思考，再输入

很多人打开 Claude Code 的第一件事就是开始打字。这往往是最贵的错误。

我现在的习惯是：

写功能前，先想清楚模块边界、数据流、异常路径；
重构前，先定义"目标形态"是什么；
调试前，先列出我已知的事实和假设。

然后按 Shift+Tab 两次进入 Plan 模式，把这些思考丢给 Claude。

Plan 模式不是让 Claude 替我想，而是让它在我已经梳理好的框架里填充细节、发现盲点、提出反例。输入越清晰，输出越可用。这个道理听起来简单，但真正做到的人不多。

如果你觉得自己还不具备独立想架构的能力，我的建议是：先从描述问题开始，和 Claude 反复对话，让它帮你把模糊的想法磨成可执行的方案。对话是双向的，不是单向许愿。

二、架构描述决定代码质量

“给我做一个认证系统” 和 “基于现有 User 模型实现邮箱密码登录，会话存 Redis 24 小时过期，给 /api/protected 加中间件”，得到的结果天差地别。

AI 生成代码的问题，往往不在于模型不够聪明，而在于你给的目标太宽泛。自由度太大，模型就会按照它自己的理解去填补，而这些填补常常和你的工程习惯、团队规范、历史包袱不一致。

我在方糖猫的项目里深有体会。AI Agent 的渲染流水线涉及 Java API 服务、Python Worker、RocketMQ、Remotion 渲染、FFmpeg 后处理多个环节。如果我只说"帮我实现一个视频生成任务调度"，Claude 可能会写出一个看起来合理但完全不符合我们现有架构的方案。但如果我把状态机、消息格式、失败重试策略、SSE 进度推送方式都描述清楚，它就能写出可以直接接入系统的代码。

好的 Prompt 不是文学，是需求文档的浓缩版。

三、CLAUDE.md：给 AI 的入职培训

CLAUDE.md 是 Claude Code 会话启动时自动读取的文件。它的作用很像新员工入职手册，但比那更关键：因为它决定了 Claude 在你项目里的"默认行为"。

我花了点时间打磨自己的 CLAUDE.md，几条原则：

1. 保持简短

Claude 能稳定遵循的指令数量有限，系统提示已经占了一部分。写太多，它只会随机忽略。我的 CLAUDE.md 一般不超过两屏。

2. 只写项目特有信息

不要解释"组件目录是什么"这种通用知识。要写真正影响决策的东西：关键 bash 命令、构建脚本、测试命令、提交规范、技术约束。

3. 写"为什么"，不只是"做什么"

比如：

差：“使用 Java 17”。
好：“使用 Java 17，因为部分依赖在 Java 21 下存在兼容性问题，计划在 Q4 统一升级。”

原因能让 Claude 在你没想到的地方做出正确判断。

4. 持续更新

工作时长按 # 键，Claude 会自动把指令写进 CLAUDE.md。我的标准是：当我第二次纠正同一个问题时，就把它固化为规则。

坏的 CLAUDE.md 像写给新人的文档；好的 CLAUDE.md 像写给"未来失忆的自己"的笔记。

四、上下文窗口不是越用越好

Opus 4.5 的上下文窗口很长，但很多人忽略了一个事实：上下文用到 20%–40% 时，输出质量就开始下降了。

每次消息、每个文件、每段生成代码、每次工具输出都会累积。等会话变得臃肿，即使 /compact 也救不回来，因为能力已经劣化了。

我的做法：

每个任务一个会话：不要在同一会话里既改认证系统又重构数据库。
用外部记忆文件：比如 SCRATCHPAD.md 或 plan.md，把中间结论落地到文件系统。
复制-压缩-清空-粘贴法：重要信息复制出来，/compact 总结，再 /clear，只粘回关键内容。
知道何时清空：会话一旦混乱，直接 /clear。CLAUDE.md 还在，项目规则不会丢。

正确的心智模型是：把 Claude 当成无状态的。状态应该由文件系统、版本控制、外部记忆来维护，而不是由会话历史来维护。

五、提示词是沟通，不是咒语

我反复说的一句话是：提示词不是玄学，是沟通。清晰永远优于模糊。

有效的提示通常包含三层：

要做什么：明确任务目标；
不要做什么：Claude 喜欢过度工程化，必须明确限制；
约束和原因：是原型还是生产代码？性能敏感还是可读性优先？为什么？

比如我会这样写：

请为 VideoRenderWorker 添加一个重试机制。要求：

最多重试 3 次，使用指数退避；

只对临时性错误重试，业务逻辑错误直接失败；

不要引入新的依赖，使用现有的 Spring Retry 配置；

这是生产代码，需要单元测试覆盖。

这样的输入，输出基本可以直接进入 Code Review。

另外记住：输出只来自输入。如果你用好模型仍然得到坏结果，问题通常在你——你的提示写法、请求结构、上下文提供方式。

六、模型路由：让合适的模型做合适的事

Claude 的不同模型有明确的分工：

Sonnet：更快更便宜，适合执行明确的编码任务；
Opus：更慢更贵，适合复杂规划、架构设计、深度推理。

我的常用模式是：

用 Opus 做架构规划和复杂方案设计；
用 Sonnet 执行实现、补全代码、跑测试；
用 CLAUDE.md 保证模型切换后仍然遵循相同的项目规则。

这和团队里让资深架构师画蓝图、让工程师写代码是一个道理。Claude Code 里切换模型成本很低，但前提是你知道什么任务该用什么模型。

七、MCP、Hooks、Slash 命令与 Skills

Claude Code 的工具生态值得花时间探索。除了前面提到的 MCP 和 Hooks，Skills（技能） 是我最近用得越来越多的能力，它把常用工作流封装成可复用的指令包。

1. MCP、Hooks 和 Slash 命令

MCP：连接外部服务。如果你还在手动复制粘贴信息进 Claude，很可能 MCP 能帮你自动化。
Hooks：在 Claude 修改代码前后执行操作，比如自动格式化、类型检查、跑 lint。
自定义 Slash 命令：把常用的提示词模板化，避免每次重复输入。

我在项目里配了几个常用 Slash 命令：

/review：让 Claude 按项目规范做 Code Review；
/test：为当前修改生成单元测试；
/doc：为新增接口补全文档。

2. Skills：把个人经验变成团队能力

Skill 是什么？

Skill 是一个 Markdown 文件（通常是 SKILL.md），带有 YAML frontmatter。它描述了一个完整的工作流、判断标准或领域知识。Claude 会在合适的时机自动加载它，或者你可以通过 /skill <name> 手动调用。

你可以把 Skill 理解为"可插拔的专长"：

CLAUDE.md 是项目通用的"入职培训"，始终加载；
SKILL.md 是按需加载的"专项手册"，只在匹配的场景触发。

Skill 放在哪里？

有两种常见位置：

个人级：~/.claude/skills/<skill-name>/SKILL.md，跨项目可用；
项目级：.claude/skills/<skill-name>/SKILL.md，跟随仓库走，团队成员共享。

我推荐项目级 Skill，因为团队规范应该和代码放在一起，而不是依赖每个人的本地配置。

一个最小 SKILL.md 示例：

---
name: spring-api-review
description: 当用户请求对 Spring Boot API 代码进行 Review 时调用此 skill。
---

# Spring Boot API Review 规范

## 检查项

1. 控制器是否只做参数校验和调用服务层？
2. 服务层是否处理业务逻辑，而不是直接操作 HTTP 上下文？
3. DTO 是否有清晰的入参/出参边界？
4. 异常是否统一处理，而不是在每个方法里 try-catch？
5. 是否有对应的单元测试覆盖核心分支？

## 输出格式

对每个问题，按以下结构输出：

- 位置：文件路径 + 行号
- 问题描述
- 风险等级：高 / 中 / 低
- 建议修改

description 字段非常关键。Claude 会根据它判断何时自动加载这个 Skill。描述越具体，触发越准确。

3. 有哪些值得尝试的 Skill？

Claude Code 本身不内置大量固定 Skill，但社区已经沉淀了不少高质量 Skill 包。以下是我觉得对工程团队最有价值的几个方向：

Skill / Skill 包	用途
gstack	比较完整的一套工程 Skill 集合，覆盖 review、qa、investigate、ship、canary、retro 等
`/review`	预着陆 PR 审查，检查 SQL 注入、LLM 信任边界、副作用等结构性问题
`/qa`	系统化 QA 测试，发现 bug 后自动修复并验证
`/investigate`	系统性根因排查，要求"无根因不修复"
`/ship`	合并主分支、跑测试、生成 PR 的发布工作流
`/canary`	部署后监控异常、性能回归、页面失败
`/retro`	基于提交历史做工程复盘
heliohq/ship	更严格的分阶段流水线：spec → dev → E2E → review → QA → refactor → handoff
Cavestack	强调"Hero Six"核心 Skill，包括 office-hours、investigate、plan-eng-review 等

我个人用得比较多的是 /review、/investigate 和 /ship。它们不是替代人的判断，而是把重复性的检查清单和流程自动化，让我把精力放在真正需要决策的地方。

4. 怎么创建自己的 Skill？

创建 Skill 的步骤很简单：

新建目录：
```
mkdir -p .claude/skills/my-skill
```
写 SKILL.md：包含 name、description、用途、步骤、输出格式、示例和约束。
测试触发：开一个新会话，描述一个匹配的场景，看 Claude 是否自动加载。如果没加载，调整 description 让它更具体。
迭代优化：使用一段时间后，把新发现的问题和约束补充进去。和 CLAUDE.md 一样，Skill 也是需要持续维护的。

我的建议是：不要一开始就写很多 Skill。先观察团队里哪些工作流是重复的、哪些判断标准是大家口头传颂的，把最常见的两三个固化成 Skill。质量比数量重要。

5. Skill、CLAUDE.md、Hooks 的分工

能力	作用	触发方式
CLAUDE.md	项目通用规则，始终加载	每次会话启动
SKILL.md	专项工作流，按需加载	匹配描述时自动加载，或 `/skill` 手动调用
Hooks	代码修改前后的强制检查	触发编辑操作时
MCP	连接外部系统的能力	需要外部数据或操作时

这几层叠加起来，才能把 Claude Code 从一个"聊天工具"变成符合团队工程规范的"协作系统"。

这些小投入会不断复利。模型每周都在变好，但你的工具链、Skill 库和流程才是属于自己的护城河。

八、当 Claude 卡住时，换策略

Claude 有时会陷入循环：改了 A 导致 B 错，改了 B 又导致 A 错。这时候继续补充说明往往没用。

我常用的策略：

清空会话：从头开始，减少污染；
拆分任务：把大问题拆成几个独立的小问题；
给示例而不是解释：“参考 UserService.java 里的错误处理模式” 比 “请优雅地处理异常” 有效得多；
换种表述方式：同一个需求用不同结构说一遍，有时能绕过模型的固化模式。

关键技能不是让 Claude 永远不出错，而是尽早识别循环，并及时切换策略。

九、构建系统，而不是一次性工具

Claude Code 最大的价值，不在于帮你完成单次任务，而在于把它嵌入工程系统。

它支持 headless 模式（-p），可以脚本化、自动化、串联命令。企业已经在用它做：

自动审 PR；
处理支持请求；
更新文档；
批量重构；
生成测试用例。

我们的飞轮是：

Claude 出错 → 改进 CLAUDE.md 或工具链 → 下次更好。

几个月后，即使模型没变，整个系统也会显著提升。这就是复利。

如果你只把 Claude Code 当成一个交互式聊天工具，你正在浪费它的大部分价值。

十、写给老工程师的话

用了 Claude Code 一段时间后，我发现一个有意思的现象：

经验丰富的工程师反而更容易用好它。

因为你知道什么是好的架构，什么是坏的妥协，什么是可以自动化的重复劳动，什么是必须人工把关的关键决策。Claude Code 不会替你承担责任，但它能把你的判断力和工程经验放大很多倍。

对我来说，它最大的帮助不是写代码更快，而是：

把重复性工作交给它，我腾出时间思考架构；
用它快速验证想法，减少原型阶段的沉没成本；
通过 CLAUDE.md 和工具链，把个人经验沉淀为团队能力。

总结

把 Claude Code 用好，核心就几句话：

先思考，再输入；
架构描述决定代码质量；
CLAUDE.md 是杠杆点；
上下文在用到 30% 时就开始劣化；
提示词是沟通，输出来自输入；
让 Opus 规划，让 Sonnet 执行；
善用 MCP、Hooks、Slash 命令，更要善用 Skills；
卡住时换策略；
构建系统，而不是只做一次性任务。

现代 AI 工具已经强得离谱。你是在和工具对抗，还是顺势而行，往往取决于这些细节。

我在 ftmao.com/blog 持续记录 AI 工程、Agent 设计与 Claude Code 等工具的落地实践，欢迎关注和交流。

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

Fri, 09 Jan 2026 10:00:00 +0800

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

参考：shareAI-lab/learn-claude-code

你有没有想过，为什么你跟 Claude Code 说“帮我改一下这个网页”，它就能自己打开文件、修改代码、运行测试，然后告诉你结果？

它看起来好聪明，像人一样会“动手”。但其实，它背后的原理并不神秘，甚至可以用几十行简单的代码讲清楚。

这篇文章是给新手的。不管你有没有学过编程，我都会尽量用生活中的例子来解释。读完之后，你会明白：

Claude Code 最核心的部分是什么；
它是怎么“看懂”文件、“动手”改代码的；
它为什么能记住很多事情、做错事能重来；
以及如果你想自己做一个类似的 AI 助手，应该从哪里开始。

一、一句话讲清楚 Claude Code

如果把 Claude Code 拆开，你会发现它只有三个东西：

一个循环 + 一张工具表 + 一个会说话的 AI

部件	作用	生活里的比喻
会说话的 AI（大语言模型）	思考、理解你说的话、决定下一步做什么	一个超级聪明的大脑
工具表	让 AI 能读写文件、运行命令、搜索代码	给大脑装上双手和眼睛
循环	不断重复“思考 → 行动 → 看结果 → 再思考”	机器人一直干活，直到做完

这个“循环”非常重要。没有它，AI 就只能说一次话，没法连续做很多事。

flowchart LR
    subgraph 工具箱["🧰 工具箱（Harness）"]
        读文件["读文件"]
        写文件["写文件"]
        执行命令["执行命令"]
        搜索["搜索代码"]
        权限["权限检查"]
    end

    大脑["🧠 AI 大脑<br/>会思考、会推理"]
    电脑["💻 你的电脑"]

    大脑 -->|我想读文件| 读文件
    读文件 -->|文件内容| 大脑
    大脑 -->|我想运行测试| 执行命令
    执行命令 --> 电脑
    电脑 -->|测试结果| 大脑
    权限 -->|这个能做吗？| 执行命令

二、最核心的 30 行代码

Claude Code 的心脏，是一段很简单的代码。你可以把它理解成“机器人干活的主流程”：

def agent_loop(query):
    # 1. 先把用户的问题记下来
    messages = [{"role": "user", "content": query}]

    while True:
        # 2. 把对话历史发给 AI，告诉它有哪些工具可以用
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        # 3. 把 AI 的回复存进历史
        messages.append({"role": "assistant", "content": response.content})

        # 4. 如果 AI 不再调用工具，就说明它说完了，结束循环
        if response.stop_reason != "tool_use":
            return

        # 5. 执行 AI 要求的工具，并把结果告诉它
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

人话解释

你问了一个问题 → 比如“帮我修一下这个 bug”。
AI 看历史和工具表 → 它想：“我需要先读一下代码文件。”
AI 说“我要用读文件工具” → 程序真的去打开文件。
把文件内容还给 AI → AI 再看，决定下一步。
一直重复，直到 AI 说“我搞定了”。

flowchart TD
    开始([你输入任务]) --> 发给AI[把任务+历史发给 AI]
    发给AI --> AI思考[AI 思考]
    AI思考 --> 判断{AI 想调用工具吗？}
    判断 -->|想| 执行工具[程序执行工具]
    判断 -->|不想| 输出答案[输出最终答案]
    执行工具 --> 返回结果[把结果返回给 AI]
    返回结果 --> 发给AI
    输出答案 --> 结束([结束])

三、20 节课都在讲什么？一张总图看懂

Claude Code 的学习资料里有 20 节课，每节课加一个新能力。它们不是乱排的，而是像打游戏升级一样，一步一步变强。

flowchart LR
    subgraph 第一阶段["🌱 第一阶段：让 AI 动起来"]
        s01["s01 循环"]
        s02["s02 工具"]
        s03["s03 权限"]
        s04["s04 钩子"]
    end

    subgraph 第二阶段["🛠️ 第二阶段：做复杂任务"]
        s05["s05 计划"]
        s06["s06 子代理"]
        s07["s07 技能"]
        s08["s08 压缩记忆"]
    end

    subgraph 第三阶段["🧠 第三阶段：记得住、错得了"]
        s09["s09 记忆"]
        s10["s10 系统提示"]
        s11["s11 错误恢复"]
    end

    subgraph 第四阶段["⏳ 第四阶段：长时间运行"]
        s12["s12 任务图"]
        s13["s13 后台任务"]
        s14["s14 定时任务"]
    end

    subgraph 第五阶段["👥 第五阶段：团队协作"]
        s15["s15 队友"]
        s16["s16 团队协议"]
        s17["s17 自治"]
        s18["s18 目录隔离"]
    end

    subgraph 第六阶段["🔌 第六阶段：扩展组装"]
        s19["s19 MCP 插件"]
        s20["s20 完整系统"]
    end

    第一阶段 --> 第二阶段 --> 第三阶段 --> 第四阶段 --> 第五阶段 --> 第六阶段

下面拆解核心部分。

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

这是所有东西的基础。就像你骑自行车，核心是“踩踏板 → 车轮转 → 车前进”这个循环。Claude Code 的核心就是：

AI 思考 → 调用工具 → 看结果 → 再思考 → 再调用工具 → …… → 完成

没有循环，AI 只能说一句话。有了循环，它就能连续做很多步。

s02 Tool Use：从一把螺丝刀到整套工具箱

最早的 AI 只有一个工具：执行终端命令（bash）。但这样很不方便，就像你修自行车只能用一个螺丝刀。

后来 Claude Code 给 AI 配了一整套工具：

read_file：读文件
write_file：写文件
edit_file：改文件中的一部分
glob：按名字找文件
grep：在文件里搜索文字

这些工具是“分发表”管理的。程序不用写一堆 if/else，而是查一个字典：

TOOL_HANDLERS = {
    "read_file":  read_file_function,
    "write_file": write_file_function,
    "edit_file":  edit_file_function,
}

# AI 说想用 read_file，就找到对应的函数执行
handler = TOOL_HANDLERS["read_file"]
result = handler(path="main.py")

好处：加新工具就像往工具箱里多放一把扳手，不用改主流程。

s03 Permission：先问能不能做，再让它做

这是 Claude Code 很重要的一课：自由要有边界。

AI 能力很强，但它不能想删啥就删啥、想改啥就改啥。权限系统就像家长给孩子定规矩：

读文件可以；
修改重要文件要问一下；
删除整个文件夹？不行。

flowchart TD
    AI想做事[AI 想执行命令] --> 查权限{权限系统检查}
    查权限 -->|允许| 直接执行
    查权限 -->|需要确认| 问用户[弹窗问用户]
    查权限 -->|禁止| 拒绝[拒绝执行]
    问用户 -->|同意| 直接执行
    问用户 -->|不同意| 拒绝

这教会我们一个工程原则：先设边界，再给自由。

s04 Hooks：在循环边上挂“挂钩”

Hook 中文叫“钩子”。想象你在书包上挂很多小挂件：钥匙扣、饭卡、耳机。主书包不变，但你可以加东西。

Claude Code 的 Hook 系统也是这样：

工具执行前，可以检查一下（PreToolUse）；
工具执行后，可以记录日志（PostToolUse）；
会话开始/结束时，可以做初始化或清理。

flowchart LR
    AI决定[AI 决定调用工具] --> 前钩子["PreToolUse 钩子<br/>检查/拦截"]
    前钩子 --> 执行工具
    执行工具 --> 后钩子["PostToolUse 钩子<br/>记录/通知"]
    后钩子 --> 返回AI

核心思想：主循环不要改来改去，把扩展功能挂到钩子上。

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

如果你要写一篇大作文，你会先列提纲，对吧？Claude Code 也是这样。

做复杂任务前，AI 会先写一个待办清单（Todo）：

1. 读 README 了解项目      [待做]
2. 找到 bug 所在的文件     [进行中]
3. 修改代码                [待做]
4. 运行测试确认修好        [待做]

每完成一步，就更新状态。如果 AI 太久没更新，系统还会“唠叨”它：“喂，你忘了更新待办清单啦！”

这个机制让 AI 不容易“跑偏”。

s06 Subagent：雇一个小助手

有时候一个任务需要查很多东西。比如“这个项目的测试框架是什么？”AI 可能要读 10 个文件才能确定答案是 pytest。

如果让主 AI 自己读 10 个文件，它的“脑子”会塞满东西，又慢又贵。

解决办法是：雇一个临时小助手（子代理）。小助手用全新的对话去读那 10 个文件，最后只把答案“pytest”告诉主 AI。

flowchart LR
    主AI["主 AI"] -->|派任务| 子AI["子 AI<br/>新开一个对话"]
    子AI -->|读10个文件| 文件["项目文件"]
    文件 -->|内容| 子AI
    子AI -->|只返回结论：pytest| 主AI

主 AI 的脑子很干净，只记住了最重要的结论。

s07 Skill Loading：需要哪本字典，就翻哪本

想象你要学数学、物理、化学三科。你不会每次上课都把三本书全背上，而是上什么课带什么书。

Claude Code 也是这样。它有很多“技能书”（比如 git 用法、测试规范、API 文档），但不会一次性全塞给 AI。

它是两层加载：

先给目录：告诉 AI 有哪些技能书；
需要时再翻开：AI 说“我要查 git 那本书”，系统才把完整内容给它。

这样就省了很多“脑容量”。

s08 Context Compact：脑子塞不下时怎么办？

AI 一次能看的文字是有限的，就像你的作业本只有那么多页。如果写得太多，就要翻页或者撕掉旧的。

Claude Code 有三种“翻页”方法：

micro_compact：把很久以前的工具结果换成一句话摘要，比如“之前用过 read_file”；
auto_compact：当文字太多时，自动让 AI 写个总结，用总结替换原来的长对话；
compact 工具：AI 自己决定什么时候该“翻页”。

flowchart TD
    subgraph 第一层["第一层：micro_compact"]
        旧结果["旧工具结果"] --> 占位符["换成占位符<br/>[之前读过 main.py]"]
    end

    subgraph 第二层["第二层：auto_compact"]
        太多文字["对话太长"] --> 写总结["AI 写摘要"] --> 替换历史["用摘要替换历史"]
    end

    subgraph 第三层["第三层：compact 工具"]
        AI判断["AI 觉得该压缩了"] --> 手动触发["调用 compact 工具"]
    end

    第一层 --> 第二层 --> 第三层

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

AI 没有真正的记忆。每次对话结束，它就忘了。如果想让它长期记住东西（比如你喜欢什么代码风格、项目有什么规矩），就需要一个“记忆系统”。

记忆系统通常分三步：

选择：哪些东西值得记住？
提取：把重要信息摘出来；
固化：存到文件或数据库里，下次对话再读出来。

flowchart LR
    对话["一段对话"] --> 选择["选择重要信息"]
    选择 --> 提取["提取关键事实"]
    提取 --> 存储["存到记忆文件"]
    存储 --> 下次对话["下次启动时读取"]

比如 AI 记住了：“这个用户喜欢用 2 个空格缩进。”下次写代码时它就会自动用 2 个空格。

s10 System Prompt：提示词不是写死的

System Prompt 就是告诉 AI“你是谁、该怎么做事”的那段话。

Claude Code 的 System Prompt 不是一次性写死的，而是运行时拼接的：

基础身份部分；
当前项目规则；
加载的技能书；
用户的偏好记忆。

就像你写作文时，老师给的题目要求 + 你自己的提纲 + 参考资料，组合在一起。

s11 Error Recovery：做错事能重来

AI 也会犯错。比如它调用了一个不存在的文件，或者写的代码运行报错。这时候怎么办？

Claude Code 有几种“重来”策略：

重试：可能是网络抖动，再试一次就好了；
换条路：这个方法不行，换另一个工具试试；
清理空间：上下文太满导致看不清，先压缩一下再试；
换个小模型/大模型：简单任务用小模型省钱，复杂任务换大模型。

flowchart TD
    出错[工具执行出错] --> 重试{重试有用吗？}
    重试 -->|有用| 再试一次
    重试 -->|没用| 换方法[换工具/换思路]
    换方法 -->|还不行| 清空间[压缩上下文]
    清空间 -->|再试| 再试一次

重要道理：错误不是终点，而是调整的起点。

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

复杂项目不能靠一个简单的 Todo 清单。任务之间有依赖关系：

A 做完了，B 才能开始；
C 和 D 可以同时进行；
E 要等 C 和 D 都做完。

Claude Code 用任务图来管理。每个任务存成一个文件，记录自己的状态、依赖谁、被谁依赖。

flowchart LR
    A["设计登录页面"] --> B["写前端代码"]
    A --> C["写后端接口"]
    B --> D["联调测试"]
    C --> D

s13 Background Tasks：慢活放后台

有些命令要跑很久，比如 npm install 可能要几分钟。如果 AI 停下来等，就太浪费了。

Claude Code 会开一个新的后台线程去跑这些慢命令，主 AI 继续思考别的事。等后台跑完了，再通知 AI。

s14 Cron Scheduler：定时任务

Cron 就是“定时器”。比如你可以让 AI 每天早上 8 点检查一遍代码仓库，看看有没有需要更新的依赖。

“到点了就干活，不用人喊。”

flowchart LR
    时间到[时间到了] --> Cron[Cron 触发器]
    Cron --> 任务[执行预设任务]
    任务 --> 结果[把结果发给 AI]

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

一个 AI 干不完的大项目，可以叫一群 AI 一起干。每个 AI 有自己的身份和“收件箱”（mailbox）。

它们通过 JSONL 文件收发消息：

{"from": "leader", "to": "alice", "content": "你去写登录页面"}
{"from": "alice", "to": "leader", "content": "我做好了"}

每行一条消息，追加写入，像写日记一样简单。

s16 Team Protocols：队友之间要讲规矩

多人协作不能乱说话。Claude Code 的团队协议规定：

每个重要请求都要带一个 request_id（像快递单号）；
回复时要引用同一个 request_id；
请求状态是 pending（等待中）、approved（同意）或 rejected（拒绝）。

这样就不会搞混谁同意了什么。

s17 Autonomous Agents：AI 自己会找活干

更高级的团队里，AI 不需要等领导分配任务。它会自己去看任务板，认领还没人做的、并且前置条件满足的任务。

如果 60 秒没活干，它就自动“下班关机”。

s18 Worktree Isolation：各干各的，不打架

两个 AI 同时改同一个文件，会互相覆盖。Claude Code 用 git worktree 给每个任务一个独立目录和独立分支：

任务 A → 目录 auth-refactor/ → 分支 wt/auth-refactor
任务 B → 目录 ui-login/     → 分支 wt/ui-login

大家互不干扰，最后再把代码合并。

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

MCP 是“模型上下文协议”。你可以把它理解成“USB 接口”：

Claude Code 本身带了一些工具；
如果你需要连数据库、查浏览器、操作 Slack，可以通过 MCP 插进来；
这些外部工具和自带工具一样，AI 都能调用。

flowchart LR
    Claude["Claude Code"] --> MCP["MCP 接口"]
    MCP --> 数据库["数据库工具"]
    MCP --> 浏览器["浏览器工具"]
    MCP --> Slack["Slack 工具"]
    数据库 -->|结果| Claude
    浏览器 -->|结果| Claude
    Slack -->|结果| Claude

s20 Comprehensive Agent：把所有东西拼起来

最后一节课，就是把前面 19 节课的所有机制都装进同一个循环里：

一个循环 + 工具 + 权限 + 钩子 + 计划 + 子代理 + 技能 + 记忆 + 压缩 + 任务图 + 后台任务 + Cron + 团队 + 自治 + Worktree + MCP = 完整的 Claude Code

听起来很多，但你已经一个个看过了。它们都是围绕最初那个简单循环加上的“配件”。

十、给新手的 5 个开发小技巧

这些技巧来自 Claude Code 的源码，平时写程序也能用到。

1. 用“查表”代替一堆 if/else

# 不推荐
if name == "read": read_file()
elif name == "write": write_file()

# 推荐
HANDLERS = {"read": read_file, "write": write_file}
HANDLERS[name]()

加新功能只要加一行。

2. 修改列表要小心

如果你想在一个函数里修改外面的列表，要用切片赋值：

messages[:] = new_list  # 正确：改原来的列表
# messages = new_list   # 错误：只是让局部变量指向新列表

3. 用 `**kwargs` 接受任意参数

def handler(**kw):
    print(kw["path"])

handler(path="main.py", limit=10)

(**kw) 表示“不管什么参数名，都装进字典 kw 里”。

4. 守护线程做后台任务

import threading

t = threading.Thread(target=download_file, daemon=True)
t.start()

主程序退出时，守护线程会自动结束，不会卡住。

5. JSONL 比 JSON 更适合追加写入

# 写：每行一条
with open("inbox.jsonl", "a") as f:
    f.write(json.dumps(msg) + "\n")

# 读：逐行解析
for line in open("inbox.jsonl"):
    msg = json.loads(line)

追加写入很安全，不会因为同时写入而损坏文件。

十一、总结

Claude Code 看起来很厉害，但它的核心其实非常朴素：

一个 while 循环 + 一张工具表 + 一个会说话的 AI。

真正让它变强的，是围绕这个循环一层层加上的“配件”：权限、计划、子代理、技能、记忆、压缩、任务图、后台任务、团队、自治、目录隔离、MCP……

这些配件都是为了解决一个核心问题：

怎么让一个只会说话的 AI，真正能在现实世界里连续、安全、高效地干活。

理解了这个骨架之后，你再回头看 Claude Code，就不会觉得它是黑魔法了。它就是一个被精心设计的“机器人工作台”，而我们看到的聪明，来自那个会思考的大脑，加上一套会执行的 harness。

大脑负责想，工作台负责做。把工作台造好，大脑就能发挥全部实力。

本文是学习 shareAI-lab/learn-claude-code 的笔记整理。如果你想动手，可以从 s01_agent_loop/code.py 开始，一课一课跟着做。

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

Wed, 16 Aug 2023 09:40:00 +0800

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

目标读者：想进入小程序开发的前端同学，或者写过 Vue/React、想搞清楚「小程序和网页开发到底差在哪」的同学。
知识骨架与编排方式参考姊妹篇《Android 开发从入门到精通》——同样是「由浅入深、踩坑驱动」。写 UI 的心法还可以看《前端 UI 开发从入门到精通（Vue 技术栈）》，小程序的组件化思想和 Vue 一脉相承。

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

flowchart LR
    A["一 环境搭建<br/>注册 AppID 跑起 Hello World"] --> B["二 语法基础<br/>WXML/WXSS/JS/JSON 四件套"]
    B --> C["三 UI 组件库<br/>写出像样的页面"]
    C --> D["四 架构与生命周期<br/>从写页面到写应用"]
    D --> E["五 网络与存储<br/>数据从哪来 存到哪去"]
    E --> F["六 平台能力<br/>登录 订阅消息 分享 支付"]
    F --> G["七 质量与发布<br/>性能 体验版 审核上线"]
    G --> H["八 AI 时代<br/>让 AI 写 80% 的代码"]
    style H fill:#e8f4e8

为什么是这个顺序？前三篇解决「能不能写出来」；第四篇解决「页面多了以后会不会散架」；第五、六篇解决「能不能和后端、和微信这个平台打交道」；第七篇解决「敢不敢提交审核发给真实用户」；第八篇解决「如何持续快下去」。

第一篇环境搭建：比 Android 友好，但坑藏在「账号」里

先说好消息：小程序的环境搭建是整个客户端开发里最友好的——不用装 JDK，不用配 SDK，不用 Gradle 转圈。坏消息是：门槛从「装软件」转移到了「注册账号」，而账号相关的坑往往要在提交审核那天才爆出来。

1.1 你需要准备的三样东西

flowchart TD
    A["小程序账号 (AppID)<br/>mp.weixin.qq.com 注册"] --> D["微信开发者工具"]
    B["微信开发者工具<br/>官方 IDE 写代码 + 模拟器 + 调试"] --> E["能跑起 Hello World<br/>= 入门完成一半"]
    C["微信扫码登录<br/>一个微信号即可"] --> D
    D --> E

动手清单：

注册小程序账号：到 mp.weixin.qq.com 选择「小程序」注册，拿到 AppID（在「开发管理 → 开发设置」里）。注意一个邮箱只能绑定一个微信公众产品账号。
下载微信开发者工具：认准官方页面，选稳定版（Stable Build）。它是「编辑器 + 模拟器 + 调试器 + 发布工具」四合一，写小程序不需要再装别的。
新建项目：填入 AppID，模板选「不使用云服务」的最小模板，后端服务选「不使用模板」。模拟器里看到 Hello World 即通关。

如果只是学习不打算发布，也可以在新建项目时选「测试号」，跳过注册——但测试号很多能力（支付、订阅消息、发布）用不了，建议还是注册一个正式的个人账号。

1.2 踩坑故事一：类目选错，审核排队两周白排

现象：朋友的小程序功能全部做完，信心满满提交审核，第二天被拒：「所选类目与小程序实际内容不符」。改类目需要提供《增值电信业务经营许可证》——他没有。推倒重来，换了个人主体账号重新注册，前面所有配置全部作废。

原因：注册时选择的服务类目和主体类型（个人 / 企业）在注册后很难改，而且直接决定你的小程序能做什么：

flowchart TD
    Q{"小程序要做什么？"}
    Q -->|"内容展示 / 工具<br/>不涉及交易"| A["个人主体即可<br/>注册免费 门槛低"]
    Q -->|"电商 / 需要微信支付"| B["必须企业主体<br/>+ 对应经营类目"]
    Q -->|"医疗 / 金融 / 社交"| C["企业主体 + 行业资质<br/>提前查资质清单再动手"]
    style C fill:#ffe4e1

教训：先查类目，再写代码。微信官方有《小程序开放的服务类目》文档，写清楚每个类目需要什么资质。个人主体不能碰电商交易、不能做陌生人社交——无数个人开发者做到一半才发现「个人号不支持」，这是小程序生态最贵的一个坑，因为它爆在最后一步。

1.3 踩坑故事二：「不校验合法域名」的虚假安全感

现象：开发期接口调得好好的，一到真机预览就白屏，控制台报 request:fail url not in domain list。

原因：小程序的 wx.request 只能请求在 mp 后台预先配置过的 HTTPS 域名（request 合法域名）。开发者工具里有个「详情 → 本地设置 → 不校验合法域名」的开关，很多人开发期一直勾着它，勾到忘记它的存在——而真机上这个开关不存在（除非打开调试模式）。

解法：

去 mp 后台「开发管理 → 开发设置 → 服务器域名」配置 request 合法域名，必须 HTTPS，且域名要 ICP 备案。
开发期就把「不校验合法域名」关掉，让问题暴露在写代码的时候，而不是发给产品经理体验的时候。

教训：小程序的「域名校验」和 Android 的「明文流量拦截」是同一类东西——平台用白名单逼你上 HTTPS。这类安全约束的特点是「先放行以后再收」基本等于永远不收，第一天就把域名配好。

第二篇语法基础：四个文件就是一个页面

环境通了，接下来是语言。小程序的语法对前端来说几乎没有学习成本——它就是「受限版的 Vue」：模板 + 数据绑定 + 指令 + 组件化。这一篇的重点不是语法本身，而是它和自由 Web 的差异，坑全在差异里。

2.1 一个页面 = 四个文件

flowchart TD
    A["index.wxml<br/>模板 ≈ HTML<br/>写结构"] --- P["一个页面"]
    B["index.wxss<br/>样式 ≈ CSS<br/>多了 rpx 单位"] --- P
    C["index.js<br/>逻辑：Page({...})<br/>data + 生命周期 + 事件处理"] --- P
    D["index.json<br/>配置：导航栏标题<br/>引入哪些组件"] --- P
    P --> E["在 app.json 的 pages 数组里<br/>注册路径才算存在"]

全局还有一组 app.js / app.json / app.wxss：App 的生命周期、全局配置（页面注册、tabBar、窗口样式）、全局样式。

一个最小页面长这样：

<!-- pages/index/index.wxml -->
<view class="container">
  <text class="title">{{title}}</text>
  <view wx:for="{{todos}}" wx:key="id" class="todo">
    <text class="{{item.done ? 'done' : ''}}">{{item.text}}</text>
  </view>
  <button bindtap="onAdd">添加</button>
</view>

// pages/index/index.js
Page({
  data: {
    title: '我的待办',
    todos: [
      { id: 1, text: '学会 WXML', done: true },
      { id: 2, text: '学会 setData', done: false },
    ],
  },

  onAdd() {
    const todos = this.data.todos.concat({
      id: Date.now(),
      text: '新任务',
      done: false,
    });
    // ⚠️ 改数据必须走 setData，直接 this.data.todos = todos 界面不会刷新
    this.setData({ todos });
  },
});

2.2 setData：小程序开发的第一性原理

小程序的视图和逻辑跑在两个不同的线程：视图层是 WebView，逻辑层是 JSCore。你在 JS 里改 data，要通过 setData 把数据序列化后跨线程发给视图层，界面才会更新。

sequenceDiagram
    participant L as 逻辑层 (JSCore)
    participant B as 原生桥 (Native)
    participant V as 视图层 (WebView)
    L->>B: this.setData({ todos })
    Note over B: 数据序列化传输<br/>大对象 / 高频调用都在这里变慢
    B->>V: 更新 data
    V->>V: 重新渲染 WXML

这一个架构事实解释了小程序里 80% 的性能问题和 80% 的新手困惑：

直接赋值 this.data.x = 1 数据变了但界面不刷新——因为没有经过那座桥。
setData 传几十 KB 的大对象会卡——桥上的运输成本。
在 onPageScroll 里每次滚动都 setData 会卡成 PPT——桥上堵车。

现在只需要记住结论：setData 是有成本的，数据要小、频率要低。 第七篇会专门讲怎么优化。

2.3 十分钟速览：和 Vue 的核心差异

Page({
  // 1. 数据：必须先声明在 data 里，模板才能用
  data: { count: 0, list: [] },

  // 2. 改数据：setData，支持路径写法
  onInc() {
    this.setData({ count: this.data.count + 1 });
    // 深层路径：this.setData({ 'list[0].done': true })
  },

  // 3. 没有计算属性，官方方案是 WXS 或 setData 时算好
  //    （新语法支持 computed 需引第三方库，见第四篇）

  // 4. 生命周期：onLoad / onShow / onReady / onHide / onUnload
  onLoad(options) {
    // options 里是页面跳转带来的参数：/pages/detail?id=1 → options.id === '1'
  },
  onShow() {
    // 每次页面显示都会来（包括从下一页返回），刷新数据的常见位置
  },
});

WXML 指令对照表（会 Vue 的看一眼就够）：

Vue	小程序 WXML
`v-if`	`wx:if`
`v-else`	`wx:else`
`v-for`	`wx:for`，配合 `wx:key`
`@click`	`bindtap`
`:src="url"`	`src="{{url}}"`
`v-model`	没有，手写 `value="{{x}}" bindinput="onInput"`

感悟：小程序没有 v-model 是刻意的——双向绑定在「两线程架构」下是个性能陷阱，官方逼着你显式处理每一次输入。理解这一点，你就理解了小程序 API 设计的整体气质：宁可啰嗦，不可模糊。

2.4 rpx：一个单位解决屏幕适配

小程序做了件 Android 和 Web 都很羡慕的事：定义了 rpx（responsive pixel），屏幕宽度恒为 750rpx。设计稿按 750 宽出图，iPhone 6/7/8 上 1rpx = 0.5px，在更宽的机型上等比放大。样式里写 width: 375rpx 就是「半屏宽」，不用算任何比例。

踩坑故事三：rpx 用在不该用的地方

现象：海报生成页用了 Canvas 手绘，按设计稿把字号写成 28rpx，导出图片在小屏手机上文字糊成一团。

原因：Canvas 2D 接口、以及 wx.createSelectorQuery 拿到的尺寸单位都是物理 px，不是 rpx。rpx 只活在 WXSS 里。

解法：涉及 Canvas / JS 计算尺寸的地方，先换算：

const { pixelRatio, windowWidth } = wx.getWindowInfo();
const rpxToPx = (rpx) => (rpx * windowWidth) / 750;

教训：记住 rpx 的管辖范围只有 WXSS。凡是在 JS 里处理尺寸，第一件事就是确认单位。

2.5 踩坑故事四：回调里的 this 指向丢了

现象：wx.request 的 success 回调里 this.setData(...) 报错 Cannot read property 'setData' of undefined。

// ❌ 经典错误：普通函数的 this 不是页面实例
wx.request({
  url: 'https://api.example.com/todos',
  success: function (res) {
    this.setData({ todos: res.data });  // this 是 undefined
  },
});

// ✅ 解法一：箭头函数（词法 this），今天的推荐写法
wx.request({
  url: 'https://api.example.com/todos',
  success: (res) => {
    this.setData({ todos: res.data });
  },
});

教训：这是 JavaScript 的老问题，但它是每个小程序新手的「成人礼」。统一用箭头函数写回调，这个问题就绝迹了。顺手把 var that = this 这种上古写法从代码里清除出去。

第三篇 UI 组件库：别从零画按钮

语法有了，马上写界面。小程序自带一套基础组件（view、text、button、image、scroll-view、swiper……），但它们是「零件」不是「成品」——没有现成的日历、下拉刷新、商品卡片。这一篇解决两个问题：选什么组件库，以及怎么用它写出一个像样的页面。

3.1 主流组件库怎么选

flowchart TD
    Q{"做什么样的小程序？"}
    Q -->|"电商 / 通用业务<br/>组件要全"| A["vant-weapp (有赞)<br/>生态最大 文档最细"]
    Q -->|"要腾讯系设计风格<br/>长期维护"| B["TDesign (腾讯官方)<br/>设计规范完整"]
    Q -->|"京东系 / 多端"| C["NutUI (京东)"]
    Q -->|"一套代码同时出<br/>小程序 + H5 + App"| D["跨端框架<br/>Taro / uni-app<br/>⚠️ 见 3.4 节的权衡"]

vant-weapp：有赞出品，事实上的生态老大。组件全（60+），电商场景（商品、优惠券、地址编辑）开箱即用，社区问题几乎都能搜到答案。不知道选什么就选它。
TDesign：腾讯官方，设计体系完整，维护稳定。和 vant-weapp 二选一主要看设计稿更接近哪个风格。
NutUI：京东出品，风格轻量，多端版本（Taro）做得好。
基础组件之外值得一提的：wxml-to-canvas（海报生成）、echarts-for-weixin（图表）、computed / mobx-miniprogram（下一篇的主角）。

引入方式（以 vant-weapp 为例）：小程序从 2019 年起支持 npm，但和 Web 的 npm 用法不一样，多一步「构建」：

npm i @vant/weapp -S

然后在开发者工具里点「工具 → 构建 npm」，再在页面的 json 里声明：

{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index",
    "van-field": "@vant/weapp/field/index"
  }
}

3.2 踩坑故事五：npm 装了，组件死活找不到

现象：npm install 成功，usingComponents 也写了，模拟器报 Component is not found in path "@vant/weapp/button/index"。

原因：小程序构建工具不直接读 node_modules，需要「工具 → 构建 npm」把它编译成 miniprogram_npm 目录。装完包没构建、或者 app.json 同级目录结构不对（project.config.json 里 miniprogramRoot 配错），都会撞上这个报错。

解法：构建 npm 后重启编译；团队项目把 miniprogram_npm 加入 git 忽略，但要在 README 里写明「拉代码后先构建 npm」——新人入职第一天栽在这上面的比例高得离谱。

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

把数据绑定、事件、vant-weapp 组件串起来——每个小程序都有的页面：

<!-- pages/login/login.wxml -->
<view class="page">
  <van-field
    value="{{form.phone}}"
    label="手机号"
    placeholder="请输入手机号"
    error-message="{{errors.phone}}"
    bind:change="onPhoneChange"
  />
  <van-field
    value="{{form.code}}"
    label="验证码"
    placeholder="请输入验证码"
    bind:change="onCodeChange"
  >
    <van-button slot="button" size="small" type="primary"
      disabled="{{countdown > 0}}"
      bindtap="onSendCode">
      {{countdown > 0 ? countdown + 's 后重发' : '发送验证码'}}
    </van-button>
  </van-field>

  <van-button type="primary" block round
    loading="{{loading}}"
    bindtap="onLogin">
    登录
  </van-button>
</view>

// pages/login/login.js
Page({
  data: {
    form: { phone: '', code: '' },
    errors: { phone: '' },
    countdown: 0,
    loading: false,
  },

  onPhoneChange(e) {
    // van-field 的值在 e.detail 里
    this.setData({
      'form.phone': e.detail,
      'errors.phone': '',
    });
  },

  onCodeChange(e) {
    this.setData({ 'form.code': e.detail });
  },

  onSendCode() {
    if (!/^1\d{10}$/.test(this.data.form.phone)) {
      this.setData({ 'errors.phone': '手机号格式不对' });
      return;
    }
    this.setData({ countdown: 60 });
    this.timer = setInterval(() => {
      const next = this.data.countdown - 1;
      this.setData({ countdown: next });
      if (next <= 0) clearInterval(this.timer);
    }, 1000);
    // api.sendSmsCode(this.data.form.phone)
  },

  onLogin() {
    const { phone, code } = this.data.form;
    if (!/^1\d{10}$/.test(phone)) {
      this.setData({ 'errors.phone': '手机号格式不对' });
      return;
    }
    this.setData({ loading: true });
    // 第五篇会把它换成真正的请求封装
    setTimeout(() => {
      this.setData({ loading: false });
      wx.switchTab({ url: '/pages/home/home' });
    }, 800);
  },

  onUnload() {
    clearInterval(this.timer);  // ⚠️ 页面销毁要清定时器
  },
});

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

表单状态装进一个 form 对象，更新用 setData 的路径语法（'form.phone': value），只传变化的那一小条数据过线程桥——2.2 节的第一性原理在这里第一次兑现。
按钮的「正常 / 加载中 / 禁用」形态由状态驱动，UI 本质是状态机，这在 Vue、Android、小程序里是同一句话。
定时器在 onUnload 里清掉——页面销毁了定时器还在跑，轻则无效 setData 报错刷屏，重则内存泄漏。这是第四篇生命周期的预演。

3.4 原生还是跨端框架？一个绕不开的决策

只要做小程序，早晚有人问你：为什么不用 Taro / uni-app，一套代码出五端？我的建议是按团队和业务的真实情况选，而不是按技术情怀：

flowchart TD
    Q{"业务分布在哪？"}
    Q -->|"只发微信小程序<br/>且追求极致体验"| A["原生开发<br/>能力最全 坑最少<br/>新 API 第一天就能用"]
    Q -->|"微信 + 支付宝/抖音多平台<br/>或同时要 H5"| B["uni-app / Taro<br/>用平台差异最小的子集"]
    Q -->|"团队全是 React 技术栈"| C["Taro"]
    Q -->|"团队全是 Vue 技术栈"| D["uni-app"]

踩坑故事六：跨端框架里用了「全平台都支持」的组件，抖音端直接白屏

现象：uni-app 项目用了一个官方组件库的级联选择器，微信端、H5 端正常，发布到抖音小程序直接白屏，排查三天发现是该组件内部用了抖音端不支持的一个 API。

感悟：跨端框架解决的是「语法转换」，解决不了「平台能力差异」。微信小程序的能力更新最快（微信自家的新能力当然先给自己），跨端框架追平永远有时间差。选跨端，就要接受「用所有平台能力的最小公约数」这个约束。小团队单平台起步，先原生，等真的要多端了再迁移，往往比第一天就上跨端框架更划算。

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

前三篇你能写出一个页面了。但真实小程序是几十个页面、被用户以你想象不到的顺序跳转、随时被微信切到后台。这一篇建立组织代码的地基。

4.1 生命周期：App、Page、Component 三层

stateDiagram-v2
    [*] --> App_onLaunch: 冷启动(整个小程序只此一次)
    App_onLaunch --> Page_onLoad: 打开第一个页面
    Page_onLoad --> Page_onShow: 页面显示
    Page_onShow --> Page_onReady: 首次渲染完成
    Page_onReady --> Page_onHide: 跳转下一页 / 切后台
    Page_onHide --> Page_onShow: 返回本页 / 回到前台
    Page_onShow --> Page_onUnload: 页面被销毁(redirect/navigateBack)
    Page_onUnload --> [*]

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

onLoad 一生只来一次，onShow 每次显示都来：onLoad 只在页面创建时执行一次，拿着跳转参数；onShow 每次显示都来。「返回时要不要刷新列表」的答案就是把刷新逻辑放 onShow，而不是假设 onLoad 会再来。
onReady 之前别碰节点：wx.createSelectorQuery() 查 DOM 要等首次渲染完成，放 onLoad 里查高度会拿到 0。
小程序没有可靠的「退出回调」：用户按胶囊按钮关掉小程序，onUnload 之后 App 可能还活着，也可能随时被系统回收。重要数据不能指望「退出时再保存」，和 Android 的 onDestroy 不保证调用是同一个道理。

踩坑故事七：编辑页保存返回，列表还是旧数据

现象：从列表页进编辑页，改完保存返回，列表纹丝不动。

原因：返回上一页走的是 navigateBack，上一页的实例没有被销毁，onLoad 不会再执行。

解法，两种主流姿势：

// 解法一：列表页把刷新放 onShow
onShow() {
  this.loadList();   // 返回时自然刷新，缺点是首次会重复加载，加 flag 控制
}

// 解法二：编辑页保存后主动通知上一页（事件总线 / getCurrentPages）
const pages = getCurrentPages();
const prevPage = pages[pages.length - 2];
prevPage.onNeedRefresh?.();   // 直接调上一页的方法
wx.navigateBack();

4.2 页面栈：小程序导航的「宪法」

小程序的页面不是平铺的，是一个栈：

flowchart LR
    subgraph stack["页面栈（最多 10 层）"]
        A["首页<br/>栈底"] --> B["列表页"] --> C["详情页"] --> D["编辑页<br/>栈顶"]
    end
    E["navigateTo<br/>压栈 保持当前页"] -.->|"+1 层"| stack
    F["navigateBack<br/>出栈返回"] -.->|"-1 层"| stack
    G["redirectTo<br/>替换栈顶"] -.->|"层数不变"| stack
    H["reLaunch<br/>清空重开"] -.->|"栈重置"| stack
    I["switchTab<br/>跳 tabBar 页"] -.->|"非 tabBar 页全部出栈"| stack

踩坑故事八：跳转到第十一层，按钮点了没反应

现象：一个「猜你喜欢 → 详情 → 相关推荐 → 详情 → …」的商品浏览链路，用户连点十次之后，再点卡片毫无反应，既不跳转也不报错（老基础库静默失败）。

原因：navigateTo 的页面栈上限是 10 层，到了第 11 次压栈直接失败。

解法：自循环的详情链路用 redirectTo（替换栈顶而不是压栈），或者监测栈深度，满了就 reLaunch 回首页。这也是「返回键要按十下才能退出」这种体验事故的根源——栈越深，用户的返回路径越长。

踩坑故事九：navigateTo 跳 tabBar 页，永远不生效

现象：wx.navigateTo({ url: '/pages/home/home' }) 调用了，纹丝不动。

原因：tabBar 页面不在普通页面栈体系里，必须用 wx.switchTab；反过来，非 tabBar 页不能用 switchTab。两类页面的 URL 在 app.json 里就决定了（tabBar.list 里的那几个），API 选错是唯一可能的原因。

教训：这条错不报错、静默失败，是新人调试时间最长的坑之一。记住口诀：tabBar 用 switchTab，栈满用 redirectTo，重启用 reLaunch，其他 navigateTo。

4.3 组件化与通信：从页面到 Component

页面大了要拆组件。自定义组件也是四文件结构，js 里用 Component({...}) 代替 Page({...})：

// components/price-card/index.js
Component({
  options: {
    styleIsolation: 'isolated',   // ⚠️ 见踩坑故事十
  },
  properties: {
    price: { type: Number, value: 0 },      // 父传子
  },
  data: { /* 组件内部状态 */ },
  methods: {
    onBuy() {
      this.triggerEvent('buy', { price: this.data.price });  // 子传父：派事件
    },
  },
});

<!-- 父页面使用 -->
<price-card price="{{item.price}}" bind:buy="onBuy" />

通信方式的全景：

flowchart TD
    A["父 → 子<br/>properties"] --- S["组件通信"]
    B["子 → 父<br/>triggerEvent 派事件"] --- S
    C["任意组件 ↔ 全局<br/>mobx-miniprogram 绑定"] --- S
    D["页面间<br/>EventChannel(navigateTo 时建立)<br/>或事件总线"] --- S

踩坑故事十：改组件库样式改不动，自己页面的样式却互相污染

现象：给 van-button 写了个覆盖样式死活不生效；反过来，A 页面给 .title 写的红色，B 页面的 .title 也变红了。

原因：小程序的样式隔离规则和直觉相反：

页面之间：样式是全局的！A 页面 WXSS 里的类名会污染 B 页面（同名类）。
组件内部：默认有隔离（isolated），外面的样式进不去，里面的样式出不来——所以改不动组件库。

解法：

页面样式一律加页面级命名空间：.page-order .title { ... }，或者干脆多用组件（组件天然隔离）。
组件需要接收外部样式时，在 options 里调 styleIsolation: 'apply-shared'（外能进内不出）或 shared（双向），改组件库主题时经常要用到。

4.4 全局状态：mobx-miniprogram 就够了

页面多了之后，「用户信息、购物车数量」这类全局状态在几十个页面间传来传去会迅速失控。小程序生态没有 Vuex/Pinia 那样的官方答案，事实标准是 mobx-miniprogram + mobx-miniprogram-bindings：

// stores/user.js
import { observable, action } from 'mobx-miniprogram';

export const userStore = observable({
  userInfo: null,
  get isLoggedIn() {
    return !!this.userInfo;
  },
  setUserInfo: action(function (info) {
    this.userInfo = info;
  }),
});

// 页面绑定：store 变了，页面 data 自动同步
import { createStoreBindings } from 'mobx-miniprogram-bindings';
import { userStore } from '../../stores/user';

Page({
  onLoad() {
    this.storeBindings = createStoreBindings(this, {
      store: userStore,
      fields: ['userInfo', 'isLoggedIn'],
      actions: ['setUserInfo'],
    });
  },
  onUnload() {
    this.storeBindings.destroyStoreBindings();  // ⚠️ 记得销毁
  },
});

思考：这套写法的心智模型和 Vue 的 Pinia + computed 完全一致——「store 是唯一数据源，页面只是绑定」。同时别忘了给 Component 配上官方扩展库 computed 和 watch（mobx-miniprogram 同一作者出品），小程序原生组件没有计算属性，手写派生状态是代码腐烂的起点。

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

架构定了，现在填数据的肉。这一篇学完，你就能写出「登录 + 联网 CRUD + 本地缓存」的完整小程序了。

5.1 wx.request：先把回调包成 Promise

小程序的联网 API 是回调风格的 wx.request，直接用会很快陷入回调地狱（2.5 节那种嵌套套嵌套）。项目第一天就该做的封装：

// utils/request.js
const BASE_URL = 'https://api.example.com';

function request({ url, method = 'GET', data, needAuth = true }) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + url,
      method,
      data,
      timeout: 10000,
      header: {
        // 统一带 token：小程序没有 Cookie 自动管理，登录态自己维护
        Authorization: needAuth ? `Bearer ${wx.getStorageSync('token')}` : '',
      },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data);
        } else if (res.statusCode === 401) {
          // token 过期：清登录态，跳登录页
          wx.removeStorageSync('token');
          wx.reLaunch({ url: '/pages/login/login' });
          reject(new Error('登录已过期'));
        } else {
          reject(new Error(res.data?.message || `请求失败 ${res.statusCode}`));
        }
      },
      fail(err) {
        // 断网、超时、域名不在白名单都走这里
        reject(new Error('网络异常，请稍后重试'));
      },
    });
  });
}

// 使用：async/await，和前端写 axios 一个手感
async onLoad() {
  try {
    const todos = await request({ url: '/todos' });
    this.setData({ todos });
  } catch (e) {
    wx.showToast({ title: e.message, icon: 'none' });
  }
}

设计要点：拦截逻辑（带 token、401 处理、错误归一化）写在这一层，业务代码就只剩一行 await——这和 Android 的 OkHttp 拦截器、前端的 axios 拦截器是同一种分层思想。

踩坑故事十一：401 了，但页面还停在原地

现象：token 过期后接口返回 401，封装的 request 里做了 reLaunch 跳登录页，但用户反馈「偶尔跳不过去」。

原因：wx.reLaunch 跳转登录页时，如果当前页面栈里有 tabBar 页，reLaunch 的目标 URL 带了 query 参数在部分基础库上被丢弃；更隐蔽的是——401 时多个并发请求会触发多次 reLaunch，第二次 reLaunch 打断了第一次。

解法：401 处理加防抖锁：

let isRedirectingToLogin = false;
function handleUnauthorized() {
  if (isRedirectingToLogin) return;
  isRedirectingToLogin = true;
  wx.removeStorageSync('token');
  wx.reLaunch({
    url: '/pages/login/login',
    complete: () => { isRedirectingToLogin = false; },
  });
}

移动端特有的提醒（小程序同理）：微信用户会进电梯、切 Wi-Fi 和流量，弱网和断线是常态而不是异常。timeout 必须配、失败要给重试入口、wx.showToast 报错别弹全屏错误页——静默重试一次，体验天差地别。

5.2 本地存储：wx.setStorage 的分寸

小程序的存储比 Android 简单得多，没有 Room 没有 DataStore，就一个 wx.setStorage / wx.getStorage（异步）和 wx.setStorageSync / wx.getStorageSync（同步）：

flowchart TD
    Q{"要存什么？"}
    Q -->|"token / 用户设置<br/>小键值对"| A["wx.setStorageSync<br/>同步 简单"]
    Q -->|"列表缓存 / 草稿<br/>几 KB 以上的数据"| B["wx.setStorage (异步版)<br/>⚠️ 同步版大数据会卡 UI"]
    Q -->|"要跟随用户换设备<br/>或免后端"| C["微信云开发<br/>云数据库 + 云函数"]
    Q -->|"敏感数据(密码之类)"| D["❌ 别存本地<br/>存 token 不存密码"]

两个数字要记住：单个 key 上限 1MB，总上限 10MB。超出直接写入失败。

踩坑故事十二：storage 同步读写把首页卡死了

现象：首页加载越来越慢，Profiling 发现 getStorageSync 一个调用占了 200ms。

原因：运营活动的弹窗配置、AB 实验分组、用户信息……十几个模块都往 storage 里塞，有个模块把整份商品列表（几百 KB）也存了进去，首页启动时同步读，主线程原地罚站。

解法：

大对象读写一律用异步版（wx.getStorage）。
启动时只读「渲染首屏必需」的字段，其余懒加载。
token 这种小且高频的用同步版没问题——按数据大小和频率选 API，不是按顺手程度。

5.3 云开发：没有后端时的另一条路

如果你是个人开发者、没有自己的服务器，微信云开发（CloudBase）值得单独了解：云数据库（类 MongoDB）、云函数（Node.js）、云存储、云调用（直接调微信 API 免鉴权），在开发者工具里一站式完成，不用买服务器、不用配域名、不用过 ICP 备案——对，云开发的请求不受 1.3 节域名白名单限制，这对个人开发者是巨大优势：

// 免鉴权、免域名配置，一行调用
const db = wx.cloud.database();
const res = await db.collection('todos').where({ done: false }).get();

代价是：数据模型简单、复杂业务（多表事务、复杂查询）不如自建后端灵活，迁移到自有后端的成本不低。工具类、内容类、Demo 项目用云开发；交易核心、复杂业务自建后端。

第六篇平台能力：登录、订阅消息、分享、支付与分包

到这里，你的小程序已经「自成一体」了。这一篇让它和微信这个平台打交道。平台能力的坑有一个共同特征：文档看着简单，但 API 的生命周期变迁极快，照着两年前的教程写必踩坑。

6.1 登录：code 换 openid 的三段握手

小程序登录是平台能力里设计最优雅的一个，也是面试必考题：

sequenceDiagram
    participant MP as 小程序前端
    participant WX as 微信服务器
    participant S as 你的后端
    MP->>WX: wx.login() 拿 code(5分钟有效)
    MP->>S: 把 code 发给自己的后端
    S->>WX: code + appid + secret 换<br/>openid + session_key
    WX-->>S: openid(用户唯一标识) + session_key
    S-->>MP: 签发自家 token(如 JWT)
    Note over MP: 之后所有请求带 token<br/>session_key 永远不出后端

三条铁律：

session_key 绝不能下发到前端——它能解密用户敏感数据，泄漏等于把用户数据大门敞开。
code 只能用一次且 5 分钟过期，换取动作必须在后端做（secret 也不能进前端代码）。
前端维护的是自家 token，不是微信的 code。5.1 节 request 封装里带的 Authorization 就是它。

踩坑故事十三：跟着老教程写 getUserProfile，提交审核被拒

现象：照着 2021 年的教程用 wx.getUserProfile 拿用户头像昵称，真机一调返回 getUserProfile:fail can only be invoked by user TAP gesture 或直接被拒审。

原因：微信在 2022 年回收了 getUserProfile 能力。现在获取头像昵称的官方姿势是两个表单组件：

<!-- 头像：button open-type="chooseAvatar" -->
<button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">
  <image src="{{avatarUrl || '/images/default-avatar.png'}}" />
</button>
<!-- 昵称：input type="nickname"，拉起微信输入法半屏 -->
<input type="nickname" placeholder="请输入昵称" bind:blur="onNicknameBlur" />

教训：这是小程序开发最重要的生存技能——微信 API 的废弃和变更极快，任何「照着教程写」的代码都要去官方文档核对一遍最新版本。关注「微信小程序开发者文档」的更新日志，比关注任何公众号都有用。

6.2 订阅消息：推送的正确打开方式

小程序没有 Android 那种「随便推」的通知系统，触达用户的正道是订阅消息：

flowchart LR
    A["用户在小程序里<br/>主动点击按钮"] --> B["wx.requestSubscribeMessage<br/>弹出订阅授权框"]
    B --> C{"用户怎么选？"}
    C -->|"允许"| D["后端在服务通知里<br/>下发一次消息"]
    C -->|"拒绝"| E["⚠️ 同一个模板<br/>短期内不能再弹"]
    C -->|"勾选『总是保持以上选择』"| F["以后静默按上次选择执行"]

关键认知：订阅消息默认是一次性的——用户点一次允许，你只能推一次。长期订阅仅对政务、医疗等特定类目开放。所以正确的产品设计是「在最关键的动作上请求订阅」（下单、预约、打卡），而不是见缝插针地弹。

踩坑故事十四：订阅消息发出去了，用户没收到

按出现概率排查：

模板 ID 不对：模板在 mp 后台「订阅消息」里申请，tmplIds 写错或用了测试模板，发送直接报错。
关键词格式不匹配：模板里的 {{thing1.DATA}}（字符串）、{{amount2.DATA}}（金额）每种类型有严格格式限制，金额必须是数字、字符数超限都会发送失败——失败原因要去查发送接口的返回码，客户端无感知。
用户没订阅 / 订阅次数用完了：一次订阅只够推一次，推完额度清零。
跳转页面未发布：消息配置的 page 路径必须是已发布版本里存在的页面，配了还在开发中的页面，用户点消息会跳到错误页。

6.3 分享与裂变：小程序的增长引擎

小程序生于社交，分享能力是它的原生优势：

// 页面级分享：定义了才有「转发」入口的内容
Page({
  onShareAppMessage() {
    return {
      title: '这个记账小程序太好用了',
      path: '/pages/home/home?from=share&uid=' + this.data.uid,  // ⚠️ 路径带参做裂变归因
      imageUrl: '/images/share-cover.png',  // 5:4 比例，自定义封面
    };
  },
});

应知应会的分寸：

分享无法拿到「是否分享成功」的回调了（早年有，已回收）——「分享成功就送优惠券」这种强制裂变做不了，这也是微信的刻意设计。
朋友圈：小程序不能直接分享到朋友圈（除了特定的「分享到朋友圈」Beta 能力且仅 Android），正道是生成海报图让用户自己发——3.1 节的 wxml-to-canvas 就是干这个的。
裂变归因全靠 path 参数：谁分享的、从哪进来的，都编码在 onShareAppMessage 的 path 里，落地页在 onLoad(options) 里解析。这套机制就是小程序增长黑客的全部基础。

6.4 支付：五步流程，前后端各管一半

微信支付是平台能力里链条最长的，画出来再写代码：

sequenceDiagram
    participant MP as 小程序
    participant S as 你的后端
    participant WX as 微信支付
    MP->>S: 1. 创建订单(商品 金额)
    S->>WX: 2. 统一下单(用商户号密钥签名)
    WX-->>S: prepay_id
    S-->>MP: 3. 返回支付参数(二次签名)
    MP->>WX: 4. wx.requestPayment 拉起收银台
    WX-->>MP: 用户输密码完成
    WX-->>S: 5. ⚠️ 支付结果异步回调(这才是到账依据)

踩坑故事十五：以前端回调为准发货，被刷单薅了羊毛

现象：wx.requestPayment 的 success 回调里直接通知后端「支付成功，发货」，上线一个月被恶意用户用篡改的客户端刷出大量未付款订单。

原因：前端的一切回调都不可信。唯一可信的到账凭证是微信支付服务器推送给你后端的异步回调（pay 通知），验签通过才算数。

教训：这条规则在 Android 内购、Stripe 支付里一模一样——客户端回调只负责 UI 表现，服务端回调才负责业务状态。凡是涉及钱的状态变更，永远以服务端到服务端的通知为准。

另外记住 1.2 节的连锁反应：虚拟商品（课程、会员）在 iOS 端不能走微信支付（苹果规则），要么引导安卓/H5 支付，要么走小程序虚拟支付通道并接受抽成——类目和主体在注册那天就决定了你有没有资格碰这块。

6.5 分包加载：2MB 限制的解法

小程序主包上限 2MB（总包 20MB），所有页面塞一个包很快就会撞线。答案是分包：

// app.json
{
  "pages": ["pages/home/home", "pages/login/login"],
  "subPackages": [
    {
      "root": "packageOrder",
      "pages": ["pages/list/list", "pages/detail/detail"]
    },
    {
      "root": "packageUser",
      "pages": ["pages/profile/profile", "pages/setting/setting"]
    }
  ],
  "preloadRule": {
    "pages/home/home": {
      "network": "wifi",
      "packages": ["packageUser"]
    }
  }
}

flowchart TD
    A["主包 ≤ 2MB<br/>首页 + tabBar 页 + 公共代码"] -->|"用户点进订单模块"| B["订单分包<br/>按需下载"]
    A -->|"Wi-Fi 下预加载"| C["个人中心分包"]
    style A fill:#e8f4e8

设计要点：首页和 tabBar 页必须在主包（启动就加载）；低频功能（设置、关于、客服）果断拆分包；preloadRule 让「首页加载完、Wi-Fi 下静默下载个人中心包」，用户点过去秒开。

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

功能做完只是上半场。小程序的发布比 Android 多了一道「平台审核」，这是它最独特的一关。

7.1 性能三板斧：setData、分包、图片

小程序性能问题的 90% 集中在这三件事上：

第一板斧：setData 瘦身（2.2 节第一性原理的兑现）

flowchart TD
    A["页面卡顿"] --> B{"setData 传的什么？"}
    B -->|"整个大列表"| C["改成路径更新<br/>'list[3].done': true"]
    B -->|"高频调用<br/>onPageScroll / 倒计时"| D["合并 + 节流<br/>攒一批一次发"]
    B -->|"传了视图用不到的字段"| E["data 里只放渲染需要的数据<br/>其余存 this 普通属性"]

// ❌ 每秒 setData 整个对象
this.setData({ form: this.data.form });

// ✅ 只传变化的字段
this.setData({ 'form.phone': value });

// ✅ 不参与渲染的数据根本别进 data
Page({
  data: { list: [] },
  onLoad() {
    this._rawResponse = null;  // 内部缓存，挂 this 上不挂 data
  },
});

第二板斧：分包——6.5 节已经讲过，启动速度的第一优化项。

第三板斧：图片——列表图一律压缩到展示尺寸的 2 倍以内、用 image 组件的 lazy-load、CDN 域名配进 downloadFile 白名单。首屏图太多时，骨架屏比 loading 转圈的感知快一倍。

踩坑故事十六：倒计时把列表页卡成 PPT

现象：团购列表每个卡片都有「距结束 xx:xx」倒计时，页面滑动掉帧严重。

原因：20 个卡片各自开了 setInterval，每秒 20 次 setData 跨线程传输——桥堵了。

解法：一个全局定时器，每秒算一次所有卡片的剩余时间，合并成一次 setData：

// 一个 timer 驱动全部卡片
this.timer = setInterval(() => {
  const updates = {};
  this.data.list.forEach((item, i) => {
    updates[`list[${i}].remainText`] = formatRemain(item.endTime);
  });
  this.setData(updates);   // 每秒只有这一次过桥
}, 1000);

7.2 调试三板斧：vConsole、真机调试与体验版

开发者工具：模拟器 + Wxml 面板（看最终渲染树）+ AppData 面板（实时看每个页面的 data，排查 setData 问题的第一现场）。
真机调试：开发版小程序右上角胶囊菜单里打开「开发调试」，vConsole 会浮在页面上——手机上看到 console.log、网络请求、storage 内容。真机和模拟器的差异比你想的大：字体渲染、安全区、性能、个别 API 行为都不一样，发布前必须真机过一遍主流程。
体验版：上传代码后在 mp 后台设为体验版，添加体验成员（微信号），扫码即用。它是「发给产品和测试同学」的标准姿势，比 Android 装 APK 优雅得多。

踩坑故事十七：体验版打不开，群里一片「白屏了」

现象：上传体验版后，自己手机正常，测试同学扫码一直白屏。

排查路径：

对方的微信号加进「体验成员」了吗？
你上传后设为体验版了吗？（上传 ≠ 自动成为体验版，要在版本管理里手动选）
对方是不是打开了「调试模式」导致走了别的版本？（体验版打开调试后会加载开发版代码，版本就乱了）

教训：小程序有「开发版 / 体验版 / 线上版」三个版本共存，版本切换的开关藏在各处。发体验版给别人之前，用一个不在体验成员名单里的微信号扫一次——模拟用户的真实路径，这一分钟能省一小时的群聊排查。

7.3 审核与发布：小程序独有的最后一关

flowchart LR
    A["开发者工具<br/>上传代码"] --> B["mp 后台<br/>提交审核"]
    B --> C{"审核结果<br/>几小时到几天"}
    C -->|"通过"| D["手动点『发布』<br/>全量上线"]
    C -->|"拒绝"| E["按驳回原因改<br/>重新排队"]
    D --> F["灰度发布<br/>按比例放量 可回退"]

提高一次过审率的实战清单：

类目和内容对齐（1.2 节）：电商功能挂企业类目，个人号别碰交易。
给用户「不登录也能逛」的路径：审核员会拒绝「打开就强制授权手机号」的小程序。登录应该发生在「需要身份的那个动作」上（下单、收藏），而不是启动时。
测试账号：审核表单里提供测试账号密码或免密通道，审核员进不去你的核心流程必拒。
敏感功能自审：UGC 内容要有举报/审核机制说明；涉及医疗、金融的回答要有资质上传。

感悟：审核这道关常被骂，但它塑造了小程序生态和 App 生态的根本不同——小程序是「寄居」在微信里的，平台既是分发渠道也是监管者。接受这个设定，把审核标准当作产品设计的一部分（登录时机、隐私协议、类目选择），而不是发布前的拦路虎，你的过审率会高得多。

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

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

8.1 AI 在小程序开发各环节的胜任度

flowchart LR
    subgraph good["AI 做得极好 放心交出去"]
        A1["单页面骨架<br/>wxml + wxss + Page({...})"]
        A2["表单页 / 列表页<br/>配 vant-weapp 组件"]
        A3["request 封装 / 工具函数"]
        A4["单元测试与类型定义"]
    end
    subgraph mid["AI 能做 但你要盯着"]
        B1["跨页面状态设计"]
        B2["性能优化(setData/分包)"]
        B3["组件库主题定制"]
    end
    subgraph bad["AI 做不好 还得靠人"]
        C1["类目/资质/审核问题<br/>(政策天天变)"]
        C2["真机才出现的 bug<br/>安全区 键盘 滚动"]
        C3["微信 API 的最新变更<br/>(训练数据滞后)"]
    end

第三格要特别说：微信 API 的变更速度（6.1 节 getUserProfile 的故事）恰好打在 AI 的软肋上——训练数据里全是旧 API 的示例。AI 给你写 wx.getUserInfo 时你要能一眼认出「这是 2021 年的写法」。

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

第一步：先写「项目宪法」，再让 AI 写代码。 在项目里放一个 AGENTS.md：

# 项目约定
- 原生小程序（不用跨端框架），组件库 @vant/weapp，less 写样式
- 页面四文件结构：wxml/wxss/js/json，页面样式加命名空间防污染
- 全局状态用 mobx-miniprogram + mobx-miniprogram-bindings，组件配 computed 扩展
- 网络统一走 utils/request.js 封装，async/await，业务代码禁止裸 wx.request
- setData 只传变化字段的路径写法；不参与渲染的数据挂 this 普通属性
- 跳转口诀：tabBar 用 switchTab，自循环链路用 redirectTo，其他 navigateTo
- 回调一律箭头函数；定时器/绑定在 onUnload 里清理
- 登录态：wx.login 拿 code 给后端换 token，前端只存 token，禁存 session_key

注意这份清单里的每一条，都对应着前面某一篇的某个坑——项目宪法本质上是踩坑笔记的浓缩。

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

第三步：让它先写数据结构和状态，再写 UI。 先生成页面的 data 结构、接口契约、状态流转，review 通过后再写 wxml——这正是第四、五篇的架构顺序。状态设计错了，UI 写得再漂亮也是白写。

第四步：报错直接喂回去，但分清两类问题。 模拟器里的 JS 报错、组件找不到这类代码级问题，贴给 AI 循环两三次基本能解；但 1.2 节那种账号类目问题、6.1 节那种 API 已废弃问题、真机上才出现的白屏——AI 帮不了，它没有你的 mp 后台权限，也没有真机。这就是为什么 AI 篇必须排在最后：它是放大器，放大的是你前七篇的水平。

第五步：人工 review 的五个必查点。 AI 生成的小程序代码，我每次都只细查五处：① setData 是不是整个大对象往里塞（性能重灾区）；② 定时器和 store 绑定有没有在 onUnload 里清理（泄漏来源）；③ 跳转 API 用对没有（tabBar 页 navigateTo 的静默失败 AI 经常犯）；④ 请求有没有走统一封装、token 处理对不对；⑤ 用的微信 API 是不是已经废弃的版本。其他代码粗看即可——review 的精力要花在 AI 的已知短板上。

8.3 一个真实对比：Demo 小程序的工时变化

第三篇那个登录页 + 一个待办列表页的小程序 Demo，三年前我要写一整天（查 API、调样式、处理状态）。2026 年用 AI 的实际耗时：

pie title 一个双页面 Demo 的 2 小时去哪了
    "写 AGENTS.md 和提示词" : 20
    "AI 生成 + 我 review 修改" : 55
    "AppID/类目/域名配置(AI帮不上)" : 25
    "真机测试与细节打磨" : 20

注意那张饼图里最大的启示：省下来的时间没有消失，它转移到了「描述需求」和「审查代码」上，还有一部分转移到了 AI 永远碰不到的「平台事务」上——注册、类目、域名、审核。AI 时代的核心能力从「打字速度」变成了三样：

把模糊需求拆成精确技术任务的能力——你对第四篇架构的理解越深，给 AI 的指令就越准。
快速判断代码对错的能力——看不懂 setData 成本的人，review 不了 AI 写的小程序代码。
搞定平台事务的能力——类目、资质、审核、API 变更，这些「和微信打交道」的事，一件都外包不出去。

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

小程序生态和 AI 有一个有趣的共同点：它们都在「消灭记忆型知识的价值」。小程序当年消灭了「会写 Objective-C/Java 才能做移动端」的门槛；AI 今天消灭了「背得出 API 参数才配写代码」的门槛。留下来的价值是同一种东西——判断型知识：

这个状态该放 data 还是挂 this 上？
这个跳转该用 redirectTo 还是 navigateTo？
这个需求个人主体能不能做，会不会死在审核？
AI 写的这段代码用的 API，是不是去年就被回收了？

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

结语：学习路线收个尾

flowchart LR
    A["第 1 周<br/>注册 AppID + 跑通模板<br/>+ 四件套语法"] --> B["第 2-3 周<br/>vant-weapp 组件库<br/>写 5 个静态页面"]
    B --> C["第 1-2 个月<br/>生命周期 + request 封装<br/>+ 登录流程<br/>写一个联网 CRUD 小程序"]
    C --> D["第 2-4 个月<br/>订阅消息/分享/支付/分包<br/>体验版 审核 发布上线"]
    D --> E["持续<br/>把 AI 变成<br/>你的初级工程师"]

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

第一周死磕账号不丢人。类目、主体、域名、备案，这些「和微信打交道」的事才是真正的门槛，写代码反而是最简单的部分。这不是你笨，是这个生态的真实成本。
第一天就用真机预览。模拟器掩盖了安全区、键盘、性能和版本差异问题——你的用户分布在几千种机型的微信里，而小程序的真机预览只要扫个码，这是整个客户端开发里成本最低的真机测试，没有借口不用。
让 AI 写代码，让自己写笔记。每踩一个坑记下「现象、根因、下次怎么一眼认出」，这些笔记是 AI 时代你不可被替代的资产——因为 AI 知道所有答案，但它不知道微信上个月又改了哪个 API，以及你的审核上次为什么被拒。

祝你的 setData 永远轻盈，审核永远一次过，小程序在 iPhone SE 和折叠屏上都一样流畅。

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 在华为和小米上都一样坚挺。

iOS 开发从入门到精通：环境搭建、Swift 语法、系统特性与 AI 时代的高效开发

Wed, 02 Aug 2023 08:30:00 +0800

iOS 开发从入门到精通：环境搭建、Swift 语法、系统特性与 AI 时代的高效开发

目标读者：会一门编程语言（前端、后端都行），想进入 iOS 开发；或者写过大半年 iOS，但对证书、内存、系统权限、上架总觉得心里没底的同学。

这篇文章是我从「被证书签名折磨到怀疑人生」到「能独立上架一个 App」的完整复盘。照例不讲完所有 API（Apple 官方文档比我权威），只讲五件事，由浅到深排布：

环境搭建：新人第一道鬼门关，很多人还没写代码就死在这里。
Swift 语法主干：真正重要的 20%。
UI 技术选型：SwiftUI 还是 UIKit，以及那些绕不开的第三方库。
系统特性与中级内功：页面写得好只是前台功夫，和系统打交道、把 App 做「上线级」才是后台功夫。
AI 时代的开发方式：怎么让 AI 帮你写掉 70% 的代码，以及剩下的 30% 为什么恰恰最值钱。

先给一张全文路线图：

flowchart LR
    A["环境搭建<br/>Xcode / 证书 / 模拟器"] --> B["Swift 语言<br/>Optional / 闭包 / 协议"]
    B --> C["UI 开发<br/>SwiftUI 或 UIKit"]
    C --> D["系统特性<br/>定位 存储 网络 通知 唤起"]
    D --> E["中级内功<br/>生命周期 架构 测试 发布"]
    E --> F["AI 协同开发<br/>更少代码 更快交付"]

第一篇环境搭建：新人劝退第一关

1.1 你需要什么

iOS 开发有个绕不开的前提：你需要一台 Mac。Apple 的生态是封闭的，Xcode 只跑在 macOS 上。

flowchart TB
    A["Mac（macOS 最新版）"] --> B["App Store 下载 Xcode<br/>约 10GB+"]
    B --> C["Xcode 内含<br/>编译器 / 模拟器 / 调试器"]
    C --> D["注册 Apple ID<br/>免费，可跑真机（7 天签名）"]
    D --> E["付费开发者账号<br/>99 美元/年，上架必备"]

预算建议：M 系列芯片的 Mac mini 是性价比之选；硬盘务必 512GB 起步——Xcode 本体加几个模拟器系统镜像，轻松吃掉 100GB。

踩坑故事 1：App Store 下载 Xcode 卡了三天

新人第一天，App Store 下载 Xcode 进度条走到 80% 反复失败。这是 App Store 的祖传毛病。正确姿势：去 Apple Developer 官网下载 .xip 安装包，或者用开源的 Xcode 版本管理器 xcodes 安装。后者还能同时管理多个 Xcode 版本，老项目用旧版、新项目用新版，互不打架。

1.2 证书与签名：iOS 开发的「百慕大三角」

开发阶段你迟早会撞见这个错误：

Code Signing Error: No signing certificate "iOS Development" found

先理解原理，再看图：

flowchart LR
    A["你的 Mac<br/>私钥 + CSR"] -->|"请求"| B["Apple 开发者后台<br/>签发证书"]
    B --> C["描述文件 Provisioning Profile<br/>绑定：证书 + 设备 + AppID"]
    C --> D["Xcode 打包时用私钥签名"]
    D --> E["iPhone 验证签名后允许运行"]

三样东西必须对应上：证书（你是谁）、AppID（哪个应用）、设备（哪台手机）。任何一个对不上，真机就跑不起来。

踩坑故事 2：上线前夜，证书被同事 Revoke 了

公司账号多人共用，一位同事在自己电脑上「修复」签名问题时，随手点了 Revoke 旧证书——全团队的 CI 打包瞬间全部失败，第二天就是提审截止日。连夜重新生成证书、更新描述文件、改 CI 配置，凌晨四点才出包。

两条教训：第一，优先用 Xcode 的 Automatically manage signing，别手动折腾证书；第二，团队共用账号时，证书动任何操作前在群里吼一声。有条件的话上 fastlane match，用 Git 仓库统一管理证书，谁也别乱动。

1.3 第一个 App：5 分钟跑起来

Xcode → Create New Project → iOS → App，Interface 选 SwiftUI，Language 选 Swift。然后你就得到了一个能跑的 App：

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            Image(systemName: "globe")
                .imageScale(.large)
            Text("Hello, iOS!")
        }
        .padding()
    }
}

Cmd + R 跑模拟器。第一次编译会慢（在构建模块缓存），之后增量编译很快。

第二篇 Swift 语法：只吃主干

Swift 是一门现代、严谨、有点「强迫症」的语言。它的设计哲学一句话概括：让错误尽量发生在编译期，而不是用户的手机上。

2.1 可选类型（Optional）：Swift 的灵魂

这是 Swift 与其他语言最大的心智差异，也是新人崩溃的第一来源：

var name: String? = "方糖猫"   // ? 表示：可能有值，也可能是 nil

// 错误：编译不过
// print(name.count)

// 正确姿势一：if let 解包
if let unwrapped = name {
    print(unwrapped.count)
}

// 正确姿势二：guard let（函数里更常用）
func greet(name: String?) {
    guard let name = name else {
        print("没名字"); return
    }
    print("你好，\(name)")
}

// 正确姿势三：?? 提供默认值
print(name ?? "匿名")

flowchart TD
    A["拿到一个 Optional 值"] --> B{"确定它永远有值？"}
    B -->|"99% 的情况：不确定"| C["if let / guard let / ??<br/>安全解包"]
    B -->|"确定（极少）"| D["! 强制解包"]
    D -.->|"万一它是 nil"| E["💥 直接崩溃闪退"]

踩坑故事 3：一个 ! 毁掉的评分

接手过一个老项目，前任开发为了省事到处强制解包：dict["avatar"]!、array.first!、Int(str)!。某天后端接口调整，一个字段从必有变成可能缺失，线上崩溃率当天飙到 3%，App Store 评分一周掉了 1.2 分。

修复原则很简单，执行起来要毅力：全项目搜 !，每一个都要能说出「它为什么不可能为 nil」，说不出的就改成安全解包。Crashlytics 的崩溃报表里，强制解包常年霸榜，这是 iOS 界公开的秘密。

2.2 struct 与 class：值类型和引用类型的分野

// struct：值类型，拷贝的是内容本身
struct Point { var x: Int; var y: Int }
var p1 = Point(x: 1, y: 1)
var p2 = p1
p2.x = 99
print(p1.x)  // 还是 1，互不影响

// class：引用类型，拷贝的是「门牌号」
class ViewModel { var title = "" }
let vm1 = ViewModel()
let vm2 = vm1
vm2.title = "改了"
print(vm1.title)  // "改了"，两个变量指向同一个对象

这个区别和 JavaScript 里「基本类型 vs 对象」一模一样，但 Swift 把它变成了显式的设计决策。经验法则：数据模型一律用 struct，需要共享状态和身份标识（ViewModel、Service）才用 class。

2.3 闭包与循环引用：内存管理必修课

Swift 用 ARC 自动管理内存，但有一个经典陷阱：两个 class 互相强引用，谁都释放不掉。

flowchart LR
    A["ViewController<br/>强引用"] --> B["Service"]
    B -->|"闭包捕获 self<br/>强引用回去"| A
    C["打破循环：闭包里写 [weak self]"] -.-> B

class DetailViewController: UIViewController {
    let service = DataService()

    func load() {
        // 错误：service 的闭包强引用 self，self 强引用 service，内存泄漏
        // service.fetch { self.updateUI() }

        // 正确：[weak self] 让闭包弱引用
        service.fetch { [weak self] data in
            self?.updateUI(with: data)
        }
    }
}

踩坑故事 4：越用越卡的 App

一个信息流 App 被用户投诉「刷十分钟就卡死」。用 Xcode 的 Memory Graph 一查：每进入一个详情页就泄漏一个 ViewController，退出页面后内存一点没降。罪魁祸首就是详情页里七八个网络回调闭包全都没写 [weak self]。逐页修复后，内存曲线从「阶梯式上升」变成了正常的「上下波动」。

感悟：前端开发者转 iOS 最容易在这里翻车——JavaScript 的垃圾回收帮你兜了底，而 Swift 的 ARC 是引用计数，循环引用它不回收。写闭包时肌肉记忆地加上 [weak self]，是 iOS 开发者的职业本能。

2.4 异步：async/await 与结构化并发

Swift 的 async/await 和 JavaScript 的很像，但多了「结构化并发」的约束：

struct User: Codable {
    let id: Int
    let name: String
}

func fetchUser(id: Int) async throws -> User {
    let url = URL(string: "https://api.example.com/users/\(id)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(User.self, from: data)
}

// 调用处
Task {
    do {
        let user = try await fetchUser(id: 1)
        print(user.name)
    } catch {
        print("请求失败：\(error)")
    }
}

需要并行时，用 async let——它保证所有并发任务在离开作用域前完成，不会像 JS 的 forEach(async...) 那样「放出去就没人管」：

async let user = fetchUser(id: 1)
async let orders = fetchOrders(userId: 1)
let (u, o) = try await (user, orders)  // 两个请求并行发出，这里等齐

2.5 协议（Protocol）：Swift 的接口哲学

protocol Drawable {
    func draw()
}

extension Drawable {
    func draw() { print("默认实现：画一个方块") }  // 协议可以有默认实现！
}

struct Circle: Drawable {
    func draw() { print("画一个圆") }
}

协议 + 默认实现（POP，面向协议编程）是 Swift 相对 Java/OC 的一大进化。第三方库大量用它做抽象，读源码时满屏都是。

2.6 阶段小结

Swift 入门标准：

看到 ? 和 ! 能条件反射地想「这里会不会是 nil」。
能徒手解释 struct 和 class 的三个区别（拷贝语义、继承、ARC）。
写闭包时下意识加 [weak self]。
会用 Codable 一行解析 JSON，不再手写字典取值。

第三篇 UI 开发：SwiftUI 还是 UIKit

3.1 两条路线的正面比较

flowchart TB
    subgraph UIKit["UIKit（2008 - ）"]
        A1["命令式：手动改 UI"]
        A2["生态成熟 资料多"]
        A3["老项目全是它"]
    end
    subgraph SwiftUI["SwiftUI（2019 - ）"]
        B1["声明式：UI = f(状态)"]
        B2["代码量少一半"]
        B3["iOS 13+ 才有"]
    end
    Q{"2026 年，学哪个？"}
    Q --> UIKit
    Q --> SwiftUI

UIKit 是命令式的：你手动创建 label、设 frame、加到视图层级。SwiftUI 是声明式的：你描述「状态是这样时，界面该长这样」，框架负责同步。写前端的同学会发现，SwiftUI 的思想和 Vue/React 一脉相承——数据驱动视图。

我的建议：学 SwiftUI 为主，UIKit 懂个大概。新项目几乎都是 SwiftUI 起手，但存量项目、某些复杂控件（高度自定义的列表、绘图）依然是 UIKit 的天下，两者通过 UIViewRepresentable / UIHostingController 互相嵌套，不是非此即彼。

3.2 SwiftUI 核心三板斧

struct CounterView: View {
    @State private var count = 0          // 状态：一变 UI 自动刷新

    var body: some View {
        VStack(spacing: 16) {             // 布局：VStack / HStack / ZStack
            Text("点击了 \(count) 次")
                .font(.title)
            Button("点我 +1") {
                count += 1
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
    }
}

三个概念吃透，SwiftUI 就懂了一半：

@State：组件私有的状态，改了自动刷新 UI。
View 协议 + body：每个界面都是「状态的函数」。
修饰符链：.font().padding().background() 这种链式调用，顺序不同结果可能不同。

踩坑故事 5：修饰符顺序引发的「灵异布局」
Text("你好")
    .padding()
    .background(Color.blue)   // 背景包住 padding，蓝底很大

Text("你好")
    .background(Color.blue)
    .padding()                // 先蓝底再撑开，padding 是透明的
新人以为修饰符像 CSS 一样「无顺序」，调了俩小时布局没对上设计稿。记住：SwiftUI 的每个修饰符都返回一个新 View，修饰符是从内往外一层层包裹的。想不通就念口诀：「谁在前，谁靠里」。

3.3 数据流：状态从哪来，往哪去

SwiftUI 的状态管理有一套属性包装器，选错一个就是 bug 温床：

flowchart TB
    A["@State<br/>本组件私有的值类型状态"]
    B["@StateObject<br/>本组件创建并拥有的 ViewModel"]
    C["@ObservedObject<br/>外面传进来的 ViewModel<br/>我不拥有 只是观察"]
    D["@EnvironmentObject<br/>全局注入的对象<br/>深层子孙直接取用"]
    E["@Binding<br/>父组件状态的引用<br/>子组件可以回写"]

踩坑故事 6：@ObservedObject 导致的状态「复活」

一个表单页用 @ObservedObject var vm = FormViewModel()——看着没问题，但这个 ViewModel 应该在父级创建并持有。结果父视图每次刷新，子视图的 ViewModel 就被重建，用户填到一半的表单数据凭空消失。

修法一行：改成 @StateObject（本组件是主人）或让父级用 @StateObject 创建后传入（子级用 @ObservedObject 接收）。记忆法：谁创建，谁 StateObject；只接收，就 ObservedObject。这条规则和 Vue 里「状态的唯一权威来源」异曲同工。

3.4 主流组件库与工具库

iOS 的第三方库生态这些年收敛得很厉害，下面是真正高频出现的：

库	干什么	备注
SnapKit	UIKit 布局的 DSL	手写 Auto Layout 必备
Kingfisher	图片异步加载与缓存	图片界的标配
Alamofire	网络请求封装	纯 SwiftUI 新项目可用原生 `URLSession`
Lottie	播放 AE 导出的动画 JSON	复杂动效的唯一解
KeychainAccess	钥匙串存取	存 token 见第四篇
SwiftLint	代码风格检查	团队项目标配

包管理工具的选择也已经尘埃落定：

flowchart LR
    A["CocoaPods<br/>老牌 重 侵入工程文件"] -.->|"逐渐淡出"| C
    B["Carthage<br/>去中心化 手动"] -.->|"边缘化"| C
    C["SPM Swift Package Manager<br/>Apple 官方 Xcode 内置<br/>新项目首选"]

新项目一律 SPM。CocoaPods 只在维护老项目时才会碰到了。

踩坑故事 7：一个第三方库拖垮整个编译

项目里接了一个功能很全但质量堪忧的统计 SDK，它要求旧版 Alamofire，而我们网络层已经升到新版，版本冲突导致 SPM 解析失败；更糟的是它混编了 OC，桥接头文件改动让全量编译时间从 3 分钟涨到 11 分钟。最后痛下决心自研了那部分功能（实际只有 200 行代码），编译时间回落，还少了一坨黑盒。

感悟：引第三方库的成本不是接入那一天，而是之后每一年。评估标准是：核心功能是否不可替代？维护是否活跃？能不能用 200 行自研替代？苹果的官方 API 每年都在吃掉第三方库的地盘（比如 URLSession 已经很好用），优先用官方的。

3.5 Demo：一个完整的 SwiftUI 待办 App

把上面的知识串起来——列表、状态、ViewModel、本地持久化，这个 Demo 可以直接跑：

import SwiftUI

// MARK: - 模型（值类型，Codable 方便持久化）
struct Todo: Identifiable, Codable {
    var id = UUID()
    var text: String
    var done: Bool = false
}

// MARK: - ViewModel
class TodoStore: ObservableObject {
    @Published var todos: [Todo] = [] {
        didSet { save() }                    // 数据一变就落盘
    }

    private let key = "todos_v1"

    init() { load() }

    func add(_ text: String) {
        let trimmed = text.trimmingCharacters(in: .whitespaces)
        guard !trimmed.isEmpty else { return }
        todos.append(Todo(text: trimmed))
    }

    func delete(at offsets: IndexSet) {
        todos.remove(atOffsets: offsets)
    }

    private func save() {
        if let data = try? JSONEncoder().encode(todos) {
            UserDefaults.standard.set(data, forKey: key)
        }
    }

    private func load() {
        guard let data = UserDefaults.standard.data(forKey: key),
              let saved = try? JSONDecoder().decode([Todo].self, from: data)
        else { return }
        todos = saved
    }
}

// MARK: - 视图
struct TodoListView: View {
    @StateObject private var store = TodoStore()   // 本视图创建并拥有
    @State private var newText = ""

    var body: some View {
        NavigationStack {
            List {
                ForEach($store.todos) { $todo in    // $ 生成 Binding，可回写
                    HStack {
                        Image(systemName: todo.done ? "checkmark.circle.fill"
                                                    : "circle")
                            .foregroundStyle(todo.done ? .green : .gray)
                            .onTapGesture { todo.done.toggle() }
                        Text(todo.text)
                            .strikethrough(todo.done)
                    }
                }
                .onDelete(perform: store.delete)     // 侧滑删除，白送
            }
            .navigationTitle("待办（\(store.todos.filter { !$0.done }.count)）")
            .safeAreaInset(edge: .bottom) {
                HStack {
                    TextField("回车添加", text: $newText)
                        .textFieldStyle(.roundedBorder)
                        .onSubmit {
                            store.add(newText)
                            newText = ""
                        }
                }
                .padding()
                .background(.bar)
            }
        }
    }
}

不到 80 行，你得到了：增删改查、勾选完成、侧滑删除、重启不丢数据。同等功能用 UIKit 写，代码量至少翻两倍——这就是声明式 UI 的威力。

第四篇 iOS 系统特性：定位、存储、网络、通知与唤起

页面写得好只是「前台功夫」，App 和系统打交道的能力才是「后台功夫」。这一篇讲五个真实 App 绕不开的系统能力。它们的坑有一个共同特征：Demo 里都好好的，一到用户手机上就出事。

4.1 定位：权限分级比 API 本身重要

iOS 定位用 CoreLocation，API 本身不复杂，复杂的是权限体系这些年越收越紧：

flowchart TD
    A["请求定位权限"] --> B{"Info.plist 配了用途说明？<br/>NSLocationWhenInUseUsageDescription"}
    B -->|"没配"| C["💥 不弹窗甚至直接崩溃<br/>新人第一坑"]
    B -->|"配了"| D{"用户怎么选的？"}
    D -->|"使用 App 期间允许"| E["前台定位可用"]
    D -->|"始终允许"| F["后台也能定位<br/>需先拿前台权限再升级"]
    D -->|"拒绝"| G["优雅降级<br/>引导去系统设置"]
    E --> H{"iOS 14+ 用户开了<br/>『精确位置』吗？"}
    H -->|"开了"| I["米级精度"]
    H -->|"关了"| J["⚠️ 只有约 1-3km 精度<br/>代码必须兼容"]

发起定位的 Demo：

import CoreLocation

class LocationService: NSObject, CLLocationManagerDelegate {
    private let manager = CLLocationManager()
    private var continuation: CheckedContinuation<CLLocation?, Never>?

    override init() {
        super.init()
        manager.delegate = self
        manager.desiredAccuracy = kCLLocationAccuracyBest
    }

    func currentLocation() async -> CLLocation? {
        manager.requestWhenInUseAuthorization()   // 触发权限弹窗
        return await withCheckedContinuation { cont in
            self.continuation = cont
            manager.requestLocation()             // 请求一次新定位
        }
    }

    func locationManager(_ m: CLLocationManager, didUpdateLocations locs: [CLLocation]) {
        continuation?.resume(returning: locs.last)
        continuation = nil
    }

    func locationManager(_ m: CLLocationManager, didFailWithError error: Error) {
        continuation?.resume(returning: nil)
        continuation = nil
    }
}

踩坑故事 9：外卖 App 定位把用户送到了两公里外

一个本地生活 App 上线后收到大量投诉：「定位的取货点离我两公里」。排查发现这批用户都在 iOS 14+ 的权限弹窗里关掉了**「精确位置」开关**——这是 Apple 给的模糊定位选项，App 拿到的坐标被人为偏移了。

解法：拿到定位后检查 manager.accuracyAuthorization，如果是 .reducedAccuracy，在 UI 上明确提示「当前为模糊定位，可能影响取货点推荐」，并给一键跳系统设置的入口。这个开关在权限弹窗里毫不起眼，但对 LBS 类 App 是生死线。

另外提醒做国内地图的同学：iOS 原生定位返回的是 WGS-84 坐标，画到高德地图前要转 GCJ-02，接百度地图要转 BD-09——坐标系天坑在 Android 和 iOS 上是同一口，偏移几百米、用户「站在河里」的事故两边都不少见。

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

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

flowchart TD
    Q{"要存什么？"}
    Q -->|"设置项 开关 小数据"| A["UserDefaults<br/>最简单 明文存储"]
    Q -->|"token 密码 敏感信息"| B["Keychain<br/>系统级加密<br/>卸载 App 后还在"]
    Q -->|"结构化数据<br/>离线缓存 消息列表"| C["SwiftData / Core Data<br/>见 5.3 节"]
    Q -->|"图片 日志 大文件"| D["沙盒文件目录<br/>Documents / Caches"]

踩坑故事 10：token 存进 UserDefaults，跟着 iTunes 备份「裸奔」

安全团队做渗透测试时发现：App 的登录 token 存在 UserDefaults 里，用 iTunes 做一个未加密备份，就能在备份文件里直接读到明文 token——拿着它就能以用户身份调通所有接口。

UserDefaults 的 plist 文件明文躺在沙盒里，还会进 iCloud/iTunes 备份。敏感信息唯一的正确归宿是 Keychain：
import KeychainAccess
let keychain = Keychain(service: "com.example.myapp")
try keychain.set(token, key: "accessToken")
let saved = try keychain.get("accessToken")
顺带记住 Keychain 的一个反直觉特性：App 卸载重装后，Keychain 里的数据还在。利用它可以做「卸载重装免登录」，但也别拿它存不该留的东西。

沙盒目录的分工也值得一提：

flowchart LR
    A["Documents/<br/>用户产生的数据<br/>会被 iCloud 备份"] --> S["沙盒"]
    B["Library/Caches/<br/>可重建的缓存<br/>系统空间不足时会清"] --> S
    C["tmp/<br/>临时文件<br/>随时可能被清"] --> S

把几个 GB 的缓存视频塞进 Documents，用户的 iCloud 备份会被撑爆，审核也可能找你麻烦——缓存进 Library/Caches，这是规矩。

4.3 网络：URLSession 的完整封装

2.4 节讲了 async/await 的姿势，这里把网络层补完。iOS 新项目的网络层可以完全不用第三方库，URLSession 已经够用：

enum APIError: Error {
    case httpError(Int)
    case decodingError
}

actor APIClient {
    static let shared = APIClient()
    var token: String?

    private let session: URLSession = {
        let config = URLSessionConfiguration.default
        config.timeoutIntervalForRequest = 15    // 弱网常态，超时必须配
        return URLSession(configuration: config)
    }()

    func get<T: Decodable>(_ path: String) async throws -> T {
        var request = URLRequest(url: URL(string: "https://api.example.com\(path)")!)
        if let token {
            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        let (data, response) = try await session.data(for: request)
        guard let http = response as? HTTPURLResponse else { throw APIError.httpError(-1) }
        guard (200..<300).contains(http.statusCode) else { throw APIError.httpError(http.statusCode) }
        do {
            return try JSONDecoder().decode(T.self, from: data)
        } catch {
            throw APIError.decodingError
        }
    }
}

踩坑故事 11：测试环境一切正常，正式包所有请求都失败

联调时后端给的是 http:// 测试地址，为了图快在 Info.plist 里加了 NSAppTransportSecurity → NSAllowsArbitraryLoads = YES，全局放开了 HTTP。提审时被 Apple 要求说明理由，更糟的是正式环境的某个 CDN 域名忘了配证书，HTTPS 升级漏了它——而全局开关掩盖了问题，直到审核人员用特定网络环境才暴露。

ATS（App Transport Security）是 Apple 强制 HTTPS 的机制，默认拦截明文 HTTP。正确姿势不是全局放开，而是用 NSExceptionDomains 为个别域名开白名单，并推动后端全量 HTTPS。审核时对任意加载开关是要写书面理由的，别给自己找事。

4.4 消息通知：iOS 最省心也最「一生一次」的能力

通知分两种：本地通知（App 自己定时触发，如提醒事项）和远程推送（服务器经 APNs 推下来）。

先说一个 iOS 相对 Android 的巨大优势：推送通道统一走 APNs。Apple 的推送服务是系统级的，App 被杀了也能收到通知——不存在 Android 那种「华为小米 OPPO 各接一套厂商通道」的割裂生态。这是 iOS 开发者少有的幸福时刻。

flowchart LR
    A["你的服务器"] -->|"携带 deviceToken"| B["APNs<br/>Apple 推送服务"]
    B -->|"系统级投递"| C["用户手机<br/>App 被杀也能收到"]
    D["App 启动时<br/>registerForRemoteNotifications"] -->|"拿到 deviceToken 上报服务器"| A

本地通知的 Demo（提醒类 App 的核心）：

import UserNotifications

// 第 1 步：申请权限（时机见踩坑故事 12）
let center = UNUserNotificationCenter.current()
let granted = try await center.requestAuthorization(options: [.alert, .sound, .badge])

// 第 2 步：排一个 5 秒后的通知
let content = UNMutableNotificationContent()
content.title = "该喝水了"
content.body = "起来活动一下"
content.sound = .default

let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 5, repeats: false)
let request = UNNotificationRequest(identifier: "drink", content: content, trigger: trigger)
try await center.add(request)

踩坑故事 12：通知权限弹窗，一生只有一次机会

新人常在 App 启动第一屏就调 requestAuthorization——用户还没搞懂这 App 是干嘛的，看到弹窗本能地点了「不允许」。这一拒就是永久：之后再调用不会弹任何窗口，想改只能引导用户自己去系统设置里翻，转化率惨不忍睹。一个工具类 App 的推送开启率，因为这个改动从 12% 涨到 47%。

正确姿势：先弹一个自己的预引导页，讲清楚「开启通知能及时收到订单状态」，用户点了「好的」再触发系统弹窗。被预引导页拒绝没有任何代价——系统弹窗那张底牌还攥在手里。

另一个高频坑：App 在前台时，推送默认不弹横幅、不响铃，需要实现 UNUserNotificationCenterDelegate 的 willPresent 方法并返回 [.banner, .sound]，否则用户在 App 里操作时收消息毫无感知。

4.5 App 唤起：Universal Links 与 URL Scheme

「唤起」分两个方向：别人拉起你（短信、网页、二维码里的链接），你拉起别人。

flowchart TD
    Q{"从哪拉起你的 App？"}
    Q -->|"网页/短信里的 https 链接"| A["Universal Links<br/>需配置 apple-app-site-association<br/>体验最好 不可抢注"]
    Q -->|"其他 App / 二维码"| B["URL Scheme<br/>myapp://detail/123<br/>简单但可被其他 App 抢注"]

Universal Links 配置要点：在 Xcode 的 Signing & Capabilities 里加 Associated Domains（applinks:ftmao.com），并在你的网站根路径放一个 apple-app-site-association 文件（无后缀的 JSON）。接收端用 SwiftUI 的 onOpenURL：

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    // 解析 https://ftmao.com/app/detail/123
                    if let id = url.pathComponents.last {
                        router.navigate(to: .detail(id: id))
                    }
                }
        }
    }
}

踩坑故事 13：Universal Link 全配置好了，就是不生效

按出现概率排查：
flowchart TD
 A["点了链接只开 Safari 不拉起 App"] --> B{"AASA 文件能访问吗？ https://域名/apple-app-site-association"}
 B -->|"404 或要求登录"| C["文件没放对位置 必须无后缀 纯 JSON"]
 B -->|"能访问"| D{"中间有重定向吗？"}
 D -->|"有"| E["⚠️ AASA 文件不允许重定向 包括 http 跳 https"]
 D -->|"没有"| F{"是在 Safari 地址栏 直接输入的吗？"}
 F -->|"是"| G["地址栏输入不会触发 必须在网页/短信里『点击』"]
 F -->|"否"| H{"之前长按选过 『在 Safari 打开』？"}
 H -->|"是"| I["系统记住了你的选择 长按链接选『在 App 中打开』恢复"]
最后一条最隐蔽：用户在链接上长按选过一次「在 Safari 中打开」，iOS 就记住了这个域名不再拉起 App，之后怎么点都没反应。测试同事就栽在这上面，以为功能坏了，其实只是他自己的手机被系统「记住」了。

4.6 平台适配：iOS 的约束比碎片化更值得关注

iOS 没有 Android 那种几十种 ROM 的碎片化，但 Apple 用另一种方式给你立规矩——权限、隐私、后台管得更严。以下是反复用到的适配清单：

深色模式

颜色全部用语义色（Color.primary、Color(.systemBackground)）或 Asset Catalog 里配置深色变体，一个写死的 Color.white 背景都不要有——写死颜色的页面在深色模式下就是一块刺眼白斑，而且这种 bug 只在用户半夜打开 App 时才暴露。

动态字体（Dynamic Type）

用 .font(.body)、.font(.title) 这类系统文本样式，字号会跟随用户在系统设置里的偏好自动缩放。写死 .font(.system(size: 14)) 的 App，把字体调大的老年用户看到的依然是小字。

安全区

刘海屏、灵动岛、底部 Home 指示条都会侵占显示区域。底部操作栏用 safeAreaInset(edge: .bottom) 而不是写死 padding，3.5 节的 Demo 里就是这么做的。

后台运行：iOS 是「假后台」，别指望它

flowchart TD
    A["App 切到后台"] --> B["几秒内被挂起<br/>代码停止执行"]
    B --> C{"想继续干活？"}
    C -->|"短时间收尾"| D["beginBackgroundTask<br/>申请约 30 秒"]
    C -->|"周期性任务"| E["BGTaskScheduler<br/>系统决定何时执行"]
    C -->|"等服务器消息"| F["静默推送唤醒<br/>APNs content-available"]

踩坑故事 14：下载功能切后台就「暂停」，用户骂声一片

一个资料下载功能在 Demo 里完美，上线后用户反馈「切到微信回个消息，下载就停了」。原因正是上图：iOS 挂起后台 App 只需几秒。解法是改用 URLSession 的后台配置（URLSessionConfiguration.background）——下载由系统进程接管，App 被杀了都在继续，完成后系统再唤醒你的 App 回调。

感悟：iOS 的假后台不是缺陷，是 Apple 对续航和隐私的坚持。适配它的姿势不是对抗（研究各种保活黑科技，审核还会被拒），而是把任务交给系统：下载给后台 URLSession，定时任务给 BGTaskScheduler，消息给 APNs。系统级方案永远比自己保活可靠。

第五篇中级应知应会：从「能跑」到「上线级」

前四篇能让你写出一个能跑的 App，这一篇补的是不常踩坑但绝不能不知道的硬知识——它们是中级和初级的分水岭。

5.1 App 生命周期：状态恢复是必修课

SwiftUI 时代的生命周期入口在 @main 的 App 结构体和 scenePhase：

stateDiagram-v2
    [*] --> active: App 启动，可交互
    active --> inactive: 来电话/下拉通知栏/切多任务
    inactive --> active: 回到前台
    inactive --> background: 完全切入后台
    background --> inactive: 从后台回来
    background --> [*]: 系统挂起后杀死进程
    note right of background
        进程死亡时不会有任何回调
        重要数据不能指望「退出时再保存」
    end note

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                // 切后台时保存草稿、暂停播放器
            }
        }
    }
}

踩坑故事 15：切出去回了个微信，半小时的表单白填了

用户在表单页填到一半，切出去回了条微信，半小时后切回来，App 从启动页重新加载，填的内容全没了。这不是 bug，是进程死亡——App 在后台久了，系统内存不足时直接杀掉整个进程，ViewModel 跟着一起死。

解法分两层：轻量状态（页面位置、草稿）用 @SceneStorage，它会把数据写入进程死亡也能存活的系统存储；重量级数据（表单草稿）在 scenePhase 变 background 时落盘。怎么测？App 切后台后，在 Xcode 里点 Stop 再手动从手机桌面点开——就模拟了进程被杀再恢复。不测这一关，你永远不知道状态恢复写对了没有。

5.2 架构：MVVM + 单向数据流

SwiftUI 和 MVVM 是天生的搭档：

flowchart TD
    subgraph UI层
        A["SwiftUI View<br/>只负责渲染和上报事件"]
    end
    subgraph 状态层
        B["ViewModel<br/>持有 @Published 状态<br/>暴露事件处理函数"]
    end
    subgraph 数据层
        C["Service / Repository<br/>数据的唯一入口<br/>决定走网络还是缓存"]
        D["APIClient<br/>远程数据"]
        E["SwiftData / UserDefaults<br/>本地数据"]
    end
    A -->|"用户事件"| B
    B -->|"状态驱动刷新"| A
    B --> C
    C --> D
    C --> E

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

View 不直接碰网络和数据库——SwiftUI 视图里出现 URLSession，就是架构腐烂的开始。
数据向下流，事件向上流：View 只读状态、只发事件，ViewModel 改状态。
ViewModel 不 import SwiftUI：不碰 UI 才能被单元测试覆盖（见 5.4），也才能让 AI（第六篇）安全地帮你改逻辑。

5.3 SwiftData：结构化数据的现代答案

第三篇的 Demo 用 UserDefaults 存 Todo，只够玩具级。真实 App 的结构化数据用 SwiftData（iOS 17+，Core Data 的现代封装）：

import SwiftData

@Model
final class Expense {
    var title: String
    var amount: Double
    var createdAt: Date

    init(title: String, amount: Double) {
        self.title = title
        self.amount = amount
        self.createdAt = .now
    }
}

// 视图里直接用 @Query 查询：数据变了 UI 自动更新
struct ExpenseListView: View {
    @Query(sort: \Expense.createdAt, order: .reverse) private var expenses: [Expense]
    @Environment(\.modelContext) private var context

    var body: some View {
        List(expenses) { expense in
            Text("\(expense.title)：\(expense.amount, format: .currency(code: "CNY"))")
        }
        .onAppear {
            context.insert(Expense(title: "咖啡", amount: 32))  // 自动保存
        }
    }
}

@Query 是 SwiftData 最优雅的用法——数据库一变，查询结果自动更新，UI 自动刷新，「增删改 → 界面刷新」这条链路不用写一行通知代码。需要支持 iOS 15/16 的老项目退回 Core Data，纯本地队列需求也可以考虑轻量的 GRDB（直接写 SQL）。

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

新版给 Expense 加了一个 category 字段，自己全新安装测试没问题，上线后老用户打开就崩。原因：老用户手机里的数据库还是旧表结构，新代码按新结构读，版本对不上。

SwiftData 对只新增带默认值的可选字段这类轻量变更能自动迁移，但改字段类型、加必填字段就必须手写 Schema 的迁移计划（VersionedSchema + SchemaMigrationPlan）。教训和 Android 的 Room 一模一样：数据库字段变更是对存量用户的承诺，每次改 @Model，先想「老用户的库里有什么」。开发期可以偷懒删库重装，上线前必须真机装旧版、覆盖安装新版测一遍升级路径。

5.4 测试：少但要有

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

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

单元测试 Demo（Swift Testing，Xcode 16 起的新框架）：

import Testing
@testable import MyApp

struct LoginViewModelTests {
    @Test func 邮箱格式错误时不发起登录() async {
        let vm = LoginViewModel()
        vm.email = "not-an-email"
        await vm.login()
        #expect(vm.emailError == "邮箱格式不对")
        #expect(vm.isLoading == false)
    }
}

务实建议：别追求覆盖率数字。给「钱相关的计算、状态机的转移、数据解析」这三类写单元测试，给「登录、主列表、下单」这三条主链路写 XCUITest，投入产出比最高。UI 层还可以用 SnapshotTesting（截图对比测试）防止 UI 被无意改坏。

5.5 调试三板斧：断点、Memory Graph 与 Instruments

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

断点 + LLDB：po variableName 打印对象，条件断点（右键断点设条件）只在特定数据时停下。经验：别用 print 大法调异步代码，断点比日志可靠得多。
Memory Graph：调试栏的小图标一键生成内存快照，泄漏的对象、循环引用的环都画成图——踩坑故事 4 就是靠它破的案。
Instruments：性能问题终极武器。Time Profiler 找卡顿（主线程耗时调用栈一目了然）、Leaks 查泄漏、Network 看请求瀑布流。发布前拿 Time Profiler 把主流程过一遍，是专业团队的基本功。

日志方面，正经项目用 os.Logger 替代 print——分级、可过滤、能在真机的 Console.app 里回看，排查线上问题时你会感谢自己。

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

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

国际化（i18n）

所有文案进 String Catalog（Localizable.xcstrings，Xcode 15+），代码里直接写英文 key，一个硬编码的中文字符串都不要留——今天不国际化，明天产品说「做个英文版」你就要全文搜索替换。
复数和变量用 catalog 的复数规则，别用字符串拼接数字。

无障碍（a11y）

图标按钮加 .accessibilityLabel("返回")——视障用户的 VoiceOver 靠它朗读界面。
可点击区域不小于 44×44 pt，系统组件默认满足，自定义绘制的按钮最容易违规。
配合 4.6 节的 Dynamic Type：字号放大五倍后布局不炸，这条顺带也服务了老年用户。
最后打开 VoiceOver 把自己的 App 主流程走一遍，十分钟，胜过读十篇规范。

5.7 发布上架：TestFlight、审核与隐私合规

flowchart LR
    A["Archive 打包"] --> B["上传到 App Store Connect"]
    B --> C["TestFlight 内测<br/>邀请码分发给测试人员"]
    C --> D["填写元数据<br/>截图 关键词 隐私清单"]
    D --> E["提审"]
    E --> F{"审核"}
    F -->|"通过"| G["发布"]
    F -->|"被拒"| H["看 Resolution Center<br/>改完重提"]

几个中级必懂的点：

TestFlight 是正式发布前的缓冲区：内部测试 100 人免审核，外部测试 1 万人需过一个简化审核。任何「我测过了」的说法，都应该建立在 TestFlight 包上——它和生产包走的是同一条签名和分发链路。
截图和预览视频分尺寸（6.7 寸、6.5 寸、iPad），用模拟器 Cmd+S 截，或 fastlane snapshot 批量生成。
审核时长通常 24-48 小时，紧急情况可以申请加急审核（Accelerated Review），但一年没几次额度，别浪费在「产品经理想早点上」这种事上。

踩坑故事 8（重提）：隐私清单引发的连环拒审

Apple 要求声明 App 用到的「必要理由 API」（文件时间戳、UserDefaults 等）以及所有收集的数据类型。我们第一次提审被打回：用的一个旧版三方统计库偷偷采集了设备 ID，隐私声明里却没写。更新 SDK、补隐私清单（PrivacyInfo.xcprivacy）、重提，前后耗了一周。

教训：隐私合规要在开发期就设计，不是提审前补作业。能不接的统计 SDK 就别接，接了就得为它的一切行为负责——结合踩坑故事 7，第三方库的两笔账（编译成本和合规成本）要一起算。

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

这部分是我最近两年工作方式最大的变化，也是这篇文章最想说的。

6.1 现实：AI 能写多少 iOS 代码

我的实测结论：AI 写 SwiftUI 页面的完成度约 70-90%，写 ViewModel 和业务逻辑约 60-80%，处理证书、签名、上架合规约等于 0。

flowchart TB
    A["需求 / 设计稿"] --> B["人：拆成清晰的任务<br/>写 Prompt"]
    B --> C["AI：生成 View + ViewModel 初稿"]
    C --> D["人：Review + 跑起来验证"]
    D --> E{"有问题？"}
    E -->|"截图 + 报错喂回去"| C
    E -->|"没问题"| F["人：处理 AI 干不了的<br/>签名 / 性能 / 审核"]
    F --> G["提审上架"]

关键变化是：你的角色从「写代码的人」变成「拆任务、验收代码、兜底的人」。

6.2 高效 Prompt 的三个套路

套路一：给足上下文，别让 AI 猜。 差的 Prompt 是「帮我写个登录页」；好的 Prompt 是：

用 SwiftUI 写一个登录页。要求：iOS 17 的 NavigationStack；ViewModel 用 @Observable 宏；账号密码字段校验（账号为邮箱格式，密码至少 8 位）；登录按钮在请求中显示 ProgressView 并禁用；错误用 alert 展示。Model 层已有 struct AuthResponse: Codable { token: String }，网络调用留一个 func login(email:password:) async throws -> AuthResponse 的协议方法，不要写死实现。

上下文越具体（部署版本、已有类型、项目约定），AI 产出能直接用得越多。

套路二：截图驱动开发。 SwiftUI 的一大红利是「所见即所得」特别适合多模态 AI：把设计稿截图发给 AI 生成初版界面，跑起来后再把模拟器截图发回去说「间距不对，标题字号小了」，来回两轮，像素级还原度能到九成。这在 UIKit 时代是不可想象的。

套路三：让 AI 先写测试和协议，再写实现。 先让它定义 protocol UserService，再生成实现和单元测试。有了测试护栏，AI 后续改代码翻车时你能立刻发现——没有测试的 AI 代码，就像没有保险的跑车。

6.3 Demo：一次真实的 AI 协同开发记录

3.5 节那个 TodoList，我用 AI 辅助重写过一版，真实过程是这样：

第一轮（2 分钟）：把半成品代码贴给 AI，说「加上本地持久化，用 UserDefaults + Codable」。它给出了 didSet 里 save 的方案——直接可用。
第二轮（踩坑）：AI 自作主张把 Todo.id 改成了 Int 自增，导致重启后 id 冲突、删除错乱。**这是 AI 代码的典型问题：它能跑通 happy path，但对「持久化后 id 唯一性」这种隐含约束没概念。**我让它改回 UUID()，并补了一条测试。
第三轮：让它加「侧滑删除」和「底部输入栏」，一次通过。

总耗时约 40 分钟，纯手写我估计要 3 小时。省下来的 2 小时 20 分钟去哪了？ 一部分花在 Review AI 的代码上——这恰恰是核心价值所在。

6.4 什么 AI 干不了，什么你必须会

flowchart LR
    subgraph AI擅长["AI 擅长，放手让它写"]
        A1["样板页面 / CRUD 界面"]
        A2["Codable 模型 单元测试"]
        A3["格式化 转换等工具函数"]
    end
    subgraph 人必须懂["AI 容易翻车，人必须把关"]
        B1["内存与生命周期<br/>weak self 状态所有权"]
        B2["系统权限与后台模型<br/>定位 通知 假后台"]
        B3["签名 上架 隐私合规"]
        B4["性能调优<br/>Instruments 读调用栈"]
    end

看出来了吗？AI 干不了的，恰好是这篇文章前面所有「踩坑故事」涉及的东西：循环引用、状态所有权、权限时机、进程死亡、签名、合规。AI 生成的代码照样犯「@ObservedObject 当主人用」「闭包没写 weak self」这些错——能一眼看出它错的人，才能真正驾驭它。

6.5 一些真心话

关于学习路径：「AI 都能写了，还要不要学语法？」——正因为 AI 能写，你才更要懂原理。看不懂的代码你不敢上线，看不懂的 bug 你修不了。AI 时代的学习重心从「记住 API」转向「理解原理 + 会拆任务 + 会验收」。

关于 SwiftUI vs UIKit 的争论：AI 的语料里 SwiftUI 越来越占主流，声明式代码也更适合 AI 生成和修改。这条技术路线的选择，AI 因素已经足以成为加分项。

关于独立开发者：AI 把「一个人做出一个上架 App」的门槛降到了历史最低。设计稿可以 AI 出，代码可以 AI 写大半，连应用图标的文案都能 AI 润色。真正的瓶颈回到了最古老的地方：你想做一个什么东西，它解决谁的问题。技术不再是门槛，判断力才是。

结语

回头看这条路：环境搭建教你敬畏平台规则，Swift 语法教你与编译器合作，UI 选型教你权衡范式，系统特性教你「把任务交给系统」，中级内功教你把 App 做到上线级，而 AI 协同教你把重心放回「想清楚要什么」。

入门的标志是你的 App 能跑在手机上；精通的标志，是审核被拒、线上崩溃、定位漂移、AI 生成了一坨看似能跑的代码时，你都知道问题出在哪、下一步做什么。

祝你的第一个 App 早日上架。

Spark 从入门到精通：架构原理、RDD/DataFrame、调优踩坑与电商实战全指南

Wed, 26 Oct 2022 09:30:00 +0800

Spark 从入门到精通：架构原理、RDD/DataFrame、调优踩坑与电商实战全指南

目标读者：写过一两年后端（Java/Scala/Python 皆可）、第一次要碰大数据的同学；或者用 PySpark 写过一些脚本、但一遇到性能问题就抓瞎的同学。写这篇文章时（2022 年 10 月），Spark 3.3 刚发布，DataFrame 早已是绝对主流，Flink 在实时方向上攻城略地。但离线批处理、数仓 ETL、特征工程这些重活，Spark 依然是绕不开的那座山。

全文六篇，顺序就是学习的顺序：

flowchart LR
    A["一 为什么是 Spark<br/>从单机到分布式"] --> B["二 架构与原理<br/>Driver Executor DAG"]
    B --> C["三 RDD 与 DataFrame<br/>两代 API 的分水岭"]
    C --> D["四 电商实战<br/>宽表 漏斗 特征"]
    D --> E["五 调优与踩坑<br/>倾斜 OOM 小文件"]
    E --> F["六 AI 时代<br/>少写代码 多写提示词"]
    style F fill:#e8f4e8

为什么是这个顺序？第一篇解决「为什么要用它」；第二篇解决「它在集群里怎么跑」——不理解这个，写出来的代码就是玄学；第三篇解决「代码怎么写」；第四篇用真实业务把知识串起来；第五篇是血泪史，生产环境和本地 Demo 是两个物种；第六篇聊怎么让 AI 替你干活。

第一篇为什么是 Spark：一台机器装不下的时代

1.1 一个电商场景把问题引出来

假设你在一家中型电商公司做后端。双十一刚过，老板要看一份报表：

昨天所有下单用户，按城市分组，统计成交额、下单次数、客单价，再看这批用户里有多少是 30 天内的新客。

订单表 8 亿行，用户表 4000 万行，行为日志（埋点）一天 20 亿条。MySQL 里跑这个 SQL？GROUP BY 一个 8 亿行的表，跑一晚上 MySQL 先把你杀了——不，是 DBA 先把你杀了。

你想到的办法是「把数据导出来，写个 Python 脚本跑」。8 亿行订单数据，CSV 导出大概 400GB。你的开发机内存 32GB。装不下，这就是大数据的全部问题。

解决思路只有两个方向：

flowchart TB
    subgraph 思路一["思路一：垂直扩展（Stack Overflow 式的天真）"]
        A1["换个 1TB 内存的机器"] --> A2["贵得离谱<br/>且有物理上限"]
    end
    subgraph 思路二["思路二：水平扩展（唯一出路）"]
        B1["把 400GB 切成 1000 份"] --> B2["1000 台机器<br/>每台处理 400MB"]
        B2 --> B3["各自算局部结果<br/>最后合并"]
    end

思路二就是分布式计算。但自己写 1000 台机器的协调代码？分发任务、处理机器挂掉、合并结果、处理网络超时……你会写出第二个 Hadoop。

Spark 就是替你把这些脏活全包了：你只写「对这批数据做什么变换」，它负责切分、调度、容错、合并。

1.2 Spark 在生态里的位置

新人最容易被一堆名词搞晕：Hadoop、HDFS、YARN、Hive、Spark、Flink。一张图说清楚：

flowchart TB
    subgraph 存储层
        HDFS["HDFS<br/>分布式文件系统<br/>（把文件切块存到多台机器）"]
        S3["S3 / OSS<br/>对象存储"]
    end
    subgraph 资源层
        YARN["YARN / K8s<br/>集群资源调度<br/>（给任务分配 CPU 和内存）"]
    end
    subgraph 计算层
        MR["MapReduce<br/>老一辈 磁盘IO 慢"]
        SPARK["Spark<br/>内存计算 快<br/>本篇主角"]
        FLINK["Flink<br/>流处理专精"]
    end
    subgraph 应用层
        HIVE["Hive/Spark SQL<br/>SQL 写报表"]
        DS["数据科学<br/>MLlib 特征工程"]
    end
    HDFS --> YARN
    S3 --> YARN
    YARN --> MR
    YARN --> SPARK
    YARN --> FLINK
    SPARK --> HIVE
    SPARK --> DS
    style SPARK fill:#ffd699

几个关键认知：

Spark 不是存储系统，它没有自己的存储，数据放在 HDFS、Hive 表、S3 甚至 MySQL 里，它读进来算完再写回去。
Spark 也不是资源调度器，它跑在 YARN 或 Kubernetes 上，向它们「申请」机器。
Spark 相对 MapReduce 的快，核心就一句话：中间结果放内存，不落地磁盘。MapReduce 每步都要写磁盘，迭代式计算（比如机器学习跑 50 轮迭代）就慢到不可用。

踩坑预告：很多人学 Spark 的第一步是去装 Hadoop 全家桶，装了一周还没跑起来 Hello World。其实本地学习完全不需要——Spark 有 local 模式， pip 装个 pyspark 就能跑。下一篇的 Demo 全是单机可运行的。

第二篇架构与原理：代码提交之后到底发生了什么

这是最重要的一篇。Spark 调优 80% 靠对这套架构的直觉，剩下 20% 才是参数。

2.1 一次 Spark 任务的全貌

flowchart TB
    CODE["你的代码<br/>spark.read... .groupBy... .write..."] --> DRV
    subgraph Cluster["集群（YARN / K8s）"]
        subgraph DRV["Driver（司机/总指挥）"]
            DAG["DAG Scheduler<br/>把代码翻译成执行计划<br/>切成若干 Stage"]
            TS["Task Scheduler<br/>把 Stage 拆成 Task<br/>派发给 Executor"]
        end
        subgraph EXE["Executor × N（干活的工人）"]
            T1["Task 1<br/>处理 Partition 1"]
            T2["Task 2<br/>处理 Partition 2"]
            T3["Task 3<br/>处理 Partition 3"]
            CACHE["内存/磁盘<br/>缓存中间数据"]
        end
    end
    TS --> T1
    TS --> T2
    TS --> T3
    T1 -.shuffle 阶段互相交换数据.-> T2

关键角色就三个：

Driver：你的 main 函数（或 PySpark 脚本）运行的地方。它不干活，它发号施令——分析你的代码、生成执行计划、把任务派发出去、回收结果。Driver 挂了，整个任务就完了。
Executor：集群里真正干活的 JVM 进程，每个 Executor 有若干核，每个核同时跑一个 Task。数据是**分区（Partition）**存储的，一个 Task 处理一个 Partition。
Shuffle：当操作需要跨机器汇总数据（groupBy、join、distinct），数据就要在网络上重新分发——这叫 Shuffle。Shuffle 是 Spark 任务慢的第一大原因，后文反复出现。

2.2 懒执行（Lazy Evaluation）：为什么你的代码"没报错"却在运行时炸了

新手最常踩的认知坑：Spark 代码写下去并不会立刻执行。

df = spark.read.csv("orders.csv")          # 没执行！只是记录"要读个文件"
df2 = df.filter(df.amount > 100)           # 没执行！只是记录"要过滤"
df3 = df2.groupBy("city").sum("amount")    # 没执行！只是记录"要分组聚合"
df3.write.save("output")                   # 现在才真正开始跑！

读数据、过滤、分组这些叫 Transformation（变换），只是往计划里加节点；write、count、collect、show 这些叫 Action（行动），碰到 Action，Driver 才把整条链路翻译成 DAG（有向无环图），切成 Stage，真正派发执行。

这个设计的好处是优化：Spark 的 Catalyst 优化器能看到整条链路，比如发现你过滤条件写晚了，它可以自动把 filter 下推到读数据时就做（Predicate Pushdown），少读一半数据。

但坑也随之而来：

踩坑故事 1：错误行号的谎言 刚转 Spark 时我排查一个任务失败，日志说第 87 行 df.write.save() 报错 “文件不存在”。我盯着 87 行看了半小时——write 语法没问题啊！后来才明白：真正的错误发生在第 12 行的 spark.read（路径写错了），但因为是懒执行，直到 87 行触发 Action 才爆出来。看 Spark 报错，永远要从日志里的执行计划往上找 Transformation 的源头，而不是看报错行号。

2.3 Stage 是怎么切出来的：宽依赖与窄依赖

理解 Shuffle 就理解了 Stage 的切分：

flowchart LR
    subgraph Stage1["Stage 1（窄依赖，流水线执行）"]
        P1["Partition 1<br/>读文件"] --> F1["filter<br/>过滤"]
        P2["Partition 2<br/>读文件"] --> F2["filter<br/>过滤"]
    end
    subgraph SHUFFLE["⚡ Shuffle（跨网络搬数据）"]
        direction TB
        S["按 city 重新分区<br/>同 city 的数据<br/>汇聚到同一 Partition"]
    end
    subgraph Stage2["Stage 2"]
        G1["Partition A<br/>北京的订单<br/>sum(amount)"]
        G2["Partition B<br/>上海的订单<br/>sum(amount)"]
    end
    F1 --> SHUFFLE
    F2 --> SHUFFLE
    SHUFFLE --> G1
    SHUFFLE --> G2
    style SHUFFLE fill:#ffcccc

窄依赖（filter、map）：子 Partition 只依赖父的一个 Partition，可以像流水线一样在同一台机器一口气算完，不分 Stage。
宽依赖（groupBy、join、distinct）：子 Partition 需要父的所有 Partition 的数据，必须 Shuffle，Stage 在这里断开。

一个 Stage 内的失败重试只重跑这个 Stage。所以 Spark 的容错单位是 Stage——这也是为什么 Spark 会把 Shuffle 的中间结果落盘（对，嘴上说自己内存计算，Shuffle 还是要写磁盘的），挂了能从这里恢复，而不是从头再来。

第三篇 RDD 与 DataFrame：两代 API 的分水岭

3.1 RDD：能看清每个零件，但要自己造发动机

RDD（弹性分布式数据集）是 Spark 1.x 的核心抽象。用它写上面的需求：

// RDD 风格：你告诉 Spark 每一步"怎么做"
orders
  .filter(_.split(",")(5).toDouble > 100)     // 自己解析 CSV，自己转类型
  .map(line => (line.split(",")(3),           // 自己取城市字段做 key
                line.split(",")(5).toDouble)) // 自己取金额做 value
  .reduceByKey(_ + _)                          // 按 key 聚合
  .saveAsTextFile("output")

RDD 的问题是：Spark 看不懂你在干什么。filter(_.split(",")(5).toDouble > 100) 对优化器来说就是一个黑盒 lambda，它不知道你在过滤哪列，没法做谓词下推，没法选更好的 join 策略。而且 JVM 里每一行都是一个 Java 对象，序列化开销大、GC 压力巨大。

3.2 DataFrame：你只说"要什么"，优化器替你想"怎么做"

DataFrame（Spark 1.3 引入，2.0 后与 Dataset 合并）给数据加了Schema（表结构），从此 Spark 能看懂你的意图：

# DataFrame 风格：声明式
(spark.read
  .schema("order_id STRING, city STRING, amount DOUBLE")
  .csv("orders.csv")
  .filter("amount > 100")
  .groupBy("city")
  .sum("amount")
  .write.parquet("output"))

两者差距有多大？同样的逻辑，DataFrame 通常比 RDD 快 2~10 倍，原因：

flowchart TB
    subgraph RDD路径["RDD：信任程序员"]
        R1["你的 lambda"] --> R2["逐行 Java 对象<br/>序列化/GC 开销大<br/>优化器爱莫能助"]
    end
    subgraph DF路径["DataFrame：信任优化器"]
        D1["声明式表达式"] --> D2["Catalyst 优化器<br/>逻辑计划优化<br/>谓词下推/列裁剪"]
        D2 --> D3["Tungsten 执行引擎<br/>二进制内存布局<br/>代码生成 绕开 GC"]
    end
    style DF路径 fill:#e8f4e8

一句话结论（2022 年视角）：新业务永远用 DataFrame/Spark SQL 写，RDD 只在两种情况下出现——操作的是非结构化数据（比如解析一堆不规则日志），或者需要逐分区精细控制（mapPartitions 里建数据库连接池这种）。面试让你手写 RDD wordcount 是考察理解，不是让你生产上这么写。

3.3 本地就能跑的完整 Demo

别急着上集群。装个 Python 环境就能跑：

pip install pyspark==3.3.0

造一份模拟电商订单数据，跑通「读 → 变换 → 聚合 → 写」全流程：

# demo01_basic.py
from pyspark.sql import SparkSession
from pyspark.sql import functions as F

spark = (SparkSession.builder
         .appName("demo01")
         .master("local[*]")      # 本地模式，用满 CPU 核
         .getOrCreate())

# 造数据：100 万行模拟订单
orders = (spark.range(0, 1_000_000)
          .select(
              F.concat(F.lit("ORD"), F.col("id")).alias("order_id"),
              (F.col("id") % 50000).alias("user_id"),
              F.element_at(
                  F.array([F.lit(c) for c in
                           ["北京", "上海", "广州", "深圳", "杭州"]]),
                  (F.col("id") % 5 + 1).cast("int")).alias("city"),
              (F.rand() * 2000).alias("amount"),
              F.date_add(F.lit("2022-10-25"),
                         -(F.col("id") % 30).cast("int")).alias("order_date")))

result = (orders
          .filter(F.col("amount") > 100)
          .groupBy("city")
          .agg(F.count("*").alias("order_cnt"),
               F.round(F.sum("amount"), 2).alias("gmv"),
               F.round(F.avg("amount"), 2).alias("avg_price"))
          .orderBy(F.desc("gmv")))

result.show()          # Action：真正触发执行
result.write.mode("overwrite").parquet("output/city_gmv")
spark.stop()

运行：

python demo01_basic.py

输出：

+----+---------+-----------+---------+
|city|order_cnt|        gmv|avg_price|
+----+---------+-----------+---------+
|  深圳|   190231|...        |  1050.12|
|  北京|   190087|...        |  1049.87|
...
+----+---------+-----------+---------+

这个 Demo 麻雀虽小，五脏俱全：spark.range 造数、element_at 数组取值、rand 随机数、聚合多指标、写 Parquet。本地玩熟了，语法迁移到集群上一行都不用改——这就是 Spark 的优雅之处。

踩坑故事 2：Windows 上的 winutils.exe 我在 Windows 笔记本上第一次跑 PySpark，直接 winutils.exe 缺失报错 + 一堆权限异常。解决办法是下载对应 Hadoop 版本的 winutils.exe 放到 %HADOOP_HOME%\bin 并设置环境变量。后来学乖了：学习期直接 WSL2 或者 Docker 起个 Linux 环境，少生一肚子气。

第四篇电商实战：把知识串成业务

这一篇用三个电商真实场景，把前面的知识点全部用起来。这三个场景也是面试里最高频的"你做过什么项目"素材。

4.1 场景一：订单宽表（每日 ETL）

业务：订单数据分散在三张表——订单主表（order_id、user_id、amount、pay_time）、订单明细表（order_id、sku_id、quantity）、商品维表（sku_id、category、brand）。数据仓库要求每天凌晨产出一张"订单明细宽表"，下游 BI 直接查它。

# demo02_dwd_wide_table.py
orders = spark.table("ods.orders").filter(F.col("dt") == "2022-10-25")
items  = spark.table("ods.order_items").filter(F.col("dt") == "2022-10-25")
skus   = spark.table("dim.sku").filter(F.col("dt") == "2022-10-25")

wide = (items
        .join(orders, "order_id")
        .join(F.broadcast(skus), "sku_id")   # ★ 维表小，广播它！
        .select("order_id", "user_id", "sku_id", "category", "brand",
                "quantity", "amount", "pay_time")
        .withColumn("dt", F.lit("2022-10-25")))

(wide.write
 .mode("overwrite")
 .partitionBy("dt")
 .parquet("warehouse/dwd/order_detail_wide"))

知识点：Broadcast Join。普通 join 两张表都要 Shuffle；但如果一张表很小（商品维表几十万行，几十 MB），Spark 可以把它整个复制到每个 Executor 的内存里，大表原地不动就能完成 join——Shuffle 直接消失，速度提升一个数量级。

判断标准：小表 < spark.sql.autoBroadcastJoinThreshold（默认 10MB，生产常调到 100MB~500MB）。写 F.broadcast(skus) 是显式强制，防止优化器估算失误。

flowchart LR
    subgraph 普通Join["普通 Sort-Merge Join（两张表都 Shuffle）"]
        A1["大表 Partition"] -.网络搬家.-> J1["Join 节点"]
        A2["维表 Partition"] -.网络搬家.-> J1
    end
    subgraph 广播Join["Broadcast Join（只有小表复制）"]
        B1["大表 Partition 1<br/>原地不动"] --> C1["本地 Join<br/>查内存里的小表"]
        B2["大表 Partition 2<br/>原地不动"] --> C2["本地 Join<br/>查内存里的小表"]
        SM["小表整表复制<br/>→ 每个 Executor"] --> C1
        SM --> C2
    end
    style 广播Join fill:#e8f4e8

4.2 场景二：用户行为漏斗（转化率分析）

业务：运营想知道双十一预热期的转化漏斗：曝光 → 点击 → 加购 → 下单 → 支付，每一步流失多少人。

# demo03_funnel.py
events = spark.table("ods.user_events").filter(F.col("dt") == "2022-10-25")
# events 字段：user_id, event_type(view/click/cart/order/pay), ts

# 每个用户在每一步的最早时间
first_ts = (events
            .groupBy("user_id")
            .agg(F.min(F.when(F.col("event_type") == "view",  F.col("ts"))).alias("t_view"),
                 F.min(F.when(F.col("event_type") == "click", F.col("ts"))).alias("t_click"),
                 F.min(F.when(F.col("event_type") == "cart",  F.col("ts"))).alias("t_cart"),
                 F.min(F.when(F.col("event_type") == "order", F.col("ts"))).alias("t_order"),
                 F.min(F.when(F.col("event_type") == "pay",   F.col("ts"))).alias("t_pay")))

# 严格漏斗：必须按时间顺序走到该步才算转化
funnel = first_ts.agg(
    F.count("t_view").alias("曝光"),
    F.count(F.when(F.col("t_click") > F.col("t_view"), 1)).alias("点击"),
    F.count(F.when(F.col("t_cart")  > F.col("t_click"), 1)).alias("加购"),
    F.count(F.when(F.col("t_order") > F.col("t_cart"),  1)).alias("下单"),
    F.count(F.when(F.col("t_pay")   > F.col("t_order"), 1)).alias("支付"))

funnel.show()

知识点：groupBy + 条件聚合（F.when inside agg）是漏斗分析的标准套路——一行 SQL 出五步漏斗，不用写五次 count 再 join。这也是经典面试题。

踩坑故事 3：漏斗口径的战争 我第一版漏斗上线后，运营说数据和他们对不上。查了半天，发现分歧在口径：我写的是"严格顺序漏斗"（必须 view 之后才 click 才算），运营期望的是"存在性漏斗"（只要当天两个行为都发生过就算）。大数据开发一半的返工不是技术问题，是口径没对齐。现在的习惯：开工前把每一步的定义写成一行白话发群里，确认了再写代码。

4.3 场景三：推荐特征工程（用户画像）

业务：算法团队要用户特征——每个用户近 30 天的购买次数、客单价、最偏爱类目、最近一次购买距今天数（RFM 模型的雏形）。

# demo04_user_features.py
from pyspark.sql.window import Window

orders_30d = spark.table("dwd.order_detail_wide").filter(
    F.col("dt").between("2022-09-26", "2022-10-25"))

# 基础聚合特征
agg_feat = (orders_30d
            .groupBy("user_id")
            .agg(F.countDistinct("order_id").alias("order_cnt_30d"),
                 F.round(F.avg("amount"), 2).alias("avg_amount_30d"),
                 F.max("pay_time").alias("last_pay_time")))

# 最偏爱类目：窗口函数按类目的购买金额排序取第一
w = Window.partitionBy("user_id").orderBy(F.desc("cat_amount"))
top_cat = (orders_30d
           .groupBy("user_id", "category")
           .agg(F.sum("amount").alias("cat_amount"))
           .withColumn("rn", F.row_number().over(w))
           .filter(F.col("rn") == 1)
           .select("user_id", F.col("category").alias("top_category")))

features = (agg_feat
            .join(top_cat, "user_id")
            .withColumn("days_since_last_pay",
                        F.datediff(F.lit("2022-10-26"), F.col("last_pay_time"))))

features.write.mode("overwrite").parquet("features/user_rfm/dt=2022-10-25")

知识点：窗口函数（Window.partitionBy(...).orderBy(...) + row_number）是"每组取 TopN"的标准解法，Hive SQL 里也是同一句，大数据面试必考。

三个场景串起来，就是一条标准的离线数仓链路：

flowchart LR
    subgraph 数据源
        DB["业务 MySQL<br/>订单/明细/商品"]
        LOG["埋点日志<br/>曝光/点击/加购"]
    end
    DB -->|Sqoop/DataX 同步| ODS
    LOG -->|Flume/直接落盘| ODS
    subgraph 数仓["数仓分层（Hive on Spark）"]
        ODS["ODS 贴源层<br/>原样搬运"] --> DWD["DWD 明细层<br/>清洗 关联 宽表<br/>★ 场景一"]
        DWD --> DWS["DWS 汇总层<br/>按主题聚合<br/>★ 场景二漏斗"]
        DWS --> ADS["ADS 应用层<br/>直接服务业务<br/>★ 场景三特征"]
    end
    ADS --> BI["BI 报表"]
    ADS --> ALG["推荐算法"]

第五篇调优与踩坑：生产环境才是真的战场

本地 Demo 岁月静好，上了生产环境才知道什么叫残酷。下面三个坑，每一个我都在凌晨两点处理过。

5.1 天坑一：数据倾斜（一个 Task 跑三小时，其他三分钟）

现象：任务 99% 的 Stage 秒过，最后一个 Stage 的 200 个 Task 里，199 个 5 分钟跑完，1 个跑了 3 小时还在爬。Spark UI 上看，那个 Task 的 Shuffle Read 是别人的几百倍。

原因：某个 key 的数据量碾压其他 key。电商里最典型的就是：

大促时某个爆款商品（iPhone 发售当天）的订单明细占全站 30%；
维表 join 时空值/默认值 key——脏数据的 user_id = null 或 '-1' 有上千万条，全挤到一个 Partition。

排查：Spark UI → Stages → 看 Task 的 Summary Metrics，Max 时间远大于 Median（中位数），就是倾斜。

解法三板斧：

# 招式1：过滤异常 key（脏数据导致的倾斜，90% 的情况）
df = df.filter(F.col("user_id").isNotNull() & (F.col("user_id") != "-1"))

# 招式2：热点 key 加盐打散（真热点，比如爆款商品）
# 给大表的热点 key 加随机后缀 0~9，小表对应 key 复制 10 份
salted = big.withColumn(
    "join_key",
    F.when(F.col("sku_id") == "爆款SKU",
           F.concat(F.col("sku_id"), F.lit("_"), (F.rand()*10).cast("int")))
     .otherwise(F.col("sku_id")))
small_exploded = small.withColumn(
    "join_key",
    F.when(F.col("sku_id") == "爆款SKU",
           F.concat(F.col("sku_id"), F.lit("_"),
                    F.explode(F.array([F.lit(i) for i in range(10)]))))
     .otherwise(F.col("sku_id")))

# 招式3：开启 AQE 自动处理（Spark 3.x 的救星）
spark.conf.set("spark.sql.adaptive.enabled", "true")
spark.conf.set("spark.sql.adaptive.skewJoin.enabled", "true")

踩坑故事 4：AQE 救了我一个通宵 2022 年上半年迁移 Spark 3.x 后开了 AQE（Adaptive Query Execution），它能在运行时发现倾斜的 Partition 并自动拆分。以前要手工调参数 spark.sql.shuffle.partitions 反复试的任务，AQE 直接自己搞定了。所以第一建议永远是：先升级到 Spark 3.x 并开启 AQE，再用脑子去调。

flowchart TB
    subgraph 倾斜前["倾斜：一个 Partition 吞掉 40% 数据"]
        K1["Partition 1: 50MB"] 
        K2["Partition 2: 8GB 😱"] 
        K3["Partition 3: 50MB"]
    end
    subgraph 倾斜后["AQE 拆分后：化整为零"]
        L1["Partition 1: 50MB"]
        L2a["Partition 2a: 200MB"]
        L2b["Partition 2b: 200MB"]
        L2c["Partition 2c: 200MB<br/>...共拆 40 份"]
        L3["Partition 3: 50MB"]
    end
    倾斜前 -->|"AQE 运行时检测拆分"| 倾斜后
    style K2 fill:#ffcccc

5.2 天坑二：OOM（内存不够，但到底谁不够）

Spark 的 OOM 分两种，报错长得像，病因完全不同：

报错关键字	病因	解法
`ExecutorLostFailure` / 容器被 kill / `java.lang.OutOfMemoryError`	Executor 内存不够：数据太多、缓存太大	加 `executor-memory`、增加分区数摊薄数据、减少 `cache` 滥用
Driver 端 OOM	Driver 内存不够：几乎永远是 `collect()` / `toPandas()` 把全量数据拉回 Driver	不要用 collect 收大数据！用 `take(100)` 抽样看，用 `write` 落盘

踩坑故事 5：一个 collect 拖垮了整个集群调度 同事为了"快速验证"，在生产任务里写了 df.collect() 然后 len() 一下——那张表 2 亿行。Driver 内存从 4G 一路撑爆，任务挂掉不说，还因为是调度系统的重要任务，报警电话打到了总监那里。从此组里 Code Review 第一条红线：搜索代码里有没有 collect()、toPandas()，有就必须说明数据量上限。

5.3 天坑三：小文件灾难（HDFS 的慢性病）

现象：任务很快跑完，但写出的结果目录里是 20000 个 100KB 的小文件。然后：Hive 查这张表慢得离谱，NameNode 内存报警，下游任务读它要启动几万个 Task。

原因：200 个分区 × 每次写 100 个文件 = 每天积累，几个月后就是几百万小文件。HDFS 的 NameNode 把每个文件的元数据放内存，小文件多是集群的头号慢性病。

解法：

# 写出前合并分区（注意：coalesce 不 Shuffle，repartition 会 Shuffle）
df.coalesce(20).write.parquet(...)        # 知道大概要几个文件时用它
df.repartition(20, "dt").write.parquet(...)  # 需要按列重新分区时用它

# 根治：开启 AQE 的 Shuffle 分区自动合并，从源头减少小文件
spark.conf.set("spark.sql.adaptive.coalescePartitions.enabled", "true")

5.4 一张排障决策图

任务慢了/挂了，按这个顺序查：

flowchart TD
    Q1{"任务挂了还是慢？"}
    Q1 -->|挂了| Q2{"Driver 日志里<br/>OOM 关键字？"}
    Q2 -->|Executor 端| F1["加 executor-memory<br/>或增大分区数"]
    Q2 -->|Driver 端| F2["查 collect/toPandas<br/>换成 write 或 take"]
    Q2 -->|文件不存在等| F3["懒执行报错错位<br/>从执行计划往上找源头"]
    Q1 -->|慢| Q3{"Spark UI 看 Stage：<br/>个别 Task 特别慢？"}
    Q3 -->|是 Max远大于Median| F4["数据倾斜<br/>过滤脏key/加盐/AQE"]
    Q3 -->|否 全都慢| Q4{"Shuffle Read/Write<br/>数据量巨大？"}
    Q4 -->|是| F5["能广播的小表广播<br/>列裁剪 过滤下推<br/>提前聚合减少数据量"]
    Q4 -->|否| F6["查上游：小文件太多？<br/>查集群：资源不够排队？"]

第六篇 AI 时代：少写代码，完成大数据开发

时间快进到 AI 编程工具普及之后。回头看，Spark 开发是最适合被 AI 改造的领域之一，因为它的代码模式极其规整：读、变换、聚合、写，套路就那么多。

6.1 AI 能替你做什么，不能替你做什么

flowchart LR
    subgraph AI擅长["AI 做得比人好"]
        A1["自然语言 → PySpark/SQL 代码<br/>按用户30天行为算RFM特征 一句话出码"]
        A2["样板代码生成<br/>Schema 定义 造数脚本 单元测试"]
        A3["报错诊断<br/>贴堆栈 直接定位到懒执行错位/倾斜"]
        A4["口径文档化<br/>把代码翻译成业务能看懂的白话"]
    end
    subgraph AI不擅长["人必须自己把关"]
        B1["业务口径<br/>漏斗是严格顺序还是存在性<br/>AI 不知道你老板要什么"]
        B2["性能直觉<br/>哪里该广播 哪里会倾斜<br/>要看真实数据分布"]
        B3["生产决策<br/>资源参数 重跑策略 数据回补"]
    end

我的实际工作流变化：

以前：写「用户漏斗分析」= 查文档 30 分钟 + 写代码 40 分钟 + 调试 30 分钟。
现在：给 AI 描述清楚——表名、字段、漏斗定义（严格按时间顺序）、输出格式——10 秒出代码，我花 20 分钟 review 口径和边界条件。总耗时砍到三分之一。

但注意：省下来的时间全部应该砸在口径确认和数据校验上。AI 写的代码语法几乎不会错，但它不知道你们的 user_id = '-1' 是脏数据、不知道运营要的是存在性漏斗。这正是第五篇那些坑的价值——AI 时代，踩坑经验不是贬值了，而是成了你最贵的资产，因为代码人人都能生成，能判断代码对不对的人变稀缺了。

6.2 具体怎么干：三个提效姿势

姿势一：需求描述模板化。 给 AI 下指令时固定四段式：

背景：表 ods.user_events，字段 user_id/event_type/ts，按天分区 dt
任务：计算 2022-10-25 的转化漏斗 曝光→点击→加购→下单→支付
口径：严格顺序漏斗，后一步的最早时间必须大于前一步
输出：一行五列，列名用中文

第四篇场景三的完整代码，用这样的提示词一次就能生成得八九不离十。

姿势二：报错即提示词。 Spark 报错堆栈又长又唬人，直接整段贴给 AI，附上你的 Transformation 代码，它对「懒执行错位」「ClassNotFound（依赖没打包）」「分区越界」这类经典错误的诊断准确率很高。

姿势三：让 AI 写测试和校验脚本。 大数据开发最缺的就是测试——数据对不对以前靠人肉抽查。现在让 AI 顺手生成校验 SQL（行数对比、NULL 比例、金额总和与上游对账），质量反而比手工时代更好了。

6.3 冷静的一句话

AI 不会让你"少学 Spark"，它让学习曲线的重心变了：以前背 API 占 60% 的时间，现在这部分 AI 补上了；剩下 40%——架构直觉、业务口径、排障经验——变成了 100% 的核心竞争力。入门变容易了，精通的标准反而更高了。

思考与感悟

写完这篇文章，有几句话想单独说：

1. 学 Spark 的本质是学"分布式的世界观"。 单机时代的直觉——数据随手可得、循环遍历随意、内存无限——全都要扔掉。你要习惯一种新的思维方式：数据是流动的、分区是平行的、Shuffle 是昂贵的、失败是必然的（所以容错设计是一等公民）。这套世界观建立起来之后，学 Flink、学 Kafka、学 ClickHouse 都会很快，因为它们要解决的是同一族问题。

2. 调优经验 = 疼痛的记忆。 没有人看文档能学会处理数据倾斜，都是被凌晨两点的报警电话教会的。所以别怕踩坑，踩了记下来——我这篇第五篇的每个坑，当年都值一个通宵。

3. 离业务近一点，离技术远一点。 做了几年大数据，最大的感悟是：把 ETL 跑得快不算本事，知道这张表给谁用、口径对不对、错了谁会亏钱才是本事。电商场景里，GMV 算错 1% 可能就是一个部门的年终奖。技术只是手段，数据是业务的镜像。

4. AI 时代最值得押注的能力是"判断力"。 生成代码会越来越便宜，判断"这段代码对不对、这个口径该不该这么定、这个架构扛不扛得住双十一"会越来越贵。把 AI 当成一个能力极强但没有常识的实习生：活让它干，锅你来背，所以你必须看得懂它干的活。

与君共勉。

React 从入门到精通：环境搭建、核心语法、组件库选型与 AI 时代的开发方式

Fri, 26 Aug 2022 10:00:00 +0800

React 从入门到精通

目标读者：会 HTML/CSS/JS 基础，想系统学前端框架的同学；或写过 Vue/jQuery 想转 React 的工程师。阅读目标：把环境搭起来、把核心语法学会、把坑提前踩掉、知道组件库怎么选，最后聊聊 AI 时代写前端的新姿势。

React 的入门门槛不高，但「会写」和「写对」之间隔着一批经典的坑。这篇按真实学习顺序组织：环境 → 语法 → 心智模型 → 踩坑 → 组件库 → Demo → AI 时代的开发方式。

一、学习路线图

flowchart LR
    A["JS 基础<br/>ES6 语法"] --> B["环境搭建<br/>Node + Vite"]
    B --> C["核心语法<br/>JSX / 组件 / Props / State"]
    C --> D["Hooks<br/>useState / useEffect / 自定义 Hook"]
    D --> E["工程化<br/>路由 / 状态管理 / 组件库"]
    E --> F["进阶<br/>性能优化 / 服务端渲染"]
    F --> G["AI 协同开发"]

二、开发环境搭建（2022 年的正确姿势）

2.1 装 Node：用 nvm，不要官网下载安装包

第一个坑往往出在环境上：老教程让你去 nodejs.org 下安装包，半年后项目要求换个 Node 版本，你就得重装。用 nvm 管理多版本：

# Windows 用 nvm-windows，Mac/Linux 用 nvm
nvm install 16        # 2022 年的 LTS 是 16/18
nvm use 16
node -v               # v16.x.x

国内网络记得配镜像：npm config set registry https://registry.npmmirror.com。

2.2 创建项目：用 Vite，不要 create-react-app

2022 年的第二个坑：老教程还在教 create-react-app（CRA），它启动慢、打包慢、官方已基本停止维护。用 Vite，秒级启动：

npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev           # 打开 http://localhost:5173

目录结构：

my-app/
├── index.html          # 入口 HTML
├── package.json
├── vite.config.js
└── src/
    ├── main.jsx        # 挂载根组件
    ├── App.jsx         # 根组件
    └── components/     # 自己的组件放这里

2.3 编辑器与插件

VS Code + 两个必装插件：ES7+ React Snippets（输入 rafce 一键生成组件骨架）、ESLint（边写边提示 Hooks 依赖遗漏等问题）。再开 VS Code 的保存自动格式化（Prettier），团队风格从此不打架。

三、核心语法：记住一个公式就够了

3.1 心智模型：UI = f(state)

React 的全部思想一句话：界面是状态的函数。你不直接操作 DOM，只改数据（state），React 负责把界面更新到和数据一致。

flowchart LR
    S["state 变化<br/>setState"] --> R["React 重新执行组件函数<br/>得到新的虚拟 DOM"]
    R --> D["Diff：对比新旧虚拟 DOM<br/>找出最小差异"]
    D --> DOM["只把差异 patch 到真实 DOM"]

这就是为什么 React 代码里永远不要 document.getElementById 去改 DOM——绕过状态直接改界面，两边就对不上了。

3.2 组件与 JSX

组件就是一个返回 JSX 的函数。JSX 是「长得像 HTML 的 JS」，注意三条规则：标签必须闭合、属性用驼峰（className 不是 class）、JS 表达式放 {} 里：

function Welcome({ name }) {          // props 是父组件传进来的参数
  return <h1 className="title">你好, {name}!</h1>;
}

function App() {
  return <Welcome name="React" />;    // 组件像标签一样使用
}

3.3 state 与事件：让界面动起来

import { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);   // 声明状态：当前值 + 修改函数

  return (
    <button onClick={() => setCount(count + 1)}>
      点了 {count} 次
    </button>
  );
}

规则：props 是父组件给的（只读），state 是自己的（用 set 函数改）。数据流向永远是父 → 子，这叫单向数据流，是 React 排查问题比双向绑定框架容易的根本原因。

3.4 列表渲染与 key

function TodoList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.text}</li>   // key 用稳定 id，不要用 index！
      ))}
    </ul>
  );
}

3.5 useEffect：处理副作用

数据请求、定时器、订阅这类「和渲染无关的事」放 useEffect：

useEffect(() => {
  fetch("/api/todos")
    .then((r) => r.json())
    .then(setTodos);
}, []);   // 依赖数组为空 = 只在组件首次渲染后执行一次

四、踩坑故事：六个我真实掉进去过的坑

坑 1：setState 是「异步」的，连续 +1 只加了一次

// 想点一下加 3，结果只加了 1
setCount(count + 1);
setCount(count + 1);
setCount(count + 1);

原因：三次 count 读的都是本次渲染的旧值。改法：用函数式更新，每次拿到最新值：

setCount((c) => c + 1);
setCount((c) => c + 1);
setCount((c) => c + 1);   // 这次真的 +3

教训：新 state 依赖旧 state 时，永远用函数形式。

坑 2：useEffect 里 setState，死循环刷爆页面

useEffect(() => {
  setList([...list, newItem]);   // list 变了 → 重新渲染 → effect 又执行 → 死循环
}, [list]);

排查套路：页面卡死/请求刷屏，先找「effect 的依赖里有没有它自己改的东西」。解法通常是改用函数式更新把依赖摘掉：setList((l) => [...l, newItem])，依赖数组就能清空。

坑 3：列表 key 用 index，勾选状态全乱了

Todo 列表勾了第 1 项，删掉它之后，第 2 项变成「已勾选」——因为 key 用 index 时，React 按位置复用 DOM，删除一项后后面所有项位置错位，复用错了组件内部状态。key 必须用数据的稳定 id。

坑 4：直接改 state 对象，界面死活不更新

user.name = "新名字";    // 页面没反应！
setUser(user);           // 还是没反应——引用没变，React 认为没变化

React 靠引用比较判断要不要重渲染。正确姿势是造一个新对象：

setUser({ ...user, name: "新名字" });

数组同理：用 filter/map/concat 造新数组，不要 push/splice。

坑 5：定时器里的 stale closure（闭包旧值）

useEffect(() => {
  const timer = setInterval(() => {
    console.log(count);        // 永远是 0！
  }, 1000);
  return () => clearInterval(timer);
}, []);

effect 只在首次渲染执行，回调里捕获的 count 永远是首次渲染的旧值。解法：把 count 加进依赖数组，或用 useRef 保存最新值。这类 bug 不报错、只是数据不新鲜，最难查——ESLint 的 exhaustive-deps 规则能提前拦住大半，别随手关掉。

坑 6：在组件里定义组件，输入框每敲一个字就失焦

function Form() {
  const Input = () => <input />;   // 每次渲染都是全新组件，DOM 被销毁重建
  return <Input />;
}

组件定义必须放模块顶层。这个坑的典型症状是「input 输入一个字符就丢焦点」，看到这个词直接想到它。

五、底层原理：为什么 React 是这样设计的

前面六个坑，背规则可以避开，但理解原理才能「预判」。这一章讲透四件事：虚拟 DOM 与 Diff、Fiber 架构、渲染两阶段、Hooks 的实现。学完你会发现：第四节所有的坑，都是这四个原理的直接推论。

5.1 虚拟 DOM 与 Diff 算法：用 JS 对象换性能

虚拟 DOM 就是用普通 JS 对象描述界面长什么样（{ type: 'div', props: {...}, children: [...] }）。每次 state 变化，React 重新生成一棵新的虚拟 DOM 树，和旧的对比（Diff），只把差异更新到真实 DOM——直接操作 DOM 慢，操作 JS 对象快，这就是虚拟 DOM 的收益。

全量对比两棵树的算法复杂度是 O(n³)，一万个节点就是十亿次比较，不可用。React 用三条「妥协」策略把它降到 O(n)：

flowchart TB
    subgraph 策略["Diff 的三条妥协策略"]
        T["tree diff：只同层比较<br/>不跨层移动节点"]
        C["component diff：组件类型变了<br/>整棵子树直接销毁重建"]
        E["element diff：同层列表<br/>靠 key 识别 谁移动/新增/删除"]
    end
    T --> R["结果：O(n) 完成对比"]
    C --> R
    E --> R

三条策略各自对应一条实践纪律：

tree diff → 跨层级移动 DOM 节点代价极大，设计组件树时保持层级稳定；
component diff → 同一个位置不要渲染「类型忽变」的组件（<div> 和  来回切换），类型一变整棵重建；
element diff → 这就是坑 3 的原理：key 是 React 识别「哪个节点是哪个」的唯一依据，用 index 当 key，删除中间项后后面所有 key 全变，React 就把节点张冠李戴了。

5.2 Fiber 架构：把渲染拆成可中断的小任务

React 15 之前，更新是递归遍历组件树，一旦开始就不能停——组件树大了，一帧 16ms 里算不完，页面就掉帧卡顿。React 16 重写架构，引入 Fiber：

Fiber 是什么：每个组件对应一个 Fiber 节点，渲染工作被拆成一个个以 Fiber 为单位的小任务；
怎么连起来：节点之间不用递归，用链表（child 第一个子节点 / sibling 下一个兄弟 / return 父节点）——用指针代替调用栈，所以随时可以暂停、恢复、放弃；
双缓存：内存里同时存在两棵树——屏幕上正在显示的 current 树，和后台正在构建的 workInProgress 树。新树在后台慢慢算，算完一次性把指针切过去，用户永远看不到「渲染到一半」的界面。

flowchart LR
    subgraph 旧架构["React 15 栈调和"]
        A1["递归遍历整棵树<br/>不可中断"] --> A2["大树直接卡顿掉帧"]
    end
    subgraph 新架构["React 16+ Fiber"]
        B1["每个 Fiber 一个小任务<br/>可随时暂停让出主线程"] --> B2["高优先级任务插队<br/>（用户输入 > 列表渲染）"]
        B2 --> B3["workInProgress 树算完<br/>一次性切换"]
    end

时间切片带来的直接体验：输入框输入（高优先级）可以打断长列表渲染（低优先级），输入再也不卡。useTransition 就是把这个优先级能力开放给开发者——把「不紧急的更新」包进 startTransition，界面保持响应。

5.3 渲染两阶段：render 可中断，commit 不可中断

一次更新分两个阶段，分工严格：

flowchart LR
    subgraph R["render 阶段（可中断）"]
        R1["调用组件函数<br/>生成新虚拟 DOM"]
        R2["Diff，算出变更清单"]
    end
    subgraph C["commit 阶段（不可中断）"]
        C1["把变更一次性<br/>写入真实 DOM"]
        C2["执行 useLayoutEffect<br/>再异步执行 useEffect"]
    end
    R --> C

这一阶段划分解释了两个「为什么」：

为什么组件函数里不能有副作用（发请求、改全局变量）：render 阶段可中断、可重试、可能被调用多次，副作用会重复执行。所以副作用必须放 useEffect——它在 commit 之后执行，每次提交只跑一次。坑 2 的死循环本质也是没搞清这个边界：effect 里改 state 触发新一轮 render→commit→effect，链条首尾相接就成了循环。
为什么 setState 看起来是异步的（坑 1）：setState 只是「登记一个更新任务」，组件函数要等 React 调度到 render 阶段才重新执行。你在 setCount 之后立刻读 count，读到的当然是本次渲染的旧值。

5.4 Hooks 的实现：一条链表 + 调用顺序

Hooks 没有魔法。每个 Fiber 节点上挂着一条链表，组件每次调用一个 Hook（useState/useEffect/…），React 就顺着链表取下一个节点存状态：

flowchart LR
    F["Fiber 节点<br/>memoizedState"] --> H1["Hook 节点 1<br/>useState count"]
    H1 --> H2["Hook 节点 2<br/>useState text"]
    H2 --> H3["Hook 节点 3<br/>useEffect"]
    H3 --> N["null"]

关键：状态不是按变量名存的，是按调用顺序存的。第 n 次调用 useState，就拿链表上第 n 个节点。这就是「Hook 不能写在 if/循环里」这条铁律的唯一原因——条件调用会让本次渲染的调用顺序和上次错位，状态全部错位：

// ❌ 条件调用：show 为 false 时少调一次，后面所有 Hook 状态错位
if (show) {
  const [a, setA] = useState(0);
}
const [b, setB] = useState(0);

用一个 20 行的迷你实现体会一下原理：

// 极简版 useState：一个数组 + 一个游标
const hookStates = [];
let cursor = 0;

function useState(initial) {
  const i = cursor++;                    // 本次调用占第 i 个槽位
  hookStates[i] = hookStates[i] ?? initial;
  const setState = (v) => {
    hookStates[i] = typeof v === "function" ? v(hookStates[i]) : v;
    cursor = 0; render();                // 重置游标，重新渲染
  };
  return [hookStates[i], setState];
}

// 每次 render 前 cursor 归零，Hook 按调用顺序对号入座

真实 React 里这个数组换成 Fiber 上的链表、render 换成调度器触发，思想一模一样。也顺带解释了坑 5（stale closure）：effect 回调捕获的是「它创建那次渲染」的作用域，而 Hook 槽位里的状态早已更新——两者不是一份数据，于是读到旧值。

5.5 批量更新：多次 setState 合并成一次渲染

React 会把同一个事件循环里的多次 setState 合并（batching）成一次渲染，避免白白渲染三次。React 18 起连 Promise、setTimeout 里的更新也自动批量。坑 1 的「连续 +1 只加一次」正是批量更新的副产品：三次调用都基于同一个旧值计算，合并后只生效最后一次；函数式更新 setCount(c => c + 1) 之所以能正确累加，是因为每次计算都基于「上一个更新任务的结果」而不是旧快照。

5.6 一张图总结：从 setState 到屏幕更新

flowchart TB
    A["setState 登记更新任务"] --> B["Scheduler 调度<br/>按优先级插队/合并"]
    B --> C["render 阶段（可中断）<br/>沿 Fiber 链表逐个执行组件函数<br/>Hooks 按调用顺序取状态"]
    C --> D["生成 workInProgress 树<br/>Diff 出变更清单"]
    D --> E["commit 阶段（不可中断）<br/>一次性写入真实 DOM"]
    E --> F["执行 useEffect"]
    F -->|"effect 里又 setState"| A

回头看第四节的坑：坑 1 是批量更新、坑 2 是 render/commit 边界、坑 3 是 element diff、坑 4 是引用比较（Diff 的判断依据）、坑 5 是 Hooks 快照机制、坑 6 是 component diff（类型变=重建）。规则会过时，原理不会——这就是先学原理的价值。

六、主流 UI 组件库：选型对比

别从零写按钮和表格，组件库选一个用熟：

组件库	风格	适合场景	备注
Ant Design (antd)	企业级、组件全	中后台管理系统（国内事实标准）	文档中文友好，生态最厚
Material UI (MUI)	Google Material 风格	海外产品、工具类	定制性强
Ant Design Mobile	移动端	H5/混合 APP	与 antd 同门
Tailwind + Headless UI	原子化 CSS	定制化要求高的产品页	没有现成组件，只有样式积木
Chakra UI	简洁现代	快速原型	主题系统好用

中后台选 antd 基本不会错。三分钟搭出一个像样的页面：

import { Table, Button, Form, Input } from "antd";

function UserPage() {
  const columns = [
    { title: "姓名", dataIndex: "name" },
    { title: "邮箱", dataIndex: "email" },
  ];
  return (
    <>
      <Form layout="inline" onFinish={(v) => console.log(v)}>
        <Form.Item name="name" label="姓名"><Input /></Form.Item>
        <Button type="primary" htmlType="submit">查询</Button>
      </Form>
      <Table columns={columns} dataSource={[]} rowKey="id" />
    </>
  );
}

组件库避坑：不要混用两个重型组件库（打包体积爆炸）；版本升级先看迁移指南（antd 4→5 改了样式方案）；表单校验规则写在 rules 里而不是手写 if-else。

七、完整 Demo：一个 Todo App

把前面的知识拼起来——增删改查、状态提升、组件拆分，都在这 60 行里：

import { useState } from "react";

function App() {
  const [todos, setTodos] = useState([]);
  const [text, setText] = useState("");

  const add = () => {
    if (!text.trim()) return;
    setTodos((t) => [...t, { id: Date.now(), text, done: false }]);  // 新数组！
    setText("");
  };

  const toggle = (id) =>
    setTodos((t) => t.map((x) => (x.id === id ? { ...x, done: !x.done } : x)));

  const remove = (id) => setTodos((t) => t.filter((x) => x.id !== id));

  return (
    <div style={{ maxWidth: 400, margin: "40px auto" }}>
      <h1>Todo</h1>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={add}>添加</button>
      <ul>
        {todos.map((item) => (
          <li key={item.id}>
            <span
              onClick={() => toggle(item.id)}
              style={{ textDecoration: item.done ? "line-through" : "none" }}
            >
              {item.text}
            </span>
            <button onClick={() => remove(item.id)}>删除</button>
          </li>
        ))}
      </ul>
      <p>共 {todos.length} 项，完成 {todos.filter((x) => x.done).length} 项</p>
    </div>
  );
}
export default App;

注意里面处处是前面坑点的正确示范：setTodos 全部函数式更新、key 用 id、改对象用展开运算符造新对象。

八、AI 时代：怎么少写代码完成 APP 开发

写完上面这些，必须承认一件事：这篇博客里 80% 的代码，AI 现在都能直接生成。Todo、表单、表格页这类「模式明确」的代码，人的价值已经不在敲键盘上。我现在的前端开发流程变成了这样：

flowchart LR
    A["人：写清需求<br/>页面结构 / 字段 / 交互 / 接口契约"] --> B["AI：生成组件代码<br/>一次给完整页面而非碎片"]
    B --> C["人：Review + 跑起来验证<br/>重点看 state 设计和依赖数组"]
    C --> D["AI：按反馈迭代<br/>改样式 / 加校验 / 拆组件"]
    D --> E["人：集成进项目<br/>接真实接口 / 统一风格"]

几条实战经验：

描述越具体，代码越能直接用。「写个用户管理页」和「用 antd Table 写用户管理页，列：姓名/邮箱/状态，顶部一个内联查询表单，分页 pageSize 20，数据从 GET /api/users 拿」得到的代码质量天差地别——这和给实习生派活是一个道理。
让 AI 一次生成完整页面，而不是一次次要碎片。碎片代码的集成成本比生成成本高；整页生成后你再删改，快得多。
Review 的重点变了：语法 AI 很少错，要盯的是架构层面的东西——state 放哪层合不合理、useEffect 依赖有没有坑（本文第四节的坑 AI 也会犯）、组件拆分粒度、key 用没用 index。基本功越扎实，Review 越快越准——AI 淘汰的是只会写不会看的人。
工具形态：代码补全（Copilot）管「写着顺」；对话式 IDE（Cursor、Claude Code）管「整个功能」；v0.dev 这类管「从截图/描述直接出页面」。三者是不同粒度，按任务大小选。
APP 整体路径：需求描述 → AI 出页面原型 → 选定组件库统一风格 → AI 按接口文档接数据 → 人工处理鉴权、错误处理、边界情况。一个中后台 CRUD 类 APP，这个流程能把工期压到原来的三分之一。

九、延伸话题：为什么国内流行 Vue，海外是 React 统治

先校准这个说法：不是非黑即白——国内大厂核心产品用 React 的不少（蚂蚁的 Ant Design 就是 React 生态），海外 Laravel 社区也带起了一批 Vue 用户。但总体格局确实存在：国内中小厂、外包、移动端 H5 里 Vue 占比明显高，海外从创业公司到大厂 React 一家独大（npm 全球周下载量 React 常年是 Vue 的数倍）。原因是多层的：

flowchart TB
    subgraph 历史时机["历史时机（2014-2016）"]
        H1["Vue 2014 年发布<br/>作者尤雨溪是华人<br/>中文文档从第一天就是一流的"]
        H2["恰逢国内移动互联网爆发<br/>海量新人入行<br/>需要低门槛框架"]
        H3["AngularJS 在国内已流行<br/>Vue 继承模板+双向绑定心智<br/>平滑承接"]
    end
    subgraph 生态锁定["生态锁定"]
        E1["饿了么 Element UI（2016）<br/>阿里系采用 Vue"]
        E2["Element / Ant Design Vue / Vant<br/>中后台组件库成套"]
        E3["uni-app 用 Vue 语法写小程序<br/>吃透国内小程序红利"]
    end
    subgraph 正循环["正循环"]
        L1["Vue 门槛低 → 培训机构主教 Vue"]
        L2["会 Vue 的人多 → 企业招 Vue 便宜快"]
        L3["企业用 Vue → 岗位多 → 新人继续学 Vue"]
    end
    subgraph 海外对照["海外对照"]
        O1["Facebook 背书 + 自家产品验证"]
        O2["React Native 吃下跨端"]
        O3["Next.js 等元框架强化生态"]
        O4["大厂招聘需求锁定人才供给"]
    end
    H1 & H2 & H3 --> 国内["国内 Vue 流行"]
    E1 & E2 & E3 --> 国内
    L1 --> L2 --> L3 --> 国内
    O1 & O2 & O3 & O4 --> 海外["海外 React 统治"]

拆开看，几个关键变量：

文档与语言的近因效应。Vue 的中文文档从发布第一天就是母语级质量，而 React 中文文档长期靠社区翻译、滞后且质量参差。对自学者，这个差异是决定性的——学什么框架，往往就是「哪份文档看得懂」决定的。
生态位被谁先占住。2016 年饿了么开源 Element UI、阿里系大量采用 Vue，中后台组件库（Element/Ant Design Vue/Vant）成套出现，「Vue + Element」成了国内中后台的标准答案。海外对应位置被 React 的 Ant Design（蚂蚁国际版反哺）、MUI、Next.js 占住。
培训机构的放大器作用。Vue 模板语法接近 HTML、双向绑定写表单快、SFC 单文件组件直观——对从后端/jQuery 转前端的人极其友好，培训周期短、就业反馈快，于是机构主教 Vue，供给端被锁定。
移动端的分野。海外跨端 = React Native，进一步巩固 React；国内跨端的真正战场是小程序，而 uni-app 这类「用 Vue 语法写小程序」的框架吃掉了这块红利，又反过来强化了 Vue 心智。
React 的门槛是真实的。JSX、函数式思维、不可变数据、Hooks 的心智负担（本文四、五章的坑就是证据），对英语文档和工程化基础都有要求——这在海外是标配，在国内快速扩张期的团队里是成本。

对学习者的启示：两个框架的核心思想（组件化、状态驱动 UI、虚拟 DOM）完全相通，Vue3 的组合式 API 和 React Hooks 已经趋同。学会一个，另一个一周能上手——别把宝押在框架上，押在原理上。而且 AI 时代框架差异进一步被抹平：AI 两个都写得很好，你需要的只是读懂它写的是什么的判断力。

十、思考与感悟

1. React 的本质不是语法，是「UI = f(state)」这个心智模型。 Hooks 语法三天能学会，但「什么该进 state、state 放哪层、如何从 state 推导 UI」要想清楚需要几个月。判断一个人 React 水平，不要问语法，问他「这个状态你会放在哪个组件」。

2. 坑大多是「引用」和「时机」两类。 本文六个坑归个类：坑 1/3/4 是没理解引用比较（key 复用、state 不可变），坑 2/5/6 是没理解渲染时机（effect 何时跑、闭包捕获哪次渲染的值）。把「每次渲染都是一次全新函数调用」这句话想透，大半坑自动消失。

3. 组件库是杠杆，不是拐杖。 antd 让中后台效率翻倍，但只会在组件里塞业务逻辑的人，换个库就废了。组件库之上是交互设计，之下是 React 基本功，两头都得懂一点。

4. AI 时代，「读代码」比「写代码」更值钱。 生成不再稀缺，判断力才稀缺。能一眼看出 AI 生成的代码里 useEffect 依赖少了、state 设计反了的人，会把 AI 用得越来越顺手；只会复制粘贴的人，会被 AI 生成的坑埋掉。学基础不是为了手写，是为了 Review。

十一、学习路线建议

第一周：搭好 Vite 环境，跟着官方教程（react.dev 的互动教程质量很高）过完 JSX/组件/state。
第二周：手写 Todo App，故意踩一遍第四节的坑（比如把 key 换成 index 看看怎么乱），踩过才算学会。
第三周：加路由（React Router）和组件库（antd），做一个有列表页+表单页的两页应用。
第四周：接一个真实后端 API，处理 loading/错误/空数据三种状态——真实项目和 Demo 的差距全在这里。
进阶：自定义 Hook 抽逻辑、Context/Zustand 管全局状态、性能优化（memo/useMemo）、Next.js 服务端渲染。

参考资料：

React 官方文档（react.dev）——新版文档质量极高，教程可交互

Vite 官方文档

Ant Design 官方文档

React Router 文档

MongoDB 从入门到精通：存储引擎、建模、索引、副本集、分片与事务实战

Tue, 26 Oct 2021 10:30:00 +0800

MongoDB 从入门到精通：存储引擎、建模、索引、副本集、分片与事务实战

目标读者：用过 MySQL 之类的关系型数据库，现在要接 MongoDB 的同学——可能是接手存量系统，可能是新业务选型，也可能是想给自己的技术栈补上 NoSQL 这一块。
本文不浪费篇幅在「什么是文档」这种名词解释上，直接从真正影响系统生死的东西讲起：存储引擎、一致性、高可用、性能。
写这篇的契机：2021 年我所在团队的电商中台把部分业务从 MySQL 迁到 MongoDB，整个过程脱了一层皮。这篇是我希望迁移前有人能拍在桌上的笔记。
文内版本基线：MongoDB 5.0（2021 年 7 月发布）、官方 Java 同步驱动 4.3、JDK 11。

全文八篇，按真实的成长路径编排：

flowchart LR
    A["一 选型认知<br/>Mongo 适合什么"] --> B["二 存储引擎<br/>WiredTiger 底牌"]
    B --> C["三 数据建模<br/>核心战场"]
    C --> D["四 索引与 explain<br/>调优基本功"]
    D --> E["五 聚合管道<br/>服务端计算"]
    E --> F["六 副本集<br/>高可用与读写语义"]
    F --> G["七 事务与分片<br/>规模化与一致性"]
    G --> H["八 运维与 AI 时代<br/>监控备份 少写代码"]
    style H fill:#e8f4e8

学习 MongoDB 要始终围绕三个问题：数据安不安全、查询快不快、流量扛不扛得住。这篇的每一节，都是对这三问的某一次正面回答。

第一篇选型认知：什么时候该用 MongoDB，什么时候别逞强

第一课不是怎么用，是什么时候用。用错场景的 MongoDB，比不用更可怕。

flowchart TD
    subgraph 适合["MongoDB 的主场"]
        P["商品中心<br/>类目属性千差万别<br/>文档模型天然契合"]
        C["购物车/会话<br/>读多写多 结构灵活"]
        L["行为日志/埋点<br/>写入量大 schema 常变<br/>TTL 索引自动过期"]
        CM["CMS/配置中心<br/>页面配置 JSON 化"]
    end
    subgraph 谨慎["需要精心设计的边界"]
        O["订单/库存<br/>可用 但要事务+对账设计"]
        M["消息/Feed 流<br/>可用 注意分片键设计"]
    end
    subgraph 别上["别硬上 Mongo"]
        F["账务/清结算<br/>强事务 强审计<br/>交给关系型"]
        S["复杂搜索<br/>交给 Elasticsearch"]
        J["重度多表关联分析<br/>交给 OLAP/数仓"]
    end
    style 适合 fill:#e8f4e8
    style 别上 fill:#fde8e8

一句话原则：MongoDB 适合「单实体自成一体、结构多变、读多」的在线业务；不适合「钱」「搜索」「重度关联分析」。 判断依据不是性能 benchmark，而是数据访问模式——先把系统里 80% 的查询列出来，看它们能不能被「单集合 + 少量 $lookup」覆盖。覆盖不了，选型本身就有问题。

思考与感悟之一：数据库选型和框架选型完全不同。框架选错了可以重构，数据库选错了是「数据搬家」级别的灾难——停机迁移、双写对账、灰度切流，每一步都在钢丝上走。所以对「不做什么」的清单，要比「做什么」的清单更长。

第二篇 WiredTiger：理解存储引擎，才配谈性能

很多人用 MongoDB 三年，不知道底下是 WiredTiger。这就像开了一辈子车不懂发动机——平时没事，出事时只能干瞪眼。这一篇先把「数据到底怎么存的」讲透，再回答那个面试必问的问题：MongoDB 为什么快，为什么扛得住大量读写。

2.1 底层数据模型：BSON，磁盘上到底存了什么

你在应用层操作的是「文档」（可以理解成 JSON），但磁盘上存的是 BSON（Binary JSON）——一种二进制、自描述、长度前缀的编码格式：

flowchart LR
    subgraph BSON["一个 BSON 文档的字节布局"]
        L["int32 总长度<br/>开头 4 字节"] --> E1["元素1<br/>类型字节 + 字段名 + 值"]
        E1 --> E2["元素2<br/>类型字节 + 字段名 + 值"]
        E2 --> EN["..."]
        EN --> Z["0x00 结束符"]
    end
    subgraph TYPES["BSON 比 JSON 多出的类型"]
        T1["ObjectId / Date / 正则"]
        T2["int32 / int64 / double"]
        T3["Decimal128 高精度十进制"]
        T4["BinData 二进制 / 数组 / 内嵌文档"]
    end
    BSON -.-> TYPES

BSON 的设计直接回答了两个性能问题：

长度前缀 + 类型字节 → 遍历时可以「跳过」字段。 查询只取 name 字段时，引擎不需要解析整个文档，读到字段长度直接指针后移——这就是为什么投影（projection）能省时间。
类型丰富 → 不需要序列化转换。 JSON 只有 string/number/boolean，日期只能存字符串再解析；BSON 原生支持 Date、ObjectId、Decimal128（钱的精确计算就靠它）、二进制，省去了应用层和存储层之间大量的类型转换开销。

更关键的是文档在磁盘上是连续存放的：一个商品文档（含内嵌的 SKU 数组、图片列表）在磁盘上是一整块连续的字节。这和关系型数据库形成鲜明对比——

flowchart TD
    subgraph MYSQL["MySQL 读一个完整商品"]
        A1["product 表的 B+ 树页"] --> J["JOIN"]
        A2["sku 表的 B+ 树页<br/>磁盘另一处"] --> J
        A3["image 表的 B+ 树页<br/>磁盘又一处"] --> J
        J --> R["多次随机 I/O<br/>才能拼出一个商品"]
    end
    subgraph MONGO["MongoDB 读一个完整商品"]
        B["一次磁盘寻道<br/>读出连续的一整块 BSON"]
    end
    style MONGO fill:#e8f4e8

这就是 MongoDB 设计哲学里最重要的词：数据局部性（data locality）。「一起读的数据，就存在一起」。嵌入建模之所以是 Mongo 的灵魂，底层原因就在这里——它不是风格偏好，是磁盘 I/O 决定的。

追问：文档是定长连续存放的，那修改、变大之后怎么办？磁盘会不连续吗？ 这要分两个时代说。MMAPv1 时代（3.0 之前）文档存在定长槽位里，变大就得整体搬家（document move），旧槽位变空洞，磁盘碎片是当年最臭名昭著的问题。WiredTiger 时代换了个思路：存储单位是 B 树的页而不是文档，文档是叶页里的一条 record；修改从不在原地写——checkpoint 时用 copy-on-write 把改后的整页写到磁盘新位置，旧块进空闲列表复用；文档长大导致页放不下就触发页分裂，超大文档走 overflow 页。所以「连续」的准确含义是「逻辑上一条 record、一次 I/O 读取」，物理位置本来就会搬。代价有两个：长期高频更新会积累碎片（用 db.collection.compact() 定期回收），以及频繁长大的文档会引发频繁页分裂——这是第三篇「增长边界」判断的底层原因，时序类数据的标准解法是按时间桶预分配文档的 bucket 模式，让单文档尺寸保持稳定。

2.2 为什么快：读快与写快的底层原因

「MongoDB 快」不能当口号喊，要能拆成具体机制。先写后读。

写入为什么快——一条写请求的完整路径：

flowchart LR
    APP["应用<br/>Java 驱动"] --> M["mongod<br/>内存操作"]
    M --> C["WiredTiger cache<br/>修改页标记为 dirty<br/>写操作到此即完成"]
    M --> J["journal 日志<br/>顺序追加写<br/>磁盘顺序 I/O 极快"]
    C -.->|"checkpoint<br/>默认每 60 秒<br/>批量刷盘"| D["数据文件<br/>压缩后的 B 树页"]
    style C fill:#e8f4e8

四个叠加的机制：

写内存即返回。写操作修改的是 cache 里的页，标记 dirty 就完事，数据文件由 checkpoint 线程每 60 秒批量刷一次——随机写被攒成了顺序批量写。这是「写快」的第一来源。
journal 用顺序写保证持久性。怕宕机丢内存里的数据？journal（WAL 日志）是顺序追加写，磁盘的顺序写比随机写快几个数量级。j: true 的写确认就是等 journal 落盘，而不是等数据文件落盘。

这里必须正面回答一个所有人都会问的问题：「写入内存就返回，服务器挂了怎么办？」 不会变成脏数据——cache 里丢掉的只是 dirty 页的内存副本，每次修改都已先追加进 journal；mongod 重启时以最后一次 checkpoint 为基线重放 journal，把丢失的写补回数据文件。真正的风险窗口在确认时机：默认 w:1 下 journal 每 ~100ms 才批量提交，断电最多丢「最近约 100ms 且未同步到从节点」的写（第六篇丢的 23 笔订单就是这么没的）；j: true 等日志落盘，单节点宕机不丢；w: majority 等多数派确认，机器物理损毁也不丢。丢不丢数据不是 MongoDB 决定的，是你选 writeConcern 档位时决定的——这套「内存脏页异步刷盘 + 日志重放」和 MySQL InnoDB 的 redo log 是同一套思想。
文档级并发。更新只锁单个文档，100 个线程写 100 个不同文档完全不互斥。对比早期 MySQL MyISAM 的表锁、乃至行锁时代的间隙锁开销，文档锁的冲突概率天然更低。
没有跨行约束的包袱。无外键检查、无触发器、单文档原子性不需要 undo log（改一个文档就是改一整块，要么全改要么不改），写入路径短。

读取为什么快——四道防线：

局部性：如上，嵌入建模让「读一个完整实体」= 一次磁盘寻道，没有 JOIN 的多次随机 I/O。
缓存：热数据常驻 WiredTiger cache（默认一半内存），命中内存的读在微秒级。
B 树索引：索引项 O(log n) 定位，千万级数据也就 4 层左右，加覆盖索引（第四篇）连文档都不用读。
副本集读扩展：readPreference: secondary 把展示类读流量分摊到从节点，读吞吐随节点数线性扩展。

大量读 + 大量写同时扛住的原因：读写分离（从节点扛读）+ MVCC（读不阻塞写、写不阻塞读）+ 写内存化。这三件事同时成立，才撑得起电商大促「几十万读 QPS 的商品页 + 几万写 QPS 的库存扣减」同框的场景。还不够？分片把写入水平切到多个副本集，写吞吐同样线性扩展（第七篇）。

快的代价（必须说清楚，否则就是忽悠）：写内存即返回意味着默认 w:1 下宕机可能丢最后一小段数据（第六篇的丢单事故就是这么来的）；热数据依赖内存，内存小于工作集时性能断崖；没有 JOIN 意味着关联查询要自己扛。MongoDB 的快是「用设计取舍换来的快」，不是魔法。

2.3 WiredTiger 你必须知道的四件事

flowchart TD
    W["WiredTiger 存储引擎<br/>MongoDB 3.2+ 默认"] --> A["文档级并发控制<br/>多线程写同一集合不互斥<br/>只有同一文档冲突才重试"]
    W --> B["压缩存储<br/>snappy 默认<br/>磁盘占用约为数据量的 30%-70%"]
    W --> C["缓存机制<br/>cacheSizeGB 默认 = 50% × (内存 - 1GB)<br/>热数据全在内存里"]
    W --> D["MVCC 多版本<br/>读不阻塞写 写不阻塞读<br/>snapshot 隔离"]

要记的结论：

文档级锁：并发写同一个集合是免费的，但并发改同一个文档会串行重试。这直接决定建模——秒杀库存如果把 100 个 SKU 的库存都嵌在一个商品文档里，大促时这个文档就是全站最热的锁热点。
缓存即命：WiredTiger cache 默认吃掉一半内存。生产上「Mongo 内存打满」往往不是泄漏，是 cache 在正常工作——看 wiredTiger.cache 指标而不是看进程 RSS 下结论。
压缩是把双刃剑：省磁盘，费 CPU。写密集型日志库可换 zlib 更高压缩比，CPU 紧张时别乱调。
MVCC 的代价：老版本数据要清理，长时间不提交的事务会压住清理线程，导致 cache 中 dirty data 堆积、写入被拖慢。

踩坑故事 #1（cache 被大事务压垮）：我们有个定时任务一次性更新 200 万条商品，跑的时候整个库延迟飙升。原因：巨型事务导致 WiredTiger 无法清理旧版本，cache 中 dirty bytes 超过阈值后应用线程被迫参与淘汰（eviction），写入集体变慢。解法：批量操作必须拆批（每批 1000 条 + 短暂让出窗口），生产环境永远不开「不设限的大批量更新」。这条后来成了团队《MongoDB 使用红线》第一条。

2.4 本地环境：直接上副本集，别玩单机

单节点 MongoDB 不支持事务，也不具备生产形态。本地练手就用 Docker Compose 起一套三节点副本集：

# docker-compose.yml
version: '3.8'
services:
  mongo1:
    image: mongo:5.0
    command: ["--replSet", "rs0", "--bind_ip_all"]
    ports: ["27017:27017"]
  mongo2:
    image: mongo:5.0
    command: ["--replSet", "rs0", "--bind_ip_all"]
  mongo3:
    image: mongo:5.0
    command: ["--replSet", "rs0", "--bind_ip_all"]

# 初始化副本集（执行一次）
mongosh --eval 'rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017" },
    { _id: 1, host: "mongo2:27017" },
    { _id: 2, host: "mongo3:27017" }
  ]
})'

第三篇数据建模：核心战场，没有之一

MongoDB 精通与否，就看建模。SQL 建模有范式护体，Mongo 建模全靠经验与取舍——这也是 AI 最帮不上忙的部分（第八篇详谈）。

3.1 唯一重要的问题：嵌入还是引用

flowchart TD
    Q["一份数据，嵌入父文档<br/>还是独立成集合？"] --> A{"三个判断"}
    A --> B["读写边界<br/>总是一起读写吗？"]
    A --> C["增长边界<br/>数量有上限吗？"]
    A --> D["并发边界<br/>会被高并发独立更新吗？"]
    B -->|"是，且"| E["嵌入<br/>如：订单内嵌 items 快照"]
    C -->|"否，无限增长"| R["引用<br/>如：商品引用评论"]
    D -->|"是，热点"| R2["引用<br/>如：SKU 库存独立成文档<br/>避免单文档成锁热点"]

三个判断，每个都对应一个坑：

读写边界：订单的 items 嵌入（下单时一次写入、之后整体读取）；但「收货地址」独立成集合——地址在下单、物流、售后多个流程被独立读写，嵌在用户文档里每次都要加载整个用户。
增长边界：单文档 16MB 硬上限。商品的「问大家」嵌进商品文档，爆款商品一年撑爆，连夜迁移。教训：文档不是仓库，是货架。
并发边界：文档级锁决定了——凡是会被高并发写的数据，从父文档里拆出去。秒杀库存必须一个 SKU 一个文档，绝不能嵌在商品里。

3.2 电商核心建模：订单快照与库存拆分

erDiagram
    USER ||--o{ ORDER : "引用"
    PRODUCT ||--o{ SKU_STOCK : "拆出 独立高并发写"
    ORDER ||--|{ ORDER_ITEM : "内嵌 商品快照"
    PRODUCT ||--o{ COMMENT : "引用 无界增长"
    PRODUCT {
        ObjectId _id
        string name
        string categoryId
        array attrs "类目属性 灵活嵌入"
        string detailUrl "富文本放对象存储"
    }
    SKU_STOCK {
        ObjectId _id
        ObjectId productId
        string spec
        int stock "独立文档 原子扣减"
        int version "乐观锁"
    }
    ORDER {
        ObjectId _id
        ObjectId userId
        array items "名称/单价/图片快照"
        long totalAmount "单位: 分"
        string status
        date createdAt
    }

两个关键设计，每个都值一次线上事故的钱：

订单必须存商品快照。下单那一刻把商品名、成交单价、主图冗余进 items。商品会改名改价下架，三个月后客服处理售后，看的必须是「成交时」的样子。快照冗余不是脏数据，是业务真相。
金额用「分」，long 存。浮点的 199.00 元在 IEEE 754 世界里是 198.999...，所有和钱有关的字段一律整数存分。这不是 Mongo 的问题，但 Mongo 的自由度会让人更容易犯懒。

思考与感悟之二：SQL 建模回答「数据之间是什么关系」，Mongo 建模回答「数据以什么节奏被读写」。前者是静态的学问，后者是动态的学问——必须预测流量形状（谁是热点、谁会暴涨、谁一起出现）才能建好模。这就是为什么 Mongo 建模更依赖业务理解，也更难被自动化。

第四篇索引与 explain：调优基本功，没有捷径

4.1 explain 是唯一标准答案

任何「这条查询为什么慢」的讨论，不贴 explain 输出就是耍流氓。Java 里看执行计划：

// 在 Java 驱动里用 explain 需要走 Document 命令（或先在 mongosh 里验证）
// mongosh 中的写法：
db.products.find({ categoryId: cid, status: "on" })
  .sort({ price: -1 })
  .explain("executionStats");

输出只盯四处：

flowchart TD
    A["winningPlan.stage"] --> B{"COLLSCAN?"}
    B -->|"是"| C["全表扫描<br/>立刻建索引"]
    B -->|"IXSCAN"| D["看三个数字"]
    D --> E["nReturned<br/>返回多少条"]
    D --> F["totalDocsExamined<br/>读了多少文档"]
    D --> G["totalKeysExamined<br/>扫了多少索引键"]
    E --> H{"理想: 三者接近<br/>危险: Examined 远大于 Returned"}

4.2 ESR 法则与 Java 建索引

复合索引字段顺序：Equality（等值）→ Sort（排序）→ Range（范围）。

商品列表页查询：{ categoryId: 等值, status: 等值 } + 按价格倒序，用 Java 驱动建索引：

// 依赖: org.mongodb:mongodb-driver-sync:4.3.x
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.model.Indexes;
import org.bson.Document;

public class IndexDemo {
    public static void main(String[] args) {
        try (MongoClient client = MongoClients.create("mongodb://localhost:27017/?replicaSet=rs0")) {
            MongoCollection<Document> products = client.getDatabase("shop").getCollection("products");

            // ESR：categoryId/status 等值(E) 在前，price 排序(S) 在后
            products.createIndex(Indexes.compoundIndex(
                    Indexes.ascending("categoryId"),
                    Indexes.ascending("status"),
                    Indexes.descending("price")
            ));

            // 部分索引：只给在售商品建，索引体积砍半
            products.createIndex(
                    Indexes.ascending("price"),
                    new com.mongodb.client.model.IndexOptions()
                            .partialFilterExpression(com.mongodb.client.model.Filters.eq("status", "on"))
            );

            // TTL 索引：埋点日志 7 天自动删除，省掉清理脚本
            client.getDatabase("shop").getCollection("access_logs")
                    .createIndex(Indexes.ascending("createdAt"),
                            new com.mongodb.client.model.IndexOptions().expireAfter(7L, java.util.concurrent.TimeUnit.DAYS));
        }
    }
}

注意：加了「价格区间筛选」后 price 就从 Sort 变成 Range，一个索引满足不了两个需求——索引设计永远是针对具体查询集合的权衡，没有万能索引。每个索引都拖慢写入，写多读少的日志库尤其敏感。

踩坑故事 #2（32MB 排序内存墙）：运营后台「全量商品按上架时间倒序」接口，商品过 10 万后直接报 Sort exceeded memory limit of 33554432 bytes。Mongo 内存排序上限 32MB，超了就炸。解法不是调参数，是建索引让排序走索引（索引天然有序）。上线红线第二条：凡带 sort 的查询，必须 explain 验证走索引排序。

踩坑故事 #3（正则索引进退两难）：模糊搜索 find({ name: /卫衣/ })，非前缀正则无法走索引，数据量上来后 P99 三秒起步。前缀匹配 /^卫衣/ 可以走索引，但中文搜索很少是前缀形态。2021 年的正经答案：Mongo 管数据，ES 管搜索，用 oplog/canal 同步，别指望一个库包打天下。

第五篇聚合管道：把计算下推给服务端

核心思维：「能在库里算完的，绝不拉回应用层」。拉 10 万条数据到 JVM 里 for 循环求和，是最常见的性能自杀。

flowchart LR
    A["$match<br/>筛: 本月已支付"] --> B["$unwind<br/>拆: items 展开"]
    B --> C["$group<br/>按商品汇总"]
    C --> D["$sort<br/>销量倒序"]
    D --> E["$limit<br/>Top 10"]
    E --> F["热销榜<br/>一次出结果"]

实战 Demo：本月热销商品 Top 10（Java 驱动写法）：

// demo01-top-sales：本月热销榜
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.model.Accumulators;
import com.mongodb.client.model.Aggregates;
import com.mongodb.client.model.Filters;
import com.mongodb.client.model.Sorts;
import org.bson.Document;
import org.bson.conversions.Bson;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Date;
import java.util.List;

public class TopSalesDemo {
    public static void main(String[] args) {
        try (MongoClient client = MongoClients.create("mongodb://localhost:27017/?replicaSet=rs0")) {
            MongoCollection<Document> orders = client.getDatabase("shop").getCollection("orders");

            Date monthStart = new Date(); // 实际取本月 1 号 0 点，此处从简
            Date monthEnd = new Date();

            List<Bson> pipeline = Arrays.asList(
                    // 第一道永远是 $match：能用索引，砍掉 99% 的数据
                    Aggregates.match(Filters.and(
                            Filters.eq("status", "paid"),
                            Filters.gte("createdAt", monthStart),
                            Filters.lt("createdAt", monthEnd))),
                    Aggregates.unwind("$items"),
                    Aggregates.group("$items.productId",
                            Accumulators.first("productName", "$items.productName"), // 快照红利：不用 $lookup
                            Accumulators.sum("totalQty", "$items.qty"),
                            Accumulators.sum("totalAmount",
                                    new Document("$multiply", Arrays.asList("$items.qty", "$items.price")))),
                    Aggregates.sort(Sorts.descending("totalQty")),
                    Aggregates.limit(10)
            );

            List<Document> hotList = new ArrayList<>();
            orders.aggregate(pipeline)
                    .allowDiskUse(true)   // 中间结果超 100MB 允许落盘，报表查询记得开
                    .into(hotList);

            hotList.forEach(doc -> System.out.println(doc.toJson()));
        }
    }
}

三个要点：

$match 必须放第一，放 $unwind 后面等于先把 500 万订单拆成 3000 万条再筛——有人这么写过，直接把一个节点的内存打爆。
allowDiskUse(true)：聚合中间结果超 100MB 默认报错，报表类查询记得开。
能不用 $lookup 就不用。它是应急手段，性能和多表 join 一样是噩梦。需要大量 $lookup 才能完成的查询，说明建模（第三篇）出了问题——回头改模型，别在查询层硬扛。

第六篇副本集：高可用与读写语义的分水岭

单节点 MongoDB 是玩具，副本集才是起点。这篇是「会用 Mongo」和「敢把核心业务放 Mongo」之间的分水岭。

6.1 架构与选主

flowchart TD
    subgraph RS["副本集 rs0（3 节点是最小生产配置）"]
        P["Primary<br/>唯一可写"]
        S1["Secondary<br/>异步复制 oplog"]
        S2["Secondary<br/>异步复制 oplog"]
        P -- "oplog 同步" --> S1
        P -- "oplog 同步" --> S2
    end
    P -.->|"心跳超时 10s<br/>自动选主"| S1
    APP["应用（驱动）"] -->|"自动感知拓扑变化<br/>故障转移对代码透明"| RS

必须理解的机制：

oplog：主节点的操作日志，从节点靠它追赶。oplog 是有界集合，从节点宕机太久会追不上，只能全量同步（initial sync）——大库的全量同步以小时计，这就是「从节点宕机要当事故处理」的原因。
自动选主：主挂了，10 秒左右选出新主。驱动自动重连新主，应用无感——前提是连接串写对了（多节点 + replicaSet=rs0），而不是只写了一个 IP。
连接池：MongoClient 是线程安全的重对象，全应用一个单例，连接池大小用 maxPoolSize 调。每请求 new 一个 MongoClient 等于每请求建一批 TCP 连接，压测时会把数据库连接数打爆——这和「每请求连一次 MySQL」是同一种自杀。

6.2 读写语义：writeConcern 与 readConcern

这部分决定你能不能睡着觉——数据到底「写没写进去」？

// demo02-write-concern：不同档位，不同的安全与延迟权衡
import com.mongodb.WriteConcern;
import com.mongodb.client.MongoCollection;
import org.bson.Document;

MongoCollection<Document> orders = client.getDatabase("shop").getCollection("orders");

// 快但可能丢：主节点内存确认就返回（埋点日志可用）
orders.withWriteConcern(WriteConcern.W1).insertOne(logDoc);

// 安全：多数派落盘 + journal 落盘才返回（订单必须这档）
orders.withWriteConcern(WriteConcern.MAJORITY.withJournal(true)).insertOne(orderDoc);

电商业务对号入座：

业务	writeConcern	理由
订单创建	`majority` + journal	主从切换时绝不能丢单
库存扣减	`majority`	丢扣减记录不可忍
行为埋点	`w: 1`	丢几条日志无所谓，别拖累写入
购物车	`majority`	用户加购后刷新没了，投诉就来了

readConcern 同理：读「已提交到多数派」的数据用 ReadConcern.MAJORITY，避免读到主从切换后被回滚的数据。钱相关的读，一律 majority；展示类的读，local 即可。

踩坑故事 #4（丢单惊魂夜）：上线初期订单写入用默认 w: 1。某天主节点宕机选主，新主上没有最后 8 秒的 23 笔订单——用户付了钱（支付回调已记录），订单却不存在，客服电话被打爆。复盘结论：支付回调链路和订单链路的 writeConcern 必须对齐 majority，宁慢勿丢。这 8 秒人工补单补了一整夜。

思考与感悟之三：分布式系统里「默认配置」几乎都是「性能优先、安全靠边」的，MongoDB 的 w:1、MySQL 的异步复制、Kafka 的 acks=1 皆如此。成熟的标志之一：每接一个中间件，先把默认一致性档位改成业务需要的档位，再开始写业务代码。

第七篇事务与分片：规模化之后的一致性难题

7.1 能不用事务就不用：原子操作的威力

MongoDB 单文档操作天然原子。电商防超卖，一条条件更新就够，根本不需要事务：

// demo03-deduct-stock：条件原子扣减，1000 并发抢 1 件也只有 1 个成功
import com.mongodb.client.MongoCollection;
import com.mongodb.client.model.Filters;
import com.mongodb.client.model.Updates;
import com.mongodb.client.result.UpdateResult;
import org.bson.Document;
import org.bson.types.ObjectId;

public class DeductStockDemo {

    public void deduct(MongoCollection<Document> skuStocks, ObjectId skuId, int qty) {
        UpdateResult r = skuStocks.updateOne(
                // 库存够不够，放进查询条件 —— 判断和修改合并成一次原子操作
                Filters.and(
                        Filters.eq("_id", skuId),
                        Filters.gte("stock", qty)),
                Updates.combine(
                        Updates.inc("stock", -qty),
                        Updates.inc("sold", qty),
                        Updates.currentDate("updatedAt"))
        );
        if (r.getModifiedCount() == 0) {
            throw new IllegalStateException("库存不足"); // 没抢到，上层返回售罄
        }
    }
}

精髓：判断（stock >= qty）和修改（$inc）合并成一次原子操作，不存在「查出来够、扣的时候不够」的竞态。这比任何分布式锁都干净。

7.2 真正需要事务的场景

跨集合的一致性——下单要同时「扣库存 + 建订单 + 核销券」，三个动作三个集合，这时上多文档事务（4.0+，需副本集）：

// demo04-place-order-tx：多文档事务下单
import com.mongodb.ClientSessionOptions;
import com.mongodb.ReadConcern;
import com.mongodb.TransactionOptions;
import com.mongodb.WriteConcern;
import com.mongodb.client.ClientSession;
import com.mongodb.client.MongoClient;
import org.bson.Document;

public class PlaceOrderTxDemo {

    public void placeOrder(MongoClient client, Document orderDoc, ObjectId skuId, int qty, ObjectId couponId) {
        TransactionOptions txnOptions = TransactionOptions.builder()
                .readConcern(ReadConcern.SNAPSHOT)
                .writeConcern(WriteConcern.MAJORITY)
                .build();

        try (ClientSession session = client.startSession(
                ClientSessionOptions.builder().defaultTransactionOptions(txnOptions).build())) {

            session.withTransaction(() -> {
                var db = client.getDatabase("shop");

                // 1. 条件原子扣库存
                var r = db.getCollection("sku_stocks").updateOne(session,
                        com.mongodb.client.model.Filters.and(
                                com.mongodb.client.model.Filters.eq("_id", skuId),
                                com.mongodb.client.model.Filters.gte("stock", qty)),
                        com.mongodb.client.model.Updates.inc("stock", -qty));
                if (r.getModifiedCount() == 0) {
                    throw new IllegalStateException("库存不足，触发回滚");
                }

                // 2. 插入订单（含商品快照）
                db.getCollection("orders").insertOne(session, orderDoc);

                // 3. 核销优惠券
                db.getCollection("coupons").updateOne(session,
                        com.mongodb.client.model.Filters.and(
                                com.mongodb.client.model.Filters.eq("_id", couponId),
                                com.mongodb.client.model.Filters.eq("used", false)),
                        com.mongodb.client.model.Updates.set("used", true));

                return null;
            });
            // 任何一步抛异常，前面所有操作自动回滚
        }
    }
}

sequenceDiagram
    participant A as 下单服务
    participant M as MongoDB 副本集
    A->>M: withTransaction 开启
    A->>M: 1. 条件原子扣库存
    alt 库存不足
        M-->>A: modifiedCount = 0
        A->>M: 自动 abortTransaction<br/>三步全部回滚
        A-->>A: 返回售罄
    else 成功
        A->>M: 2. 插入订单(含快照)
        A->>M: 3. 核销优惠券
        A->>M: commit (w:majority)
        M-->>A: 提交成功
    end

踩坑故事 #5（事务的 QPS 税）：压测发现全事务下单链路 QPS 比「原子扣减 + 消息队列异步落单」低约 40%，且长事务会压住 WiredTiger 的旧版本清理（第二篇的坑）。大促链路的最终方案：核心扣减用单文档原子操作（快），订单与券的一致性用 MQ + 定时对账任务兜底（最终一致）。事务留给后台管理类低频强一致操作。教训：事务是保险丝，不是日常用电。

7.3 分片：单副本集扛不住之后

数据量单副本集放不下（经验值：单集合过 2TB 或写入 QPS 过万再考虑），才上分片：

flowchart TD
    APP["应用"] --> MONGOS["mongos 路由层"]
    MONGOS --> S1["Shard 1<br/>副本集"]
    MONGOS --> S2["Shard 2<br/>副本集"]
    MONGOS --> S3["Shard 3<br/>副本集"]
    MONGOS -.-> CFG["Config Server<br/>元数据副本集"]
    S1 -.->|"均衡器<br/>chunk 迁移"| S2

分片键（shard key）是 Mongo 最「一选定终身」的决策，选错无法修改（5.0 之前）。三条铁律：

高基数：用 status（只有几个枚举值）做分片键，所有数据挤在少数 chunk 里，分了个寂寞。
避免单调递增：用 createdAt 或自增 ObjectId 做分片键，所有新写入都打到最后一个分片——热点分片被写爆，其他分片围观。日志类业务要么 hash 分片键，要么接受这个形态。
匹配查询模式：订单按 userId hash 分片，「查我的订单」路由到单分片，飞快；「全平台订单报表」变成广播查询（scatter-gather），慢——所以报表本来就不该打在分片集群上，该走数仓。

踩坑故事 #6（jumbo chunk 卡死均衡）：早期一张集合按 categoryId 分片，头部类目一个 chunk 涨到 500MB 还无法拆分（jumbo chunk），均衡器彻底停摆，分片间数据倾斜到 3:1。最后导出数据重建集合换 hash 分片键才解决，停机 4 小时。分片键评审必须过架构组，这是红线第三条。

第八篇运维底线与 AI 时代：把系统做稳，把代码写少

8.1 生产运维的最低纲领

不展开讲 DBA 手册，只列必须亲自盯的五件事：

flowchart TD
    M["监控<br/>slow query / cache 压力 / oplog 窗口 / 复制延迟"] --> A["告警<br/>复制延迟 > 30s 即报警<br/>别等追不上才发现"]
    B["备份<br/> mongodump 逻辑备份<br/>+ 快照物理备份<br/>恢复演练每季度一次"] --> A
    C["慢查询<br/>profiler 只开采样<br/>每周过 top 慢查询"] --> A
    D["容量<br/>磁盘水位 70% 预警<br/>oplog 大小按写入峰值调"] --> A
    E["权限<br/>最小化授权 禁止裸奔<br/>生产禁 dropDatabase"] --> A

踩坑故事 #7（恢复演练救了我们一命）：团队坚持每季度做一次「备份恢复演练」，被吐槽形式主义。直到有人误删集合（drop() 当 deleteMany() 用了），靠备份 40 分钟恢复，业务无损。没演练过的备份等于没有备份——这句话值一个 P0 事故。

8.2 AI 时代：如何少写代码把系统做稳

写这篇博客的 2021 年，GitHub Copilot 刚发布。站在工程视角，做几个判断，留给未来验证：

AI 会吃掉「模式化代码」，吃不掉「模式化决策」。 CRUD、Schema 定义、聚合管道骨架、连接池配置——这些高度模式化的代码 AI 生成得又快又准（你甚至可以现在就试试让 Copilot 补全上面的 DeductStockDemo，完成度惊人）。但「嵌入还是引用」「分片键选什么」「writeConcern 定哪档」——这些依赖业务流量预测的决策，AI 给不出答案。核心竞争力从「会写」转向「会判断」。
「少写代码」的正确姿势是把决策做在数据层。 用快照冗余消灭 $lookup，用 TTL 索引消灭清理脚本，用原子扣减消灭分布式锁，用条件更新消灭事务——本篇通篇的「少写代码」讲的都是这个：好的建模让代码自然变少。AI 是放大器，放大的既可以是好设计，也可以是坏设计。
一个人撑起一个 App 的门槛在崩塌。 MongoDB Atlas（托管副本集/分片）+ Serverless 函数 + AI 生成 CRUD 层，一个小电商的服务端几天就能搭起来。2021 年这还只是苗头，我确信它会成常态。但反过来：门槛越低，线上事故越便宜——不懂 writeConcern 的人也能上线了，丢单的事故只会更多。AI 时代的工程教育，重点应该从「怎么实现」转向「哪里会炸」。
AI 生成代码的第一评审项是资源语义。 连接谁关、事务多长、批量多大、一致性哪档——AI 生成的代码功能往往是对的，资源语义常常是错的（比如给你 w: 1 的默认写入）。Code Review 的重心会整体迁移到这四个问题上。

思考与感悟之四（收尾）：工程的本质，是「替业务把不确定性挡在系统之外」。MongoDB 给了你自由度，也把范式的保护伞收走了——锁粒度、一致性档位、分片拓扑，每一个都要自己选。AI 会帮你把代码写得越来越快，但「选什么」的责任永远在人身上。这既是这份工作的辛苦之处，也是它的护城河。

附录：Demo 与检查清单

Demo	类/片段	覆盖知识点
建索引	`IndexDemo`	ESR 复合索引、部分索引、TTL 索引
热销榜聚合	`TopSalesDemo`	`$match` 前置、`$unwind`/`$group`、`allowDiskUse`
写入档位	`demo02-write-concern`	`w:1` / `majority` / journal 的取舍
原子扣库存	`DeductStockDemo`	条件原子更新防超卖
事务下单	`PlaceOrderTxDemo`	多文档事务、回滚、事务读写关注级别

MongoDB 生产红线（本文沉淀，可直接抄进团队规范）：

生产环境永远不开不设限的大批量更新，批量操作必拆批 + 让出窗口。
凡带 sort 的查询，必须 explain 验证走索引排序。
分片键评审必须过架构组；能用副本集解决的绝不上分片。
钱相关的读写一律 majority；默认配置永远不可信。
备份必须每季度做恢复演练，没演练过的备份等于没有备份。

文中代码基于 MongoDB 5.0 + 官方 Java 同步驱动 4.3 实测可编译运行。如果你正站在「要不要接 MongoDB」的门口，建议按八篇顺序在本地副本集上把每个坑亲手复现一遍——看别人踩坑是故事，自己踩一遍才是经验。

AI 编程 on 方糖猫Blog

高 bug 率的人该怎么对待：一场项目争论背后的对事、对人与系统

高 bug 率的人该怎么对待：一场项目争论背后的对事、对人与系统

一、第一步：把「高 bug 率」变成数据

二、第二步：逐条验证，五种说法归并成四种病根

三、第三步：病根怎么找全——三层归因方法论

第一把刀：引入链分解——按 bug 的生命周期切

第二把刀：鱼骨图 6M——按要素维度切

第三把刀：控制变量——把相关性变成归因

四、第四步：行业里的成熟方法论与工具地图

归因层：ODC（正交缺陷分类）

度量层：DORA 指标与缺陷逃逸率

防线层：shift-left 与工具链

机制层：错误预算与安灯——「宽猛相济」的工程制度

五、第五步：轮到「人」之后——Just Culture 三分法

六、更高处的统一：系辞与 Dalio

七、落地：一棵判断树

八、收尾

把 Claude Code 用成工程杠杆：落地心得

把 Claude Code 用成工程杠杆：落地心得

一、先思考，再输入

二、架构描述决定代码质量

三、CLAUDE.md：给 AI 的入职培训

1. 保持简短

2. 只写项目特有信息

3. 写"为什么"，不只是"做什么"

4. 持续更新

四、上下文窗口不是越用越好

五、提示词是沟通，不是咒语

六、模型路由：让合适的模型做合适的事

七、MCP、Hooks、Slash 命令与 Skills

1. MCP、Hooks 和 Slash 命令

2. Skills：把个人经验变成团队能力

3. 有哪些值得尝试的 Skill？

4. 怎么创建自己的 Skill？

5. Skill、CLAUDE.md、Hooks 的分工

八、当 Claude 卡住时，换策略

九、构建系统，而不是一次性工具

十、写给老工程师的话

总结

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

一、一句话讲清楚 Claude Code

二、最核心的 30 行代码

人话解释

三、20 节课都在讲什么？一张总图看懂

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

s02 Tool Use：从一把螺丝刀到整套工具箱

s03 Permission：先问能不能做，再让它做

s04 Hooks：在循环边上挂“挂钩”

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

s06 Subagent：雇一个小助手

s07 Skill Loading：需要哪本字典，就翻哪本

s08 Context Compact：脑子塞不下时怎么办？

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

s10 System Prompt：提示词不是写死的

s11 Error Recovery：做错事能重来

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

s13 Background Tasks：慢活放后台

s14 Cron Scheduler：定时任务

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

s16 Team Protocols：队友之间要讲规矩

s17 Autonomous Agents：AI 自己会找活干

s18 Worktree Isolation：各干各的，不打架

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

s20 Comprehensive Agent：把所有东西拼起来

十、给新手的 5 个开发小技巧

1. 用“查表”代替一堆 if/else

2. 修改列表要小心

3. 用 **kwargs 接受任意参数

4. 守护线程做后台任务

5. JSONL 比 JSON 更适合追加写入

十一、总结

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

3. 用 `**kwargs` 接受任意参数

第一篇环境搭建：比 Android 友好，但坑藏在「账号」里

第二篇语法基础：四个文件就是一个页面

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

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

第六篇平台能力：登录、订阅消息、分享、支付与分包

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

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

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

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

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

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