同一份清单被写成十几篇:这波解读为什么全在讲 CORS 和限流

原创2026-11-02 19:40:272,308 阅读
文章标签:文档知识库

同一份清单被写成十几篇:这波解读为什么全在讲 CORS 和限流

9 月中旬的十几天里,同一份 Markdown 清单在中文技术社区被反复"解读"了十几遍:标题里八个带着同一个 Star 数字,摘要里几乎每一篇都在讲 Auth/HTTPS/CORS 三件套,一半以上的篇幅留给了 429 和跨域代理。而当我打开本地这份 public-apis 仓库,把它自己的校验脚本跑一遍时,得到的是一屏 634 条报错、退出码 1。

这两个画面对不上。一篇写得好的解读,本该比读者更早发现这件事。本文不重复第四遍"这个仓库是什么",而是把社区样本摊开,用仓库里的字段定义、校验脚本和 CI 配置,回答一个更实用的问题:为什么这波内容会不约而同地挤进 CORS 和限流这两个口子,以及还有哪些真正没人写、但能被仓库源码验证的切口。

样本盘点:八篇标题同一个数字,两篇提过校验脚本

把这次抓到的社区快照按"文中究竟出现了什么"做一次计数,结果很整齐,也很单调。

观察项 15 篇 CSDN 样本中的出现次数 仓库中可核对的事实
标题直接写 474k / 47 万 / 47.4 万 Star 8 仓库本身无法自证 Star 数,但能自证 2,720 行 README
摘要明确提到 CORS 10 篇以上 CORS 是表格第 5 列,取值只有三态
摘要明确提到 429 / 限流 / 配额陷阱 6 篇以上 全文 2,190 条数据行里,只有 3 条描述提到 rate limit
提到 scripts/validate 校验脚本 2 实际存在 2 个校验器、3 个 workflow、638 行单元测试
提到 MCP Servers 段 0 README 第 60 行起有独立章节,25 条 MCP 条目,字段体系与 REST 完全不同

更值得说的是一篇被我随机打开核对原文的样本(发布于 9 月 18 日,页面顶部标注"墨衍一键同步至各平台",同步目标列出 CSDN、公众号、知乎、掘金、百家号等九个渠道)。它的正文里有这样两句话:仓库目录下"躺着一堆看起来差不多的 .md 文件,每个文件对应一个分类,比如 weather.md、animals.md、finance.md",以及"没有任何代码逻辑,没有依赖,没有构建流程"。

这两句都不成立。当前仓库根目录只有 README.md、CONTRIBUTING.md、LICENSE 和 scripts/,所有分类都挤在同一份 2,720 行的 README 里;而 scripts/validate/ 是一个带 requests 依赖、带 unittest 测试、被三个 GitHub Actions 流水线调用的 Python 包,依赖清单在 scripts/requirements.txt,测试在 scripts/tests。

这不是挑刺。它解释了同质化的成因:大量"解读"没有读源码,只读了上一篇文章。 当第一篇文章把仓库描述成"一个 Markdown 文件",后面九篇就会继承这个错误;当第一篇把选题定在 CORS 和 429,后面九篇的目录结构就会自动对齐。

为什么 CORS 和 429 成为默认切入点:清单的字段就是选题的天花板

被复读最多的那句话是"用 Auth、HTTPS、CORS 三个字段快速筛选"。这话之所以成立,不是因为作者观察力好,而是因为表格里真的只有这些字段。

看 scripts/validate/format.py 的前二十行,整个仓库对"一条 API 应该描述什么"的定义就写死在这里:

anchor = '###'
auth_keys = ['apiKey', 'OAuth', 'X-Mashape-Key', 'User-Agent', 'No']
https_keys = ['Yes', 'No']
cors_keys = ['Yes', 'No', 'Unknown']

index_title = 0
index_desc = 1
index_auth = 2
index_https = 3
index_cors = 4

num_segments = 5
min_entries_per_category = 3
max_description_length = 100

num_segments = 5 意味着一条条目的信息容量被永久限制在五格:标题、描述、Auth、HTTPS、CORS。描述还被 max_description_length = 100 卡死在 100 字符以内。换句话说,清单的 schema 里没有任何字段可以承载"这个接口多久失效一次""429 之后要不要退避""免费额度是永久还是 14 天试用"。写作者能谈的深度,天然被表格的列数锁死了。

按 ## Index 之后的表格行做统计(以 | 切分,取第 3、4、5 段),这份清单当前的元数据分布是这样的:

  • CORS:Unknown 1,038 条(47.4%),Yes 892 条(40.7%),No 259 条(11.8%)。
  • Auth:No 1,050 条(47.9%),apiKey 980 条(44.7%),OAuth 150 条(6.8%),X-Mashape-Key 6 条,User-Agent 2 条。

两个数字放在一起看很有意思。第一,近一半的条目在 CORS 这一栏里是"不知道"。第二,近一半的条目需要 apiKey。这两条恰好是同一件事的两面:需要密钥的接口大概率不允许浏览器裸调,而"不允许"和"未验证"在表格里长得几乎一样。于是"跨域怎么办"成了每个读者必然会撞上的墙,也成了每篇解读必然会写的一节。

那 429 呢?我 grep 了全文,rate limit 只出现在三处:

README.md:593  | Currency-api | Free Currency Exchange Rates API with 150+ Currencies & No Rate Limits | No | Yes | Yes |
README.md:599  | Economia.Awesome | Portuguese free currency prices and conversion with no rate limits | No | Yes | Unknown |
README.md:844  | TidyTools | Web page to clean Markdown and AI crawler robots.txt checks, free without a key (rate limited) | No | Yes | Yes |

三条。一份收录两千多条接口的清单,关于限流只说了三句话。这意味着 429 是读者在接入时踩出来的经验,不是清单提供的事实。也正因如此,它特别好写:不需要任何仓库证据,只需要复述一次"加缓存、加退避、加降级",就能凑满一节,永远不会写错,也永远不会写出新东西。

所以同质化不是文风问题,是结构问题:CORS 是唯一一个既在 schema 里、又真的会挡住读者的字段;429 是唯一一个既不需要 schema、又能无限复述的坑。 两个条件一交叉,十几篇文章必然长得一样。

清单自己在变:MCP 段、六列残留和被删掉的 Postman 列

如果只读二手解读,你会以为这份清单还停在"REST API 五列表"的年代。实际不是。

README 第 60 行起是一个独立章节 ## MCP Servers,25 条条目,表头是 Name | Description | Auth | Transport | Install。它没有 HTTPS,也没有 CORS。CONTRIBUTING.md 把原因写得很直白:MCP server 是"装进客户端"而不是"通过 HTTP 调用"的,所以 HTTPS 和 CORS 对它根本不适用。Transport 只接受 stdio、HTTP、SSE(可逗号分隔),Install 只允许填写真实存在的市场页面,并明确规定"链到 404 的市场页会让 PR 被关闭"。

这条规则直接击穿了"用 CORS 判断能不能用"这个流行论断的普适性:对 25 条 MCP 条目来说,CORS 这一列根本不存在。而这 25 条,在 15 篇样本里被提及 0 次。

同一份 README 里还留着一层更旧的地质痕迹。CONTRIBUTING.md 里的条目格式仍然写着六列,最后一列是 Call this API(Postman Collection 按钮),示例是:

| [NASA](https://api.nasa.gov) | NASA data, including imagery | No | Yes | Yes | [Run in Postman Button]

但正文表格的表头已经缩成五列(API | Description | Auth | HTTPS | CORS),行的末尾却还留着那个空单元格。我统计到 105 行仍然是 6 列,写法是 ... | Unknown | |,集中在 Cloud Storage & File Sharing、Data Validation、Finance、Documents & Productivity、Health 几个分类里。列被删了,数据没清干净——这就是"清单在演进、但演进只做了一半"的直接证据。

对写作者来说,这是个比 CORS 好得多的题:同一份清单里同时存在三套 schema(五列 REST、六列遗留、五列 MCP),而校验器只认第一套。 这句话是我跑脚本跑出来的,不是想出来的。

替代切口一:失效治理——跑一次仓库自己的校验器,得到 634 条报错

这是全部切口里最容易验证、也最少人写的一个。在仓库根目录执行 scripts/README.md 里给出的第一条命令:

python scripts/validate/format.py README.md

我这边的结果:

exit=1
共 634 条 (Lxxx) 报错
  ├─ 553 条 常规五列区
  ├─  66 条 MCP 表(`HTTP` / `stdio`, `HTTP` 不是合法 HTTPS 选项、标题语法不符)
  └─  15 条 顶部 APILayer 三列横幅

634 条里,属于规则本身的分布也很说明问题:

  • 234 条 each segment must start and end with exactly 1 space,主要来自那 105 行尾部多出的空单元格;
  • 48 条 auth value is not enclosed with backticks,48 条 Title syntax should be "TITLE";
  • 46 组 :--- is not a valid Auth / HTTPS / CORS option,因为分隔行写成了 |:---|,而 format.py 的跳过条件是 line_content.startswith('|---'),冒号写法恰好绕过了它,整行被当成数据解析;
  • 30 条 category is not alphabetical order——51 个分类里,字母序这条最基础的规则已经在 30 个分类上失效。

这条线索的传播价值在于它的可复现性:任何人 clone 下来跑一条命令,就能得到同一个数字。而且它指向一个真问题——.github/workflows/test_of_push_and_pull.yml 在每次 push 到 master 和每个 PR 上都会执行 python scripts/validate/format.py README.md,脚本失败即 sys.exit(1)。也就是说,当前 master 的格式门禁是红的。二手解读里那句"社区加了 CI 校验脚本,补上了纯 Markdown 方案的短板",只对了一半:脚本确实在,但它已经追不上清单的演化速度了。

替代切口二:限流问题的真实样本,在巡检脚本自己身上

所有人都写"遇到 429 要退避",但没有人打开过 scripts/validate/links.py——那个每天真的会撞上 429 的程序。它的核心逻辑只有十几行:

resp = requests.get(link, timeout=25, headers={
    'User-Agent': fake_user_agent(),
    'host': get_host_from_link(link)
})

code = resp.status_code

if code >= 400 and not has_cloudflare_protection(resp):
    has_error = True
    error_message = f'ERR:CLT: {code} : {link}'

三个细节值得逐条拆开:

  1. 没有重试,没有退避,没有 Retry-After。check_if_list_of_links_are_working 是一个朴素的 for 循环,顺序请求,失败即记录。429 落在 code >= 400 分支里,被原样写成 ERR:CLT: 429,和 404、500 享受同等待遇。
  2. 只有 Cloudflare 被豁免。has_cloudflare_protection() 专门识别 403/503 加 Server: cloudflare 加一串人机校验文案(_cf_chl、Ray ID:、Checking your browser before accessing 等,共 20 个特征串),命中就判为"没坏"。换句话说,这份代码承认"403 可能只是反爬",却不承认"429 可能只是限流"。
  3. 巡检范围还会漏。find_links_in_file 先定位 readme.find('## Index'),只从 Index 之后取链接。而 MCP 段和 APILayer 横幅都在 Index 之前——那 25 条 MCP 条目、以及顶部那一整块赞助商链接,从来不参与每日链接巡检。

把这三条合起来看:.github/workflows/validate_links.yml 每天 0 0 * * * 从同一个 GitHub runner IP 出发,把两千多个域名扫一遍,无并发限速、无失败分类、无重试。这个动作本身就是一次典型的限流诱因:被扫的免费接口看到的是同一个 IP 在几分钟内连续请求,返回 429;脚本把 429 记成"链接坏了";第二天告警依旧。

这个切口的价值在于它给了读者可执行的东西。基于现有函数签名,最小改动可以是这样(保持 check_if_link_is_working 的返回契约不变,只在 429/503 上做有限重试):

import time

RETRYABLE = {429, 503}

def check_if_link_is_working(link: str, retries: int = 2) -> tuple[bool, str]:
    for attempt in range(retries + 1):
        resp = requests.get(link, timeout=25, headers={
            'User-Agent': fake_user_agent(),
            'host': get_host_from_link(link),
        })
        if resp.status_code in RETRYABLE and attempt < retries:
            wait = int(resp.headers.get('Retry-After', 2 ** attempt))
            time.sleep(wait)
            continue
        if resp.status_code in {429, 503}:
            # 限流 ≠ 失效:单列一类,不参与"链接坏了"的结论
            return (False, f'ERR:RLT: {resp.status_code} : {link}')
        if resp.status_code >= 400 and not has_cloudflare_protection(resp):
            return (True, f'ERR:CLT: {resp.status_code} : {link}')
        return (False, '')
    return (False, '')

配套的单元测试文件 scripts/tests/test_validate_links.py 已经把 403/503/200 三种 FakeResponse 都造好了,加一个 code_429 用例几乎不需要改结构。这类"在真实文件里改五行的限流实践",比任何一篇"加个缓存加个退避"的散文都更有说服力。

替代切口三:合规边界与成本模型,其实写在 CONTRIBUTING 里没人引

CONTRIBUTING.md 开头有一段被所有解读跳过的声明,语气相当硬:

有些 PR 是为了给提供付费方案的公司 API 做营销而开的。这份清单不是营销工具……被识别为营销行为的 PR 不会被接受。

请确认你要添加的 API 提供完整的免费访问,或至少有一个免费层级,并且不依赖购买设备/服务。一个会被拒绝的例子是控制智能插座的 API——API 本身免费,但你必须先买那个插座。

这段话定义了这份清单的收录边界:不是"能调通",而是"零前置成本即可调通"。它同时也暴露了一个无法用字段表达的矛盾——free tier 被允许,但 free tier 的形态(永久免费额度?14 天试用?每天 100 次?绑卡才能用?)在五列 schema 里完全无处安放。我统计了描述列,明确写出 free tier 的只有 30 条,占 2,190 条数据行的 1.4%。剩下 98.6% 的条目,"免费"这个词只有靠读者点进去自己判断。

这就带来两个可以写成数据文章的合规/成本视角:

  • Auth 是唯一可量化的成本信号。 980 条 apiKey(44.7%)意味着近一半条目需要注册、可能需要绑卡、可能附带配额;150 条 OAuth 意味着要处理回调、刷新令牌和用户授权。而这 980 条里有 30 条在描述里承认自己是 free tier——其余 950 条的计费边界仍然不透明。
  • 按分类看的 CORS 分布,比单条 API 的 CORS 更有预测力。 在条目数 ≥30 的分类里,CORS: Yes 的占比从 Machine Learning 的 65%(35/54)一路降到 Documents & Productivity 的 21%(11/53)、Music 的 17%(6/36)、Social 的 24%(14/58)。含义很实际:选型时先看分类,再看条目——机器学习类接口大多允许浏览器直连,而音乐、文档、社交类接口基本注定要走后端代理。

这两个视角都能用一段脚本复现,也都能被仓库数据证伪,符合"能落地的技术文章"的最低标准:

# 按分类统计 CORS 分布(在仓库根目录执行)
python3 - <<'PY'
lines = open('README.md', encoding='utf-8').read().splitlines()
start = next(i for i, l in enumerate(lines) if l.startswith('## Index'))
cur, stat = None, {}
for l in lines[start:]:
    if l.startswith('### '):
        cur = l[4:].strip(); stat[cur] = [0, 0]; continue
    if cur and l.startswith('| [') and not l.startswith('|---'):
        seg = [s.strip() for s in l.split('|')[1:-1]]
        if len(seg) >= 5:
            stat[cur][0] += 1
            stat[cur][1] += seg[4] == 'Yes'
for k, (n, y) in sorted(stat.items(), key=lambda kv: -(kv[1][1] / max(kv[1][0], 1))):
    if n >= 30:
        print(f'{k:30s} {y:3d}/{n:3d}  {y / n * 100:5.1f}%')
PY

给内容作者的话:热点不必跟着写,跟着卡点写

回头看这波同质化,最刺眼的不是观点重复,而是所有文章都在描述读者的卡点,却没有一篇文章去描述维护者的卡点。

读者的卡点确实是 CORS 和 429——所以前十篇写它,是合理的。但第十一篇开始,边际收益就变成了零。而维护侧的卡点一直摆在那里,只是需要跑一次命令才能看见:

  • 一份 2,720 行、51 个分类的清单,格式门禁已经积压 634 条报错,其中 66 条来自新增的 MCP 段,30 条是字母序失守;
  • 一个每天扫两千条链接的巡检脚本,会把 429 判成失效,且从不检查 Index 之前的 25 条 MCP 与赞助商链接;
  • 一个"免费但不许营销"的收录规则,只靠 100 字符的描述来承载,98.6% 的条目没有任何配额说明。

这三件事都比"加个代理解决跨域"更难写,也更有价值。判断标准也很简单:你写下的每一句判断,能不能用仓库里的某个文件、某条命令、某段输出反驳。 能,就值得写;不能,那大概只是把上一篇的目录换了个顺序。

顺带一提,如果你也想验证本文的结论,最省事的方式不是再读一篇文章,而是在仓库根目录跑那两条命令:python scripts/validate/format.py README.md 和 python scripts/validate/links.py README.md -odlc。前者会告诉你清单的规则哪里已经失效,后者会告诉你重复链接还剩几条。数字会变,方法不会。

登录后查看全文
public-apis