free-programming-books 俄语自由编程书籍列表：文档结构、收录规范与自动化质检机制解析

本篇以 books/free-programming-books-ru.md（俄语版免费编程书籍清单）为主体，讲解该文档的章节组织、条目元数据约定（作者、格式、许可证、存档标记、译者署名）以及背后由 docs/CONTRIBUTING.md 定义、由 GitHub Actions 与本地 Linter 脚本执行的自动化质检规则。读完后你可以准确检索俄语编程学习资源，理解清单条目的可机读结构，并掌握维护此类列表时触发 URL 校验与排序检查的实操方法。

一、文档定位：多语言资源矩阵中的俄语书籍清单

该仓库是一个多语言免费编程资源聚合项目，README 将其划分为书籍、Cheat Sheets、免费在线课程、交互式教程、竞赛题集、播客/视频与在线 Playground 几大板块。俄语书籍清单是其中"Other Languages"板块下按语言切分的一份书籍列表，README 中以 Russian / Русский язык 条目挂载。与书籍清单并列，仓库还收录了同语言的姊妹文档：

• 俄语免费在线课程列表：courses/free-courses-ru.md
• 俄语播客与视频列表：casts/free-podcasts-screencasts-ru.md
• 俄语交互式教程列表：more/free-programming-interactive-tutorials-ru.md

需要说明的是，仓库对每份文件采用 CC BY 许可证授权（见根目录 LICENSE），且文档中的资源链接可能因上游站点变动而失效——这正是仓库引入自动化 URL 校验机制的原因，详见第五节。

二、文档结构：Index 目录 + 两级标题分区

free-programming-books-ru.md 全文约 635 行，其骨架由一个 ### Index 目录区块和若干语言/主题区块构成，遵循 docs/CONTRIBUTING.md 中"Formatting"一节定义的通用规范：

1. 所有列表文件以 Index 开头：Index 内列出全部章节与子章节的锚点链接，并按字母序排列。该文档的 Index 包含 80 个条目，例如 0 - Language Agnostic（含 8 个子章节）、Arduino、Assembly、Bash……直至 Unix。
2. 章节使用三级标题（###），子章节使用四级标题（####）。例如 ### Java 之下有 #### Android、#### Hibernate、#### JUnit、#### Maven、#### Spring 等子章节；### JavaScript 之下有 #### AngularJS、#### jQuery、#### Node.js、#### nuxt.js、#### React、#### vue.js。
3. 空行规则：上一个链接与新章节之间留 2 个空行；标题与该章节第一个链接之间留 1 个空行；相邻两条链接之间留 0 个空行；每个 .md 文件末尾留 1 个空行。这些规则不是风格偏好，而是会被 lint 工具自动检查的硬性约束。

2.1 章节全景

从 Index 的覆盖范围看，该文档收录的编程语言/技术主题包括（节选）：

章节	代表性子章节	收录资源特点
0 - Language Agnostic	应用架构、云计算、编程范式、性能、网络、配置管理、开源生态、IDE 与编辑器	语言无关的横切主题，含操作系统、算法、HTTP/SOAP 指南等
C / C++	—	俄语社区经典教材，如 Beej 网络编程俄语 PDF 译本
Java	Android、EasyMock、Hibernate、JDBC、JUnit、Maven、Spring、Swing UI	子章节最多、生态最完整的语言板块之一
JavaScript	AngularJS、jQuery、Node.js、nuxt.js、React、vue.js	覆盖前端框架全家桶
PHP	CakePHP、CodeIgniter、Laravel、Symfony、Yii	以框架文档俄语译本为主
Python	Django、Jupyter Notebook、NumPy、Pycharm	含 Telegram 机器人教程等俄区特色资源
SQL	FirebirdSQL、PostgreSQL	含 Firebird 语言参考俄语版、PostgreSQL 官方教育书目
Rust / Go / Haskell / Scala	—	含 Rustonomicon 俄语翻译、Effective Go 俄语版等社区翻译项目
Unix	—	含 Linux 内核模块编程指南、Linux From Scratch 俄语版等系统级书目

其中 0 - Language Agnostic 区块的 8 个子章节值得单独说明，它们按主题而非语言划分：应用架构（如 The API 一书俄文版）、云计算（Cloud Native 微服务/Docker/Kubernetes 俄文版）、编程范式（函数式编程导论、重构实践）、性能（《Продуманная оптимизация》）、网络（HTTP/2 详解俄语 PDF、IPv6 专著）、配置管理（Ansible 俄语教程）、开源生态（开源应用架构）以及 IDE 与编辑器（Vim cookbook 与《Просто о Vim》）。这种"横切主题 + 纵切语言"的双维组织方式，是该文档相对其他语言版清单的特色之一。

2.2 交叉引用

文档内部使用锚点实现子章节间的互引，例如 #### AngularJS 子章节开头有提示"See also … Angular"，#### Angular 子章节开头有"See also … AngularJS"，二者通过 Index 锚点形成双向参照，帮助读者区分旧版 AngularJS 与新版 Angular 的资源归属。

三、条目格式：可机读的元数据约定

清单中每一条资源都是一个结构化 Markdown 列表项。结合 scripts/rtl_ltr_linter.py 中用于解析书籍条目的正则 BOOK_ITEM_RE，其可机读结构为：

* 标题 - 作者 (格式) (许可证) (状态标记)

即"标题 + 链接 + 可选作者 + 可选元数据"四段式。各段约定如下（均来自 docs/CONTRIBUTING.md "Formatting" 一节，俄语版见 docs/CONTRIBUTING-ru.md）：

1. 链接与标题之间不允许空格：* 书名 合法，* [书名] (url) 不合法。
2. 作者前用 -（空格-短横线-空格）：* 书名 - John Doe。
3. 作者位于格式之前：* 书名 - Jane Roe (PDF) 合法；格式在作者前不合法。
4. 链接与格式之间留 1 个空格：* 书名 (PDF)。
5. 多格式时优先单链接；确需多格式时为每个格式追加一条链接，如 * 书名 - Jane Roe (HTML) (PDF, EPUB)。
6. 旧版书籍把年份写入标题：* A Very Awesome Book (1970) - Jane Roe，而非在作者后追加年份。
7. 状态标记（该文档中有真实用例）：
   • 编撰中的资源：*( :construction: в процессе написания)*，例如 0 - Language Agnostic 中的《Наука о Сетях》；
   • 已存档链接：*( :card_file_box: archived)*，条目 URL 指向 web.archive.org 存档快照，例如 Go в примерах、Вглубь языка Python、Ruby on Rails Tutorial 俄语版；
   • 访问限制说明：如 C# 板块 Design Patterns via C# 标注 *(Требуется аккаунт)*（需要账号）。
8. 许可证标注：支持 CC BY、CC BY-SA、GFDL 等简短代码（不带版本号），置于格式之后、其他说明之前。该文档中的真实用例：Arduino 板块的《Автомато-программато-компарадио-кружок》标注 (PDF) (CC BY-SA)。
9. 译者署名：使用 MARC relator 代码 `trl.:` 标注译者，作者列表用逗号分隔，过长可省略为 et al.。该文档中多个板块使用了这一约定，例如 Git 板块的《Волшебство Git》标注 "Ben Lynn, trl.: Tikhon Tarnavsky, trl.: Mikhail Dymskov, et al."，Unix 板块的 Beyond Linux From Scratch 同样列出了多位 trl.: 译者。这体现了仓库"为翻译者署名"的贡献者规范。

以上约定之所以重要，是因为它们不仅面向人类读者，还面向自动化工具：条目解析正则直接依赖"标题/URL/作者/元数据"的固定顺序与分隔符。

四、内容质量维度：资源类型的收录边界

文档中的资源并非任意网页，其收录边界由 docs/CONTRIBUTING.md "Notes" 一节约束，理解这些边界有助于评估清单条目的可信度：

• URL 要求：禁止短链、必须去除跟踪参数、优先 https、链接应直接指向资源本身而非跳转页。该文档中 0 - Language Agnostic 板块的多个 PDF 直链（操作系统、网络应用开发等）符合"直接指向可下载资源"的要求。
• 时间有效性：不收录限定免费期或限定注册窗口的资源；因此条目要么永久免费，要么标注存档/访问限制。
• "书"的判定特征：有 ISBN、有目录、提供可下载版本（尤其 ePub）、有版本迭代、不依赖交互式内容、自成一体。清单中如《Структура и интерпретация компьютерных программ》（SICP 俄语版 PDF）、《Укус Питона》等即按此标准收录。
• 不收录类型：博客、单篇博文、零散文章、非课程类视频、书籍章节、试读样本、IRC/Telegram 频道等。

同时文档对元数据有明确取舍：标题不杜撰、不写全大写、不带 emoji；作者不使用 "Prof."/"Dr." 等头衔；汇编类资源可用描述性署名（如 "Compiled from StackOverflow documentation"）。

五、自动化质检：排序、格式与链接校验

该文档不是静态文本，而是处于仓库 CI 流水线约束下的受管文件。docs/CONTRIBUTING.md "Automation" 一节（及俄语版 docs/CONTRIBUTING-ru.md 对应章节）说明了三层自动化机制：

5.1 格式与字母序检查（fpb-lint）

格式规则与列表字母序由 fpb-lint 工具经 GitHub Actions 强制执行。Index 区块要求严格字母序，正文条目同样要求按标题字母序排列（同字母开头时依次比较后续字符；带空格的 one two 排在 onetwo 之前）。从文档实际内容可以验证这一点：### Java 下的子章节 Android → EasyMock → Hibernate → JDBC → JUnit → Maven → Spring → Swing UI 即为字母序排列。若排序错误，lint 会指出应互换的具体行号。

5.2 URL 校验（awesome_bot + check_urls 触发器）

链接有效性由 awesome_bot 检查，且采用显式触发模式：推送一个提交信息中包含 check_urls=<文件名> 的 commit 即可对该文件发起 URL 校验，例如俄语版文档中给出的示例：

check_urls=free-programming-books.md free-programming-books-ru.md

多文件用单个空格分隔。注意其已知限制：指定多个文件时构建结果以最后一个文件的检查结论为准，可能出现"整体变绿但个别文件存在死链"的假阴性，因此需要到 PR 的 Checks 详情中逐一确认。这一机制解释了文档中大量条目带 web.archive.org 存档 URL 的原因——死链被替换为永久存档快照并打上 archived 标记，而不是直接删除。

5.3 RTL/LTR Linter：为什么 ru 文件不在其检查范围

仓库内置 scripts/rtl_ltr_linter.py 用于处理混合方向文本（RTL/LTR）的 BIDI 显示问题，其配套配置为 scripts/rtl_ltr_linter_config.yml。从源码结构看，该脚本按文件后缀判定方向上下文：is_rtl_filename()（scripts/rtl_ltr_linter.py）仅识别 -ar.md、-he.md、-fa.md、-ur.md 四类 RTL 语言文件；其余文件（包括俄语的 free-programming-books-ru.md）均按 LTR 上下文处理，因此 BIDI 失配、‏/‎ 标记检查对俄语文件基本不产生告警。俄语使用西里尔字母，属于左到右书写系统，这一设计与语言特性一致。

该 Linter 的解析逻辑对理解全部列表文件格式仍有参考价值：它用 LIST_ITEM_RE 识别列表项、用 BOOK_ITEM_RE 抽取"标题/URL/作者/元数据"四段、用 split_by_span() 处理嵌套 <span dir=...> 方向上下文，并支持 <div dir=... markdown="1"> 块级方向切换。配置项 ignore_meta 中列出的 PDF、EPUB、HTML、podcast、videocast 等格式说明词会被自动豁免，min_ltr_length: 3 则控制纯 LTR 片段的最小检查长度。

5.4 本地复现与验证方式

维护者在本地可用同样方式验证自己改动的条目：将改动文件路径交给 Linter 脚本（其 main() 接受 paths_to_scan 位置参数、--changed-files 与 --log-file 选项），或遵循"推送 check_urls= 提交"的流程触发 URL 校验。所有检查失败信息都会写入日志文件（默认 rtl-linter-output.log），而 PR 标注仅出现在 PR 实际改动的行上——从 get_changed_lines_for_file() 使用 git diff --unified=0 origin/main... 的实现可以看出这一过滤逻辑。

六、实战检索指南

结合文档结构，给出三类常见检索路径：

1. 按语言找入门书：跳到 Index 锚点定位语言章节。例如学 Go 可看 Go 章节（《Введение в программирование на Go》、《Эффективный Go》俄语版、The Little Go Book 俄语翻译）；学 Rust 可看 Rust 章节（Rustonomicon 俄语翻译、Rust 官方书籍俄语版、Rust 示例教程俄语版）。
2. 按主题找横切资源：0 - Language Agnostic 及其子章节覆盖算法与数据结构（《E-maxx.ru: Сборник алгоритмов с примерами на C++》）、操作系统（《Операционные системы》俄语 PDF）、网络（HTTP/SOAP 指南、HTTP/2 详解俄语版）、云原生（Docker/Kubernetes 俄文书籍）等。
3. 按框架找配套文档：Java 生态下 Maven/Spring/JUnit/Hibernate 各有独立子章节且多为俄语完整教程；前端生态下 React/Vue.js/nuxt.js/Angular 的条目多为官方文档的俄语翻译版，适合语言障碍读者。

使用时应注意的适用前提：条目链接为编写时有效的上游地址，个别资源可能已下线（文档中已有 archived 与 in process 标记先行提示）；部分资源标注"需要账号"，实际访问成本需自行评估；本清单只收录"可免费阅读"的资源，是否"完全开源"需结合条目后的许可证标注（如 (CC BY-SA)）判断。

七、小结

books/free-programming-books-ru.md 以"Index + 三级标题章节 + 结构化列表项"的固定骨架组织了从语言无关主题到 40 余个编程语言/技术的俄语免费书籍资源，其条目格式（标题、作者、格式、许可证、状态标记、trl.: 译者署名）同时服务于人类阅读与机器解析；字母序与格式约束由 fpb-lint 自动化执行，链接有效性由 awesome_bot 按 check_urls= 提交显式触发，BIDI 检查则经 RTL/LTR Linter 按文件后缀定向作用于阿拉伯语等 RTL 语言文件。理解这三条自动化约束，即可准确评估清单中任一可信度，并按照仓库既有规范安全地补充或修正条目。