开发原型和写 AI 工具函数缺数据源?聊聊 GitHub 上那个维护了上千个免费接口的 public-apis

平时写个人项目、做黑客松 Demo、验证某个前端组件，或者给大语言模型编写 Function Calling / MCP（Model Context Protocol）工具函数时，我们经常会卡在一个很具体的问题上：去哪里找真实、可直接调用的外部接口？

自己手写 Mock 数据固然快，但静态 JSON 很难模拟真实网络环境下的分页、延迟、动态参数和边界状态；而如果去接入商业云厂商或大型平台的官方 SDK，往往要经历注册开发者账号、实名认证、绑定信用卡、申请配额等一整套流程——有时只是想花半小时写个天气查询或汇率换算的小工具，光走审批流程就要折腾大半天。

如果你也有这类找数据源的困扰，GitHub 上的 public-apis/public-apis 仓库值得放进常用书签里。它不是一个软件框架，而是一份由开源社区长期共同维护的免费公共 API 目录清单。

一、项目基本信息与核心定位

先通过一张简表快速了解这个项目的概况：

简单来说，public-apis 解决的是**“信息不对称”和“筛选成本高”**两个痛点。

互联网上其实散落着大量由政府机构、科研组织、开源社区或商业公司开放的免费 API（涵盖完全免费和提供免费额度 Free Tier 两类），但通过搜索引擎挨个找，经常会遇到文档过期、接口早已停服、或者调通到最后一步才发现不支持跨域（CORS）等问题。public-apis 将这些接口按行业与用途进行了归类，并用统一的五维表格把开发者最关心的前置技术指标直接标了出来。

二、目录结构与核心设计拆解

打开 public-apis 的 README，看不到花哨的宣传语，主体就是一套高度结构化的索引表。之所以能成为几十万开发者常备的参考手册，主要得益于它在信息组织和仓库治理上的几个务实设计：

1. 覆盖 50+ 垂直领域的分类体系

项目将收录的 1400 多个接口划分成了 50 多个具体分类（Categories）。除了常见的天气（Weather）、金融加密货币（Cryptocurrency & Finance）、地理编码（Geocoding）之外，还有很多非常垂直且有趣的领域：

• •开发与工程测试类
  ：测试数据生成（Test Data）、代码分析、持续集成、网络工具（IP 查询、DNS 解析、端口扫描）、URL 短链服务等；
• •学术与公共数据类
  ：开放科学数据（Science & Math）、NASA 航天数据、图书文献（Books）、政府公开数据（Government）、医疗健康数据集等；
• •内容与多媒体类
  ：字典与翻译（Dictionaries）、新闻聚合、音乐曲库、影视动漫元数据、免费图库与壁纸、表情包生成等；
• •日常生活与工具类
  ：汇率换算、节假日日历、邮政编码查询、公共交通时刻表、垃圾邮件检测等。

2. 一目了然的五维技术指标

在每个分类下，所有 API 都严格按照统一的 5 列 Markdown 表格呈现。这 5 个字段直接决定了你在技术选型时要不要点进去看文档：

这几个字段对实际开发非常友好。比如你想写一个纯静态部署在 GitHub Pages 或 Vercel 上的前端小工具，不想搭后端中转服务，那么在表里直接筛选 Auth: No + HTTPS: Yes + CORS: Yes 的接口，拿过来就能直接用 fetch 调通，省去了大量试错时间。

3. 背后的 Python 自动化校验机制（为什么仓库主语言显示是 Python？）

很多人第一次看到这个仓库时会好奇：明明是一个 Markdown 文档清单，为什么 GitHub 语言统计显示主要语言是 Python？

点进仓库的 scripts/ 目录就能看到原因。对于这种收录上千个外部链接的列表型项目，最大的敌人就是“链接腐烂（Link Rot）”和“格式混乱”。为了保证 PR 质量，维护团队用 Python 编写了一套完整的自动化校验工具（含单元测试）：

• •格式检查（validate/format.py）
  ：强制检查分类是否按字母序排列、每个字段的长度限制、表格列数与分隔符是否规范、描述首字母是否大写且末尾不带句号、Auth 字段是否属于合法的枚举值等；
• •链接有效性探测（validate/links.py）
  ：自动检查是否存在重复提交的链接，并发起真实网络请求检测目标地址是否返回 404/500 等异常状态码，同时带有针对 Cloudflare 防护页面的识别逻辑。

每次有贡献者提交 Pull Request，GitHub Actions 都会自动跑一遍这套 Python 校验脚本。这种“用工程化手段维护文档仓库”的做法，也是我们自己管理团队内部知识库或开源 Awesome 系列清单时非常值得借鉴的经验。

三、快速上手与典型使用场景

public-apis 不需要安装任何依赖，最直接的用法就是在 GitHub 页面按 Ctrl + F（或 Cmd + F）搜索关键词。但在实际工程开发中，我们可以结合具体场景把它用得更顺手。

场景 1：零配置快速联调（以免鉴权 API 为例）

当你需要测试 HTTP 客户端、练习异步编程，或者给前端列表组件填充真实数据时，可以优先挑表格里标注 Auth: No 的接口。例如里面收录的几个经典免 Key 接口：

• •GitHub / iTunes / 维基百科公开搜索接口
• •Open-Meteo
  （免费开源天气 API，无需注册 Key）
• •ExchangeRate-API / Frankfurter
  （免费开源汇率查询接口）
• •Dog API / Cat Facts / PokeAPI
  （常用于前端列表、卡片瀑布流与分页组件调试）

以清单中收录的开源汇率接口 Frankfurter 和天气接口 Open-Meteo 为例，在终端直接用 curl 就能拿到结构清晰的 JSON 响应：

# 1. 查询最新美元兑人民币、欧元汇率（免 Key、支持 HTTPS 与 CORS）curl -s "https://api.frankfurter.app/latest?from=USD&to=CNY,EUR" | jq .# 返回结果示例：# {#   "amount": 1.0,#   "base": "USD",#   "date": "2026-10-30",#   "rates": {#     "CNY": 7.1245,#     "EUR": 0.9218#   }# }# 2. 查询北京当前实时气温与风速（Open-Meteo，免 Key）curl -s "https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074&current_weather=true" | jq .

场景 2：用脚本在本地按条件筛选接口

如果你经常需要按特定条件（比如“必须免鉴权 + 支持跨域 + 支持 HTTPS”）批量查找某类接口，可以把仓库克隆到本地，用几行 Python 代码把 README 解析成自己的本地检索小工具：

git clone --depth 1 https://github.com/public-apis/public-apis.gitcd public-apis

编写一个简单的筛选脚本 find_api.py，按关键词和条件过滤出可直接用于纯前端项目的接口：

import reimport sysdefsearch_public_apis(readme_path="README.md", keyword="", require_no_auth=True, require_cors=True):withopen(readme_path, "r", encoding="utf-8") as f:        lines = f.readlines()    current_category = ""# 匹配 Markdown 表格行：| [Name](URL) | Description | Auth | HTTPS | CORS |    row_pattern = re.compile(r"^\|\s*\[([^\]]+)\]\(([^)]+)\)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|"    )    results = []for line in lines:if line.startswith("### "):            current_category = line.replace("### ", "").strip()continuematch = row_pattern.match(line.strip())ifnotmatch:continue        name, url, desc, auth, https, cors = [m.strip() for m inmatch.groups()]        auth_clean = auth.replace("`", "")# 过滤条件if require_no_auth and auth_clean.lower() != "no":continueif require_cors and cors.lower() != "yes":continueif https.lower() != "yes":continueif keyword.lower() notin (name + " " + desc + " " + current_category).lower():continue        results.append({"category": current_category,"name": name,"url": url,"desc": desc,"auth": auth_clean,"cors": cors        })return resultsif __name__ == "__main__":    kw = sys.argv[1] iflen(sys.argv) > 1else"weather"    matched = search_public_apis(keyword=kw, require_no_auth=True, require_cors=True)print(f"找到 {len(matched)} 个免鉴权、支持 HTTPS 与 CORS 的 [{kw}] 相关接口：\n")for item in matched[:10]:print(f"- [{item['category']}] {item['name']}: {item['desc']}")print(f"  文档地址: {item['url']}\n")

运行 python3 find_api.py weather 或 python3 find_api.py finance，就能立刻筛出符合纯前端直连要求的接口列表。

场景 3：作为 AI Agent / MCP Server 的工具数据源

这两年大家在开发大模型应用、自定义 GPTs、Dify 工作流或者编写本地 MCP Server 时，经常需要给模型挂载各种外部感知能力（比如查论文、查实时股价、查 IP 归属地、查节假日、获取某本书的 ISBN 信息）。

与其自己去写爬虫解析网页（不仅容易触发反爬，网页 DOM 结构一改代码就崩），不如先去 public-apis 对应的分类下搜一搜有没有现成的标准 RESTful 接口。标准 API 返回的 JSON 结构稳定、字段语义明确，只需把接口参数写成 JSON Schema 传给模型的 tools 参数，几分钟就能封装出一个高可靠性的 Agent 工具函数。

四、实际使用中的几点注意与避坑建议

虽然 public-apis 极大地方便了开发检索，但毕竟里面收录的是全球各地第三方提供的接口，在实际接入项目时，有几个工程细节需要注意：

1. 1.区分“玩具/测试级”与“生产级”接口
    清单中有很多接口是由个人开发者或小型开源组织用爱发电维护的。如果只是写个人工具、课程设计、技术验证 Demo，直接用完全没问题；但如果你的项目准备上线面向大量真实用户，务必仔细阅读目标 API 的服务条款（Terms of Service）和 SLA 说明，并做好降级兜底方案（Fallback），防止上游接口突然限流或停服导致你的应用白屏。
2. 2.注意速率限制（Rate Limiting）与本地缓存
    绝大多数标注为 Free 或 Auth: No 的公共接口都有严格的并发或基于 IP 的调用频率限制（例如每分钟 10~60 次请求）。在开发调试时，建议在代码里加上一层简单的本地文件缓存或内存缓存（比如用 Redis 或 Python 的 functools.lru_cache / requests-cache），避免在热重载调试页面时因为循环请求被对方服务器封禁 IP。
3. 3.不要在前端代码中硬编码 apiKey
    对于表格中标注 Auth: apiKey 的接口，哪怕申请的是免费额度，也尽量不要把 Key 直接写在纯前端代码并推送到公开仓库。一方面容易被 GitHub 爬虫扫走滥用导致账号被封，另一方面如果该账号后续绑定了付费方式，会有产生意外账单的风险。涉及 Key 的请求建议统一通过服务端 API 路由或 Cloudflare Workers 等轻量级无服务器函数中转，并在环境变量中配置密钥。
4. 4.CORS 为 No 或 Unknown 时的处理方式
    如果你在浏览器端直接调用某个 API 遇到跨域报错，看一眼表格里的 CORS 列。如果是 No，说明目标服务端没有配置 Access-Control-Allow-Origin 响应头。此时不要在前端死磕，直接在本地开发环境配一层 Vite/Webpack Proxy，或者部署时用 Nginx / Serverless 函数做一层简单的反向代理转发即可解决。

小结

public-apis/public-apis 本身并没有复杂高深的代码架构，但它切中了开发者日常最高频的需求之一。不管是用来练手学一门新语言的网络库、给前端作品集找真实动态数据，还是为 AI 智能体扩展外部工具能力，这份经过社区脚本持续校验的接口名录都能帮你省下不少到处搜索和踩坑的时间。建议把它收藏进浏览器书签，需要找外部数据时随时翻一翻。