KotlinBenchmark —— 性能评测：以项目为准的教程

一句话：每节先讲清理论，再动手改项目；项目本身就是教材，不再有「理论文档 + 代码文档」两套。

三个目录，只有三个

目录	是什么	规矩
source/	初始项目 v0：一个普普通通的订单 CRUD（Ktor + H2），没有任何性能设施	只读，严禁修改。它是整套教程的地基
code/	每一节完成后的项目快照：code/00/01/、code/01/02/ …	第 N 节 = 拷贝上一节快照 → 改 → 存成自己的快照。快照一旦生成就不再回头改
docs/	教程正文：docs/<章>/<节>.md，一节一篇	一节 = 理论 + 实战（先解释理论，再改项目）

为什么这么放

• 你读到的每一行代码，都是那一刻真实存在的项目：code/01/05/ 就是第 1.5 节结束时的完整工程， 单独打开就能构建、运行，不会混进后面章节的代码。
• source/ 冻结 → 任何时候都能从零重来，也能看出「整套教程一共改了什么」。
• 后面小节只往自己的新快照里加东西：旧快照不会变，你读完的部分不会再被动过。

怎么跑任意一个快照

每个快照都是自包含的单模块 Gradle 项目（项目根就是模块根，没有 app/ 这层子模块）。

# 构建 + 起服务（v0 之后的小节，端口/数据量按那一节的说明给）
cd code/00/01
./gradlew installDist
SEED_ORDERS=200 PORT=8080 nohup build/install/shop/bin/shop > /tmp/shop.out 2>&1 &

# 冒烟
curl -s localhost:8080/health

# 收尾（一定要做：8080 端口不留后台进程）
pkill -f shop.ApplicationKt
lsof -nP -iTCP:8080 -sTCP:LISTEN      # 期望：没有输出

构建时建议用隔离的 Gradle 目录，别写你的 ~/.gradle：

GRADLE_USER_HOME=/tmp/gh ./gradlew installDist

实验环境（所有数字的出处）

全书 68 节的数字都来自同一台机器、同一套版本：

项	值
机器	Apple M5（Mac17,3），10 逻辑核 = 4 性能核 + 6 能效核，32 GB 内存
系统	macOS 27.0（build 26A428），arm64
JDK	Oracle JDK 21.0.12（默认人机工程：最大堆 8 GB、G1）
工具链	Kotlin 2.4.10 / Gradle 9.6.0 / Ktor 3.2.2 / H2 2.3.232 / micrometer 1.14.5 / logback 1.5.18
数据量	SEED_ORDERS=20000（约 2 万订单 / 4.98 万明细），数据量专题除外
负载	项目自带的 LoadGen（本机没有 k6）
端口	第 05 章用 8080，第 69 章改 18080（避开用户自己的容器，服务端行为与端口无关）
时间窗	2026-09-22 ~ 2026-09-24

完整清单（含这台机器测不到的项、以及复现时该怎么读差异）见 docs/ENVIRONMENT.md。

每节的固定结构

1. 一句话结论 —— 这节回答什么问题；
2. 理论 —— 概念、类比、为什么，以及方法的边界；
3. 实战 —— 从上一节快照拷出本节快照，逐个文件给出改动（新增文件给全文，修改文件给改动前后对比）；
4. 怎么验证 —— 可以直接复制的命令；
5. 实测输出 —— 真实跑出来的数字（不是「预期」），并说清它在什么机器、什么参数下得到；
6. 小结与自测 —— 折叠答案。

进度

章	节数	快照	正文目录
第 0 章 导论	10 / 10 ✅	code/00/01 … code/00/10	docs/00-introduction/
第 1 章 指标与 SLO	9 / 9 ✅	code/01/01 … code/01/09	docs/01-metrics-and-slo/
第 2 章 JVM 性能基础	9 / 9 ✅	code/02/01 … code/02/09	docs/02-jvm-basics/
第 3 章 测试金字塔	8 / 8 ✅	code/03/01 … code/03/08	docs/03-test-pyramid/
第 4 章 工具链	9 / 9 ✅	code/04/01 … code/04/09	docs/04-toolchain/
第 5 章 实验设计与方法论	9 / 9 ✅	code/05/01 … code/05/09	docs/05-experiment-design/
第 6 章 数据库与存储	4 / 4 ✅	code/06/01 … code/06/04	docs/06-database-and-storage/
第 7 章 应用层	4 / 4 ✅	code/07/01 … code/07/04	docs/07-application-layer/
第 8 章 门禁与交付	3 / 3 ✅	code/08/01 … code/08/03	docs/08-gates-and-delivery/
第 9 章 复盘与容量	3 / 3 ✅	code/09/01 … code/09/03	docs/09-review-and-capacity/

每完成一小节就单独提交一次 git（一小节一个 commit）；快照一旦生成不再回头改。