freehire 的 Eightfold 源适配器:用 board-keyed 方式接入 Microsoft、Micron 与 Netflix 的 ATS 职位目录

原创2026-10-23 14:38:251,711 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

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_description HTML 和 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 的调用需要两个值:

  1. 公开 host——用于请求路径(https://<host>/api/...);
  2. 必填的 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"一节把以下取舍写得很直白,值得作为维护该源的心智模型保留:

  1. N+1 请求成本:列表不带描述,每次抓取约 1 次列表页 + N 次详情(Microsoft 租户当时列约 1.4k 个职位)。fetchDetails 有界扇出并隔离失败;列表没有描述,不存在更便宜的路径。
  2. domain 是硬性要求:省略返回 422;"host/domain" 的 board 格式让它显式化,且 board 校验本身要求非空。
  3. 对 Eightfold API 重命名脆弱:若 /api/pcsx/search 或 /api/apply/v2/jobs 形状变化,映射会坏——防护手段是提交进仓库的 fixture 与单元测试,与仓库里所有 JSON 适配器同一姿态。
  4. 不做工作地过滤:抓取走整个目录(空 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 + 代理分层防御)。

登录后查看全文
freehire