跳到正文
零到全栈 · 卷 8 · 从作品到产品

把项目讲清楚

本合集目录
本章目录

单册说明:本文件是卷 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 弄乱了,回附录。

→ ../附录/附录A-命令行速查.md