把项目讲清楚
本合集目录
本章目录
单册说明:本文件是卷 8 的第 6 章,可独立阅读。前置:第 5 章(迭代与协作)。本章是三件事的收口:写一份别人能照着跑的 README、准备一条三分钟演示路径、把项目变成简历上说得清的一个点。文末给出结课后的三条学习方向。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 8 · 从作品到产品(第 6 / 6 章) |
| 前置章节 | 8.5 迭代与协作 |
| 本章产出 | README.md(八部分)+ 三分钟演示脚本 + 一份复盘 + 简历上的一行 |
| 对应代码 | 仓库根目录 README.md、docs/demo.md、docs/retro.md |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 一个没参与项目的人,只读 README 就能在 10 分钟内把项目跑起来 |
8.6.1 一句话结论:讲不清,等于没做完
有人问你:"你这个项目是做什么的?"
你说:"我用 Next.js 做前端、FastAPI 做后端、SQLite 存数据,部署在 Nginx 上,还配了 HTTPS。"
对方点点头,然后没有下一个问题。不是因为不感兴趣,是因为你没告诉他这跟他有什么关系。
另一种回答:"很多人读论文时把摘录存在微信收藏、txt、PDF 批注里,写综述时找不回来。我做了一个小站,把一段摘录存进去并打上标签,十秒内完成,下次按标签就能找到。现在有 5 个同学在用,存了 300 多条。"
一句话结论:项目的价值不在"用了什么技术",在"替谁解决了什么、你做了哪个关键取舍、结果如何"。README、演示、复盘、简历,讲的都是同一件事的四个版本。
这一章没有新代码,但它是整本书的收口:前七卷证明你能做出来,这一章证明你能让别人相信它值得存在。
8.6.2 原理与方法
README 的八个部分
README 是项目的门面,也是你六个月后回来时的说明书。八部分,顺序不要乱:
| # | 部分 | 写什么 | 常见错误 |
|---|---|---|---|
| 1 | 一句话定位 | 替谁解决什么问题,一句人话 | 写"基于 XX 的全栈应用" |
| 2 | 截图或短动图 | 真实界面,含数据 | 用开发中期的旧图,或带自己邮箱 |
| 3 | 在线地址 + 演示账号 | 能直接点开,账号可登录 | 只写"本地可运行" |
| 4 | 技术栈 | 一句"为什么选它" | 罗列十几个库 |
| 5 | 本地跑起来 | 三步,含环境变量与建表 | 写十步,缺 .env 说明 |
| 6 | 目录结构 | 只列三层,标清职责 | 贴一整棵几十行的树 |
| 7 | 已知限制 | 诚实写 3–5 条 | 假装没有限制 |
| 8 | 许可 | 一行 MIT 或"保留所有权利" | 不写 |
第 7 部分最容易被跳过,也最能建立信任。 一个敢写"全文搜索未实现、SQLite 写入超过每秒 20 次会排队"的 README,比一个声称"高性能、可扩展"的 README 可信得多。面试官和潜在用户都见过太多吹牛的项目。
本地跑起来:三步,不是十步
新人跑不起来的三大原因,按出现频率排:
| 原因 | 表现 | 修法 |
|---|---|---|
| 没配环境变量 | 启动即报 KeyError: 'DUDao_SECRET' |
提供 .env.example,README 第一行就写 cp |
| 没建表 | 第一个请求报 no such table: users |
给一条 init_db 命令,且可重复执行 |
| 版本不对 | SyntaxError 或依赖装不上 |
写明 Python 3.11+、Node LTS,不写具体小版本 |
所以"三步"应该是:克隆并装依赖 → 复制环境变量并建表 → 起两个进程。所有可选的步骤(换端口、开 HTTPS、配邮件)折叠到"进阶"里,不要放在主路径上。
三分钟演示:讲一个故事,不是逛一遍功能
演示最容易犯的错是从"注册"开始,一个一个点菜单。三分钟里,观众记不住第六个功能,只会记住"这个人想解决什么问题"。
| 时间 | 你说什么 | 你做什么 |
|---|---|---|
| 0:00–0:30 | 问题:摘录散在三个地方,写综述时找不回来 | 展示微信收藏、PDF 批注、txt 三个来源 |
| 0:30–1:30 | 主线:存 → 打标签 → 按标签找回 | 现场存一条,打两个标签,筛选出它 |
| 1:30–2:10 | 一个关键取舍:为什么用 session Cookie 而不是把 token 存进 localStorage | 打开 F12,展示 Cookie 是 HttpOnly |
| 2:10–2:40 | 数据隔离:换一个账号,看不到刚才那条 | 用第二个账号访问同一个 id,得到 403 |
| 2:40–3:00 | 限制与下一步:搜索还没做,SQLite 写到一定量要换 | 指着 README 的"已知限制" |
这个脚本的结构是:问题 → 解决 → 取舍 → 边界。前三段证明你懂用户在干什么,最后一段证明你知道自己方案的代价。只讲功能的人很多,能讲清代价的人很少。
复盘:三件事,各三条
复盘不是写感想,是产出下一次可以直接用的东西。固定三栏,每栏三条:
| 栏目 | 写什么 | 反例 | 正例 |
|---|---|---|---|
| 做对了什么 | 可复用的做法 | "我很努力" | "先写接口测试再改逻辑,标签重构那次 10 分钟就验证完" |
| 卡在哪 | 根因,不是情绪 | "部署好难" | "Nginx 502 排查 2 小时,根因是应用只监听 127.0.0.1" |
| 下次怎么改 | 有触发时机的动作 | "以后要多学习" | "下次部署前先跑 ss -lntp 确认监听地址" |
第二栏最值钱。把"卡住"写成根因,它才会变成经验;写成情绪,它只会变成抱怨。
简历上的一个点:问题 → 决策 → 结果
技术罗列式的写法,读者无法判断你的能力;问题式的写法,读者能立刻知道你能干什么。
| 层次 | 写法 | 问题 |
|---|---|---|
| 技术罗列 | 使用 Next.js、FastAPI、SQLite 开发个人知识管理平台 | 只说明你见过这些词 |
| 功能描述 | 实现了摘录、标签、筛选、多用户登录 | 说明你做完了 CRUD,没说明难在哪 |
| 问题-决策-结果 | 见下 | 说明你判断过、取舍过、验证过 |
一个可用的版本:
为需要写文献综述的研究生做一个摘录工具,把"存一条摘录"从跨三个应用缩短到 10 秒内;用 session + 行级归属校验实现多用户隔离,补了越权接口测试;列表接口经字段裁剪与联合索引,P95 从 400 ms 降到 90 ms,目前 5 位用户累计存入 300+ 条。
它包含四样东西:为谁、解决什么、关键决策、可验证的结果。数字不必大,真实就行;"5 位用户、300 条"比"面向全网用户"可信。
结课之后:三条方向
「读到」做到这里就完整了。接下来往哪走,取决于你想补哪一层能力:
| 方向 | 学什么 | 拿「读到」练什么 | 怎么算学会 |
|---|---|---|---|
| 更深的后端 | 事务与隔离级别、索引设计、任务队列、可观测性 | 把 SQLite 换成 PostgreSQL,加一个异步任务(关键词预计算) | 不改接口就能换库,且有慢查询与错误率监控 |
| 前端工程化 | TypeScript、组件测试、性能预算、设计系统 | 前端迁 TS,补组件测试,给打包产物(bundle)设体积上限 | 持续集成(每次提交自动跑测试)能拦住超过预算或测试不通过的提交 |
| AI 能力集成 | 结构化输出、检索增强、评测集、成本与延迟控制 | 给摘录做"自动标签建议",要求可量化准确率 | 有一份 50 条样本的评测集和一组准确率/成本数字 |
三条不互斥,但不要同时开始。选一条做三个月,判断标准只有一个:有没有人真的在用你新做的东西。 没有用户的功能,学不到东西,只学到语法。
8.6.3 动手:写、跑、讲、复
第一步:写 README
# 读到
把网页和 PDF 里的摘录存进来,打上标签,下次能找回来。多用户各自登录,只看自己的数据。
截图:`docs/screenshot-notes.png`(首屏放一张列表页截图,比任何形容词都有说服力)
在线地址:https://dudao.example.com
演示账号:[email protected] / demo-pass-2026
## 技术栈
Next.js App Router · FastAPI · SQLite · Nginx + systemd。
选这套是因为一台 1 核 2G 的服务器就能跑完,不需要额外的数据库运维。
## 本地跑起来
需要 Python 3.11+ 与 Node.js LTS。
```bash
git clone <仓库地址> && cd dudao
# 1. 后端依赖与环境变量
python -m pip install -r backend/requirements.txt
cp backend/.env.example backend/.env # 填入 DUDao_SECRET
# 2. 建表(可重复执行)
python backend/scripts/init_db.py
# 3. 起两个进程
uvicorn app.main:app --reload --app-dir backend # 终端 A
cd frontend && npm install && npm run dev # 终端 B
```
打开 http://localhost:3000,注册一个账号即可。
## 目录结构
```
backend/app/{main.py,routers/,services/,storage/} 接口、业务、SQL
backend/tests/ pytest 用例
frontend/app/ 页面与组件
scripts/ 运维与自查脚本
```
## 已知限制
- 单机 SQLite,持续写入超过约 20 次/秒会排队
- 全文搜索未实现,只能按标签筛选
- 没有找回密码流程,忘记只能重建账号
## 许可
MIT
写完做一次自检:把仓库克隆到一个新的空目录,只按 README 操作,记录每一步是否报错。报错的地方就是 README 缺的那一句。
第二步:让一个没参与的人跑
找一个同学,给他仓库地址,只说一句"照着 README 跑一下",不要口头补充任何东西。他在哪一步停下、问了什么,就是 README 要补的地方。这一步的价值远高于你自己再读三遍。
第三步:录一遍三分钟演示
用系统自带录屏,按上一节的五段时间走一遍,不剪辑。回放时检查三件事:
- 有没有超过 10 秒的空白(页面在加载,而你在等);
- 有没有出现真实邮箱、真实姓名、别人的数据;
- 讲到"限制"时,有没有卡壳——卡壳说明你还没想清楚代价。
第四步:写复盘
# 读到 · 第一阶段复盘(2026-11-20)
## 做对了什么
1. 先写接口测试再改标签逻辑,重构只花了 10 分钟验证
2. 发布前先写回滚预案,第二次发布出问题时 3 分钟退回
3. 把"先不做"写进 README,少做了 6 个没人用的功能
## 卡在哪
1. Nginx 502 排查 2 小时:应用只监听 127.0.0.1
2. 标签大小写导致 500:两个入口没共用规范化函数
3. 列表首屏 4.2 秒:接口返回全文且没压缩
## 下次怎么改
1. 部署后第一件事跑 `ss -lntp` 确认监听地址
2. 任何"规范化"逻辑只留一个出口,入口层不重复实现
3. 新接口默认只返回列表需要的字段,压测后再加
8.6.4 三个坑
坑 1:README 写成十步安装指南
症状:新人跑到第 4 步就卡住,问你"这个 DATABASE_URL 填什么";你自己半年后也跑不起来。
成因:把"我当时怎么装的"原样写下来,包含了一堆一次性操作(装编辑器插件、配镜像源、改 hosts)。
修法:主路径压缩到三步,且每步都能复制粘贴;把环境变量、建表、启动合成一条命令或一个脚本;所有"可选"折叠到文末。判断标准是"空机器上照做能否成功",不是"写得多详细"。
坑 2:截图是旧的,还带着自己的邮箱
症状:README 的截图里是三个月前的界面,按钮位置都变了;右上角赫然是你的真实邮箱,甚至有一条别人的摘录。 成因:截图是开发时随手截的,后来没更新。 修法:用演示账号重新截,数据用假数据;截完检查三处:账号信息、URL 参数、列表内容。发布前把截图当成代码一样 review 一次。
坑 3:简历写成技术清单
症状:"熟练掌握 React、Next.js、FastAPI、SQLite、Nginx、Git、Linux",投十份没有回音。 成因:以为关键词越多越容易被筛中,实际读者无法判断你会到什么程度。 修法:一个项目只写三行——为谁解决什么问题、你做的关键决策、可验证的结果。技术名词放在决策句里("用 session + 行级校验"),而不是单独罗列。
本章验收
- README 八个部分齐全,一句话定位里没有技术名词
- 在一个全新目录里只按 README 操作,能成功启动并登录
- 至少一个没参与的人照 README 跑通过,且他的提问已补进文档
- 三分钟演示能不看稿走完,且包含一处"取舍"和一处"限制"
- 复盘三栏各三条,"卡在哪"写的是根因而非情绪
- 简历上这个项目不超过三行,含一个真实数字
自测
Q1:为什么 README 要写"已知限制",这不是自曝其短吗?
看答案
恰恰相反,它建立信任。读者默认任何项目都有边界,你不写,他会假设你要么没想过、要么想隐瞒;你写了,他会认为你知道自己在做什么。更重要的是,限制会挡住不合适的用户——一个需要全文搜索的人看到"未实现",就不会注册后失望离开,这比多一个流失用户更划算。Q2:演示时为什么要专门讲一处"技术取舍"?
看答案
功能演示证明"能做出来",取舍说明"想过为什么这样做"。比如用 session Cookie 而不是把 token 放 localStorage,理由是 HttpOnly 能挡住 XSS 窃取——这句话展示的是判断力,而判断力正是面试和合作中最难验证的部分。只讲功能的人很多,能讲清代价的人很少。Q3:三条后续方向,应该按什么顺序选?
看答案
不按"哪个热门",按"你的项目现在最缺哪一层"。如果用户量开始上来、写入变慢,选后端;如果界面越来越难维护、改动经常碰坏别处,选前端工程化;如果有明确的智能需求(自动标签、摘要)且能定义评测标准,选 AI 集成。选一条做三个月,用"有没有人真的在用"来验收,而不是用"学完了没有"。下一步
卷 8 到此结束。项目已经有了测试、性能基线、安全底线、协作规范和一份讲得清的说明。接下来是查阅手册:命令忘了、状态码记不清、Git 弄乱了,回附录。