每日一仓

ONE OPEN-SOURCE REPO A DAY

每天 08:00 更新 数据来源 · Atlas 精选榜 2026 年 11 月 18 日

第 16 期 · 2026-11-16

practical-tutorials/project-based-learning — 按语言分好的“做项目学编程”教程清单

第 16 期:practical-tutorials/project-based-learning——289,805 Star 的“做项目学编程”清单,22 种语言、457 条教程入口,一份从 2017 年维护到今天的自学路线图。

一句话定位

project-based-learning 是一份按编程语言分区的“做项目学编程”教程清单:它本身不含任何教程正文,只收录指向外部教程的链接,每条教程的共同标准是——跟着做完,能拿出一个完整可用的东西(解释器、数据库、游戏、聊天应用、爬虫),而不是只讲概念。仓库创建于 2017 年 4 月,至今仍在更新,最近一次推送是 2026 年 11 月 9 日的每周死链扫描。

源码结构

实测浅克隆 436 KB(含 .git),工作区只有 14 个文件、264 KB,是 Atlas 榜上结构最简单的仓库之一:

  • README.md:52,344 字节、676 行,仓库的全部内容资产。24 个二级标题:目录 1 个、22 个语言分区、附加资源 1 个;另有 18 个三级子分区(如 Python 下的 Web Scraping、Web Applications、Bots、Data Science、Machine Learning、OpenCV、Deep Learning;C/C++ 下的 Network programming、OpenGL;Dart 下的 Flutter、Mobile Application、Web Applications;Lua 下的 LÖVE)。
  • scripts/check_readme.py:1,178 行、44,939 字节,仓库里唯一的“代码”,也是 GitHub 把本仓主语言判定为 Python 的原因——一个 Markdown 清单仓的主语言是 Python,只因为校验脚本是 Python 写的。
  • .github/workflows/:3 个工作流共 200 行——link-rot.yml(114 行,每周一 06:17 UTC 全量扫链)、validate-pr.yml(47 行,PR 校验)、stale-prs.yml(39 行,清理陈旧 PR)。
  • .github/link-rot-state.json:119,240 字节,456 条 URL 的健康档案,每条记录首次发现时间、连续失败次数、最近一次分类与状态码。
  • .github/ISSUE_TEMPLATE/:1-broken-link.yml(报死链)、2-tutorial-suggestion.yml(推荐新教程)两个表单式模板,另有 config.yml;PULL_REQUEST_TEMPLATE.md 18 行。
  • CONTRIBUTING.md:34 行、1,808 字节;LICENSE.md:MIT,21 行;scripts/linkcheck-domains.txt(14 行)与 scripts/lint-allow-duplicates.txt(12 行)是校验脚本的两份策略表。

量化上,README 里共有 460 个 Markdown 链接、458 个 URL(自带校验脚本 lint 命令的输出:entries=457、urls=458、sections=23、errors=0、warnings=0),分布在 161 个不同域名上。按语言分区统计链接行(含多集教程的缩进子行):Python 129 条、C/C++ 98 条、HTML and CSS 73 条、Go 33 条、Rust 17 条、Lua 16 条、PHP 14 条、Dart 13 条、Ruby 11 条;另一端是 F#、Kotlin 各 1 条。JavaScript 分区只有 4 条——大量前端与 Node 教程实际收在 HTML and CSS 分区里(Angular、Vue、Node 子节都在该分区下),分类名是历史遗留。

架构图

flowchart TB
    Reader[读者] --> Readme[README 总入口]
    Readme --> TOC[目录 22 种语言]
    TOC --> Lang[语言分区层]
    Lang --> Python[Python 129 条]
    Lang --> Cpp[C C++ 98 条]
    Lang --> Web[HTML CSS 73 条]
    Lang --> Go[Go 33 条]
    Lang --> Others[其余 18 种语言]
    Python --> Entry[教程条目层]
    Cpp --> Entry
    Web --> Entry
    Go --> Entry
    Others --> Entry
    Entry --> Single[单篇教程]
    Entry --> Series[多集系列 缩进 Part 1 N]
    Single --> Ext[外部教程站 161 个域名]
    Series --> Ext
    Readme --> Gov[治理层]
    Gov --> Contrib[投稿规则]
    Gov --> Script[校验脚本 1178 行]
    Gov --> CI[PR 校验工作流]
    Gov --> Sweep[每周扫链工作流]
    Sweep --> State[死链状态档案 456 条]
    State --> Sweep
    Script --> CI

分层设计说明

这座仓库的分层只有两层是内容、两层是治理,界限非常干净。内容层是“目录 → 语言分区 → 教程条目 → 外部站点”的单向引用链:README 不托管任何教程正文,只做策展与导航;多集教程用“标题行 + 缩进 Part 1…N”的固定格式表达(如 Lua 的 BYTEPATH 游戏教程共 15 集、Django 实时聊天应用共 6 集),格式本身就是结构的一部分,校验脚本能解析它。

治理层是这份清单能活 9 年半的关键。投稿规则(CONTRIBUTING.md)只有 34 行,但每条都是硬约束:教程必须免费开放(无付费墙、登录墙、订阅墙),必须是项目制(读完能做出完整可用的东西),作者自荐必须声明利益关系,每个教程单独一个 PR,链接直指教程本身(禁用短链),投稿前本地跑 python3 scripts/check_readme.py lint 且必须 0 退出。校验脚本把这些规则变成了可执行的检查:lint 查格式、目录与重复链接,check-diff 只查 PR 新增的行,check-links 逐条验证存活;CI 在 PR 改动 README 时自动跑前三项;每周一次的扫链工作流把 456 条 URL 的健康状态写回 link-rot-state.json 持久化,失败次数与首次失败时间都留档,而不是每次从头扫。

值得注意的是,这套治理承认自动检查的边界:linkcheck-domains.txt 把 Medium、Reddit、X、LinkedIn、Udemy、Quora 等 14 类已知反爬域名记为 BLOCKED——查不通不算死链,只提示人工核实;52 条历史遗留的 http:// 链接被标记为“祖父条款”豁免,不阻塞 lint,但新增链接必须用 HTTPS。规则、例外与例外的原因都写在代码和注释里,而不是只存在于维护者脑子里。

技术亮点

亮点一:死链治理做成了带状态的持续过程,而不是一次性清理。 .github/link-rot-state.json 是 456 条 URL 各自的健康档案,字段包括 first_seen、consecutive_failures、first_failed、last_class、last_status。实测最新状态:368 条 OK、12 条 HARD_DEAD、73 条 BLOCKED、3 条 SUSPECT,另有 14 条连续失败 3 次以上;档案从 2026 年 7 月 4 日开始积累。配合每周一 06:17 UTC 自动跑的扫链工作流(link-rot.yml,失败不阻断后续步骤,状态提交与 issue 更新照常进行),死链从“某天被发现”变成了“有首次失败时间、有连续失败计数、有分类的待办事项”。代价是清理有滞后:有链接自 2026 年 7 月 4 日首次失败至今仍挂在清单里,12 条 HARD_DEAD 说明档案记录与实际下线之间还有人工确认的缺口。

亮点二:一个 1,178 行的校验脚本就是全部“后端”。 scripts/check_readme.py(44,939 字节)把 README 当作结构化文档解析:Document、Entry、Header 三个类建模标题与条目,classify_line 判定每行类型,parse_readme 产出条目表;三个子命令分工明确——lint 检查语法、目录完整性与重复/短链,check-diff 只检查 PR diff 里新增的行,check-links 做带域名策略的存活探测(_single_http_call 有字节上限与超时控制,extract_title 用 HTMLParser 提取标题做辅助判断)。本地实测 python3 scripts/check_readme.py lint 退出码 0,输出 entries=457 urls=458 http=52 sections=23 errors=0 warnings=0 info=52。这个脚本的存在解释了仓库的一个反直觉事实:一个纯 Markdown 清单仓的 GitHub 主语言是 Python。代价是规则与脚本强耦合——改格式要先改解析器,投稿者遇到 lint 报错需要读脚本才能理解某些规则(如重复链接白名单 lint-allow-duplicates.txt)。

亮点三:选品标准写进了投稿流程,而不是 README 的宣传语。 CONTRIBUTING.md 的“项目制”定义很具体:跟着教程走,读者要做出一个完整可用的东西。清单里的条目也确实符合这条线:C/C++ 分区有从零写 Shell、写 FUSE 文件系统、写文本编辑器(kilo)、写 Lisp、写哈希表、写简单数据库(cstack 的 db_tutorial)、写内核、写 CHIP-8 模拟器、写 NES 游戏、写操作系统;Python 分区有 Flask Mega-Tutorial、Django Girls、testdriven.io 的 Docker + Flask + React 微服务;Go 分区有 astaxie 的《Build Web Application with Golang》;Swift 分区有 Hacking with Swift 的 39 个项目与斯坦福 CS193p。同一标准下,纯概念讲解与付费内容被挡在门外,这是清单质量的来源,也是它的边界:想找“十分钟讲清某个概念”的速读材料,这里没有。

值得参考的设计或实现

  • 把清单当作数据库来维护。 内容(README)与校验(脚本 + 工作流 + 状态文件)分离,条目有固定格式、可解析、可计数;每周扫链把外部链接的健康状态持久化成 JSON,而不是依赖人的记忆。这是任何“awesome 清单”类仓库都可以直接抄走的做法:先有格式,再有检查,最后才有规模。
  • 用“祖父条款”处理历史债务。 52 条旧 http:// 链接不强制改写,lint 只报 INFO 不报错;新链接必须 HTTPS。规则收紧时不搞一刀切,给存量留出口,给增量立新规,PR 校验只查新增行(check-diff)是同一思路的另一面。
  • 区分“查不到”与“死了”。 反爬域名判 BLOCKED 而非 HARD_DEAD,单独给人工核实留口子,避免自动化把活链误杀;这比简单的“通不过就删”更诚实,也更适合链接资产。
  • 投稿门槛写成可本地验证的命令。 python3 scripts/check_readme.py lint 必须 0 退出——贡献者不用猜标准,跑一次就知道合不合格;CI 跑的是同一条命令,本地与线上没有两套标准。
  • 多集内容的缩进格式约定。 标题行 + 缩进 Part 1…N 子行,既让人一眼看出是系列,也让脚本能按深度解析;Lua 的 BYTEPATH(15 集)与 Django 实时聊天(6 集)都是这个格式的实例。

适合谁

  • 正在自学编程、看够了语法教程、想“动手做出点东西”的人:按自己学的语言进分区,挑一个感兴趣的项目跟着做。
  • 想换语言或技术栈的开发者:C/C++ 分区(98 条)偏底层与系统,Python 分区(129 条)偏 Web、爬虫、数据科学与机器学习,Go、Rust 分区偏后端与系统工具,各区的选题密度本身就是一份技术地图。
  • 带新人、备课或做学习规划的老师与团队负责人:清单的“项目制”标准保证了每条都能当作作业或练手项目,附加资源一节还收了 Exercism、Egghead、Node School、Full Stack Python、CodeCrafters 等 12 个平台(CodeCrafters 也是本系列第 1 期介绍的 build-your-own-x 的运营方)。

怎么上手

仓库本身不用安装、不用构建:打开 https://github.com/practical-tutorials/project-based-learning ,按目录进自己语言的分区,点链接直接去外部教程站跟着做。建议从三条线开始:Python 分区先做 Flask Mega-Tutorial 或 Django Girls(二者都是公认的入门级完整项目),C/C++ 分区先做 Write a Shell in C 或 cstack 的 Let's Build a Simple Database(代码量小、成就感直接),HTML and CSS 分区先挑一个带 Node 后端的全栈小项目。想贡献教程:先 fork,再按 CONTRIBUTING.md 检查(免费、项目制、未收录、格式 - [标题](链接)、多集用缩进格式),本地跑 python3 scripts/check_readme.py lint 通过后再提 PR,每个教程单独一个 PR;自荐自己写的教程要在 PR 里声明。

数据卡

  • 仓库:https://github.com/practical-tutorials/project-based-learning
  • Star:289,805(实时;Atlas 快照 288,445,14 天涨约 1,360)
  • Fork:36,842
  • Watch:3,463
  • 主要语言:Python(仓库唯一的 .py 文件是校验脚本,语言检测据此判定)
  • 许可证:MIT
  • Atlas 分类:学习资源与Awesome
  • 领域:教育与研究
  • 创建时间:2017-04-12
  • 最近推送:2026-11-09(每周死链扫描提交)
  • 最近更新(API):2026-11-15
  • Open issues:218
  • 实测体量:工作区 14 个文件、264 KB;README 52,344 字节、676 行;457 条教程入口、458 个 URL、161 个域名;校验脚本 1,178 行;死链档案 456 条 URL

← 返回仓库目录