freehire 的 Google 招聘源适配器:无头浏览器之外,如何从服务端渲染页面里提取 3600+ 岗位
freehire 的 Google 招聘源适配器:无头浏览器之外,如何从服务端渲染页面里提取 3600+ 岗位
本文以 freehire 仓库中归档的 OpenSpec 变更 2026-06-17-google-careers-source 的提案文档为主体,结合 internal/ingest/sources/google.go 的最终实现与配套测试,完整拆解"把 Google 官方招聘目录接进 freehire 共享抓取池"这一工程问题:为什么旧 JSON API 失效后 Google 曾被标记为"blocked"、新的服务端渲染页面里 AF_initDataCallback 内嵌 JSON 是如何被定位与解析的、逐位( positional )字段映射如何组织、分页终止条件如何设计,以及 fixture 测试如何为脆弱的布局打上"钉子"。读完后,你能掌握一套"无 API 的大型公司招聘站接入"的完整方法论:DOM 定位脚本块、正则隔离 JSON 数组、typed 位置访问器、降级守卫与 fixture 回归测试。
1. 背景:为什么 Google 是一个"高价值但曾被判定 blocked"的源
提案文档(openspec/changes/archive/2026-06-17-google-careers-source/proposal.md)的 Why 部分交代了立项动机:
- Google 官方招聘站(
www.google.com/about/careers/applications/jobs/results)列有约 3,640 个在招岗位; - 旧的公开接口
careers.google.com/api/v3/search已下线(404),因此早期可行性探测把 Google 标记为"blocked"; - 重新探测发现新站点是服务端渲染的:每个列表页都把完整的岗位载荷内联在一段
AF_initDataCallback({key:'ds:1', data:[…]})的<script>块中——不需要无头浏览器、不需要登录、没有 GraphQL persisted query。
这三点合起来意味着 Google 可以作为一个"干净的高价值单公司源"接入,与仓库中已有的 uber/amazon 等 boardless(无租户看板 id)单公司适配器并列,进入 freehire 的共享抓取池。
值得强调的是提案中划定的边界(Non-Goals,见 design.md):
- 不用无头浏览器、不用代理、不用鉴权;
- 不新增环境变量、数据库列或迁移;
- 不支持按查询词搜索——抓取走的是"全量目录"(空查询),这正是 ingest 管线所需的行为。
2. 在 freehire 源适配器体系中的位置
freehire 的源适配器注册表位于 internal/ingest/sources。每个适配器实现 Source 接口,其定义在 source.go:
// Source adapts one job-source platform. Provider is the platform key that selects
// the adapter (it matches CompanyEntry.Provider and the stored jobs.source); Fetch
// returns all current postings for one configured board.
type Source interface {
Provider() string
Fetch(ctx context.Context, e CompanyEntry) ([]Job, error)
}
对于"一个公司 = 整个目录、不存在 per-tenant board id"的源,仓库用标记接口 boardless(source.go)来区分,这样配置校验可以允许其条目省略 board 字段。Google 适配器正是这一类。
提案的 What Changes 部分明确了改动面,而最终实现与之一一对应:
| 提案要求的改动 | 仓库中的落点 |
|---|---|
新增 google 源适配器 |
internal/ingest/sources/google.go |
单行注册进 sources.All |
registry.go 中 NewGoogle(c),与 NewAmazon(c)、NewApple(c) 同列于 "International single-company adapters (boardless)" 分组 |
| 单测 + fixture | google_test.go 与 testdata/google_list.html、google_empty.html、google_full.html 三个 fixture |
| 复用现有基建,零依赖 | 共享 HTTPClient.GetHTML、html.go 的 walk/textContent DOM 遍历、sanitizeHTML |
| DB:无迁移 | 复用 UpsertJob,source = "google",external_id 命名空间化 |
从源码结构看,Google 适配器的形态与同为服务端渲染的 successfactors、vk 适配器一致,区别仅在于"数据在页面上的位置":不是 schema.org microdata,而是一段内嵌 JSON 载荷。
3. 核心实现一:定位脚本块,再解析 JSON
这是 design.md 中第一条决策:先定位 blob、再解析 JSON,而不是用正则对整页 HTML 硬扫。
最终实现分为两级:
3.1 DOM 定位:findGoogleDS1Script
google.go 用 walk 遍历 DOM,找到第一个包含 key: 'ds:1' 的 <script> 文本节点:
func findGoogleDS1Script(root *html.Node) string {
var found string
walk(root, func(n *html.Node) bool {
if found != "" {
return false
}
if n.Type == html.ElementNode && n.Data == "script" {
if t := textContent(n); strings.Contains(t, "key: 'ds:1'") {
found = t
return false
}
}
return true
})
return found
}
这里有一个容易被忽略的细节(源码注释写得很清楚):页面上存在多个框架脚本都引用了裸字符串 'ds:1',所以匹配必须锚定在确切的回调参数 key: 'ds:1' 上,才能选中真正携带数据载荷的那一个脚本。这正是 design.md 所说"通过 DOM 定位(而非全页正则)保持对无关标记的稳健性"的落地。
3.2 正则隔离 JSON 数组:extractGoogleDS1
拿到脚本文本后,用一条惰性正则把 data 参数中的 JSON 数组切出来:
// googleDS1Data isolates the JSON array passed to AF_initDataCallback for the ds:1 key:
// `…data:[…], sideChannel: {}…`.
var googleDS1Data = regexp.MustCompile(`(?s)data:(\[.*?\]), sideChannel`)
捕获组的终止锚点是紧随数组之后必然出现的 , sideChannel。google.go 的注释明确承认了一个已被接受的边界:正则假设没有任何岗位正文包含字面量 ], sideChannel;若真包含,捕获会提前截断、页面 JSON 解码失败——结果是报错而非静默坏数据,这是脆弱内嵌载荷接缝上可以接受的代价。
随后把捕获到的数组 json.Unmarshal 成 <a href="https://link.gitcode.com/i/80822bfcd25221ddf87760b56b50c828" target="_blank">]json.RawMessage 树,并取出两个关键位置([google.go):
data[0]:岗位记录列表;超出末页时该字段为null,解码为零条记录(不报错);data[2]:目录总条数,注释标明[2] = catalogue total ([3] is the page size)。
一个值得注意的细节:归档的 design.md 写的是 data[3](total count),而最终提交的代码把总数字段读在 data[2]、把 data[3] 注释为 page size。这提醒读者:归档文档记录的是设计阶段的认知,逐位映射最终以代码注释 + fixture 测试为准——这也正是后文第 6 节要讲的"用测试钉住布局"这一工程姿态的直接原因。
4. 核心实现二:逐位记录的 typed 访问器与 toJob
design.md 的第二条决策是:用带注释的 typed 位置访问器建模记录,而不是把匿名下标散落在映射器各处。因为 ds:1 的每条岗位记录是一个无 key 的位置数组,所有"脆弱位置"必须收敛到一处有文档注释的地方。
toJob(google.go)把一条记录映射为归一化 Job:
func (google) toJob(e CompanyEntry, record json.RawMessage) (Job, bool) {
var rec []json.RawMessage
if err := json.Unmarshal(record, &rec); err != nil {
return Job{}, false
}
id := googleString(rec, 0) // [0] = numeric job id
if id == "" {
return Job{}, false
}
// Description assembles about-the-job [10], responsibilities [3], qualifications [4] in
// reading order; each is a [null, "<html>"] pair.
desc := googleHTMLField(rec, 10) + googleHTMLField(rec, 3) + googleHTMLField(rec, 4)
return Job{
ExternalID: id,
URL: fmt.Sprintf(googleJobURL, id),
Title: googleString(rec, 1), // [1] = title
Company: firstNonEmpty(googleString(rec, 7), e.Company), // [7] = hiring brand
Location: googleLocations(rec, 9), // [9] = locations array
Description: sanitizeHTML(desc),
PostedAt: parseEpochSeconds(googleEpochSeconds(rec, 12)), // [12] = [seconds, nanos]
}, true
}
字段位置一览(以代码注释为准):
| 下标 | 含义 | 读取方式 |
|---|---|---|
[0] |
数字岗位 id,即 external_id |
googleString;为空则整条丢弃(避免在 (source, external_id) 去重键上碰撞) |
[1] |
标题 | googleString |
[3] |
responsibilities,[null, "<html>"] 对 |
googleHTMLField |
[4] |
qualifications,同上 | googleHTMLField |
[7] |
hiring brand(如 DeepMind),缺省时回落到配置的 e.Company |
googleString + firstNonEmpty |
[9] |
地点数组,每项首元素是 "City, Region, Country" 形式的人读名称 | googleLocations,用 "; " 连接 |
[10] |
about the job 正文,[null, "<html>"] 对 |
googleHTMLField |
[12] |
Unix 时间戳 [seconds, nanos] |
googleEpochSeconds → parseEpochSeconds |
四个小助手(google.go)的共同特征是越界与类型不符一律返回零值,绝不 panic:
googleString(rec, i):非字符串或越界返回"";googleHTMLField(rec, i):解码[null, "<html>"]的第二元素,结构不符返回"";googleLocations(rec, i):逐条取地点首元素,拼成自由文本;googleEpochSeconds(rec, i):取<a href="https://link.gitcode.com/i/191e3979ac47dff86da1e4c996193252" target="_blank">seconds, nanos]的秒数,缺失返回 0,由parseEpochSeconds([dates.go)统一折算,并保证未来日期守卫(NotFuture)行为一致。
两条设计决策在此体现:
- description 组装顺序:按阅读顺序拼接 about-the-job(
<a href="https://link.gitcode.com/i/5241b17ddc022bc6b22d193aea742b2a" target="_blank">10])→ responsibilities([3])→ qualifications([4]),每段本身已是 HTML 字符串,最后整体过一次sanitizeHTML(实现见 [sanitize.go); - location 保持自由文本:payload 的地点项尾元素是 ISO 国家码,本可作为"nice-to-have"结构化字段,但设计文档明确决定不新增结构化字段——地点字典本就会从自由文本重新推导地理位置,保持与所有其他适配器一致、避免管线变更。同理,payload 没有结构化的远程工作标志,
WorkMode留空,交由管线的地点字符串启发式处理,行为与 uber/amazon 相同。
5. 核心实现三:URL 策略与分页终止条件
5.1 url 用公开 results 页,而不是 apply 链接
design.md 记录了实测结论:…/jobs/results/<id>(只带数字 id、不带 slug)返回 200 并正常提供岗位页——Google 完全忽略尾部 slug(即使给错 slug 也能解析)。因此适配器构建的是裸 results/<id> URL(常量 googleJobURL,见 google.go),不依赖复现 Google 的 slug 生成规则。记录里内嵌的 apply URL([2])需要登录且不稳定,明确弃用。
5.2 Fetch 的分页循环
google.go 的循环与 uber 适配器同构:page 从 1 开始,每页请求 googleListURL(即 …/jobs/results?page=%d,每页 20 条),双重终止条件:
for page := 1; ; page++ {
root, err := g.http.GetHTML(ctx, fmt.Sprintf(googleListURL, page))
// ...
records, total, err := extractGoogleDS1(root)
// ...
if len(records) == 0 {
break // past the last page: ds:1 carries a null/empty job list
}
// ...逐条 toJob...
if total > 0 && len(jobs) >= total {
break
}
}
design.md 对这两个条件做了重要的可靠性论证:总条数是优化项而非正确性要求——实测越界页的 ds:1 岗位列表为 null,空页检查本身就足以终止循环;即使 Google 将来删掉 total 字段,抓取依然安全收敛。错误处理则遵循"整页失败即报错"的语义:任何一页取 HTML 或解析 ds:1 失败都会带着页码向上返回 google: list page %d: …,而不是静默跳过。
整个流程没有 per-job 详情请求:列表载荷已携带标题、正文、职责、资格、地点与日期,一次分页列表爬取即可组装全部 Job。
6. 用 fixture 测试钉住"脆弱的位置映射"
design.md 的风险一节开宗明义:ds:1 是位置数组,若 Google 重排字段,映射会静默错配。缓解手段是"提交的 HTML fixture + 断言映射字段的单元测试;布局漂移时测试会大声失败(与 amazon 适配器 id_icims 字符串陷阱同一姿态)"。
google_test.go 正是这一姿态的完整实现,对应 tasks.md 中全部完成(勾选)的任务项:
TestGoogleExtractDS1(google_test.go):解析真实抓取自…/jobs/results?page=1并裁剪到少量记录的 fixturetestdata/google_list.html,断言data[0]解出 2 条记录、total 为 3640(与提案中"~3,640 个在招岗位"的实测值吻合);TestGoogleToJob(google_test.go):对一条真实记录逐字段断言——ExternalID、Title(DeepMind 的 Staff Developer Experience Engineer)、Company为记录自带的 hiring brand "DeepMind" 而非配置的伞形名、URL为纯 id 的results/<id>、Location为 "Bengaluru, Karnataka, India"、description 包含三段正文片段且不含<script(验证 sanitize 生效)、PostedAt精确等于由嵌入时间戳折出的 UTC 时刻;TestGoogleToJobGuards(google_test.go):钉住分页循环依赖的降级守卫——空 id 记录返回ok=false(会被丢弃),缺时间戳字段的记录映射出nil posted_at而非越界 panic,brand 字段缺失时回落配置的公司名;TestGoogleFetchPagesUntilEmpty(google_test.go):用routedHTTP假客户端按page=1→ 真实 fixture、page=2→google_empty.html路由,断言恰好产出 2 条且循环在空页停止;TestGoogleFetchStopsAtTotal(google_test.go):fixturegoogle_full.html的 total=2,断言计数达到 total 后不再请求下一页——若循环误发 page-2 请求,会命中未路由的假客户端而报错,因此"干净返回"本身就是提前终止的证明。
三个 fixture 的体积也很说明问题:google_list.html 与 google_full.html 各约 10 KB(裁剪后的真实页面),google_empty.html 仅 394 字节(模拟越界页的 null 列表)。
7. 注册、调度与部署
从源码结构看,这个变更的"增量成本"几乎为零,提案 Impact 一节列得很清楚,仓库现状也与之吻合(含后续演化):
- 新代码:
google.go+google_test.go,外加 registry.go 的一行注册; - 配置:提案时代是往
sources/*.ymlboard 文件加一条google条目; - DB:无迁移,复用
UpsertJob; - 依赖:无新依赖,只有共享
HTTPClient.GetHTML、html.go的 DOM 遍历与sanitizeHTML; - 部署:适配器编译进现有 ingest 二进制,因此需要镜像重建 + 重新部署(而非仅 rsync sources 目录),并为新 board 文件配置 cron 调度。
需要注意仓库现状相对提案的一个演化:按 internal/ingest/sources/AGENTS.md 的说明,sources/ 目录与所有 sources/*.yml board 文件后来已被移除,调度改为按数据库 boards 表中 status IN ('pending','active') 的 provider 枚举;新增一个 board 现在通过 cmd/add-board 完成(该命令的注释自称是"手工编辑 sources/*.yml 的数据库化替代"),用法形如:
go run ./cmd/add-board --provider=google --company="Google" [--apply]
对 boardless 源,--board 参数可省略(见 cmd/add-board/main.go 的 flag 注释 "board id (required unless the provider is boardless)")。也就是说,今天把 Google 目录挂进抓取池,走的是 add-board 写 boards 表这一条路径,而不是再维护一个 yml 文件。
8. 已知弱点与适用边界
最后收拢 design.md 与提案共同声明的三个已知接缝(known seams),它们是评估任何"内嵌 JSON 载荷"类抓取器的通用检查点:
- 脆弱的位置布局:
ds:1记录若重排,映射静默错配。仓库的处置是接受风险 + fixture 测试钉住当前布局,理由是"不存在稳定的带 key API 可供瞄准"。对下游读者,这意味着:接入同类站点时,位置映射必须单点收敛、逐下标注释,并配套"布局漂移即红"的回归测试; - 正则的惰性捕获假设:
(?s)data:(\[.*?\]), sideChannel依赖"岗位正文不含字面量], sideChannel"。违反时表现为整页 JSON 解码失败(报错路径),而非静默坏数据——这是设计上刻意选择的失败模式; - 无 work-mode 信号:payload 没有结构化远程标志,
WorkMode留空交由管线启发式;同时 apply 链接需要登录,url只能落在公开的results/<id>页上。
此外,时间维度上要提醒:本文所有字段位置(如 <a href="https://link.gitcode.com/i/ef707f78c2577f31c9461675f1c33671" target="_blank">2] 为 total、[12] 为 [seconds, nanos])以当前仓库的 [google.go 与 fixture 测试为准;归档的 proposal/design 文档记录的是 2026-06-17 变更的设计过程,个别下标描述(如 design.md 中的 data[3] 总条数)与最终代码存在出入,引用时请以代码注释和 google_test.go 的断言为最终依据。
9. 小结:这套模式能迁移到什么场景
把 Google 案例抽象出来,freehire 展示的是一条可复用的"无 API 大站接入"管线:
- 先做可行性探测:区分"接口 404 = 真 blocked"与"数据其实内嵌在 HTML 里";
- 数据定位优先于解析:DOM 找到唯一承载脚本 → 一条锚定正则切出 JSON 数组 →
json.RawMessage树逐位解码; - 脆弱性单点收敛:位置下标只出现在一组带
// [n] = …注释的访问器里,越界/类型不符一律零值降级; - 终止条件双保险:空页检查保证正确性,total 字段仅作优化;
- fixture 钉住布局:真实页面裁剪为提交进仓库的 HTML fixture,字段级断言让任何上游布局漂移在 CI 中大声失败;
- 归一化落库零成本:复用
Source接口、UpsertJob与(source, external_id)去重键,新源不碰 schema。
对 freehire 而言,这次接入的净增量是"一个适配器文件 + 一行注册 + 三个 fixture";对任何要做招聘/内容聚合的团队,它示范了如何在不引入无头浏览器、不加依赖、不改数据库的前提下,把一个大公司的服务端渲染目录变成共享池里的一页可调度配置。