freehire 的 Deel ATS 适配器:单请求解析 Next.js flight payload 抓取多租户职位
freehire 的 Deel ATS 适配器:单请求解析 Next.js flight payload 抓取多租户职位
freehire 是一个面向求职者的开源搜索引擎,它的职位目录由上百个 internal/ingest/sources 下的适配器(adapter)分别对接不同 ATS 平台汇聚而成。本文以 Deel 适配器规格 为主线,结合 设计文档、变更提案 与真实实现 internal/ingest/sources/deel.go,讲清楚一个新 ATS 源如何以"一次 GET、内嵌 payload 解析"的方式接入 freehire:读完你可以独立判断该适配器的契约边界、理解 $N → T<hexlen> 这条 RSC 文本行解析链路,并能照此模式新增或排查同类适配器。
1. 为什么需要 Deel 适配器
Deel 在 jobs.deel.com/<orgSlug> 上推出了自己的多租户 ATS,背后是 api-prod.letsdeel.com 的 rest/v2 接口。提案文档指出,主流技术类 ATS(Greenhouse / Lever / Ashby)已被覆盖,而 Deel ATS 是一个净新增平台,属于明确的覆盖缺口(见 proposal.md)。
关键的前置调研结论有两条:
- 公开看板页是完整服务端渲染的。每个
jobs.deel.com/<slug>都把自己的整份职位目录内联进 Next.js 的 RSC flight 流,其中包含每个职位的完整 HTML 描述; - 职位的描述不是内联字符串,而是一个
$N引用,指向同一 payload 中带长度前缀的文本行。
因此适配器能够做到"一个看板一次 GET 就组装出全部 Job",不需要逐条请求详情页,也不需要无头浏览器。这一点与已有 google 适配器的"内嵌 payload"思路一致(google 的公开 JSON API 同样已不可用,其列表页内联了数据)。
仓库当前的规模快照也印证了这个源已经实际产出数据:docs/sources.md 中 deel 一行为 696 个在架职位(快照日期 2026-10-20)。
2. 规格的五条验收口径
规格文档以"ADDED Requirements + Scenario"的形式固定了行为契约,这是适配器实现的唯一权威来源。逐条拆开如下。
2.1 requirement:deel 是已注册的 provider
- 平台键(provider key)为
deel; board的值就是组织的 URL slug(例如klarna),不是 boardless(无 board)源;- 枚举入口是
GET https://jobs.deel.com/<board>,一次请求; - 数据来源是页面内的 Next.js flight payload,即
self.__next_f.push各分块 JS 字符串解码后拼接的结果; - 职位来自 payload 的
jobPostings数组; external_id= 职位的id(即公开 URL 里的 UUID),url=https://jobs.deel.com/<board>/job-details/<id>/overview;- 不得发出逐职位的详情请求。
对应场景:Deel board is enumerated from the embedded flight payload。
2.2 requirement:描述由 $N 引用解析并做 sanitize
当职位的 richtextDescription 形如 "$N" 时,适配器要把它解析到同一 payload 里的 N:T<byte-length>,<html> 文本行,并按声明的字节长度切片取出 HTML,经 HTML 清洗后作为 description;结构(段落、列表)保留,活动内容(脚本等)剥离,同时保证是正确 UTF-8。
对应场景:Description is resolved from a $N reference and sanitized。
2.3 requirement:公司名优先取 career page 设置
careerPageSettings.preferredOrganizationName 存在时用它作为公司名;缺失时回退到 board 条目中配置的公司名(CompanyEntry.Company)。
对应场景:Company name comes from the career-page settings。
2.4 requirement:空看板 / 无职位看板不算错误
jobPostings 为空时产出 0 个职位且不报错,于是这个看板被自然跳过。
2.5 requirement:畸形 payload 必须报错,而不是静默产出坏数据
页面里没有可解码的 jobPostings 时,返回 board 级错误,而不是静默返回 0 个职位——目的是让"页面结构变了"这件事浮出水面,而不是悄悄清空目录。
这两条一起构成关键的设计取向:"空"是合法状态,"坏"必须响亮失败。
3. flight payload 的解析链路
设计文档给出了伪代码级算法(design.md 的 Parsing algorithm 一节),仓库中的实现把它拆成了可复用原语,位于 internal/ingest/sources/nextflight.go。
3.1 整体调用链
Fetch(board) deel.go L34
└─ fetchFlight(ctx, http, "https://jobs.deel.com/<board>") nextflight.go L28
├─ c.GetHTML(...) → 解析后的 HTML 树
└─ decodeNextFlight(root) nextflight.go L86
├─ walk <script> 收集内联脚本
├─ 正则匹配 self.__next_f.push([1,"…"])
└─ json.Unmarshal 每个 chunk(JS 字符串反转义)后拼接
├─ extractDeelPostings(flight) → flightArraydeelPosting L89
├─ extractDeelOrgName(flight) → bracketSlice + json.Unmarshal L95
├─ nextFlightTextRows(flight) → map[rowID]HTML(按字节长度切片) L165
└─ toJob(...) 逐条映射,并统计引用解析成功率 L113
3.2 分块捕获:保留引号再当 JSON 字符串解码
flight 分块的正则刻意保留了包裹字符串的引号,使得每个分块可以直接当作 JSON 字符串反序列化:
var nextFlightPush = regexp.MustCompile(`self\.__next_f\.push\(\[1,("(?:[^"\\]|\\.)*")\]\)`)
self.__next_f.push(<a href="https://link.gitcode.com/i/6483609469f9e3970df778a47218af74" target="_blank">0]) 这种初始化推送不含 [1,"…"] 载荷,会被忽略。之所以用 JSON 字符串反转义而不是手写转义表,是因为 flight 的转义规则(\"、\\、\n、\uXXXX、\/)与 JSON 字符串完全一致,且 json.Unmarshal 能保证多字节 UTF-8 不被破坏——这是"描述里出现 world’s favorite 这种弯引号不能变成乱码"的硬要求。测试 [deel_test.go 与字段映射测试都断言了这一点。
一个页面里若一个 flight 分块都没匹配到,decodeNextFlight 直接返回 no flight payload found 错误;单个分块解码失败也会带上下文返回错误。
3.3 定位 JSON 值:bracketSlice 的括号配对
payload 里既有对象(careerPageSettings)也有数组(jobPostings),实现方式是"先找到键名,再对随后的括号做配对扫描",而不是试图解析整个 flight 流——因为 flight 流本身并不是一个合法 JSON 文档。
func bracketSlice(s, key string, open, closing byte) (string, bool)
其关键细节是只在 JSON 字符串字面量之外计数深度。否则一个租户可控的标题里出现 <a href="https://link.gitcode.com/i/f1e8604221a4b17d642ba09d5db9d65d" target="_blank">EMEA]、[remote] 就会把数组扫描的深度算乱。这条陷阱有专门回归测试 TestDeelTitleWithBrackets([deel_test.go),断言 "[EMEA] Senior Engineer [remote]" 这类标题仍能整块解析出 1 个职位。
flightArray[T] 在此之上做泛型包装:键名不存在时返回 flight array <key> not found 错误,键存在但内容是 [] 时返回空切片 + nil 错误——正是规格 2.4 / 2.5 的落点。
3.4 $N → 文本行:hex id 与字节长度
这是整个适配器最容易写错的地方,设计文档把它单列为一条"live-smoke 才发现"的坑。
文本行的标记格式是 N:T<hexlen>,<内容>:
T表示这是一个文本块;N是行 id,小写十六进制,不是十进制。一个真实看板的引用会依次是…$28, $29, $2a, $2b … $30 …。如果只按十进制匹配,所有 id 含a–f的行都解析不到,实测一个真实看板约 40% 的描述会变成空字符串;<hexlen>同样按十六进制解析,并且计的是字节数,不是 rune 数——所以切片必须落在[]byte上;- 内容本身可能包含换行和逗号,因此只能靠声明的长度切,不能靠分隔符。
实现:
var nextFlightTextRowMarker = regexp.MustCompile(`^0-9a-f:T([0-9a-f]+),`)
// start = 完整匹配的结束位置(逗号后的第一个内容字节)
// end = start + hexlen,越界则截断到 len(b)
rows[id] = string(b[start:end])
正则前置一个非 hex 字节是为了锚定 id 的左边界,避免把 a2a:T 读成 2a:T(Go 正则不支持 lookbehind)。解析长度时还做了 n > math.MaxInt 与 end < start 双重保护,防止 32 位构建上整型回绕。
测试里同时断言了 $23 与 hex 的 $2a 都能解析出非空 HTML,正是为了钉死这条回归(deel_test.go)。
3.5 只用到的字段才建模
deelPosting 是 jobPostings 元素的最小投影(deel.go):
type deelPosting struct {
ID string `json:"id"`
Title string `json:"title"`
RichtextDescription string `json:"richtextDescription"`
CreatedAt string `json:"createdAt"`
Job struct {
JobLocations []struct {
Location struct {
Name string `json:"name"`
} `json:"location"`
} `json:"jobLocations"`
} `json:"job"`
}
jobId、applicationFormId、isCompensationVisible、updatedAt、jobEmploymentTypes、currentCompensation 等字段在真实 payload 中确实存在,但规格没有要求映射,结构体里就不出现。设计文档的解释是"只有适配器需要的字段被建模,其余忽略",这样 payload 增删无关字段不会影响解析。
注意 jobPostings 数组本身是合法 JSON($N 引用只是普通 JSON 字符串),所以取出括号片段后可直接 json.Unmarshal,不需要预处理。
4. 字段映射:规格到 Job 的逐项对照
Job 是仓库统一的规范化职位形状,定义在 internal/ingest/sources/source.go;映射逻辑在 toJob(deel.go)。
Job 字段 |
来源 | 实现细节 |
|---|---|---|
ExternalID |
posting id |
用公开 URL 与组织 sitemap 都使用的 UUID,而不是 jobId;为空则整条丢弃 |
URL |
拼接 | https://jobs.deel.com/<board>/job-details/<id>/overview |
Title |
title |
原样 |
Company |
careerPageSettings.preferredOrganizationName |
缺失/解码失败时 firstNonEmpty(org, e.Company) 回退到配置值 |
Location |
job.jobLocations[].location.name |
全部收集后用 joinNonEmpty 连接;允许为空 |
Description |
$N 解析后的 HTML |
经 sanitizeHTML 清洗 |
Remote |
共享启发式 | isRemote(title + " " + location) |
PostedAt |
createdAt |
parseRFC3339,缺失或不可解析时为 nil |
WorkMode |
空 | Deel 没有结构化工作形态字段,刻意留空交给下游位置解析器 |
几个值得展开的点:
为什么 ExternalID 用 id 而不是 jobId。 设计文档的 Decisions 一节写明:id 同时出现在公开职位 URL 和组织的 sitemap 中,是"公开可寻址单元",这样 external_id、url、sitemap 三者保持一致。sitemap 一致性不是洁癖——cmd/harvest-boards/prober.go 的 deelProber 正是靠 sitemap 中 /job-details/ 的出现来判断租户是否存活。
Remote 只来自启发式,WorkMode 保持空。 设计文档给出了验证结论:真实 payload 里 workplaceType/remote/onsite 这些键为 0 个。因此适配器不伪造结构化信号,只设置布尔 Remote,把 hybrid/onsite 的判定留给管线里的位置解析器。这与 source.go 对 WorkMode 的契约注释一致:只承载平台"结构化声明"的信号,绝不承载位置启发式。
isRemote 的实现(helpers.go)是大小写不敏感地匹配 remote 与俄语 удал,被所有适配器共享以保持跨平台一致。因此一个标题写作 (Fully Remote - Sweden) 的职位会被标记为远程,而 Office Manager 不会——两条都有测试。
描述清洗不是简单 strip。 sanitizeHTML 转发到 internal/platform/htmltext/sanitize.go,使用 bluemonday 的显式 prose 白名单:保留标题、段落、列表、表格、强调等结构元素,剥离脚本/样式/表单,并且刻意不允许 <img>——否则一条职位里的图片会在每个浏览者渲染时成为跟踪像素。<a> 也刻意不在白名单里,bluemonday 对不允许的元素是"拆标签留文本",所以正文里的链接文字和内联强调会保留,不会在句子里打洞。
5. 失败语义:三处"响亮失败"与两处"容忍降级"
规格里两条看似矛盾的场景(空看板 OK / 畸形 payload 报错),在代码里被细化为五条边界:
| 情形 | 行为 | 依据 |
|---|---|---|
| 页面没有 flight payload | board 级错误 | decodeNextFlight 返回 no flight payload found |
有 flight 但没有 jobPostings 键 |
board 级错误 | flightArray 返回 flight array "jobPostings": not found |
jobPostings: [] |
0 个职位 + nil 错误 | 空数组是合法 JSON |
| 有引用但全部解析不到文本行 | board 级错误 | refs > 0 && resolved == 0 判定行解析崩了 |
| 个别引用解析不到 | 该职位以空描述产出 | 容忍的降级,不牵连同看板 |
posting id 为空 |
丢弃该职位 | 否则会在 (source, external_id) 去重键上冲突 |
"全部解析失败"这条守卫是 Fetch 里唯一一段带统计的代码:
refs, resolved := 0, 0
for _, p := range postings {
if ref, ok := strings.CutPrefix(p.RichtextDescription, "$"); ok {
refs++
if strings.TrimSpace(rows[ref]) != "" {
resolved++
}
}
if j, ok := d.toJob(e, org, rows, p); ok {
jobs = append(jobs, j)
}
}
if refs > 0 && resolved == 0 {
return nil, fmt.Errorf("deel: board %q: %d description references but none resolved", e.Board, refs)
}
为什么不能"部分失败就报错"?因为那会让一个租户改一行富文本就拖垮整个看板的抓取;为什么不能"全失败也静默"?因为那等于把一次 markup 变更变成整板 0 描述入库,且没有任何外部信号。这条边界有专门的回归测试 TestDeelUnresolvedRefsError(引用 $ff,无对应文本行)。
各个错误都用 fmt.Errorf("deel: board %q: %w", e.Board, err) 包裹看板上下文。仓库的板上健康机制(board_health 的 consecutive_failures / last_error)依赖这个上下文定位问题看板,而单个看板失败不会中止同 provider 下其他看板的抓取(见 internal/ingest/sources/AGENTS.md 的 "one failing board is counted (stats.Failed) but does not abort the rest")。
6. 测试与 fixture:用真实抓取裁剪出"形状正确"的数据
任务清单(tasks.md)把实现拆成 TDD 步骤,仓库中的产出与之一一对应:
- fixture:internal/ingest/sources/testdata/deel_klarna.html 是从真实
jobs.deel.com/klarna页面裁剪出的约 2 条职位 + 它们的文本行 +careerPageSettings,保持 flight 格式原样(两个self.__next_f.push脚本,其中push(<a href="https://link.gitcode.com/i/cdc92a335e938e6b5c0a311f01dc4782" target="_blank">0])为初始化推送);[deel_empty.html 则是"jobPostings":[]的看板页。 - flight 解码:
TestDeelDecodeFlight断言拼出的流里有"jobPostings":,且多字节文本未损坏。 - 文本行解析:
TestDeelTextRows同时断言十进制 id23(内容以<p>开头并含弯引号)与 hex id2a均能解析。 - 单请求:
TestDeelFetch用fakeHTTP记录被请求的 URL,断言恰好是https://jobs.deel.com/klarna,并断言两条职位描述都非空。由于deel没有实现HydratingSource/StreamingSource,Fetch内只有这一次网络调用,测试因此可以严格断言"无逐条详情请求"。 - 字段映射:
TestDeelFieldMapping逐字段钉死ExternalID、URL、Title、Company(配置的公司名是Configured Co,期望值仍是Klarna,即 careerPageSettings 优先)、Location、描述非空且不含<script、Remote == true。 - 时间:
TestDeelPostedAt断言createdAt落到 2025-11-04(按 UTC 天粒度比较,避开时区与小数秒)。 - 回退与启发式:
TestDeelCompanyFallback在org == ""时回退到Acme;TestDeelRemoteHeuristic用Remote Data Engineer/Office Manager两个标题验证布尔值。 - 边界:
TestDeelEmptyBoardYieldsNoJobs、TestDeelNoPayloadIsError、TestDeelDropsEmptyID、TestDeelTitleWithBrackets、TestDeelUnresolvedRefsError。
本地复现:
go test ./internal/ingest/sources/ -run 'TestDeel' -v
这条命令覆盖 provider 身份、boardless 断言(TestDeelIsBoardBased:适配器不得实现 boardless 标记接口)、解析、映射与全部边界。任务清单里的最终验证还包含 go build ./... && go vet ./... && go test ./internal/sources/... 与一次对真实 klarna 看板的 live 校验。
7. 注册与配置:一条注册线,两端校验
7.1 注册
适配器实现的是两步的 Source 接口(source.go):
type Source interface {
Provider() string
Fetch(ctx context.Context, e CompanyEntry) ([]Job, error)
}
注册方式是 internal/ingest/sources/registry.go 里 All 参数列表中的一行 NewDeel(c)。All 是所有适配器共享同一个 HTTP client 的注册表,reg(...) 带重复 provider 守卫。
因为 deel 不实现 boardless,它会自动出现在可筛选的来源 facet 中——filterableProviders 只排除"单公司且 boardless"的适配器(registry.go)。规格里"board-based,不是 boardless"这条要求因此是可验证的行为,而不是注释。
7.2 校验
Config.Validate(config.go)会在抓取前做 fail-fast 校验:provider 必须在 registry 里,company 不能为空,非 boardless 源的 board 不能为空。这解释了为什么实现里可以有 CompanyEntry{Company: "Acme", Board: "acme"} 这样的测试输入,但不可能出现"deel 但 board 为空"的合法配置。
7.3 看板从哪来:从 yml 到 Postgres
规格与提案写作时的表述是"在 board file 里列一条 provider 为 deel 的条目"(sources/deel.yml)。需要如实指出:仓库已演进为看板目录存 Postgres,internal/ingest/boardcatalog/AGENTS.md 明确记录 boards 表取代了 sources/*.yml 作为 cmd/ingest 的输入,sources/ 目录已不存在(本仓库中确实已无 sources/deel.yml)。因此规格中"board file"的语义,在当前代码里由 boards 表 + CompanyEntry 投影承载:
cmd/ingest <provider>读取该 provider 下status IN ('pending','active')的看板行,经boardcatalog.LoadForProvider投影成CompanyEntry交给pipeline.Runner;- 人工加入一个 Deel 看板用 cmd/add-board/main.go:
go run ./cmd/add-board --provider=deel --board=klarna --company="Klarna" # 只报告
go run ./cmd/add-board --provider=deel --board=klarna --company="Klarna" --apply # 真正写入
--apply 之前不会落库,这是该命令与 harvest-boards、merge-companies 共享的约定。新行以 active(策展人已验证)或 pending(未证实但可抓取)进入,pending 在首次成功抓取后被管线提升为 active。
7.4 租户发现
提案要求把租户清单"收割"进配置,做法是复用 cmd/harvest-boards 的模式。仓库中已落地专门的 prober(cmd/harvest-boards/prober.go):
type deelProber struct{}
func (deelProber) probe(ctx, c, slug) (string, int, error) {
// GET https://jobs.deel.com/<slug>/sitemap.xml
// 统计 loc 中匹配 /job-details/ 的条目数
}
为什么用 sitemap 而不是看板页做存活判定?提案写得很直接:Deel 的看板页对不存在的租户也返回 200(返回一个 HTML 外壳),所以页面状态码不可靠;而真实租户的 /<slug>/sitemap.xml 返回 XML。prober 返回的公司名为空(sitemap 不含公司名),由种子数据里的公司名兜底。调用方式:
go run ./cmd/harvest-boards deel seed.json # 只报告
go run ./cmd/harvest-boards --apply deel seed.json # 探活通过的写入目录
种子里可以写裸 slug,也可以写 {"board": "acme", "company": "Acme Inc"} 或带 expect_id 的强断言形式。
7.5 URL 反查
除了适配器本身,仓库的 ATS 链接识别表也登记了 Deel:internal/ingest/atsboard/board.go 中 {"jobs.deel.com", "deel", modePath}。这意味着一条形如 https://jobs.deel.com/acme/jobs/123 的外链可以被反解为 provider=deel, board=acme(modePath 取第一个非平台保留段作为 board,见 board.go),并有对应测试用例。用户提交的招聘链接因此能落到同一套抓取身份上,而不是变成一个孤儿 URL。
8. 为什么解析内嵌 payload,而不是调用 JSON API
设计文档专门用一节回答了这个问题,值得完整保留其推理:
- Deel 的数据确实来自
api-prod.letsdeel.com的rest/v2,但调用发生在 React Server Component 的服务端,公开路径不出现在任何客户端 chunk 里,探测也没能恢复出来; - 看板页本身已经内嵌了完整目录与完整描述,所以内嵌解析每个看板恰好一次请求,已经完全够用;
- 发现并切换到 JSON API 被记录为"未来的加固选项",不是阻塞项。
被明确否决或推迟的替代方案:
| 方案 | 结论 | 理由 |
|---|---|---|
sitemap → 逐条 /job-details/<id>/overview 抓详情 |
否决 | 看板页已内联全部描述,逐条抓是纯 N+1 开销 |
| 无头浏览器捕获 JSON API | 推迟 | 成本更高,且在内嵌 payload 完整的前提下没有必要 |
映射结构化薪酬 currentCompensation / isCompensationVisible |
超范围 | 薪酬归 enrichment 负责,Job 形状里也没有对应字段 |
| 映射部门/团队/雇佣类型 | 超范围 | 同上,规格未要求 |
也要如实记录这条设计自带的脆弱性:flight 格式解析天生对 markup 变更敏感。这被接受为有意的权衡——因为失败模式被设计成"响亮报错"(解码错误或 board 级错误),而不是"静默的坏数据",与 google 适配器的内嵌解析是同一种取舍。
9. 接入一个"内嵌 payload 型"源的检查清单
把 Deel 这个变更抽象成可复用的操作清单:
- 确认 payload 是否自足:列表页是否已包含每条职位的完整描述?若否,才考虑详情请求(并评估是否要实现
HydratingSource以免每次抓取都重取全量详情)。 - 确认 board 的语义:是租户 slug、子域、还是搜索关键词?这决定
Source是否需要实现boardless/aggregator,以及是否需要写fold规则进boardIdentity以避免同一 board 的两种写法造成错误关岗。 - 确认稳定的公开寻址 id:优先选同时出现在公开 URL 与 sitemap 中的那个 id,保证
external_id、url、sitemap 三者不漂移。 - 检查 id 与长度的进制:RSC 文本行的行 id 与字节长度都是 hex;切片只能落在字节上。写测试时务必同时覆盖
0–9与a–f的 id。 - 括号扫描必须在字符串之外计数:租户可控标题里的
[]{}是最常见的破绽,用一条带方括号标题的回归测试钉住。 - 区分"空"与"坏":空数据集返回 0 条 + nil;结构缺失、或全体引用解析失败返回错误。为每条都写一个测试。
- 提供 fixture 而非联网测试:从真实页面裁剪,保留原始格式,这样脆弱的解析被钉在真实形状上,测试又可离线运行。
- 登记三处身份:适配器(
sources.All)、URL 识别表(atsboard)、租户探活 prober(harvest-boards)。缺一处就会出现"能抓但链接不认"或"能加但探不出"的缝隙。 - 验证命令:
go build ./... && go vet ./... && go test ./internal/ingest/sources/ -run 'TestDeel' -v,再对真实租户做一次 live 检查。
10. 小结
Deel 适配器的价值不在代码量(deel.go 不到 140 行),而在于它把一条容易踩坑的链路拆成了四段可独立验证的原语:decodeNextFlight 负责 flight 拼接与 UTF-8 正确性,bracketSlice 负责在非 JSON 文档里安全地取出 JSON 值,nextFlightTextRows 负责 hex id + 字节长度切片,toJob 负责把"平台说了什么"与"启发式猜了什么"严格分开(WorkMode 留空、Remote 用共享启发式)。再叠上"空是合法、坏要响亮"的失败语义,一个新 ATS 源就变成了可观测、可回归、可运维的一等公民——而不是一个靠运气解析 HTML 的脚本。