应用骨架:从一行路由到一个可维护的最小全栈Copy Anchor Link

这一章讲一件事:把一个玩具 API 养成「像一个正经项目」的最小全栈,要补哪些课。 四段:先讲代码怎么摆(八种组织方案);再把 API 从头长到尾——路由、JSON、数据库、 错误格式、模块化重构(主线例子);然后临时拉一个 JS 前端顶上,讲清前后端联调时 必然撞见的同源策略和 CORS;最后补上两个工业界地基——数据库迁移和持续集成。 读完你会有一个能给别人看的项目骨架,以及「为什么这样拆文件」的完整理由。

1. 这一章在全书链条里的位置Copy Anchor Link

第 2 章选了型(客户端-服务器 + Axum + SQLite + 日后再上 ORM)。 第 3 章兑现这个选型,但刻意选「最小」路线:先把一个只有两个端点的 API 写对、 写整洁、写上 CI——骨架结实了,第 4 章才往上面盖业务。 书里给这一路定了个调子,是著名的软件工程三步:

Make it work. Make it right. Make it fast.¹

——先能跑,再做对,最后才求快。本章全部力气花在第二步。

2. 顶层全景Copy Anchor Link

  代码组织:八种切法 + C4 模型(先想清楚文件怎么摆)
    ↓
  主线例子 minimalist-api 的生长史
    两条硬编码路由 → JSON 序列化 → 接 SQLite(SQLx)→ 统一错误格式 → 按职责拆文件
    ↓
  临时前端:Vite/SolidJS 四件套 + 同源策略与 CORS + 双 dev server 并行
    ↓
  工业界地基:数据库迁移(可复现)+ 持续集成(Rust/JS/安全审计三条流水线)

  图说:先摆对文件,再长对代码,再接上前端,最后把「可复现」和「自动化」钉死。

3. 代码组织:八种切法,没有唯一答案Copy Anchor Link

解决什么问题: 文件和文件夹怎么摆,就是代码组织;它是架构的最后一个视角(第 2 章)。 书里摆了八种方案,每种一句话说清「按什么切」²:

按模块切的那一节有一个重要警告: 模块之间如果共用代码,要把共用代码搬进 独立的共享库,绝不允许模块 A 伸手进模块 B 里拿——否则模块性就是假的; 模块长大以后可以整体挪成独立项目,但前提是低耦合保持住了³。

C4 模型(Simon Brown 提出): 给上面所有切法一个统一的变焦镜头—— 四个 C 是四种放大级别,每个级别的「构件块」可以包含下一级的构件块⁴:

书里给的总提醒: 没有「终极目录结构」;只用「刚好够把文件区分开」的组织量—— 提前把所有可能目录都建好,只会收获一堆被版本控制无视的空文件夹⁵。 结构跟不上代码生长时,用重构把它扳回来,关键是避免重复和紧耦合⁶。

4. 主线例子:minimalist-api 的生长史Copy Anchor Link

这一节是本章的承重墙:一个真实项目从零长到「可维护」的每一步,都在这儿走一遍。 每一步都有原书给的命令、代码或输出。

第 ① 步:骨架——两条路由Copy Anchor Link

cargo new minimalist-api,依赖照旧是 axum + tokio。 先写能跑通的最小版:/tickets 挂两个 handler,GET 返回 "GET Tickets", POST 返回 "POST Tickets"⁷。

  curl 127.0.0.1:8000/tickets         → GET Tickets
  curl 127.0.0.1:8000/tickets --data  → POST Tickets
                                                (--data 让 curl 发 POST)

  图说:路由表 "/" + get/post(handler) 是 Axum 的最小骨架,第 1 章见过,这里换了真资源名。

第 ② 步:接 JSON——Serde 登场Copy Anchor Link

定义数据模型:Ticket { id: i64, title: String }, 给它挂上 #[derive(Serialize, Deserialize)]——这两个 trait 来自 Serde, 效果是「这个结构体能变成 JSON、也能从 JSON 变回来」。

• GET 改成返回 response::Json(Ticket { id: 1, title: "New Ticket" }): 响应体会自动序列化成 JSON,Content-Type 头自动设为 application/json⁸;
• POST 用提取器接输入:async fn post_tickets(Json(ticket): Json<Ticket>)—— Axum 看到 handler 参数里有 Json<Ticket>,会帮你把请求体反序列化好递进来⁹。

第一次撞墙(故意演示的): 不带 Content-Type: application/json 头发请求, 会得到一条错误:Expected request with 'Content-Type: application/json'—— 提取器在 handler 跑起来之前就把关了¹⁰。正确的 curl:

  curl --header "Content-Type: application/json" \
       --data '{"id":1, "title":"Hello from the other side"}' \
       127.0.0.1:8000/tickets
  → {"id":1,"title":"Hello from the other side"}

第 ③ 步:开发体验——格式化和热重载Copy Anchor Link

书里先补两件「舒服」的事,再动数据库:

• 保存即格式化: VS Code 设置里给 Rust 指定 editor.formatOnSave: true 并默认用 rust-analyzer 当 formatter;再把 rust-analyzer.check.command 从 check 改成 clippy——保存文件时自动排版 + 自动 lint¹¹;
• 热重载: cargo install cargo-watch 之后, cargo watch -w src -x run——盯 src 目录,一变就重编译重跑; 加 -c 每次先清屏¹²。这是 Rust 世界对「别的语言的热重载」的标准答案。

第 ④ 步:接数据库——SQLx、连接池、.envCopy Anchor Link

目标:把收到的工单真的存下来、随时取得出。 端点定型为两个: GET /tickets/:id(取一个)和 POST /tickets(存一个)¹³。

依赖加一行:

sqlx = { version = "0.6", features = ["runtime-tokio-rustls", "sqlite", "macros"] }

三个 feature 逐个解释:runtime-tokio-rustls——用 Tokio 当异步运行时、 用 rustls 加密连接(「能不离开 Rust 就不离开」);sqlite——驱动选 SQLite, 零配置,而且「后面容易换」;macros——不是必需,但让代码更好读¹⁴。

连接池(connection pool): 不建单条连接,直接建池:

let pool = SqlitePoolOptions::new()
    .max_connections(5)                 // 池里最多养 5 条连接
    .connect(&database_url)
    .await
    .unwrap();                          // 连不上库,程序就该当场死——fail fast

书里给了理由:数据库连接不该成为瓶颈;连接是异步建立的; 连不上就没有启动应用的意义,所以这里 unwrap(让程序 panic)是合理的¹⁵。

配置从哪来: 加 dotenvy crate,从环境变量(操作系统级的键值配置)或 .env 文件读 DATABASE_URL。 用 anyhow 的 .context("DATABASE_URL must be set") 给 panic 补上上下文—— 裸的 dotenvy::var 报错时不会告诉你缺的是哪个变量¹⁶。

池子怎么进 handler: 路由上挂一层 .layer(Extension(pool))—— 之后每个 handler 都能把 Extension<SqlitePool> 当参数要,框架自动注入¹⁷。

第 ⑤ 步:写查询——宏检查的 SQLCopy Anchor Link

取工单(handler 签名进化): async fn get_tickets(pool: Extension<SqlitePool>, Path(id): Path<i64>) -> impl IntoResponse

• Path(id): Path<i64>:路径提取器。/tickets/:id 里的那段会被解析成 i64;解析不了请求直接被拒——「没有 id,就没有票」¹⁸;
• 查询本身:

let result = sqlx::query_as!(Ticket, "SELECT * FROM tickets WHERE id = $1", id)
    .fetch_one(&*pool)
    .await;

query_as! 是 SQLx 的宏:它在编译期把你的 SQL 拿去跟真实数据库核对 ——表存在吗?列名对吗?类型对得上吗?核对不过,编译就报错。 这就是第 4 节「六军规」里 SQLx 那条「编译期检查查询、无 DSL 附加层」的含义¹⁹。

错误要统一成 JSON。 查不到(id 不存在)时,第一版直接返回 (StatusCode::NOT_FOUND, "Not Found")——纯文本,客户端会懵; 书里升级成带 Content-Type: application/json 的 JSON 错误体:

struct JsonError { code: String, message: String }
// 响应:({"code":"404 Not Found","message":"no rows returned by a query ..."},)

实测:curl 127.0.0.1:8000/tickets/4 返回

  {"code":"404 Not Found","message":"no rows returned by a query that expected to return at least one row"}

且 -v 能看到 content-type: application/json 确实设对了²⁰。

写(insert): sqlx::query!("INSERT INTO tickets (title) VALUES ($1)", ticket.title), 成功后结果里有 last_insert_rowid()——数据库自增出来的真 id, 把它包进 Ticket 返回给客户端²¹。实测细节值得记住:

  发:{"id":0, "title":"Hello from the other side"}
  收:{"id":1,"title":"Hello from the other side"}
  ——发 0 收 1 是正常的:程序故意忽略客户端给的 id,数据库自增说了算。

  图说:幂等地「以服务器为准」——客户端撒谎不影响数据。

第 ⑥ 步:错误格式的最后一课——422 与统一错误函数Copy Anchor Link

再试一个边界:POST 一个 {}(缺字段)。Axum 默认会回 422 Unprocessable Entity 加一段纯文本:Failed to deserialize the JSON body into the target type: missing field 'id'... ——状态码对,格式又不对了²²。

Axum 允许把提取器包成 Result<Json<Ticket>, JsonRejection> 自己处理; 但「好几个提取器组合、还要统一响应」时,匹配逻辑会迅速复杂。 书里的折中:接受包 Result,再抽一个统一错误函数:

fn uniform_error(code: StatusCode, message: String) -> impl IntoResponse {
    (code,
     [(header::CONTENT_TYPE, HeaderValue::from_static("application/json"))],
     json!(JsonError { code: code.to_string(), message }).to_string())
}

定制提取器(把每个内置提取器都包一层、保证任何错误都统一响应)被点名是 「advanced option」,现在做就是 overkill(过度设计)——先记住这个名字,第 4 章还会遇到 「early return of errors」这个更顺手的方案²³。

第 ⑦ 步:按职责拆文件——bootstrap 原则Copy Anchor Link

现在代码能跑了,但主文件臃肿、错误处理重复。书里的重构原则: 文件要 thin(薄),最优是一个文件一个目的;main 文件的存在理由只有一个: 启动应用。所以划一条线:「启动应用所需的一切」留在 main; 其余一切,搬出去²⁴。落地成三个文件:

  src/
  ├── main.rs        ← bootstrap:读配置、建连接池、调 api::serve(pool)
  ├── api.rs         ← serve():起服务器;router():并路由、挂 layer
  │   ├── error.rs   ← JsonError + to_uniform_response()
  │   └── tickets.rs ← Ticket 结构体 + 两个 handler + 本资源路由表

  图说:错误、启动、资源各归其位;新增资源 = api/ 下新增一个文件 + 一行 merge。

api.rs 里的 router() 干一件事:Router::new().merge(tickets::router()).layer(Extension(db)) ——资源各自带路由表,顶层只负责合并;以后加 users,就是 api/users.rs + merge(users::router())²⁵。main 瘦成了 18 行。

最后留了一个「想过但不做」的决定: 把 API 组件和 axum 解耦(抽象掉框架依赖、 以便将来换框架)。书里的理由很实在:现实中没人换写好了应用的框架,所以不值得²⁶。 ——「可替换性」也是一种成本,按六军规的「合目的」一项,这笔不买。

第 ⑧ 步:数据库本体Copy Anchor Link

touch dev.sqlite 建空文件,SQLite Browser 打开,执行:

CREATE TABLE "tickets" (
  "id"    INTEGER NOT NULL UNIQUE,
  "title" TEXT    NOT NULL,
  PRIMARY KEY("id" AUTOINCREMENT)
)

AUTOINCREMENT:id 从 1 起自动递增——这就是第 ⑤ 步「发 0 收 1」的来源²⁷。

书里特意加了注释:这不是建表的业界标准做法。 手动操作缺两个性质: 可追溯性(traceability)和可复现性(reproducibility)——下一个开发者怎么知道 该有哪些表?正确答案是迁移,马上就到²⁸。

5. 临时前端:一次故意的「离开 Rust」Copy Anchor Link

解决什么问题: API 已经能用 curl 调了,但「别人得自己写客户端才能看内容」。 书里做了一个刻意的安排:先用一版 JavaScript 前端顶上(因为它成熟), 正式 Rust 前端(Yew)留到第 4 章²⁹。

技术栈四件套:Vite(极速打包/热更新)、Tailwind CSS(utility-first 的 CSS 写法)、 daisyUI(Tailwind 上的预置组件和主题)、SolidJS(类 React 体验、 但没有状态层层传递的麻烦)³⁰。不加 TypeScript,省去导出类型的麻烦³¹。

5.1 同源策略与 CORS:前后端联调的第一道墙Copy Anchor Link

先解释词。 浏览器有一条安全规矩叫同源策略(same-origin policy): 网页 A 里的脚本,不能读网页 B 的数据——防的是「你开着银行页面时, 恶意网站冒你的名义发请求偷数据」。「源(origin)」= 协议 + 域名 + 端口, 任何一个不同就算跨源³²。

问题来了:开发时后端在 8000 端口,前端 Vite 自己的 dev server 在 5173—— 不同端口 = 不同源,浏览器会把前端的请求拦下³³。

解法:CORS(Cross-Origin Resource Sharing,跨源资源共享)。 思路翻转:同源策略默认全拒;服务器可以在响应里加 access-control-allow-origin 头显式声明「我接受谁来」。 Axum 有现成中间件:

let cors = CorsLayer::new()
    .allow_methods([Method::GET, Method::POST])
    .allow_headers(Any)
    .allow_origin(Any);          // 开发期:接受任何来源(通配)
// ...
Router::new().merge(tickets::router())
    .layer(Extension(db))
    .layer(cors)

中间件的意思是:它拦下所有出站的响应,统一补上那个头³⁴。 生产环境的提醒(书里注释): 上线后不走 Vite dev server, 但前后端仍可能在不同域名——那时要双向配置,让两头知道对方的地址³⁵。

5.2 两个 dev server,一键并起Copy Anchor Link

前后端热更新机制不同(各自热各自的,别互相掺和), 但希望一条命令都拉起来。书里选了「后端挂进前端的构建脚本」, 理由:Node.js 的构建支持更成熟,而 Cargo 侧得自己写构建代码; concurrently 这个工具让两条任务并行跑、共享输出³⁶:

"dev": "concurrently -k \"cargo -Z unstable-options -C ../ watch -c -w src -x run\" \"vite\""

一个时代的痕迹值得会心一笑:当时 Cargo 不支持切目录,得开 nightly 的 unstable options(-Z unstable-options -C ../)³⁷。之后 npm run dev 一条命令, 8000 和 5173 一起活。

前端发请求用浏览器自带的 Fetch API(书里也提了 Angular 的 HttpClient 可选): GET 要带 Accept: application/json 头,POST 要带 Content-Type: application/json 头和 JSON 字符串正文³⁸。回来的响应做 duck typing(鸭子类型:看它「有没有 id 和 title 属性」来判断是不是 Ticket)³⁹。

5.3 为什么把前端塞进 Rust 项目的子目录Copy Anchor Link

frontend/ 放在 Rust 项目根下的一个子文件夹,不共享项目根—— 不想让 JS 的配置文件污染 Rust 项目根;分离清楚,将来想把前端项目拆出去也容易⁴⁰。

判断(我们的,不是书里的): 「临时 JS 前端」这个安排是全书的教学法点睛之笔—— 它先在读者熟悉的世界里把前后端协作的通用难题(同源、CORS、联调)讲完, 等第 4 章换 Yew 时,读者只需要学「新工具」而不是同时学「新问题」。 如果错,会错在: 对已经熟 Yew 或只想全 Rust 的读者,这一章显得绕路; 但对目标读者(后端背景的 Rust 学习者),这是降低坡度的正解。

6. 工业界地基之一:数据库迁移Copy Anchor Link

解决什么问题: 手动建表把「数据库该长什么样」变成了藏在某个人脑子里的隐性知识。 迁移(migration)= 受管理的 SQL 脚本,跟着项目走,任何人任何环境都能一键追平⁴¹。

SQLx 的 CLI 工具(cargo install sqlx-cli)给了一套动词:

  sqlx database drop        # 删掉旧库(会要确认)
  sqlx database create      # 按 DATABASE_URL 建新库
  sqlx migrate add tickets  # 建 migrations/ 目录 + 一个带时间戳的 tickets.sql
  sqlx migrate run          # 立即执行未跑过的迁移

  图说:每个迁移文件一份 SQL;数据库记着自己跑到第几个,只补差的部分。

迁移脚本的内容就是之前那条 CREATE TABLE。然后把它挂进 bootstrap: main 里建池之后加一行 sqlx::migrate!().run(&pool).await.unwrap();—— 应用启动时自动补表,新同事的机器上「clone → 起库 → 跑应用」三步完事⁴²。

这引出 SQLx 的一个鸡生蛋问题(书里实打实演示的): SQLx 的宏要在编译期核对 SQL,可新机器上数据库还没建好、迁移还没跑, 核对什么?解法:offline 模式。Cargo.toml 给 SQLx 开 offline feature, 在开发机上跑一次 cargo sqlx prepare -- --workspace——它生成一个 sqlx-data.json (描述 schema 的元数据),提交进版本库,再给 .env 加 SQLX_OFFLINE=true。 之后任何机器编译时,宏拿这份 JSON 核对,不需要活的库⁴³。

.env 的去留也在这里交代: 目前全项目共用一个 .env 因为没敏感配置; 将来环境一多(各连各的库),就得改成「提交 .env.sample、各人自配」的规矩⁴⁴。

7. 工业界地基之二:持续集成(CI)Copy Anchor Link

解决什么问题: 多人共推一个仓库,每次推送都可能带进错误。 持续集成(CI)= 推送触发的一串自动化检查,书里列了它可能包括的活: 构建、依赖检查、代码质量分析、lint、格式化、测试、覆盖率、文档生成⁴⁵。

配置载体是仓库里的 YAML 工作流文件(.github/workflows/,push 和 pull_request 触发)。 三条流水线:

细节里藏着两个工程常识:npm ci 是「按 lock 文件干净重装」, 和 npm install 不同;矩阵构建用一个参数表把「多版本兼容」跑成三次独立构建⁴⁶。

收尾:README 徽章(badge)。 三条流水线各配一张 SVG 徽章, 状态随流水线结果自动更新——绿不绿,一眼看见⁴⁷。

判断(我们的,不是书里的): 注意书里 CI 的先例:「我们一行测试都没写, 但 Cargo 宽容,pipeline 不会红」——它把 CI 架在「还没有测试」的项目上, 因为 CI 的价值一半在「以后写的每个测试自动有人跑」。测试债是第 6 章才还的内容, 但 CI 的地基第 3 章就打——这个顺序在真实项目里也是对的。 如果错,会错在: 「没有测试的 CI」容易给人虚假安全感;如果有人因此推迟写测试, 绿灯就是自欺欺人。书的第 6 章确实回头补了这一课。

8. 作者的判断与证据(分开标)Copy Anchor Link

有出处的: fail-fast(连接失败即 panic)与 anyhow 的用法来自原书代码与注释¹⁵¹⁶; CORS 与同源策略是 Web 平台标准行为³²³⁴;迁移与 CI 的命令序列是原书实操记录⁴¹⁴⁵。

作者自己的评估:

• 「先 JS 前端后 Yew」的教学安排(见 5.3 判断块);
• 「框架解耦层不值得做」是基于经验的工程判断²⁶;
• 八种代码组织方案「没有终极结构」的结论⁵。

9. 边界与局限Copy Anchor Link

• 版本快照再提醒: sqlx 0.6、axum 0.6、-Z unstable-options -C 那个 nightly 技巧 都是写书时的状态;新版 Cargo 已支持 --manifest-path 等更稳的替代。
• SQLite 是教学选择不是生产选择: 并发写、多机部署都会撞墙——第 4 章就会迁走。
• CI 深度有限: 只到「三条流水线跑起来」,覆盖率门禁、部署流水线没有展开(第 9 章才碰部署)。
• 错误处理还只是过渡方案: 统一错误函数 + 包 Result 的提取器, 第 4 章会换成更地道的「? 早返回」。

10. 可带走的Copy Anchor Link

主线例子一行走完: cargo new minimalist-api → 两条硬编码路由 → Ticket + Serde JSON → SQLx 连接池(max_connections(5))挂 Extension → query_as! 编译期核对 SQL → JsonError 统一错误(404/422)→ uniform_error 抽公共 → 拆成 api/{error, tickets}.rs + 瘦 main → SQLite 手动建表 → 迁移 + offline 元数据 → 三条 CI 流水线 + 徽章。

1. 代码组织没有终极答案,但有红线: 共享代码进共享库,模块间不许伸手; 目录组织量「刚好够区分文件」。
2. 提取器是 Axum 的关卡: Json<T>、Path<i64> 在 handler 前把关, 参数不对请求根本到不了你的代码。
3. SQLx 的宏在编译期核对 SQL; 代价是构建时要活库或 sqlx-data.json 离线元数据—— 后者必须进版本库。
4. 连接池 + fail fast: 池防瓶颈;启动必需的连接建不上,panic 是正确选择。
5. 统一错误格式是 API 的「普通话」: 状态码 + JSON 错误体;默认错误格式(纯文本) 一定要覆盖掉。
6. 前后端不同端口必撞同源策略; 开发期 CORS 通配、生产期双向白名单。
7. main 只干 bootstrap: 启动所需留下,其余搬走;「能跑」和「整洁」是两步,别合并。
8. 迁移买的是可复现性;CI 买的是每次推送都有人检查。 两个地基都比业务功能优先。

11. 原文地图Copy Anchor Link

4. 主线例子再走一遍:minimalist-api 的每一步状态(带真数字的复盘)Copy Anchor Link

把第 4 节的八步压缩成一张「状态快照表」——每一步旁边是当时的代码形态与 可观测的输入输出,读者照着能重建整个项目:⁴⁸

第 ⑥ 步的「发 0 收 1」为什么重要: 它演示了服务器是唯一的事实来源—— 客户端给的 id 被忽略,AUTOINCREMENT 从 1 开始发号。恶意或错误的客户端 输入不会污染数据;「幂等地以服务器为准」是写接口时的默认立场⁴⁹。

第 ⑤ 步的 fail-fast 再补一刀: 连接池建不上就 unwrap 崩掉—— 「连不上数据库,这个应用就没有启动的意义」。anyhow 的 .context() 只负责把「哪个变量缺失」写进遗言。第 4 章会把这个脾气改良成 ? 早返回, 但启动路径的 panic 立场不变⁵⁰。

5.4 前端一节的更多细节(CORS 之外的三件事)Copy Anchor Link

为什么开发期可以通配、生产期不行: 开发时前后端是两个 dev server (8000 对 5173),加 allow_origin(Any) 只为图省事;生产环境前后端 仍可能在不同域名(静态资源走带缓存的优化存储),「那时要两头配置, 让后端知道前端地址、前端知道后端地址」。CORS 的Wildcard 出不了开发机—— 这是常识,书里用一句注释带过,别当没看见⁵¹。

concurrently 那行的时代痕迹: cargo -Z unstable-options -C ../ watch… ——当时 stable Cargo 不支持切目录,被迫 nightly。今天这条已经可以用 --manifest-path 或 workspace 根跑,但**「前端脚本编排后端」的结构本身 仍成立**:构建生态 Node 更成熟,就让 Node 当总指挥⁵²。

Fetch 与 duck typing 的分工: GET 带 Accept: application/json (告诉服务器我要 JSON),POST 带 Content-Type: application/json + JSON.stringify(ticket)(告诉服务器我发的是 JSON);回来以后不建类、 只查形状——result.hasOwnProperty('id') && result.hasOwnProperty('title') 就当 Ticket。这个「鸭子判别」很土,但对 DTO 足够⁵³。

6.1 迁移一节的完整命令账本Copy Anchor Link

  # 一次性准备
  cargo install sqlx-cli                     # 装 CLI

  # 数据库级
  sqlx database drop                         # 删库(要确认)
  sqlx database create                       # 按 DATABASE_URL 建库

  # 迁移级
  sqlx migrate add tickets                   # 生成 migrations/<时间戳>_tickets.sql
  sqlx migrate run                           # 执行未跑过的迁移

  # 应用级(bootstrap 内)
  sqlx::migrate!().run(&pool).await.unwrap() # 启动时自动补表

  # 离线元数据(编译期核对的「死库替身」)
  cargo sqlx prepare -- --workspace          # 生成 sqlx-data.json
  SQLX_OFFLINE=true                          # .env 里告诉宏:别找活库,查 JSON

  图说:开发机上有活库 → prepare 出 JSON 入库;任何机器上 JSON 代库编译。

鸡生蛋问题的一次完整叙述: SQLx 的宏要在编译期核对 SQL;新同事的 机器上库还没建、迁移还没跑,核对什么?解法分两半:开发机上跑一次 prepare 生成 sqlx-data.json(它必须提交进版本库),再给 .env 加 SQLX_OFFLINE=true——宏切换数据源,用 JSON 描述的旧 schema 做编译期核对。 「clone 项目的人不用重做这套」——可复现性的最后一公里就是这么走的⁵⁴。

7.1 CI 三个工作流的逐项账Copy Anchor Link

Rust CI(三条 job 的分工哲学):

• test:checkout → toolchain → rust-cache → cargo test。 此时一行测试都没有,Cargo 宽容不报错——CI 的价值一半在 「以后写的每个测试自动有人跑」;
• fmt:cargo fmt --check——强制格式;不统一的排版直接红;
• clippy:cargo clippy -- -D warnings——把警告升格为错误; lint 债不过夜。

JS CI 的两个细节: npm ci(按 lock 干净重装,不是 npm install); matrix 策略对 Node 16.x/18.x/20.x 各跑一遍构建——「兼容矩阵」的 CI 形态⁵⁵。

Security Audit 的双触发: cron 0 0 * * *(每天零点,不管有没有改动)

• push 且 Cargo.toml/lock 变化时。cargo deny check advisories 扫的是 依赖树里已知漏洞——供应链安全的底线哨兵,和第 3 章的依赖检查是同族⁵⁶。

徽章为什么不是虚荣: 三张 SVG 随流水线结果自动变——README 的徽章 是「对外可见的健康度」,别人(和三个月后的你)第一眼就看到这套项目 还能不能 builds⁵⁷。

12. 原文地图补充Copy Anchor Link

3.1 八种代码组织方案的适用判据(什么时候选哪种)Copy Anchor Link

把第 3 节的清单补一张「选法判据」——原书没有明写判据,但每种方案的描述里 都藏着它的触发条件(我们的归纳,依据原文各节):⁵⁸

书里对最后一种的警告最重: 模块间共享代码必须进独立共享库, 「绝不允许模块 A 伸手进模块 B 拿代码」——伸手一次,模块边界就名存实亡; 而「保持低耦合,模块长大后才能整体搬走成独立项目」。⁵⁹

C4 的落地提醒: 四级变焦(System context → Container → Component → Code) 是画图的脚手架不是目录规范;文件系统怎么摆仍由上面的判决定, 「不同框架做法不同,没有固定命名法」。⁶⁰

5.5 前端目录与构建的三个决定(及其理由)Copy Anchor Link

1. frontend/ 放 Rust 项目根的子目录,不共享项目根—— 「不想让 JS 配置文件污染 Rust 项目根;分离清楚,将来拆出去也容易」;
2. 前端管后端一起起(concurrently)而不是反过来—— 「Node.js 的构建支持更成熟;Cargo 侧得自己写构建代码」;
3. 完整实现不进书、进仓库——「前端创建流程各家不同,全部代码在 项目仓库里」。这个决定贯穿全书:正文讲机制,代码在 GitHub⁶¹。

6.2 CI 之前的一条暗线:从 .env 到 .env.sampleCopy Anchor Link

书里在迁移节末尾补了一条演进路线:现在全项目共用一个 .env 是因为 它还没有敏感配置;「将来各环境数据库不同,就得改成提交 .env.sample、 各人自配真文件」——这个转变在第 4 章真发生了(数据库凭据进 .env, 再往后 .docker.env、compose 的 env_file 一路延续)。配置文件的 谱系本身,就是环境复杂度增长的年轮⁶²。

7. 作者的判断与证据(补记)Copy Anchor Link

有出处的: 发送/接收实录、CI 三工作流、迁移命令序列均为原书实操; 「make it work/right/fast」与「不重复造轮子」的引用在原文⁶³。

作者自己的评估: 「先 JS 前端顶上」是教学安排(见 §5.3 判断块); 「框架解耦层不值得做」是经验判断;「测试留作练习」在前言里就声明过—— 这三处都是立场,引用时请带主语。

4.8 本章三条工程纪律的汇总(比步骤更重要的东西)Copy Anchor Link

minimalist-api 这一章表面上给了「一个 API 怎么写」,底子里立了三条 贯穿全书的纪律:⁶⁴

1. 格式与 lint 进保存动作(rustfmt + Clippy 钩子)——把「事后收拾」 变成「顺手发生」;第 3 章 CI 的 fmt --check 与 clippy -D warnings 就是这条纪律的服务器端镜像;
2. 错误格式是协议——JsonError{code,message} 从第 ③ 步立起来, 一路用到第 10 章(加 origin)、第 13 章(加 details); 「客户端永远读得懂失败」是 API 设计里不许省的预算项;
3. main 只 bootstrap——启动所需的留下,其余搬走;这条线从 30 行的 骨架一直拉到第 9 章的七个服务(每个服务一个启动入口)。

与下一章的交接: 骨架章刻意停在「SQLite + 手写 SQL + 包 Result 的 提取器」;第 4 章开头的第一件事就是给这套骨架换发动机——换库领教方言 之苦,换 ORM 领教范式转移,两件烦事挨在一起做,正是为了让你看见 ORM 的账单和它的价值是同一笔⁶⁵。

4.2 主线例子的失败路径全集(每种错都试一遍)Copy Anchor Link

minimalist-api 调通之后,书里特意带读者把「会错的请求」挨个试了一遍—— 这份失败样例集比成功路径更值钱,因为它演示了统一错误格式的实际成色:⁶⁶

从这张表能读出的三层防线: 提取器(Content-Type、JSON 形状、路径 参数类型)在 handler 前拦;业务查询(查不到行)在 handler 里拦; 基础设施(连接池)在深处拦——三层全部归一到同一种 JSON 错误体。 「API 有了统一语言(成功与失败同格式),客户端可以依赖这种一致性」⁶⁷。

4.3 重构动机的完整链条(为什么非要拆文件)Copy Anchor Link

拆文件不是洁癖,书里给了因果链:⁶⁸

1. 错误处理逻辑重复(每个 handler 里 copy 一份 JsonError 构造)—— 「比我们愿意看到的重复还多」;
2. uniform_error 帮手函数出现——「这个函数和 JsonError 是好候选人: 该搬出去,别让它污染 main 里的业务逻辑」;
3. 「文件要 thin,最优一个文件一个目的;main 的存在理由只有一个: 启动应用」——划界:启动所需留下,其余搬走;
4. 结构成形:api/error.rs(错误)、api.rs(serve + router 合并)、 api/tickets.rs(资源);「以后加资源,就是 api/ 下一个新文件 + router() 里一行 merge」。

「想过但不做」的框架解耦层(第 1919 段的完整论证):把 API 组件与 axum 解耦、抽象掉框架依赖,好处是「将来能换框架」;但「现实中几乎没人 换写好了应用的框架」——可替换性也是成本,按「合目的」军规,这笔不买。 这句和第 2 章「避免 lock-in」的立场看似相反,其实一致:lock-in 要防的是 「外部世界逼你换」(数据库方言),不是「自己心血来潮想换」(框架)⁶⁹。

6.3 持续集成的八类自动化的完整映射Copy Anchor Link

书里列的 CI 可能包含的八类活,与本书实际三条流水线的对应关系:⁷⁰

「三种工作流(Rust CI / JavaScript CI / Security Audit)就位后,每次推送 都会按触发器持续验证应用;流水线失败还会邮件通知」——CI 的闭环 = 自动化 + 通知 + 徽章对外可见⁷¹。

8. 本章一页复习(骨架项目的最终形态)Copy Anchor Link

  一个命令的真相:clone → touch dev.sqlite → npm update && npm run dev
      │  ① 迁移自动建表(bootstrap 里的 migrate!)
      │  ② cargo-watch 盯后端,trunk/vite 盯前端,concurrently 总指挥
      │  ③ CI 在云端盯着每一次 push(测试/格式/lint/审计)
      ▼
  文件结构的全景:
      src/main.rs          bootstrap(配置+连接池+serve)
      src/api.rs           router 合并 + serve()
      src/api/tickets.rs   资源:路由 + handlers + Ticket
      src/api/error.rs     JsonError + to_uniform_response
      migrations/          sqlx 迁移(SQL 文件 + 时间戳)
      sqlx-data.json       离线 schema 元数据(入库)
      frontend/            独立前端(临时 JS,正式 Rust 在第 4 章)
      .github/workflows/   三条流水线

  图说:骨架 = 「能跑」+「能改」+「能复现」+「有人盯」四件事的最小合集。

与「Make it work / right / fast」的对位: 第 ①–⑥ 步是 work; 第 ⑦ 步(拆文件 + uniform_error)是 right;fast 全书没追—— 「先把正确性做满,性能等第 14 章的观测工具来指路」。这个顺序本身就是 一条可带走的纪律⁷²。

4.9 SQLite 环境的完整搭建账(三平台命令实录)Copy Anchor Link

原书给了一条跨平台的 SQLite 安装路径,照抄可用:⁷³

建库 = 建一个空文件——touch dev.sqlite;用 SQLite Browser 打开, 在 Execute SQL 标签页粘贴 CREATE TABLE,「点播放按钮执行,点 Write Changes 落盘」。AUTOINCREMENT 的含义: PRIMARY KEY("id" AUTOINCREMENT) = 主键自动发号,从 1 起、永远取「已用最大值 +1」——这就是「发 0 收 1」的 机制本体⁷⁴。

DATABASE_URL 的三个来源(优先级从低到高): 环境变量 (set/export 平台各异)→ .env 文件(SQLx 宏的硬性要求)→ docker 环境的注入(第 9 章接管)。书里选 .env 的动机很生活化: 「作者不想在三个操作系统上分别教怎么设环境变量」;代价第 4 章就付: 凭据混进开发目录,.gitignore 与 load diff 的教训接踵而来⁷⁵。

dotenvy + anyhow 的组合技: dotenvy::var("DATABASE_URL") 找不到 变量时,错误信息不说是哪个变量;.context("DATABASE_URL must be set") 用 anyhow 的上下文包装补上遗言。这个「错误上下文」技巧在第 4 章的 ? 早返回里会升级成标配⁷⁶。

4.10 临时前端的遗产(这一章给后面留下了什么)Copy Anchor Link

那版「临时起意」的 JS 前端没有被第 4 章扔掉,而是留下了三件传家宝:⁷⁷

1. /backend 反代约定——第 9 章 lighttpd 把这条约定原样搬进生产 容器(Wasm 读不到 env 的同一约束);
2. CORS 中间件的挂法(.layer(cors) 加在 Extension 之后)—— 中间件的层叠顺序自此成为全书的固定手艺;
3. 「先占位、后灌水」的异步呈现模式——fetch → 默认渲染 → 数据到了再补; Yew 版前端(第 4 章)与 SSE 推送(第 12 章)都是这条模式的变形。

「教学项目的每一章都该给后面留东西」——本章留下的这三件,比 minimalist-api 本身活得更久⁷⁸。

4.11 与第 4 章的交接清单(骨架章留下的五个接口)Copy Anchor Link

本章结束、下一章开始时,以下五件东西以「现状」交接:⁷⁹

交接的用意: 每个接口都处在「能跑但不够好」的状态—— 「Make it work」到此为止,接下来四章轮流做「Make it right」; 这也正是原书把换装放在第 4 章开头的理由:「现在还没做多少,正是 范式转移最便宜的时机」。⁸⁰

13. 原文地图补充Copy Anchor Link

14. 本篇卷尾(一句话版)Copy Anchor Link

骨架章的全部贡献,可以浓缩成一句验收标准:「一个新同事 clone → 建库 → 一条命令,十分钟内看到系统在自己机器上跑起来」——迁移管住了「建库」, CI 管住了「系统没坏」,模块化管住了「一条命令」。第 4 章从这幅骨架上 直接长肉。⁸¹

15. 本篇卷尾补记(骨架验收口诀)Copy Anchor Link

「新同事 clone → 建库 → 一条命令,十分钟跑起来」——这句验收标准 背后是四件套:迁移管建库、CI 管没坏、模块化管一条命令、.dockerignore 管别泄密。四件缺一,骨架就有洞。⁸²

16. 本篇卷尾补记(骨架的度量)Copy Anchor Link

骨架好不好,不看代码行数看四件事:新同事上手分钟数、改一行代码触发的 重编范围、错误格式的一致性、CI 红灯的频率。四件都向好,骨架就是活的; 反之,「能跑」只是暂时的幻觉。⁸³

17. 本篇卷尾补记(交接检查单)Copy Anchor Link

交给下一章前逐项打勾:错误格式统一了吗?迁移入库了吗?CI 三条流水线 绿了吗?前端能联调吗?四勾全绿,骨架章才算真正收卷。⁸⁴