全栈应用架构复盘

学习目标

十六课的零件拼成了一台完整的单人全栈应用。本课退后一步看全局：单人应用的边界在哪，渲染、交互、本地持久化、备份、模型服务各负责什么——把「会用」升级成「能讲清楚为什么这样分工」。

问题场景

朋友问你：「这站不就是个网站吗，跟把所有逻辑写进 React 组件有什么区别？」你如果只能答「用了 Next.js」，说明还停在 API 使用层。架构复盘要回答更根本的问题：为什么渲染在服务端、状态在客户端、数据在本地文件、模型调用单独一层——每条边界划在哪、为什么。

核心解释

单人应用的第一原则：信任边界极小，省下的复杂度全部花在体验上。 没有多租户、没有权限系统、没有水平扩展——这些省下来的预算，换来「本地优先」的架构取向：

层	职责	本站落点	不负责什么
渲染层（RSC）	查库、读文件、产出 HTML	服务端组件 + node:sqlite	不持有交互状态
交互层（客户端组件）	表单、编辑器、乐观更新	features/ 下的客户端组件	不直接碰数据库
写入层（Action / Handler）	校验、事务、缓存失效	app 内 actions 与 api 路由	不决定「长什么样」
持久层（本地数据目录）	SQLite + 上传文件 + 备份	data/，REACTLAB_DATA_DIR 可迁移	不理解业务语义
模型服务（lib/ai）	对话、工具调用、模型适配	统一 adapter，密钥只在服务端	不绕过数据层直接写库

两条贯穿性边界值得单独说。

数据边界：一切写操作过数据层。 无论 Server Action 还是 Route Handler，写库前都走同一个校验与事务封装——备份、迁移、冲突检测才有统一起点。判断标准很简单：如果绕过某层直接写库，哪些保证会失效？答案是校验、revision 锁、缓存失效、备份完整性全部失效。

信任边界：秘密不跨层。 数据库文件路径、模型 API 密钥只存在于服务端进程；跨层传递的只有可序列化的数据快照。这是 N05 组件边界在架构尺度上的重演——同一原则，不同粒度。

浏览器                            Node 进程（本机）
┌──────────────────┐             ┌───────────────────────────┐
│ 交互层（客户端组件） │ --数据快照--> │ 渲染层（RSC）               │
│ 表单 / 编辑器      │             │   │ node:sqlite           │
│ useOptimistic     │ <--HTML---  │   ▼                       │
└──────────────────┘             │ 持久层  data/database/*.db │
                                 │ 备份    data/backup/*.json │
       模型 API <--------------- │ lib/ai（密钥只在这里）       │
                                 └───────────────────────────┘

复盘的价值在于可迁移：换一个单人文档工具、一个本地记账应用，这套分层照样成立——因为边界是按「信任范围」和「变更频率」划的，不是按 Next.js 的 API 划的。

示例拆解

对照本机工程自查：

1. 从任意一次「保存笔记」出发，列出它穿过的每一层与每层的产出（校验结果、事务、失效调用、新 HTML）。
2. 检查 features/ 下的客户端组件有没有 import 数据库模块——应当一处都没有。
3. 检查 data/ 里只有数据（库文件、上传、备份），没有任何业务逻辑脚本。

关键点：好的架构日常是「感觉不到的」——每层职责清楚，出问题时你能立刻指出该去哪一层修。

动手任务

在本机工程里完成：

1. 写出你工程里一次写操作的完整穿越路径，标注每层做了什么。
2. 全局搜索客户端组件里的越界引用（数据库、密钥、node: 内置模块），确认为零。
3. 给这个架构写一段 200 字的「电梯说明」，要求不提任何框架名词也能成立。

常见错误

• 把「用了多少技术」当架构：架构是职责划分，不是依赖清单；说不出每层「不负责什么」就还没分清。
• 客户端组件里出现数据层 import：一次不小心的引入就把 Node 模块或密钥打进浏览器包，构建报错是防线不是障碍。
• 模型层绕过数据层直接写库：AI 工具调用的写入和人工写入必须走同一套校验与事务，否则冲突检测对它失效。
• 备份与数据库结构脱节：持久层改了表结构没同步备份格式，恢复时丢字段；每次迁移都要过一遍导出导入。

检查与复盘

自查清单：

• 能脱稿讲清五层的职责与「不负责什么」
• 一次写操作的跨层路径画得出、说得通
• 信任边界与数据边界的判断标准能迁移到其他单人应用

参考资料

• Next.js 文档：Server and Client Components —— 渲染与交互边界的官方说明
• Next.js 文档：数据获取 —— 数据层职责划分背景
• Next.js 文档：项目结构 —— 分层在目录上的落点