freehire 的 Eightfold 源适配器:用 board-keyed 方式接入 Microsoft、Micron 与 Netflix 的 ATS 职位目录
freehire 的 Eightfold 源适配器:用 board-keyed 方式接入 Microsoft、Micron 与 Netflix 的 ATS 职位目录
本文基于 freehire 仓库中归档的变更提案 proposal.md 及其配套设计文档 design.md、任务清单 tasks.md,结合已落地的 eightfold.go 适配器源码、eightfold_test.go 测试用例,完整讲解如何把一个多租户 ATS(Eightfold AI)以"一个可复用的 eightfold 适配器 + 一组 board 配置"的方式接入 freehire 的职位摄入管线:包括两代列表 API 的自动探测、start 分页策略、逐职位详情的并发拉取、限流退避与字段到归一化 Job 结构的映射规则。读完后你可以理解 freehire 新增一个 ATS 源的标准路径,并能独立排查 Eightfold 租户的抓取问题。
背景:一个"看起来不可达"的新招聘目录
提案的出发点是:apply.careers.microsoft.com 并不是此前可行性评估标记为 "blocked" 的旧 careers.microsoft.com 站点,而是一个构建在 Eightfold AI 之上的新前端。Eightfold 是一个多租户 ATS,许多企业共用同一套后端 API。通过对它做探测,确认了背后有两个公开的、无需认证的 GET-JSON 端点:
- 列表(List):
GET /api/pcsx/search?domain=<domain>&query=&start=<n>&num=10,返回data.positions[]加上data.count。注意num被服务端硬性限制为 10(请求num=200也只返回 10 条),因此start是唯一可用的分页杠杆;更高层的/api/apply/v2/jobs列表端点对该租户返回403 PCSX。 - 详情(Detail):
GET /api/apply/v2/jobs/<id>?domain=<domain>,返回完整职位,包括列表中没有的job_descriptionHTML 和canonicalPositionUrl。
由于这两个端点是 Eightfold 平台通用的(并非 Microsoft 专属),提案确定的形态是:做一个按 board 寻址的可复用 eightfold 适配器——与按 host 寻址的 jibe/icims 适配器、按 host/site 寻址的 oracle 适配器同构——并以 Microsoft 作为第一个配置的 board。
提案明确划出的范围(Non-Goals,见 design.md):
- 不使用无头浏览器、代理或任何认证(两个端点都是公开 GET JSON);
- 不新增环境变量、数据库列或迁移;
- 不做按 query / work-site 过滤——抓取走的是整个目录(空 query),这正是摄入管线需要的。
两代列表 API:一个租户只支持其一
Eightfold 存在两代列表 API,且一个租户恰好支持其中一代(另一代会返回 403):
| 维度 | 新一代 /api/pcsx/search |
旧版 /api/apply/v2/jobs(列表) |
|---|---|---|
| 代表租户 | Microsoft、Micron | Netflix |
| positions 位置 | 嵌套在 data.positions |
顶层 positions |
| 日期字段 | postedTs(Unix 秒) |
t_create |
| 工作地点字段 | workLocationOption |
work_location_option |
| 位置字段 | 仅 locations[] 数组 |
单字符串 location(另带列表级 canonicalPositionUrl) |
| 详情端点 | 两代共享 /api/apply/v2/jobs/<id> |
同左 |
适配器对此的对策是自动探测:先试 pcsx 列表,出错则回退到 v2 列表,且回退时从第一页重新走。这样无论租户属于哪一代,board 配置形式都是统一的 host/domain,批量添加已发现的租户时不必预先知道它是哪一代;代价是每个旧版租户每次抓取多一次很快的 403 探测请求。
这一策略在源码中由 listPositions 直接体现(eightfold.go):
// listPositions 返回该 board 的职位列表,自动探测列表 API 代际:先试新一代 pcsx 列表,
// 失败(旧版租户返回 403)则回退到 v2 列表。一个租户恰好支持其一,
// 所以谁分页成功谁就是权威;回退会从第一页重新开始。
func (s eightfold) listPositions(ctx context.Context, b eightfoldBoard) ([]eightfoldPosition, error) {
positions, err := s.pageList(ctx, b, s.pcsxPage)
if err != nil {
positions, err = s.pageList(ctx, b, s.v2Page)
}
...
}
两代的 JSON 差异用一个结构体同时解码:eightfoldPosition 把两种字段名作为独立的 JSON tag 并列声明,未使用的字段保持零值(eightfold.go):
type eightfoldPosition struct {
ID int64 `json:"id"`
Name string `json:"name"`
Location string `json:"location"` // 旧版 v2 单字符串
Locations []string `json:"locations"` // 两代都有
PostedTs int64 `json:"postedTs"` // pcsx
TCreate int64 `json:"t_create"` // 旧版 v2
WorkLocationOption string `json:"workLocationOption"`
WorkLocationOptionV2 string `json:"work_location_option"`
CanonicalPositionURL string `json:"canonicalPositionUrl"` // 旧版 v2 列表中携带
}
对应的响应外壳也各有一个结构体:pcsxListResponse(positions 嵌在 data 下)与 v2ListResponse(positions/count 在顶层)。
Board 设计:host/domain 双段 key
Eightfold 的调用需要两个值:
- 公开 host——用于请求路径(
https://<host>/api/...); - 必填的
domain查询参数——Eightfold 的租户键(tenant key),省略它会得到422。
两者不能互相可靠推导(一个租户的 domain 未必等于 host 的注册域),因此 board id 直接携带两者:"apply.careers.microsoft.com/microsoft.com",解析方式与 oracle 拆分 "host/site" 相同。parseEightfoldBoard 在第一个 / 处切分,缺失任一半即报错(eightfold.go):
func parseEightfoldBoard(board string) (eightfoldBoard, error) {
host, domain, ok := strings.Cut(board, "/")
if !ok || host == "" || domain == "" {
return eightfoldBoard{}, fmt.Errorf("eightfold: board %q must be \"host/domain\"", board)
}
return eightfoldBoard{host: host, domain: domain}, nil
}
这一点在 eightfold_test.go 中被完整钉住:合法 board 拆出正确的 host/domain;apply.careers.microsoft.com(无斜杠)、/microsoft.com(空 host)、apply.careers.microsoft.com/(空 domain)、空串四种输入全部必须报错。提案也强调 eightfold 是基于 board 的适配器(非 boardless),domain 是硬性要求,malformed 的 board 会快速失败。
分页:start 逐页推进直到目录耗尽
由于服务端把页面大小固定为 10,分页循环以 start 为唯一杠杆。pageList 的实现(eightfold.go)遵循仓库内"列表走到底"的统一规则:
- 每页请求
https://<host>/api/pcsx/search?domain=<domain>&query=&start=<n>&num=10&sort_by=relevance(或 v2 的对应路径); - 按实际返回的条数推进
start(而不是固定加 10); - 当某页为空、或累计条数达到服务端声明的
count时停止。空页检查是正确性兜底——万一count出错或缺失,循环仍会终止;count只是优化手段,这一思路与oracle/jibe一致。
两个列表页取数函数分别对应两代 API(eightfold.go):
func (s eightfold) pcsxPage(ctx context.Context, b eightfoldBoard, start int) ([]eightfoldPosition, int, error) {
url := fmt.Sprintf(
"https://%s/api/pcsx/search?domain=%s&query=&start=%d&num=%d&sort_by=relevance",
b.host, b.domain, start, eightfoldPageLimit)
var resp pcsxListResponse
if err := s.getJSONRetrying(ctx, url, &resp); err != nil {
return nil, 0, err
}
return resp.Data.Positions, resp.Data.Count, nil
}
值得注意的完整性语义:eightfold 实现了 fullBoardListing 标记接口(eightfold.go)。其含义(见 internal/ingest/sources/AGENTS.md 中对 fullBoardListing 的定义)是:该适配器的 Fetch 对每个 board 要么用来源自身报告的总数校验了抓取量、要么分页走到了来源的自然终点;任何一页失败都会丢弃已收集内容并使整个列表抓取失败,绝不把部分结果当成功返回。pageList 里"任意页错误即 return nil, err"正是这一承诺的落地,eightfold_test.go 的 TestEightfoldMarkers、TestEightfoldRegisteredAsFullBoardListing 与 TestEightfoldFetchPropagatesAListingError 三个测试分别钉住了标记存在、注册表可见、列表错误必须传播这三件事。该标记决定了后续"未再出现的职位"清理(board-scoped sweep)可以按 board 粒度关闭职位——这是 Eightfold 作为"列表权威"源在生命周期机制里的位置。
详情拉取:N+1 的成本与字段分工
列表不携带描述文本,因此每个职位都要补一次详情请求(约 1 次列表页 + N 次详情),成本轮廓与 oracle/icims 相同——提案在"Out of scope"中把这列为已知取舍,因为列表没有描述,不存在更便宜的路径。
字段来源的分工是明确的(design.md):列表携带元数据,详情携带描述。具体映射在 detail 方法中完成(eightfold.go):
Job 字段 |
来源 | 说明 |
|---|---|---|
ExternalID |
列表 id 字符串化 |
Eightfold 的数字 position id,是详情端点与 canonical URL 的 key;displayJobId/atsJobId 只是面向人的标签,不用作 API key |
URL |
详情 canonicalPositionUrl,回退列表同名字段,再回退 https://<host>/careers/job/<id> |
三级回退,保证 URL 总有确定值 |
Title |
列表 name(TrimSpace) |
|
Company |
配置的 company | 来自 board 目录,而非列表 |
Location |
列表 location,否则 locations[] 第一项 |
覆盖两代字段 |
PostedAt |
postedTs(为 0 时用 t_create),经 parseEpochSeconds |
复用现成 helper,保持与其他 epoch 日期适配器一致的 NotFuture 守卫 |
WorkMode / Remote |
列表 workLocationOption(或 v2 字段)经 workplaceTypeMode |
Eightfold 的值本就是 remote/hybrid/onsite,未知/空值得到 "",管线回退到位置字符串启发式 |
Description |
详情 job_description 经 sanitizeHTML |
唯一必须来自详情的内容 |
pageURL := firstNonEmpty(
d.CanonicalPositionURL, p.CanonicalPositionURL,
fmt.Sprintf("https://%s/careers/job/%s", b.host, id))
一个实现细节是:详情的 work_location_option 曾被观测为 null,而列表的 workLocationOption 是有值的——所以 work mode 只从列表读,避免"从详情里重读列表字段"的歧义。
详情失败不等于丢弃职位
与"请求失败"和"平台宣告职位消失"是两种答案的仓库通则不同,Eightfold 的选择更温和:详情请求失败时记录日志并以 list-only 形态摄入该职位(无描述,下一次抓取补上),绝不因此丢掉整条职位;只有列表失败才作为 board 级错误上抛。这一"best-effort 详情"策略写在 fullBoardListing 的注释里(eightfold.go),并在 detail 中实现——getJSONRetrying 失败只打日志,Job 依然以 ok=true 返回。
限流对抗:403 重试、低并发与共享代理预算
Eightfold 对 IP 有每窗口约 290 个请求的配额,超限返回 403(而非 429)。围绕这一点,实现分三层防御:
第一层:针对 403/429 的指数退避重试。 getJSONRetrying(eightfold.go)在共享客户端已会重试 429/5xx/网络错误的基础上,额外把 403 纳入重试范围——Eightfold 用 403 表示限流(而非认证失败),并等待足够长的时间让整窗口过去:
const (
eightfoldMaxRetries = 6 // 限流请求最多重试次数
eightfoldRetryBase = time.Second // 首次退避延迟,每次翻倍、封顶
)
重试范围被刻意收窄:非限流错误(如 404)立即返回,不进入重试。测试把两条边界都钉住了(eightfold_test.go):
TestEightfoldRetriesRateLimitedDetail:详情端点前 3 次返回 403、第 4 次成功,断言detailCalls == 4且职位最终入库——"被限流的详情必须重试穿越 403";TestEightfoldDoesNotRetryNonRateLimitError:404 只请求一次(detailCalls == 1),职位仍以 list-only 形态摄入。
另一个工程细节:首次退避延迟 retryBase 是结构体字段而非包级变量,测试置零即可跳过真实睡眠,不触碰任何共享状态。
第二层:低并发详情扇出。 eightfoldDetailWorkers = 2(eightfold.go),远低于共享的 defaultDetailWorkers,让突发足够温和,把剩下的交给退避重试——"宁可慢,也不要把配额打满然后丢职位"。
第三层:出口代理与整体 pacing。 由于生产数据中心的 IP 被 Eightfold 边缘整体拒答(403),而住宅 IP 正常服务,Eightfold 被列入 proxy.go 的 proxiedProviders 白名单:配置 SOURCES_PROXY_URL(格式 http://user:pass@host:port)后,只有白名单内的 provider 走代理出口,其余保持直连;未设置时为无操作,设置但非法则在启动时失败。同时(见 pacer.go 的历史记录),未做 pacing 时约 95 个 board 中有 44 个连列表请求都 403——这是整个 run 的聚合速率花光了共享代理 IP 的窗口预算,而非硬性 IP 封禁。因此 eightfold 还被包上 pacedEightfoldGetter,以约 1 req/s(eightfoldRequestInterval = 1s,burst 1)限速,所有 board 的列表页与详情扇出竞争同一个令牌桶。
// proxy.go:白名单条目本身就把限速一并装配好
"eightfold": func(c HTTPClient) Source { return NewEightfold(pacedEightfoldGetter(c)) },
retryBase 之外的这些数字——290/窗口、1 req/s——都带仓库内的测量依据,且 pacer 注释说明了调参纪律:以 board_health 中该 provider 的不健康数为观测信号,"board 还在失败列表请求就往下调,只有没有任何失败时才允许上调"。
与摄入管线的集成:注册、契约与部署
注册:一行进 sources.All
适配器通过 NewEightfold(c) 注册进共享 HTTP 客户端之上的 provider 注册表(registry.go):
NewOracle(c),
NewEightfold(c),
NewFreshteam(c),
Provider() 返回 "eightfold";eightfold 无需凭证、无 cookie 会话,因此直接走 reg(...) 的普通条目,不需要 cookieSessionSource 之类的特殊构造。注册表按 Provider() 建键并对重复键 panic(registry.go),保证一个平台只有一个适配器声明它。
Fetch 与 FetchStream 并存:FetchStream 先列全列表,再用 fetchDetailsStream 并发拉详情,每完成一个详情立即 emit 一个组装好的 Job,使管线能对一个很长的、被限流节奏拉慢的抓取做增量持久化;Fetch 保留给非流式调用方与测试(eightfold.go)。
board 目录与调度
提案原定交付一个 sources/eightfold.yml board 文件(Microsoft、Micron 在 pcsx 代,Netflix 在旧版列表代)。需要注意的是,仓库当前的 board 目录机制已经演进:如 internal/ingest/sources/AGENTS.md 所述,board 目录现在存放在 Postgres 的 boards 表(通过 cmd/add-board --provider=eightfold --board="apply.careers.microsoft.com/microsoft.com" --company=Microsoft --apply 添加),cmd/ingest <provider> 通过 internal/ingest/boardcatalog 读取活动 board;provider 是否被排程由"它是否有 live board"决定。因此对当前仓库而言,接入一个新 Eightfold 租户的操作是"加一行 board 配置",不需要任何代码改动——这正是提案"其他 Eightfold 租户后续以更多配置条目加入"的意图在现行机制下的形态。
契约与前端
eightfold 是非 boardless 的 provider,因此 sources.FilterableProviders() 会把它自动纳入 source facet 的 SOURCE_VALUES。在仓库中可验证:web/src/lib/generated/contracts.ts 的 SOURCE_VALUES 常量里已包含 'eightfold',由 make gen-contracts 再生成。
数据库与部署
- 数据库:零迁移。 复用既有
UpsertJob写路径,去重键为jobs.UNIQUE (source, external_id)——source = "eightfold"、external_id为按 board 命名空间的职位 id。 - 部署: 适配器编译进既有的 ingest 二进制,所以新增适配器需要镜像重建 + 重新部署(不是仅仅 rsync sources),并为其 board 文件/目录行配上 cron 排程(run-once-and-exit 的 cron worker,一个 provider 一个排程,providers 相互独立抓取)。
测试证据:fixture 钉住 API 形状
tasks.md 记录了这个变更按 RED→GREEN 推进的任务分解(board 解析、字段映射、适配器与分页、质量与集成),eightfold_test.go 中可见的测试覆盖:
- 完整映射路径(
TestEightfoldFetchListsAndFetchesDetail):用 canned JSON 走列表→详情→映射全流程,列表携带元数据(name、locations[]、postedTs、workLocationOption),详情携带job_description与canonicalPositionUrl,并覆盖canonicalPositionUrl缺失时的 URL 回退与postedTs为 0 时日期为 nil 的分支; - 两代 API 的回退:fake 只服务 v2 列表路由、不服务 pcsx 路由时,断言 v2 字段(
t_create、单字符串location、work_location_option)映射正确; - 限流重试与错误隔离:如上所述的 403 重试、404 不重试两条;
- 完整性契约:列表错误必须让
Fetch整体失败(见前文三个标记相关测试)。
任务清单的最后一项还要求对真实 Microsoft board 做一次 live smoke:确认返回真实职位且映射健全(title、url、location、非空描述、有日期)。
已知边界与取舍
提案"Out of scope"一节把以下取舍写得很直白,值得作为维护该源的心智模型保留:
- N+1 请求成本:列表不带描述,每次抓取约 1 次列表页 + N 次详情(Microsoft 租户当时列约 1.4k 个职位)。
fetchDetails有界扇出并隔离失败;列表没有描述,不存在更便宜的路径。 domain是硬性要求:省略返回422;"host/domain"的 board 格式让它显式化,且 board 校验本身要求非空。- 对 Eightfold API 重命名脆弱:若
/api/pcsx/search或/api/apply/v2/jobs形状变化,映射会坏——防护手段是提交进仓库的 fixture 与单元测试,与仓库里所有 JSON 适配器同一姿态。 - 不做工作地过滤:抓取走整个目录(空 query),代价由调度与 pacing 吸收。
后续仓库演进(提案归档之后的事实,见 pacer.go 与 proxy.go 的注释)进一步给这个源加了两层生产化约束:生产 IP 被封 → 走 SOURCES_PROXY_URL 共享出口;共享出口上的聚合速率超限 → 1 req/s 的全 run pacing。这些都是在"同一份适配器代码不变"的前提下,通过 transport 装配(NewEightfold(pacedEightfoldGetter(c)))完成的,体现了该仓库"适配器描述平台语义,transport 描述出口策略"的分层。
小结
freehire 的 Eightfold 源是一个教科书式的"新 ATS 接入"样本:以提案文档明确为什么(两代公开 GET-JSON 端点、多租户通用)、变什么(一个适配器 + 一行注册 + board 配置 + 契约再生成)、代价是什么(N+1 详情、API 脆弱性);源码侧则把每一个决策落成可验证的断言——host/domain 解析的四种非法输入、两代 API 的单结构体双 tag 解码、start 分页的空页兜底、403 重试与 404 不重试的边界、fullBoardListing 标记背后的"部分结果不得算成功"。对读者而言,这套材料同时回答了两类问题:如何用最小改动面接入一个多租户 ATS(配置即扩展),以及如何把一个"限流即 403"的平台做成可以持续、完整、增量入库的抓取源(退避 + 低并发 + pacing + 代理分层防御)。