进阶手册

技术架构与选型

这是手册，不是第 3 章的替代品；读完十章并做过一个项目后再回来查。 当 AI 说出 Vue、FastAPI、PostgreSQL、Docker，或你遇到「该不该买服务器」「为什么本机能跑、服务器报错」时，按小节查即可。

定位

随时查阅

前置

第 3 章 · 软件是怎么跑起来的

关键词

分层、选型、排障

你能查到什么

• 某一层的常见方案、最大代价，以及什么时候才该选它。
• 从四个约束出发，定位到四套组合套餐中的一套。
• 按症状定位到 16 步链路的某一步、某一层，再把问题说准交给 AI。

全文只围绕一个前提：技术方案没有绝对优劣，只有在具体约束下的合适与否。 使用人数、数据规模、生命周期、出错代价——这四个约束变了，正确答案可能完全相反。

为什么要分层

分层只有一个目的：换掉一层时，其他层不用跟着重写。 三格地图、五层定义和餐厅比喻见 第 3 章，本页不再重复。

对 vibe coding 的意义：当 AI 改错地方时，你能说出「这是接口层的问题，不是界面层」，它就少猜三轮。你不需要会写每一层，但需要知道每层负责什么、什么时候该换。

五层结构：三格地图之外还有两格

五层的标准定义、每层在对话里的常见说法，见 第 3 章 · 三格 → 五层 + 横切。 下面这张图留作查选型和排障时的定位地图。

一次请求的 16 步：从点击到画面更新

这条链路不用背。它的用处是：出问题时能判断现在坏在第几步、属于哪一层。

界面层（前端）

负责呈现和采集：把后端数据渲染成画面，把点击、输入、拖拽翻译成动作。 它不做业务判断——判断错了会算错账，界面不该承担这个风险。基础定义见 第 3 章 · 一个软件是由什么组成的。

主流方案怎么选

对应 16 步第 1–4 步：渲染界面、捕获操作、更新状态、组装请求。

接口层（API）

规定界面层和逻辑层之间「怎么问、怎么答」。它的价值不在传输本身，而在解耦： 只要接口约定不变，前端换成手机 App、后端换成另一种语言，两边都不必改动。

地址与方法

每个操作对应一个地址（如 /api/sales-orders/123）和一个动作（取、建、改、删）。

请求与返回格式

前端送上去、后端答回来的数据结构，通常是 JSON。返回格式一旦定下就是契约。

状态码

200 成功、400 参数不对、401 没登录、403 没权限、404 找不到、500 服务器出错。

接口文档

把上述约定写下来，供两边对照。FastAPI 这类框架能自动生成。

主流方案怎么选

REST 的写法最直白：资源地址 + 动作 + 返回 JSON。 取销售订单列表是「对 /api/sales-orders 做取动作」，新建订单是「对同一地址做建动作」。 浏览器地址栏、命令行工具、调试软件都能直接测试。

GET /api/sales-orders?status=paid

200 OK
{
  "items": [
    { "id": 123, "customer": "张三", "amount": 99.0, "status": "paid" },
    { "id": 124, "customer": "李四", "amount": 45.5, "status": "paid" }
  ],
  "total": 2
}

POST /api/sales-orders
{ "customer": "王五", "amount": 128.0 }

201 Created
{ "id": 125, "customer": "王五", "amount": 128.0, "status": "pending" }

对应 16 步第 5–8 步：路由匹配、参数校验、权限校验、封装响应。

逻辑层（后端）

所有判断和计算发生的地方：这条数据能不能改、这个用户有没有权限、这个指标该怎么算。 它同时是唯一能安全保管密钥的地方——任何放在前端的密码或密钥，等同于公开。

• 路由：把接口层的每个地址分派给对应的处理逻辑。业务逻辑：真正的规则与计算，指标口径只在这里写一遍。
• 数据访问：读写数据层的统一入口，避免查询散落各处。权限与参数校验：判断能不能做，并拦住格式非法的数据。
• 定时任务：每日汇总、自动同步、定期清理。第三方调用：访问大模型、短信、支付，并在服务端保管密钥。

主流方案怎么选

对应 16 步第 9–12 步：读取规则、计算判断、请求数据、组装结果。

数据层

把数据存下来、按需找出来，并保证三件事： 不丢（有备份）、不乱（多人同时写不出冲突）、 不假（写入时有校验，脏数据进不来）。

主流方案怎么选

对应 16 步第 13–16 步：获取连接、执行查询、事务提交、返回数据集。

运行层

让程序真的「跑起来」并「被访问到」：代码放在哪台机器上执行、别人用什么地址打开、 这份环境能撑多久、一个月要花多少钱。部署的基础定义见 第 3 章 · 运行层：从本机到别人能打开。

• 运行环境：系统与软件版本。版本不一致是「本机能跑、服务器报错」的头号原因。服务器 / 托管平台：决定性能上限、成本与可访问范围。
• 域名：把 IP 换成好记的网址；中国大陆服务器需要备案。HTTPS 证书：加密传输，主流平台可自动申请和续期。
• 容器：把程序与依赖打包成可移植单元，解决「环境不一样」。自动化部署：提交后自动检查、构建、上线，省掉手动传文件。

主流方案怎么选

运行层不在 16 步链路里；它承载第 1–16 步所在的机器与平台。

横切关注点：七件比技术选型更重要的事

以下七项不属于任何单独一层，但若缺失，程序会在某个时刻整体失效。 对非技术使用者而言，这一节的优先级高于前面五层的技术选择—— 这里的疏忽往往不是「做得不好」，而是「造成实际损失」。

怎么选型：从约束出发，不是从技术主流出发

常见错误顺序是「先看哪个技术主流，再想办法用上」。正确顺序是从约束出发—— 先明确四个约束，再让约束决定方案。同一件事在不同约束下，正确答案可能完全相反。

决策表：三个问题定位到套餐

先问「谁在用」，多数情况再问一个是/否，就能落到后面的组合套餐。

三条通用原则

最常见的三个错误

什么时候该升级

四套组合套餐

把前面五层的选择组合起来，就是一套完整方案。以下四套覆盖绝大多数实际需求，可按场景直接对号入座。

一个最小闭环：从页面到数据

完整的「页面 → 接口 → 逻辑 → 数据」闭环，在 实验：午饭登记 里动手做； 三格与五层的定义在 第 3 章。本页不再重复同一份实现。

排障速查：症状 → 最可能的层

这张表把 16 步链路压缩成「看到什么 → 先去哪一层找」。 它的用法不是自己修，而是把问题说准，再交给 AI。

AI 时代的补充：写代码便宜了，选错没有

生成代码的成本在下降，但选错架构的代价没有下降。 AI 能把任何方案写出来，包括不适合你的那一个。

一、AI 默认选「语料最多」的方案

训练语料里 React、Next.js、PostgreSQL 的出现频率远高于原生 HTML 和 SQLite。 所以 AI 很容易对一个「只有一页的个人工具」推荐一整套现代前端工具链。 这不是它坏，而是它在选最像标准答案的答案，不是在选最适合你的答案。

二、AI 会发明不存在的字段和接口

AI 很擅长让代码「看起来对」：调用一个从未定义过的接口、返回前端不认识的字段、引用不存在的库函数。 这类错误往往不在语法层面报出来，只在运行时变成空白或 undefined。 对策是先写契约，再让它实现：接口地址、请求字段、返回字段、错误格式，写进规格。 然后让 AI 按契约实现，最后用一条真实请求验证。这正好是 第 7 章和 第 8 章在做的事。

三、AI 可能把密钥写进代码

当你把 API Key 粘进对话，AI 很可能直接把它写进前端文件、示例代码或配置文件， 然后告诉你「已经接好了」。上线前必须专门检查： 前端代码里有没有出现任何 Key、密码、内部地址。

术语表

本页出现的术语统一收在 第 10 章 · 一页术语表， 按「网络 / 软件结构 / 数据 / AI / 工程」分组，并标注首次出现的章节。这里不再维护第二份。

来源与边界