自己写聚合脚本,还是直接翻清单:两条找接口路径的成本对比

原创2026-11-02 18:46:581,822 阅读
文章标签:文档知识库

自己写聚合脚本,还是直接翻清单:两条找接口路径的成本对比

"找个免费 API 用一下"这句话,背后其实藏着两个完全不同的工程决策:一是去清单里翻,二是自己写个采集聚合脚本。前者看起来只是打开一个 Markdown 文件按 Ctrl+F,后者听起来像是"顺手写几十行 Python"。但真正落到项目里,两者的成本结构完全不在同一个维度上。

这篇文章不讨论哪种做法更"优雅",只做一件事:把两条路径的成本拆成可以数的项——条目规模、字段可信度、去重难度、验活耗时、增量维护开销,并用 public-apis 这个仓库里真实存在的脚本和当前 README 的实测数据来支撑结论。读完你应该能判断:你手上这个项目,该翻清单,还是该写脚本,还是走第三条路。

先看清清单本身是什么资产

public-apis 不是一个 API 网关,也不是一个可查询的服务,它就是一个 2720 行、约 316 KB 的 Markdown 文件 README.md。所有价值都压在这张表上。

对当前仓库做一次结构化统计(从 ## Index 段之后开始计数),可以得到几个关键数字:

指标 实测值
分类(### 小节) 51 个
表格数据行 2190 条
最大分类 Development,221 条
最小分类 Patent,5 条
不同域名数 1971 个
Auth 为 No(无需鉴权) 约 48%
HTTPS 为 Yes 约 96%
CORS 为 Unknown 约 47%

这组数字说明了清单的真实定位:它是一份"候选集",不是一份"可用集"。接近一半的条目不需要任何鉴权,可以直接 curl;但同样有接近一半的条目,在 CORS 这一列上写的是 Unknown——也就是说,清单自己承认它不知道。

字段定义写在 CONTRIBUTING.md 里,取值范围是封闭的:Auth 只接受 OAuth、apiKey、X-Mashape-Key、User-Agent、No;CORS 只接受 Yes、No、Unknown;HTTPS 只有 Yes 和 No。这种封闭枚举是清单最被低估的工程价值——它把"选型"从自然语言判断变成了四列枚举值的布尔组合。

看一条真实条目:

| [Cat Facts](https://catfact.ninja/) | Random cat facts | No | Yes | Yes |

四个字段连起来读,就是一句可以直接执行的结论:无鉴权、支持 HTTPS、支持跨域,浏览器端可以直接调。这是自建聚合脚本最难复制的部分——脚本能抓到 URL,但抓不到"这个 API 要不要注册申请 key"。

翻清单能省什么,不能省什么

能省的:初筛与否定

清单最省成本的地方不是"帮你找到能用的",而是"帮你快速排除不能用的"。

按 Auth=No + CORS=Yes + HTTPS=Yes 三个条件做交集,从 2190 条里筛出的候选,基本可以认为"浏览器端直连大概率可行"。这个筛选不需要发一个网络请求,纯文本匹配,毫秒级完成。

在 Linux/macOS 上甚至不需要写脚本:

awk -F'|' 'NF>=7 && $4 ~ /^ *No *$/ && $5 ~ /^ *Yes *$/ && $6 ~ /^ *Yes *$/ {print $2, $3}' README.md

这条命令的局限也很明显:它依赖表格列数固定,且 Description 里不能出现 |。所以真正常用的还是几行 Python:

import re

ROW = re.compile(
    r'^\|\s\[(?P<name>[^\]]+)\]\((?P<url>https?://[^)]+)\)\s*'
    r'\|\s(?P<desc>[^|]*)\|\s*(?P<auth>[^|]*?)\s*'
    r'\|\s*(?P<https>[^|]*?)\s*\|\s*(?P<cors>[^|]*?)\s*\|'
)

def rows(path):
    category = None
    with open(path, encoding='utf-8') as f:
        for line in f:
            if line.startswith('### '):
                category = line[4:].strip()
                continue
            m = ROW.match(line.rstrip())
            if m and category:
                yield category, m.groupdict()

for cat, r in rows('README.md'):
    if r['auth'] == 'No' and r['cors'] == 'Yes' and r['https'] == 'Yes':
        print(f"{cat}\t{r['name']}\t{r['url']}")

这段代码有一个必须注意的坑:当前 README 里 51 个分类中,有 50 个分类的表头行写成了 API | Description | Auth | HTTPS | CORS,缺少行首竖线,只有 2 处写成了标准的 | API | Description | ...。所以任何解析器都必须以"行首是否为 | ["作为数据行判据,而不能依赖表头。这就是清单路径的第一个隐性成本:格式是约定,不是契约。

不能省的:字段时效性与端点真实性

清单解决的是"去哪找",不解决"现在能不能用"。

我用清单里的真实条目标做了抽样验活:

条目 标注 实测
catfact.ninja No / Yes / Yes 200,可用
open-meteo.com No / Yes / Yes 200,可用
api.nasa.gov No / Yes / No 200,可用
thecatapi.com/v1/breeds apiKey / Yes / No 403,符合标注
fishwatch.gov/developers No / Yes / Yes 403,与标注不符

最后一行值得展开:FishWatch 在清单里被标为"无需鉴权",但实际请求其文档页返回 403。这不是清单作者写错了,而是站点侧的网关策略、UA 过滤、Cloudflare 挑战会随时间变化,而表格里的四列是静态文本。清单没有能力表达"这个 API 在 2026 年 10 月对 Python requests 的默认 UA 返回 403"这种状态。

还有一个更隐蔽的边界:清单里的 URL 是文档地址,不是调用地址。以 dog.ceo 为例,条目链接是 https://dog.ceo/dog-api/,真正的调用点是 https://dog.ceo/api/breeds/list/all。对文档页做健康检查得到 200,只能证明"这个项目还活着",不能证明"这个接口还能用"。这个区别决定了验活脚本到底在验什么。

自建聚合的四笔隐性账

如果决定自己写聚合脚本,成本会分布在四个环节。public-apis 仓库里恰好有一套现成的校验脚本,可以直接当作"成本证据"来读——因为维护方自己也在为这四件事付出代价。

第一笔:抓取与解析

自建聚合的第一步是采集源。你可以采 public-apis 本身,也可以采其他清单、API 市场、厂商文档。无论采谁,都会立刻遇到解析健壮性问题。

证据在 scripts/validate/format.py 里。这个格式校验器定义了明确的约束:

num_segments = 5
min_entries_per_category = 3
max_description_length = 100
anchor = '###'

它要求每个分类至少 3 条、描述不超过 100 字符、每列前后恰好 1 个空格、每个分类必须出现在 Index 里。规则很清晰。但用它在当前仓库上跑一遍:

python scripts/validate/format.py README.md

会输出 634 条错误,其中 234 条是 each segment must start and end with exactly 1 space,48 条是 Title syntax should be "TITLE",46 条是 :--- is not a valid Auth option。

这些错误的大部分来源不是"作者写错了",而是文档结构演进了,而校验器的假设没跟上:新增的 ## MCP Servers 段使用了 Name | Description | Auth | Transport | Install 五列格式,Transport 的取值是 `stdio`、HTTP、`SSE`,落到校验器眼里就变成了"HTTPS 值非法"。校验器还把 |:---| 分隔行当成了数据行,于是 :--- 被当成 Auth 值。

这就是自建聚合最真实的第一个成本:你写下的每一行解析逻辑,都是对上游格式的一次假设;上游每改一次结构,你就要改一次代码。而且这种失配是静默的——脚本不会崩,它只会给你一份错误的输出。

第二笔:去重

直觉上,去重是 len(set(urls))。实际不是。

public-apis 自己的去重实现放在 scripts/validate/links.py:

for link in links:
    link = link.rstrip('/')
    if link not in seen:
        seen[link] = 1
    else:
        if seen[link] == 1:
            duplicates.append(link)
        seen[link] += 1

它只做了一件事:去掉尾部斜杠后做字符串比较。用这套逻辑跑当前 README,得到 5 组重复:

  • https://isitdownstatus.com(同时出现在 Development 和 Monitoring 两个分类)
  • https://tastedive.com/read/api(Entertainment 与 Music)
  • https://github.com/lukePeavey/quotable(Quotes 与 Personality)
  • https://api.nasa.gov 与 https://api.nasa.gov/(仅差一个尾斜杠)
  • https://open-meteo.com 与 https://open-meteo.com/

前三条是同一服务被归入多个分类,这在语义上是合理的,但在聚合场景下就是三条重复记录。后两条是URL 规范化问题,rstrip('/') 恰好能兜住。

更难的是另一类重复:当前 2190 条条目分布在 1971 个域名上,其中 36 个域名承载了 255 条记录。github.com 有 113 条,rapidapi.com 有 28 条,documenter.getpostman.com 有 6 条。这些条目共享宿主域名但指向不同仓库或不同文档路径,字符串去重完全无效,必须做"服务身份"级别的归并——而服务身份没有稳定 ID。

如果只是去重 URL,成本很低;如果要按"服务"去重,就是一个人工或半人工的实体对齐问题。

第三笔:验活

这是自建聚合最容易低估的一笔,因为它看起来只是"发个 GET 请求"。

验活的核心实现在 scripts/validate/links.py 的 check_if_link_is_working():

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. 超时设为 25 秒。单条最长 25 秒,2192 条链路,最坏情况是 15 小时。
  2. 随机 UA + 强制 Host 头。因为部分托管服务会拦截非白名单 UA,不加这两项,你会得到大量假阴性。
  3. Cloudflare 白名单。has_cloudflare_protection() 匹配了 20 多个特征串(_cf_chl、Ray ID:、Checking your browser before accessing 等),只有 403/503 且 Server: cloudflare 且命中特征时才放行,避免把"人机验证页"误判为"接口已死"。

而调用方式是纯串行的:

for link in list_of_links:
    has_error, error_message = check_if_link_is_working(link)

我实测了 12 条链接的串行耗时:11.9 秒,平均 0.99 秒/条。按这个速率线性外推,全量 2192 条需要 约 36 分钟。这还是网络状况良好的情况,没有任何重试。

一个可用的并发版本只需要加十几行:

import sys
sys.path.insert(0, 'scripts')

from concurrent.futures import ThreadPoolExecutor
from validate.links import check_if_link_is_working

def probe(urls, workers=16):
    with ThreadPoolExecutor(max_workers=workers) as pool:
        for url, (bad, msg) in zip(urls, pool.map(check_if_link_is_working, urls)):
            print(url, 'OK' if not bad else msg)

probe(urls, workers=16)

把 36 分钟压到 3 分钟量级。但并发一上来,新的成本立刻出现:目标站点会把你当成爬虫,403 和 429 的比例显著上升。验活脚本从"测接口"变成了"测自己的出口 IP 信誉"。所以真实的验活成本不是 CPU 时间,而是限速策略设计:并发度、退避曲线、按域名分桶、失败重试次数,每一项都要调。

顺带一个边界:check_if_link_is_working() 判断的是 code >= 400 即失败。这意味着一个需要鉴权的正常端点返回 401/403 时,会被判为"链接已死"。这正是清单选择"只验文档页"的原因——文档页通常 200,而接口端点不一定。验活对象选错了,得到的是系统性偏差。

第四笔:更新

自建聚合最贵的不是第一次跑通,是第 100 次跑通。

public-apis 的做法值得直接借鉴,因为它把"更新"拆成了两条成本差异极大的路径。.github/workflows/validate_links.yml 是全量巡检,触发方式是定时任务:

on:
  workflow_dispatch:
  schedule:
    - cron:  '0 0 * * *'

每天 0 点跑一次全量。而 PR 场景走的是另一套逻辑,scripts/github_pull_request.sh:

DIFF_URL="$DUMMY_SCHEME://patch-diff.githubusercontent.com/raw/$GITHUB_REPOSITORY/pull/$GITHUB_PULL_REQUEST.diff"
curl -L "$DIFF_URL" -o diff.txt
cat diff.txt | egrep "\+" > additions.txt
python scripts/validate/links.py "$LINK_FILE"

它拉取 PR 的 diff,只保留新增行,然后只对新增行跑链接校验。一次 PR 通常只加 1 条 API(CONTRIBUTING.md 明确要求 Add one link per Pull Request),所以校验成本是 1 条链接,而不是 2192 条。

这是整篇文章里最重要的一条成本结论:全量验活是分钟到小时级,增量验活是秒级。聚合系统的可维护性,取决于你能否把 99% 的操作变成增量操作。

还有一个容易忽略的细节:find_links_in_file() 的读取范围是从 ## Index 开始的:

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

当前 README 全文有 2298 个 http(s) 链接,而脚本实际检查 2192 个,差值 106——正好等于 ## Index 之前的链接总数(赞助商区块 9 条 + MCP Servers 段 25 行里的 57 个链接等)。也就是说,MCP 段新增的条目完全不在每日验活范围内。

这不是 bug,而是一个明确的设计取舍:验活范围被限定在"传统 REST API 表格"。但它提醒你——任何时候看到"清单里的链接都验过了"这句话,都要追问一句:验的是哪一段。

混合方案:用清单做初筛,用脚本做候选验活

把上面的成本项摊开之后,第三条路的轮廓就很清楚了:不要二选一,而是让清单承担它最擅长的事(结构化初筛),让脚本只处理被筛出来的少量候选。

流程分三步:

第一步,用清单收敛候选集。 按你的硬约束做布尔过滤。比如做纯前端项目,条件就是 Auth=No、CORS=Yes、HTTPS=Yes;做后端服务,CORS 可以直接忽略,候选池会大得多;需要代表用户操作数据,才需要 OAuth。这一步的成本是毫秒级,且不产生任何网络请求。

第二步,只对候选做增量验活。 假设筛出 40 条,用 16 并发跑一遍,耗时在秒级。此时应该验的不是文档页,而是真实调用端点——但清单只提供文档链接,所以这一步需要人工或半自动地从文档里提取一个 endpoint。这是混合方案唯一无法自动化的环节,也是最值得投入的环节,因为它同时验证了"接口存在"和"参数形态符合预期"。

第三步,把 CORS 从标注变成实测。 清单里 47% 的条目是 Unknown,这个数字意味着"翻清单"在前端场景下有一半的概率会踩空。一条命令就能拿到确定答案:

curl -sSI -H 'Origin: https://example.com' https://catfact.ninja/fact \
  | grep -i '^access-control'

有 access-control-allow-origin 响应头,才是真的支持跨域;没有,就只能在服务端调用。这一步的成本是每条 1 个请求,但它把"未知"变成了"已知",比任何标注都可靠。

这个混合方案的总成本可以粗略估成:清单检索 1 分钟 + 候选验活 N×1s/并发度 + CORS 实测 N 次请求。对于 N=40、并发 16 的场景,是分钟级的一次性投入,而不是全量 2192 条的 36 分钟。

什么规模该选哪条路

把结论收敛成一张决策表:

场景 推荐路径 核心理由
一次性原型、Hackathon、课程作业 直接翻清单 只需 1–3 个接口,自建脚本的固定成本永远收不回来
长期项目,稳定依赖 5–20 个接口 清单初筛 + 手工维护白名单 接口数量少,人工维护白名单比维护采集管道便宜
需要按业务条件动态检索接口 清单初筛 + 增量验活脚本 检索逻辑会变,但采集源不变,脚本只需处理候选
对外提供 API 检索服务、需要 SLA 自建聚合,但照抄清单的 schema 你需要自己承担时效性责任,字段枚举必须和上游对齐

判断标准其实只有一个:你的接口集合是"一次性消费"还是"持续运营"。一次性消费,清单的静态文本就是最优解,因为它把 2190 条记录的组织成本分摊给了上千个贡献者。持续运营,你就必须自己承担验活和更新,因为清单不会为你的可用性负责——它连自己的 MCP 段都没纳入每日巡检。

如果最终选择自建,有一条经验值得记住:不要重新设计字段,直接沿用 Auth / HTTPS / CORS 这套三列枚举。它的价值不在于精确,而在于封闭——封闭的枚举才能做布尔过滤,布尔过滤才能把"找接口"从人工判断降级成脚本可执行的操作。这套 schema 是 public-apis 沉淀下来最耐用的东西,比那 2190 条记录本身更值得复用。

登录后查看全文
public-apis