前置:沿请求读代码。先按业务顺序读,再把这张表当字典;不需要从上到下背所有文件。源码路径相对项目根目录。
装配与基础#
| 文件 | 负责什么 | 阅读时先问 |
|---|---|---|
| go.mod ↗ | 模块、Go工具链、直接/间接依赖 | 为什么go声明与toolchain不同? |
| go.sum ↗ | 下载依赖校验 | 为什么不手动删除来绕错误? |
| cmd/server/main.go ↗ | 配置、连接、种数据、HTTP、关机 | 哪一步失败会停止启动? |
| cmd/hash-password/main.go ↗ | 终端隐藏读取密码并生成bcrypt | 为什么不接受命令行明文参数? |
| internal/config/config.go ↗ | 默认值、生产必填、开发持久密钥 | 密钥何时生成,是否重启变化? |
| internal/config/config_test.go ↗ | 开发密钥与生产配置测试 | 不完整生产配置是否被拒绝? |
| internal/database/database.go ↗ | Windows URI、连接、PRAGMA、初始迁移 | 什么时候关闭rows/事务? |
| internal/database/database_test.go ↗ | 较新schema拒绝与失败连接释放 | 旧程序是否能误读未来数据库? |
| internal/database/schema.sql ↗ | 全部表、约束与索引 | 唯一性由谁最终保证? |
| internal/domain/types.go ↗ | Actor、错误、Profile、Note、Comment、分页和输入 | JSON名与Go字段怎样映射? |
业务与HTTP#
| 文件 | 负责什么 | 优先函数 |
|---|---|---|
| internal/service/service.go ↗ | 通用约束、媒体URI、错误和审计辅助 | require、admin、mediaURI |
| internal/service/auth.go ↗ | 验证码、登录、签发/验证、退出、密码 | SendCode → Login → issueToken → Authenticate |
| internal/service/users.go ↗ | 资料、更新、关注、双向列表和用户搜索 | Profile、UpdateProfile、Follow、Relations |
| internal/service/notes.go ↗ | 保存、可读条件、互动、搜索与游标 | SaveNote、ReactNote、SearchNotes、Published |
| internal/service/comments.go ↗ | 回复结构、评论权限、分页、赞和删 | PublishComment、Comments、DeleteComment |
| internal/service/admin.go ↗ | 快照统计、账户管理、审计、完整性检查 | Dashboard、ModerateUser、Integrity |
| internal/service/seed.go ↗ | 初始管理员和空库教学资料 | Seed:何时不插演示资料? |
| internal/httpapi/server.go ↗ | 全路由、别名、请求/响应、身份、限流、静态 | Handler → route → withIDs → routes |
| internal/httpapi/uploads.go ↗ | 文件类型/大小、随机名、资料multipart | saveUpload、upload、updateProfile |
| internal/httpapi/server_test.go ↗ | HTTP到真实临时SQLite的跨层测试 | 先看测试名,再读准备/触发/断言 |
前端与部署#
| 文件 | 作用 | 注意点 |
|---|---|---|
| frontend/package.json ↗ | 固定依赖、Node约束、构建命令 | runtime与dev依赖区分 |
| frontend/package-lock.json ↗ | 可重现安装图 | npm ci依赖它 |
| frontend/vite.config.ts ↗ | React构建和/api代理 | 一个后端target,strictPort |
| frontend/src/main.tsx ↗ | React root、StrictMode和样式入口 | 开发effect检查 |
| frontend/src/App.tsx ↗ | 所有屏幕与交互 | 沿组件名查业务,不从1830行硬读 |
| frontend/src/api.ts ↗ | 统一网络层 | JSON解包、FormData、401、超时 |
| frontend/src/types.ts ↗ | 前端契约 | number范围、可选字段 |
| frontend/src/mock.ts ↗ | 显式原型模式 | 默认不代替真实API |
| frontend/src/styles.css ↗ | 基础组件样式 | 共享结构与媒体查询 |
| frontend/src/journal.css ↗ | 生活手册品牌、响应式和焦点 | 覆盖顺序与选择器权重 |
| frontend/index.html ↗ | 文档与入口 | 标题、root容器 |
| scripts/bootstrap.ps1 ↗ | 固定Node下载和SHA256 | 只写.tools,不改系统 |
| scripts/build.ps1 ↗ | ci、前端构建、Go编译 | 每阶段检查退出码 |
| scripts/dev.ps1 ↗ | .env加载与前台运行 | 逐字解析,Ctrl+C停止 |
| scripts/verify.ps1 ↗ | 一键测试/构建/审计/文档 | 任意失败停止 |
| scripts/check-docs.py ↗ | 链接、编码、初学顺序检查 | 只读验证,不改文档 |
| scripts/visual-check.mjs ↗ | 桌面/手机截图与坏图检查 | 用独立演练服务 |
| scripts/business-check.mjs ↗ | 实际页面完整回归 | 会写演练数据,不能指生产 |
| Dockerfile ↗ | Node/Go构建、非root运行 | 需实际Docker环境验证 |
| compose.yaml ↗ | 本地容器开发与卷 | 默认是development |
| .env.example ↗ | 所有后端配置说明 | 不放真实密钥 |
| third_party/ASSETS.md ↗ | skill、图片与许可出处 | 参考资料不等于全局安装 |
一次读不懂时#
先抄下函数的输入和输出,把SQL表名标到数据模型图上,再找覆盖它的测试。遇到库函数先确认它负责什么,不必立刻深入整个驱动。新文件加入时同步本索引与相关教学章节,避免索引变成过时目录。