课程大纲 第 242 课,共 250 课 · 综合项目:交付它(打包你的项目)
综合项目:交付它(打包你的项目)

README + 一条命令运行

你有了干净的结构和真正的测试。最后一公里是审阅者实际上最先碰到的部分:README,以及运行它的那一条命令。一个要猜上十分钟才能启动的项目,即使能用也让人觉得是坏的。一个克隆下来一行命令就能运行的项目,即使很小也让人觉得很专业。同样的代码,给人的印象天差地别。

README 是一份契约。读者从上到下扫读,并期待一个可预测的形状:项目名作为标题,然后是怎么安装,然后是怎么使用,然后是怎么测试。具体来说,一份好的 README 有一行顶层标题(# Something),然后按这个顺序是这些部分:

# Triage Copilot

## Setup
pip install -e .            # editable install
cp .env.example .env        # then paste your real key into .env

## Usage
python -m triage            # the one-command run

## Tests
pytest

顺序很重要,因为读者会把它当作步骤来跟。先写 Usage 再写 Setup 会让人困惑:你没法使用还没安装的东西。所以你要写一个检查器 validate_readme(text),只有当出现了 #  标题,后面依次跟着 ## Setup、## Usage、## Tests,并且每一个都在前一个之后时,才返回 True。缺少某个部分,或者各部分顺序错乱,都返回 False。诀窍是:把所有行走一遍,保留一个记录你当前位置的"光标",并要求每个部分都出现在光标之后的位置。

一条命令运行。注意上面的 ## Usage 那一行就是一条命令。这正是 Makefile 或 justfile 里像 make run 这样的目标要达到的:一条好记的命令就能启动项目,这样就没人需要记住完整的调用方式。写 make_run(name),为一个项目返回那条命令字符串,例如 python -m triage(或 make run)。它必须嵌入项目名,并以与包目录相同的方式规范化,这样不同的项目会得到不同的命令。

关于真实仓库的两条诚实的、不评分的说明。第一,机密:cp .env.example .env 这一步之所以存在,是因为你真正的 API 密钥放在 .env 里,你把它加进 .gitignore,并且永远不要提交它。你只提交 .env.example,也就是带占位值的配置形状。把密钥泄露到公开仓库,是作品集项目的经典错误。第二,部署它:要把它放到网上,你会写一个小的 Dockerfile(复制仓库,pip install,把运行命令设为入口点),然后推送到像 Render、Railway 或 Fly 这样的 PaaS。那一部分无法在你的浏览器里运行或评分:等你发布时由你自己来做。按 Run 验证一份完整的 README 并打印运行命令。

轮到你了

写出一份好 README 的两个确定性部分。validate_readme(text) 当且仅当出现一个顶层 #  标题,然后依次是 ## Setup、## Usage、## Tests,并且每一个都在前一个之后时,才返回 True(缺少某个部分或顺序错乱 -> False)。make_run(name) 返回一条命令运行的字符串(例如 python -m <pkg> 或 make run),其中嵌入项目名,并像包目录那样规范化,这样不同的名字会得到不同的命令。

发现这节课有问题?报告它 · 就这节课提问

这个练习即将开放

完成它前面的那一课,这一课就会解锁。整门课程免费,无需账号,而且你现在就可以阅读这节课。