运行图#
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 的关系。未来接第二种数据库时,应引入清楚的存储接口与契约测试,不能只改驱动名字。
启动顺序#
- config.Load 检查环境,创建数据目录;开发密钥若不存在则生成并持久化。
- database.Open 拼合法 file URI,启用 foreign_keys、WAL 和 busy_timeout,限制单连接。
- 在事务中创建 schema,并在 schema_migrations 记录版本 1。当前是初始 schema,不是完整的任意旧库自动升级器。
- service.Seed 确保管理员存在;只在没有普通用户时插入教学资料。重启不重置用户密码、笔记或状态。
- httpapi.New 注册精确路由和兼容别名。
- 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 和外部短信分别在哪,能说出每层一个失败点。