小蓝书 Go
系统架构

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

前置:初学检查表 · 接着读:数据模型

运行图#

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 和外部短信分别在哪,能说出每层一个失败点。

— 本篇阅读完毕 —
来源:小蓝书 Go / docs / 02-architecture/architecture.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭