2016 年的 Markdown 仓库,为什么还在被新读者当成新发现

原创2026-11-02 18:30:311,717 阅读
文章标签:文档

2016 年的 Markdown 仓库,为什么还在被新读者当成新发现

2026 年 9 月,中文技术社区里同时出现了一批标题几乎可以互换的文章:public-apis、474k Star、免费 API 清单、五列 Markdown 表格、Auth/HTTPS/CORS 三列怎么读。它们被反复推送到信息流里,评论区常见的一句话是“第一次知道还有这种东西”。

但仓库本身并不新。它从 2016 年的一份 README 起步,如今已是 2720 行、322 KB 的单个 Markdown 文件;本地克隆只有一条浅提交,git rev-list --count HEAD 返回 1,十年的提交历史被压缩成一次合并。也就是说,这个仓库的“年龄”既不在版本号里,也不在 release 里,只能从结构里读出来。

这正是本文想回答的问题:一个没有构建、没有依赖、没有运行时、核心资产就是一张表格的仓库,凭什么在十年后仍被当成“新发现”?而新读者对它的误解,又集中在哪些可以被源码和数据证伪的地方?

一、读者换了:从“逛清单”到“接清单”

把社区情报按时间排开,能看到一条清晰的分界线。

2025 年 10 月和 2026 年 1 月的那批文章,重点是“怎么拿到、怎么挑、怎么提 PR”:克隆安装、五列表格解读、三步过滤法、curl 验证、提交规范。到了 2026 年 9 月,同一批平台上的标题集体转向了另一端:CORS 与限流接入指南、选型避坑、从选型到工程落地的完整指南、生产级避坑要点,正文里开始出现 401/400/429 错误码排查、免费额度陷阱、接口失效风险、密钥安全与数据合规。

读者结构的变化,在互动数据上也有痕迹。阅读量 846、收藏 15 的那篇《完整指南》,收藏率约 1.8%;而阅读量 342、收藏 2 的“每日一项目”体,收藏率只有 0.6%。前者被当成工具书存下来,后者被当成资讯划过去。更值得注意的是,2025 年那批文章反复提醒“部分接口会停止维护,而列表还没来得及清理”,2026 年那批则直接给出结论:“免费”背后是额度制与试用制,生产依赖前必须评估稳定性、合规与密钥安全。

换句话说,十年前读者来这里是为了“看看有什么好玩的”,现在的读者来这里是为了“明天要上线的小工具该接哪个接口”。前者消费的是列表的新鲜感,后者消费的是字段的确定性。

二、老清单在当下的三个优势(都能被数据验证)

第一,它的结构是纯文本,天然可 diff、可脚本消费。整个仓库除了 README 就是两支校验脚本:format.py 与 links.py,用法写在 scripts/README.md 里。没有数据库、没有服务端,任何人 git clone 之后就能把清单变成自己项目里的常量表。对副业项目来说,这种“零基础设施依赖”比任何 API 市场都划算。

第二,成本边界被写进了枚举值,而不是藏在定价页里。CONTRIBUTING.md 规定 Auth 只接受 OAuth、apiKey、X-Mashape-Key、No、User-Agent,CORS 只接受 Yes、No、Unknown;并且明确拒绝“API 免费但必须先买设备”的伪免费条目。这条规则看似琐碎,实际是在替读者做接入成本分级:No 是直接调用,apiKey 是注册换额度,OAuth 是一整套授权流程。

第三,它有一条别人不会替你跑的健康巡检。.github/workflows/validate_links.yml 用 cron: '0 0 * * *' 每天全量跑一次链接检查;links.py 对每个地址发 requests.get,超时 25 秒,伪装随机 User-Agent 并补 host 头,还把 Cloudflare 的 403/503 挑战页(_cf_chl、Ray ID:、cf-spinner-please-wait 等 20 多个特征串)判定为“通过”而非失效。这份“哪些站点会拦爬虫、哪些站点已经死了”的经验,是十年时间堆出来的,不是新清单能复制的。

按 README 当前内容统计,最需要外部数据的几个分类恰好密度最高:Development 220 条、Government 126 条、Geocoding 113 条、Games & Comics 111 条、Finance 97 条、Transportation 97 条。做小工具最常缺的地图、天气、假数据、政府开放数据,都在这几类里。

三、被重新发现,不等于被重新理解

社区文章里最常被复读的一句话是“1400+ 个 API,50+ 大类”。这句话在两个维度上都已经过期,而它恰好是理解这份清单的第一个坑。

误解一:条目数是个会漂移的数字

直接在仓库根目录数一遍:

python3 - <<'EOF'
rows = [[c.strip() for c in l.strip().strip('|').split('|')]
        for l in open('README.md', encoding='utf-8') if l.startswith('| [')]
print(len(rows))                      # 2226
print(len([r for r in rows if len(r) == 5]))  # 2109
EOF

2226 这个数字是错的。它把三类东西混在了一起:Index 之前 11 行只有 3 列的赞助位、MCP Servers 表里的 25 条记录,以及正文 2190 条 REST 条目。真正属于“免费公开 API”的是 2190 条,分类数是 51。表格列数也不整齐:2109 行是 5 列,105 行是 6 列,1 行是 7 列(Social 分类下的 Discord 那行末尾多了两个空列)。

更细的分布如下(仅统计 2190 条 REST 条目):

字段 取值分布
Auth No 1050 · apiKey 980 · OAuth 150 · X-Mashape-Key 6 · User-Agent 3 · 误写 `No` 1
HTTPS Yes 2101 · No 88 · 误写 `Yes` 1
CORS Unknown 1038 · Yes 892 · No 259 · 误写 `Unknown` 1

也就是说,社区文章里那句“优先挑 Auth = No”只对了一半:免鉴权条目确实占 48%,但同时满足 Auth=No、HTTPS=Yes、CORS=Yes——也就是“浏览器里能直接 fetch、不用注册、不怕混合内容”的零摩擦组合——只有 525 条,不到四分之一。而 CORS 一列有 47.4% 是 Unknown,这意味着你最需要确定性的那个字段,将近一半是空的。

误解二:“免费”不是一个字段

五列表格里没有价格列。它只有 Auth、HTTPS、CORS。所谓“免费”只是 CONTRIBUTING.md 对投稿者的准入要求:“完全免费,或至少有免费层,且不依赖购买设备/服务”。免费额度、速率上限、商用许可、是否需要信用卡,全都要回到各家文档里确认。

这一点在数据上留下了直接痕迹:同一个 URL 在不同分类里给出了互相冲突的元数据。

地址 出现位置 Auth HTTPS CORS
jsonplaceholder.typicode.com Development(L750) No Yes Yes
jsonplaceholder.typicode.com Test Data(L2368) No No Unknown
tastedive.com/read/api Entertainment(L1013) apiKey Yes No
tastedive.com/read/api Music(L1782) apiKey Yes Unknown
www.foaas.com Personality / Social No No / Yes Unknown
api.nasa.gov Science & Math(NASA / NASA InSight) No / apiKey Yes No / Yes

仓库自己的重复检测就在报这些地址。跑一次只查重复链接的快捷模式:

python3 scripts/validate/links.py README.md -odlc

输出是:

Found duplicate links:
https://isitdownstatus.com
https://tastedive.com/read/api
https://github.com/lukePeavey/quotable
https://api.nasa.gov
https://open-meteo.com

脚本以退出码 1 结束。这不是 bug,而是把 Markdown 当数据库用必然要付的代价:表格没有主键,没有唯一约束,同一条记录可以以两种口径存在两个分类下。NASA 与 NASA InSight 尚可解释为两个端点,JSONPlaceholder 的 Yes/Yes 与 No/Unknown 则纯粹是两次投稿时的事实不一致。新读者如果把它当权威数据库直接取字段,就会把这类历史遗留当成服务本身的属性。

误解三:“校验通过”不等于“整份清单可信”

这是最容易被跳过的一点。项目自带格式校验,于是很多人默认“能合并进来的行就是对的”。但把校验器打开看,会发现它校验的是约定,不是事实。

format.py 顶部把规则写死了:

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

num_segments = 5
min_entries_per_category = 3
max_description_length = 100

它做的事是:标题必须是 TITLE 形式、描述首字母大写且不以标点结尾、不超过 100 字符、Auth 必须带反引号且落在枚举内、每个分类至少 3 条、分类内按字母序、单元格两侧各留一个空格。

而现在拿它跑当前 README,会得到成百条报错,退出码 1。摘录几条有代表性的:

(L011) APIs Covered Under APILayer Suite! category is not alphabetical order
(L043) entry does not have all the required columns (have 3, need 5)
(L064) Transport is not a valid HTTPS option
(L2330) `Yes` is not a valid HTTPS option

原因很清楚:脚本假设“### 之后的一切都是 5 列 REST 表”。于是顶部的赞助位被当成 3 列的 API 条目,MCP Servers 表被按 HTTPS/CORS 的枚举去校验它的 Transport/Install 列。此外还有 12 条描述超过 100 字符(最长 128 字符),以及至少 3 处把枚举值也套上了反引号的手误。

这不必然说明仓库的 CI 是红的——workflow 只在 push/PR 到 master 时触发,合并进来的大多是单行新增,增量改动很容易通过;它说明的是另一件更重要的事:校验器覆盖的是“新增行长得对不对”,不是“存量数据是不是真的”。CORS 标了 Yes 到底是不是真的允许跨域,HTTPS 标了 Yes 证书会不会过期,脚本一概不管。Unknown 高达 1038 条,本身就是这种“只校验格式、不校验事实”的直接产物——不确定就填 Unknown,反正格式合法。

还有一层更隐蔽的边界:links.py 的 find_links_in_file 从 ## Index 开始截取内容:

readme = file.read()
index_section = readme.find('## Index')
if index_section == -1:
    index_section = 0
content = readme[index_section:]

也就是说,每天定时巡检的范围只有 Index 之后的正文。顶部赞助区的链接、MCP Servers 表里的 25 条安装地址,全部不在巡检范围内。清单的可信边界,是被这几行代码画出来的,而不是被 README 的组织结构画出来的。

四、下一个十年:从端点清单长成能力清单

这个仓库其实已经给出了自己的答案,只是大多数人还停留在旧版本的文章里。

README.md 在 ## Index 之前新增了一张完全不同的表:MCP Servers,列头是 Name | Description | Auth | Transport | Install,目前 25 条。CONTRIBUTING.md 为此单开了一节,并解释了字段替换的原因:MCP server 是安装进客户端、而不是通过 HTTP 调用的,所以 HTTPS 和 CORS 对它不适用;Transport 只接受 stdio、HTTP、SSE(可逗号分隔),Install 则链接到 Cursor、Anthropic、Glama 等实际收录它的市场,未上架就写 –。

这次结构变更的信息量,远大于任何一次条目新增:

  • 抽象从“HTTP 端点”变成了“agent 可调用的能力”;
  • 元数据从传输层(HTTPS/CORS)换成了分发层(Transport/Install);
  • Auth 枚举被复用,说明鉴权成本仍是跨时代不变的度量;
  • 用 – 明确表示“未上架是正常状态,不计入负面评价”,这是一条很克制的数据设计。

但工具没有跟上。format.py 仍是 num_segments = 5 的硬编码,https_keys 与 cors_keys 仍是二元/三元枚举,所以每一条 MCP 记录都会被误判一次。这就是“下一个十年”最真实的工程债:内容结构已经演进了,校验层还停在上一代。

如果要往下修,方向并不复杂,而且都能在现有代码上小步完成:把 num_segments 与枚举从模块级常量改成按 section 分派的 schema(### 之后的第一张表用 REST schema,## MCP Servers 下用 MCP schema);把 ok/not ok 的判定从“格式是否合法”扩展到“同一 URL 的元数据是否自洽”,用现成的 check_duplicate_links 结果做冲突检测,而不只是数量检测;再把 README 从“手工维护的源文件”改成“由结构化数据生成的产物”,格式校验就自然退化成生成器的一部分。在这之前,任何基于这份清单做二次产品的人,都应该自己再跑一遍可访问性抽查,而不是相信一个 Yes。

十年过去,这个仓库解决的问题其实没有变:在“我需要某类数据”和“我知道该调哪个接口”之间,填一张足够便宜的对照表。它之所以一次次被当成新发现,是因为每一代新读者都要重新走一遍这段路;而它之所以值得被重新理解,是因为表格里那三列枚举,是十年里无数人用失效链接和跨域报错换来的经验值——这些东西不会因为一篇文章的标题而更新,只会因为你亲自跑一次 format.py 和 links.py 而显形。

登录后查看全文
public-apis