文档【免费下载链接】public-apisA collective list of free APIs项目地址https://gitcode.com/GitHub_Trending/pu/public-apis点击查看免费下载本篇技术指南围绕开源仓库 public-apis项目根目录 README 中社区维护的免费 API 清单的scripts目录展开系统讲解该项目用于保障README.md数据质量的两大 Python 校验工具——格式校验器format.py与链接校验器links.py的安装、用法、命令行参数与底层实现原理并完整演示基于unittest的测试运行方式。读完本文你将掌握如何在本地复现 public-apis 的 CI 质量门禁、理解其数据表格式规范的具体约束并能将这些校验思路迁移到自己的 Markdown 数据仓库中。一、scripts 目录结构与定位在 public-apis 仓库中scripts目录承担了全部“验证与测试”职责。目录内同时包含校验 Python 包validate、单元测试tests、依赖清单requirements.txt以及一个用于 CI 环境的 Shell 脚本github_pull_request.sh。其完整结构如下scripts │ github_pull_request.sh # 用于校验 Pull Request 变更的 Shell 脚本 │ requirements.txt # validate 包的依赖清单 │ ├───tests # validate 包的全部单元测试 │ test_validate_format.py │ test_validate_links.py │ └───validate # validate 包本体 format.py links.py从结构看这一目录形成了一条清晰的“检查器validate→ 测试tests→ CI 集成github_pull_request.sh”流水线开发者修改README.md后先本地运行校验器提交 Pull Request 后 CI 再通过 Shell 脚本对 PR 的 diff 增量做链接检查而tests目录则为校验器的每个函数提供了行为级回归保障。二、安装依赖Python 与 pip 前置条件使用这些脚本的前提是系统中已安装 Python脚本均为 Python 3 语法并使用了typing注解与f-string见 format.py 与 links.py同时需要借助 pip 安装validate包的依赖。在仓库根目录执行$ python -m pip install -r scripts/requirements.txtrequirements.txt文件内容当前固定了如下依赖版本包名版本用途requests2.27.1链接可用性检测时发起 HTTP 请求urllib31.26.8requests 的底层传输库certifi2021.10.8SSL 证书校验所需的 CA 证书包charset-normalizer2.0.10响应内容字符集归一化idna3.3国际化域名IDNA编解码其中requests是核心依赖——链接校验器正是基于它实现并发请求、超时控制与异常捕获的。三、运行格式校验保障 README 数据表符合规范格式校验器读取README.md按公开 API 清单约定的表格格式逐行检查。在仓库根目录执行$ python scripts/validate/format.py README.md若校验通过脚本正常退出若发现问题脚本会按(L行号) 错误描述的格式逐条打印错误并以sys.exit(1)非零退出见 format.py main 函数。结合 format.py 源码 与 test_validate_format.py 中的测试用例其检查项可归纳为以下几类3.1 单条条目Entry的五列约束README.md主表每行 API 条目固定包含 5 个信息段num_segments 5索引顺序为title / description / auth / https / cors对应源码index_title到index_cors五个常量。逐段的检查规则为Title标题必须符合TITLE的 Markdown 链接语法且标题不得以 API结尾——因为该清单中的每一项本身都是 API重复后缀无意义对应check_title的报错Title should not end with ... API。Description描述首字符必须大写结尾不允许出现标点符号punctuation中剔除了()两个字符后参与判定长度不得超过 100 个字符常量max_description_length 100。这三条规则分别对应check_description中的三个分支。Auth认证取值只能来自auth_keys [apiKey, OAuth, X-Mashape-Key, User-Agent, No]除No外其余取值必须用反引号包裹即写成apiKey形式对应check_auth的auth value is not enclosed with \backticks 报错。HTTPS取值只能为Yes或Nohttps_keys。CORS取值只能为Yes、No或Unknowncors_keys。check_entry将五段检查的错误合并返回若某行拆分出的段数不足 5会直接报entry does not have all the required columns (have N, need 5)。此外每一段两侧必须恰好各有一个空格源码中通过lstrip/rstrip长度差等于 1 来判定这是 Markdown 表格渲染对齐的硬性要求。3.2 分类Category级约束README.md使用###三级标题划分 API 分类。check_file_format与check_alphabetical_order共同保证每个分类标题必须已添加到文件开头的## Index目录中否则报category header (X) not added to Index section对应测试用例见 test_validate_format.py分类标题本身格式必须正确需匹配### 标题形式每个分类至少包含 3 条 API 条目常量min_entries_per_category 3不足则报does not have the minimum 3 entries每个分类内的条目必须按标题的字母序排列get_categories_content会先按###锚点解析出每个分类及其条目标题列表再与sorted()结果比对乱序时报X category is not alphabetical order。错误消息统一由error_message(line_number, message)生成行号从 1 开始并补齐为三位例如(L002)、(L011)、(L101)这一格式在 test_error_message_return_and_return_type 中有明确断言。四、运行链接校验重复检测与在线可用性检测链接校验器负责扫描README.md中的全部外链检查重复项并默认逐一发起请求验证链接是否仍然可用。基本用法$ python scripts/validate/links.py README.md由于链接数量众多完整检查“可能耗时较长”。如果只想检查链接是否存在重复、不关心链接是否真实可访问可加-odlc参数--only_duplicate_links_checker的缩写$ python scripts/validate/links.py README.md -odlc命令行参数解析位于 links.py 的__main__分支第三个参数仅接受-odlc或--only_duplicate_links_checker大小写不敏感传入其他值会打印用法提示并以非零退出。4.1 链接提取与去重逻辑find_links_in_file只从README.md的## Index段即## Index起始位置之后开始提取链接——若找不到该锚点则回退到文件开头。链接提取使用一段复杂的正则见find_links_in_text可匹配http://、https://及www.开头的 URL也能从Example这类 Markdown 语法中抓取真实地址同时过滤掉example.com这类裸域名。check_duplicate_links的去重策略是先对每个链接做rstrip(/)去掉末尾斜杠因此https://x.com与https://x.com/会被视为重复再用字典记录出现次数第二次及以后出现即记入重复列表重复列表非空时整体判定为存在重复并逐个打印重复链接后退出。4.2 在线可用性检测请求策略与错误分类默认模式下start_links_working_checker会遍历所有链接并打印总数量随后调用check_if_link_is_working对每个链接发起请求。其请求与判定策略值得关注请求参数requests.get(link, timeout25, headers{...})超时上限为 25 秒User-Agent 伪装fake_user_agent()会从 4 个浏览器 UA 中随机挑选一个。源码注释明确说明这一设计原因——部分托管服务会拦截未在白名单中的 UA见 fake_user_agentHost 头注入通过get_host_from_link从链接中解析出主机名剥离协议、路径、查询参数与锚点作为host请求头发送。错误按类别以统一前缀格式输出错误前缀含义触发条件对应异常ERR:CLT客户端错误HTTP 状态码 ≥ 400且非 Cloudflare 防护ERR:SSLSSL 错误requests.exceptions.SSLErrorERR:CNT连接错误requests.exceptions.ConnectionErrorERR:TMO请求超时TimeoutError/ConnectTimeoutERR:TMR重定向过多requests.exceptions.TooManyRedirectsERR:UKN其他未知错误兜底的通用Exception/RequestException4.3 Cloudflare 防护识别避免误报死链链接失效判定并非简单地“状态码 ≥ 400 即失败”。has_cloudflare_protection专门识别 Cloudflare 的 DDoS/访问校验页当响应状态码为 403 或 503 且响应头Server为cloudflare时会进一步在响应 HTML 中检索cloudflare_flags列表如403 Forbidden、Please Wait... | Cloudflare、We are checking your browser...、Ray ID:、_cf_chl等约 20 个特征标记中的任意一个。若命中说明该 4xx/5xx 状态码来自 CDN 防护而非 API 真实失效因此不计为错误。这一逻辑在 test_has_cloudflare_protection_with_code_403_and_503_in_response 中通过伪造 403/503 cloudflare 响应头的FakeResponse得到验证。五、运行单元测试为校验器做回归保障tests目录下的两个测试文件覆盖了validate包的核心函数。运行全部测试前需先切换到scripts目录$ cd scripts然后执行$ python -m unittest discover tests/ --verbose-m unittest discover会自动发现tests目录下的测试模块--verbose输出每个用例的详细执行结果。若只想运行格式校验器的测试用--pattern限定文件名$ python -m unittest discover tests/ --verbose --pattern test_validate_format.py同理只运行链接校验器的测试$ python -m unittest discover tests/ --verbose --pattern test_validate_links.pytest_validate_format.py覆盖了格式校验的几乎所有规则分支错误消息格式error_message、分类内容解析get_categories_content、字母序检查check_alphabetical_order、标题/描述/Auth/HTTPS/CORS 五项字段检查check_title、check_description、check_auth、check_https、check_cors以及整文件格式检查check_file_format中关于 Index 缺失、分类条目不足、列数不足、空格缺失等场景。test_validate_links.py则覆盖链接提取、重复检测、UA 伪装、Host 解析与 Cloudflare 防护判定。两个测试文件分别以from validate.format import ...和from validate.links import ...导入被测函数validate/__init__.py文件内容中的显式导入进一步保证了validate作为包被正确加载。六、CI 集成github_pull_request.sh 的 PR 校验流水线github_pull_request.sh脚本内容将前述校验能力接入 Pull Request 场景是理解整个校验体系闭环的关键一环。其核心思路是只校验 PR 新增的行而非全量 README参数校验脚本要求恰好 3 个参数$0 github-repo pull-number filename否则打印用法并退出set -e保证任何一步失败都会中断。进入工作区cd $GITHUB_WORKSPACE并对待校验文件执行realpath解析绝对路径。拉取 PR diff通过https://patch-diff.githubusercontent.com/raw/$GITHUB_REPOSITORY/pull/$GITHUB_PULL_REQUEST.diff下载 diff 到diff.txt并完整打印 diff 内容供 CI 日志回溯。提取新增行cat diff.txt | egrep \ additions.txt只保留以开头的变更行存入additions.txt作为待校验的链接来源文件注释中说明DUMMY_SCHEMEhttps这一变量名是为了“骗过”链接校验器避免把 diff URL 本身当作待检链接。增量链接校验执行python scripts/validate/links.py $LINK_FILE对新增行中出现的链接做重复与可用性检测失败则退出并提示link validation failed on additions!成功则输出link validation passed on additions!。由此可知public-apis 的 CI 采用“增量优先”策略PR 每次只验证本次改动引入的链接从而大幅缩短全量扫描耗时同时仍能通过后续全量校验流程兜底整个 README 的健康度。七、实战小结把校验体系迁移到自己的数据仓库public-apis 的 scripts 目录提供了一套低成本、可复用的“Markdown 数据仓库质量保障”范式核心可借鉴点包括用校验器代替人工 review将数据表格式的隐性约定标题语法、描述长度、取值白名单、字母序、最少条目数写成可自动执行的检查错误消息带精确行号让贡献者能自助修复区分“结构错误”与“外部失效”链接检查拆成“重复检测”与“在线可用性检测”两个可独立开关的阶段-odlc模式满足快速自查需求全量模式配合 Cloudflare 特征识别避免把 CDN 防护页误判为死链测试先行每个检查函数都有对应的unittest用例构造最小化的合法/非法输入样本如 test_validate_format.py 中的fake_contents与incorrect_lines后续扩展校验规则时不会破坏既有行为CI 增量校验通过解析 PR diff 只检查新增行在“覆盖完整”与“速度”之间取得平衡。如果你正在维护类似的大型清单类仓库API 列表、资源导航、配置大全可以直接复用本文介绍的命令与检查思路先跑 format.py 保证表格规范再跑 links.py必要时加-odlc保证链接质量最后用unittest discover守住校验器自身的正确性形成从本地到 CI 的完整闭环。赞分享文档【免费下载链接】public-apisA collective list of free APIs项目地址https://gitcode.com/GitHub_Trending/pu/public-apis点击查看免费下载相关推荐Fluent Bit Commit Linter 实战指南本地校验、单元测试与 CI 集成Fluent Bit Commit Linter 实战指南本地校验、单元测试与 CI 集成 Fluent Bit 的提交信息Commit Message需可观测性日志分析云原生流处理AWX Ansible Collection 测试指南单元测试、集成测试与完整性校验的完整实践AWX Ansible Collection 测试指南单元测试、集成测试与完整性校验的完整实践 导读 awx.awx 是 AWX 官方维护的 Ansible后端运维任务调度Public APIs项目自动化流程解析链接验证、格式检查与持续集成Public APIs项目自动化流程解析链接验证、格式检查与持续集成 Public APIs项目作为开发者社区中广受欢迎的API资源集合其自动化流程的高效运知识库文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考