企业官网建设流程全解析

• 文档

本指南围绕当前仓库根文档 README.md 展开，系统讲解 public-apis 这一社区人工维护的免费公共 API 精选集的组织方式：从 50+ 领域分类的索引体系、每条 API 条目的五大字段规范，到 MCP（Model Context Protocol）服务器专区，再到配套的格式校验、链接健康检查脚本与单元测试的完整使用流程。读完本文，你将能快速定位任意领域的可用公共 API、准确读懂并编写符合仓库规范的 API 条目，并能在本地复现仓库维护者使用的自动化校验工具链。

项目定位：一份"社区人工精选"的免费 API 清单

README 开篇即明确了仓库的定位：由社区成员与 APILayer 团队共同人工维护（manually curated）的公共 API 集合，覆盖众多领域，可直接用于开发者自己的产品。它并非自动抓取的目录，而是经过筛选与格式约束的质量清单，核心标准是"免费可用"：要求被收录的 API 具有完整免费访问权或至少提供免费档位（free tier），且不依赖购买实体设备才能使用（详见 CONTRIBUTING.md 顶部说明）。

与之配套，仓库还提供了完整的工具链来保证清单质量，集中在 scripts 目录：

scripts │ github_pull_request.sh # PR 变更的链接校验脚本 │ requirements.txt # validate 包的依赖 ├───tests # validate 包的单元测试 │ test_validate_format.py │ test_validate_links.py └───validate # 校验包 format.py # Markdown 表格格式校验 links.py # 链接重复与可用性校验

全局索引：50+ 领域的分类导航

README 在正文中段（## Index之后）维护了一张完整的领域导航表，每个分类既是章节锚点，也是该领域的 API 表头。当前仓库共收录约 50 个分类，覆盖从基础开发工具到垂直行业数据的方方面面：

每个分类下都遵循统一表格结构。以 Animals 分类为例，其结构为：

### Animals API | Description | Auth | HTTPS | CORS |:---|:---|:---|:---|:---| | Cat Facts | Random cat facts | No | Yes | Yes | | Dogs | Based on the Stanford Dogs Dataset | No | Yes | Yes | | The Dog | A public service all about Dogs... | `apiKey` | Yes | No |

各分类的典型条目（仅举代表性示例，均出自 README）：Weather 分类下的 OpenWeatherMap（apiKey）与 wttr.in（支持终端输出与 JSON）；Cryptocurrency 下的 CoinGecko（无需鉴权）；Geocoding 下的 IPstack（apiKey）；Test Data 下的 JSONPlaceholder（无鉴权、适合原型测试）。你既可以在 README 中按领域浏览，也可以直接 Ctrl+F 搜索 API 名称快速定位。

条目字段规范：五列表格的取值约束

README 中每条 API 条目均固定为五列，这是仓库数据质量的核心契约。字段含义与取值规范如下（规范来源：CONTRIBUTING.md 的 "Formatting" 章节，并与 格式校验脚本 的常量一一对应）：

其中Auth字段的五种取值语义（见 CONTRIBUTING.md）：

• OAuth—— API 支持 OAuth 授权流程；
• apiKey—— API 使用私有的密钥字符串/令牌进行鉴权；
• X-Mashape-Key—— 需要发送指定名称的请求头；
• No—— API 无需任何鉴权即可调用；
• User-Agent—— 需要随请求发送 User-Agent 头。

CORS字段的意义在于提示该 API 能否被浏览器前端直接调用：CONTRIBUTING.md 明确提醒，"缺少正确的 CORS 配置时，API 只能服务端使用"（Without proper CORS configuration an API will only be usable server side）。因此Unknown是一个诚实且被允许的取值——不确定时如实标注，而不是猜一个Yes。

格式校验脚本 format.py 将这些规范固化成了可执行的规则，核心常量与检查点包括：

• 枚举常量：auth_keys、https_keys、cors_keys 直接对应上述合法取值；
• 条目约束：num_segments = 5、min_entries_per_category = 3（每个分类至少 3 条）、max_description_length = 100；
• 逐行检查逻辑：check_file_format 会依次校验——分类头必须登记在 Index 索引中、每分类条目数不低于最小值、每个字段列两侧恰好各 1 个空格、缺失列数检查，再对每条记录执行 check_entry 的五项子校验（标题语法、描述、鉴权、HTTPS、CORS）；
• 全局检查：check_alphabetical_order要求每个分类内的 API 按名称字母序排列，乱序会直接报错退出。

MCP Servers 专区：为 AI Agent 准备的独立入口

README 在## MCP Servers章节为 Model Context Protocol 服务器单独设置了专区，这是它与普通 REST API 条目的关键差异：MCP 服务器不是被"调用"的 HTTP 接口，而是被安装进 AI 客户端（如 Claude、Cursor、VS Code）的工具。因此其表格字段也完全不同：

该专区的字段规范在 CONTRIBUTING.md 中有专门说明：

• Auth字段沿用普通 API 的同一套合法取值（OAuth、apiKey、X-Mashape-Key、No、User-Agent）；
• Transport目前仅接受三种取值：`stdio`（作为本地子进程通过标准输入输出运行）、`HTTP`（通过流式 HTTP 可达）、`SSE`（传统 Server-Sent Events 传输），支持多种时用逗号分隔，如`stdio`, `HTTP`；
• Install字段链接到该服务器实际发布的市场（仓库当前跟踪 Cursor、Anthropic、Glama 三个市场），若尚未在任何市场收录则用–标注，这是正常状态、不扣分；但只允许链接真实存在的市场页面，指向 404 页面的链接会导致 PR 被关闭。

链接健康检查：从格式到可达性的双重保障

除了表格格式，仓库还通过 links.py 对 README 中所有链接做两层检查：

1. 重复链接检测：脚本从 README 的## Index章节开始提取全部 URL（见 find_links_in_file，忽略 Index 之前的广告与说明区域），再去掉尾部/后比较，发现重复即列出并退出码 1（见 check_duplicate_links）。

2. 链接可达性检测：对每条链接发起真实 HTTP 请求（见 check_if_link_is_working），技术要点包括：

• 25 秒超时，并携带随机挑选的浏览器 User-Agent（部分托管服务会拦截非白名单 UA，见 fake_user_agent）；
• 同时发送匹配的host请求头（从 URL 解析主机名，见 get_host_from_link）；
• 针对 Cloudflare 防护的误报处理：当状态码为 403/503 且响应头Server: cloudflare时，进一步在 HTML 中查找 "Cloudflare"、"We are checking your browser..."、cf-spinner等特征标志，命中则视为"链接其实可用"而非错误（见 has_cloudflare_protection）；
• 错误分类清晰：ERR:CLT（HTTP ≥400）、ERR:SSL（TLS 错误）、ERR:CNT（连接失败）、ERR:TMO（超时）、ERR:TMR（重定向过多）、ERR:UKN（未知异常）。

此外，github_pull_request.sh 用于 CI 中对 Pull Request 的 diff 增量行单独做链接校验：它拉取patch-diff.githubusercontent.com的补丁、提取以+开头的增行，仅对新添加的链接执行校验，从而把全量扫描的耗时隔离在 PR 之外。

本地复现校验：命令行实操

按 scripts/README.md 的说明，你可以在本地完整复现这套校验流程。前置条件是需要安装 Python 与 pip，随后安装依赖：

python -m pip install -r scripts/requirements.txt

在仓库根目录对 README 执行格式校验：

python scripts/validate/format.py README.md

执行链接校验（注意链接数量庞大、全量可达性检查可能耗时较长）：

python scripts/validate/links.py README.md

若只想检查重复链接而跳过可达性检查，可加-odlc（即--only_duplicate_links_checker的缩写）：

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

运行整套单元测试（需先进入 scripts 目录）：

cd scripts python -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.py"

测试用例视角：校验规则的"验收标准"

校验逻辑的正确性由 scripts/tests/test_validate_format.py 与 scripts/tests/test_validate_links.py 两个测试文件保障，它们本身就是仓库规范的"可执行文档"。例如格式测试覆盖了：

• 标题语法：A(https://www.ex.com)这种残缺写法会被拒绝（Title syntax should be "[TITLE"）；
• 标题命名：A API会被拒绝（Title should not end with "... API"）；
• 描述质量：首字母未大写、以标点结尾、超过 100 字符分别触发对应错误；
• 字段枚举：yes/no/Unknown等大小写或取值错误分别触发 Auth/HTTPS/CORS 的非法取值报错；
• 结构性约束：分类头未登记到 Index、分类条目不足 3 条、缺少必需列、列间空格不足 1 个，均有对应错误消息。

链接测试则覆盖了 URL 正则提取（带参数与锚点的合法链接 vshttps:/example.com等非法写法）、重复链接判定、User-Agent 生成、host 解析以及 Cloudflare 防护特征检测（通过构造 403/503 响应模拟验证，见 test_validate_links.py）。

快速上手：三条实操路径

1. 纯使用者：打开 README.md，通过## Index定位领域分类，直接浏览对应表格；阅读条目时重点看Auth（是否需要密钥）与CORS（能否浏览器直连）两列，结合HTTPS列判断传输安全级别，即可快速评估某 API 是否适合你的项目。
2. AI Agent 开发者：优先查看## MCP Servers专区，按Transport（stdio 或 HTTP）与Install（市场渠道）选择合适的 MCP 服务器安装进客户端。
3. 贡献者：阅读 CONTRIBUTING.md 掌握条目格式与 PR 规范（每条新增一个 API、保持字母序、描述 ≤100 字符、PR 标题形如Add Api-name API等），提交前先在本地跑一遍format.py与links.py校验，并确认 CI 构建通过。

附：许可证与延伸阅读

仓库采用 MIT 许可证。与此主题强相关的仓库内文档还有：用于理解条目编写规范的 CONTRIBUTING.md、用于掌握校验工具链使用方法的 scripts/README.md，以及可直接阅读并运行的校验实现 scripts/validate/format.py 与 scripts/validate/links.py。如需提交变更，可参考 README 中 "Get Involved" 章节的指引并遵循贡献规范操作。

• 文档