PostgreSQL Buildfarm 终于有了查询 API，不用再爬网页了

PostgreSQL Buildfarm 是社区持续集成的基础设施——几十个成员在不同平台、不同分支上跑构建和测试，结果汇总到 Buildfarm 数据库。多年来，想拿这些数据的人只有一个办法：爬网页。Andrew Dunstan 最近收到同事询问，才发现确实没有正式 API，于是借助 Claude Code 动手写了一个，现在已经上线。

为什么需要这个 API

Buildfarm 网页展示的是人读的信息，但不少开发者需要机器读的数据——做仪表盘、跑统计、触发告警。过去大家各写爬虫，解析 HTML 结构，一旦页面改版就全崩。一个稳定的查询 API 直接解决了这个问题：数据格式固定、调用方式标准、不怕前端重构。

API 能查什么

根据 GitHub 上的 API 文档，核心查询围绕 Buildfarm 的两个维度展开：

• 成员（member）：每个构建机器的名称，比如 crake、mandrill。
• 分支（branch）：PostgreSQL 的各开发分支，比如 master、REL_16_STABLE。

你可以查某个成员在某个分支上的最新构建状态，也可以查更宽范围的历史数据。返回的是结构化 JSON，不再需要从 HTML 表格里硬抠。

实际调用示例

最典型的用法：查某个成员在指定分支上的最新状态。Dunstan 给出的例子是查 crake 在 master 分支上的情况。

用 curl 直接请求：

# 查询成员 crake 在 master 分支上的最新构建状态
curl -s "https://buildfarm.postgresql.org/api/query?member=crake&branch=master&limit=1" | python3 -m json.tool

如果你想在脚本里批量查多个成员，可以这样：

#!/bin/bash
# 批量查询多个成员在 master 分支上的最新状态
MEMBERS="crake mandrill batfish coypu"

for m in $MEMBERS; do
  echo "=== $m ==="
  curl -s "https://buildfarm.postgresql.org/api/query?member=$m&branch=master&limit=1"
  echo
done

用 Python 写一个轻量监控也很直接：

import requests
import sys

BUILDFARM_API = "https://buildfarm.postgresql.org/api/query"

def latest_status(member: str, branch: str = "master") -> dict:
    """查询指定成员在指定分支上的最新构建状态"""
    resp = requests.get(
        BUILDFARM_API,
        params={"member": member, "branch": branch, "limit": 1},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    member = sys.argv[1] if len(sys.argv) > 1 else "crake"
    branch = sys.argv[2] if len(sys.argv) > 2 else "master"

    data = latest_status(member, branch)
    for record in data:
        status = record.get("status", "unknown")
        build_date = record.get("snapshot", "N/A")
        print(f"{member} @ {branch}: status={status}, date={build_date}")

运行方式：

python3 buildfarm_check.py crake master

注意：以上 URL 和参数格式基于 API 文档的描述，实际端点和参数名请以 GitHub 上的 API.md 为准，发布前可能有小调整。

从爬虫迁移到 API 的注意事项

如果你之前在爬 Buildfarm 网页，迁移时留意几点：

• 字段映射：HTML 页面上的显示名称和 JSON 里的键名不一定一致，先对照一两条数据确认映射。
• 频率控制：API 虽然比爬虫友好，但 Buildfarm 是社区资源，别高频轮询。做监控的话，5 分钟一次已经足够。
• 缺失数据：API 返回的结构可能不包含网页上的所有信息（比如某些装饰性字段），确认你需要的字段确实有。

还能怎么扩展

Dunstan 明确表示想听反馈——API 刚上线，功能范围还在探索。几个方向值得考虑：

• 失败构建的聚合查询：按平台、按分支统计最近 N 天的失败率，对发布决策很有价值。
• 历史趋势：某个成员的构建时长变化，帮助发现性能退化。
• Webhook / 通知：构建失败时主动推送，而不是被动轮询。
• 跨分支对比：同一成员在不同分支上的状态一览。

如果你有具体需求，去 GitHub 提 issue 或直接联系 Dunstan，这个 API 的下一步形状很大程度上取决于用户反馈。

小结

一句话：如果你之前在爬 Buildfarm 页面，现在可以停了——换成 API 调用，更稳、更快、更体面。