# 架构总览：一个进程里的清晰边界

前置：[初学检查表](../01-beginner/10-checklist.md) · 接着读：[数据模型](data-model.md)

## 运行图

```mermaid
flowchart LR
  B[浏览器 React] -->|HTTP JSON /api| H[httpapi 路由与身份]
  H --> S[service 业务规则]
  S --> D[(SQLite WAL)]
  H --> U[uploads 文件目录]
  H --> W[frontend/dist 静态页面]
  S -->|生产验证码| M[HTTPS 短信适配器]
```

开发时 Vite 位于浏览器和 Go 之间，只代理 API/上传请求；正式构建后由 Go 直接提供静态文件。图片上传先落盘，笔记记录保存图片 URL。数据库不会把整张图片塞进 content 字段。

## 分层的原因

| 层 | 输入与输出 | 不应该负责的事 |
| --- | --- | --- |
| config | 环境变量 → 配置，检查启动条件 | 查询用户、回 HTTP |
| database | 路径 → 连接，版本化建表 | 决定哪个人能改笔记 |
| domain | 描述 Actor、输入、输出和错误 | 启动网络服务 |
| service | context + Actor + 输入 → 数据/错误 | 操作 React 状态、写响应头 |
| httpapi | HTTP → 参数/Actor → JSON | 复制一套独立点赞规则 |
| cmd/server | 装配和生命周期 | 在 main 写所有业务 SQL |

service 持有 database/sql 连接池。当前项目没有为了形式把每条 SQL 包装成一个只有一行的 Repository 方法：教学读者可以直接看见规则、事务与 SQL 的关系。未来接第二种数据库时，应引入清楚的存储接口与契约测试，不能只改驱动名字。

## 启动顺序

1. config.Load 检查环境，创建数据目录；开发密钥若不存在则生成并持久化。
2. database.Open 拼合法 file URI，启用 foreign_keys、WAL 和 busy_timeout，限制单连接。
3. 在事务中创建 schema，并在 schema_migrations 记录版本 1。当前是初始 schema，不是完整的任意旧库自动升级器。
4. service.Seed 确保管理员存在；只在没有普通用户时插入教学资料。重启不重置用户密码、笔记或状态。
5. httpapi.New 注册精确路由和兼容别名。
6. http.Server 开始监听；收到 Ctrl+C/SIGTERM 后最多等待 10 秒关闭在途请求，再关闭数据库。

若端口占用、数据库打不开或生产密钥缺失，程序应返回失败退出码，不在看似健康的页面里悄悄换成内存演示。

## 请求边界

HTTP 层每次为请求创建 20 秒 context，设置 25 MiB 总请求体限制；JSON 另外限制 1 MiB，图片/视频最多 20 MiB，头像 5 MiB。服务端不信任 body 中自报的 userId，使用已验证 JWT 与 sessions 得到 Actor。匿名读请求 Actor.ID=0，业务写方法会明确拒绝。

安全响应头包括 nosniff、frame 拒绝、CSP 和 referrer 策略。前端去掉了把标题与昵称直接作为 HTML 插入的用法，因此笔记标题中的 `<script>` 只是文本。

## 一致性与性能取舍

点赞、收藏、关注使用唯一关系行，当前统计直接查这些行。搜索直接查同一数据库的标题、正文、昵称、handle，删除和私密变更不会等待异步索引追平。这换来了简单清晰的一致性，也意味着大规模数据需要查询优化、索引方案与压测，不能照搬原 Elasticsearch 规模预期。

单进程单写连接适合本地和小型社区。请求会排队，因此所有结果集应及时 Close；不要在事务里发短信或长时间处理图片。当前短信请求发生在验证码记录创建之后，失败会按摘要清理相应验证码，避免删掉更晚的新码。

## 扩展顺序

先用实际慢查询证据决定索引，再考虑 PostgreSQL/全文索引；需要多实例时先替换会话、限流和文件共享策略，再引入连接池/业务锁协议；需要搜索副本时加入事务 outbox、消费幂等与重建工具。每一步都要写出失效边界，不要仅因为原项目有 MQ 就添加一个没有消费闭环的消息依赖。

验收：画出“发布”和“登录”两条链路，指出文件系统、SQL 和外部短信分别在哪，能说出每层一个失败点。
