为 freehire 接入 Reed 招聘源:基于 TDD 任务清单解析 Keyed 聚合器适配器实现
为 freehire 接入 Reed 招聘源:基于 TDD 任务清单解析 Keyed 聚合器适配器实现
本文以 freehire 仓库中 openspec/changes/archive/2026-06-18-add-reed-source/tasks.md 这份已归档的实现任务清单为主线,完整还原 freehire 如何把英国招聘网站 Reed(reed.co.uk)的 Jobseeker API 接入到它的采集流水线。读完后你会掌握:如何用 TDD 拆分一个"带 API Key、按关键词枚举、按需水合详情"的聚合器适配器;Reed 的 Basic Auth 认证与分页/配额约束在代码里如何落地;以及从任务清单到最终实现之间发生的两处关键设计演进(Streaming → Hydrating、sources/reed.yml → board catalog)。
任务清单的完整骨架
tasks.md 把工作切成两个阶段:阶段 1 是适配器本身的 TDD 循环(1.1 抓 fixture → 1.2 红灯 → 1.3 绿灯 → 1.4 注册),阶段 2 是验证(测试/构建/vet、gofmt、真实 API 冒烟)。原文的勾选项与最终仓库中的落点可以一一对应:
| 任务项 | 清单要求 | 仓库中的实际落点 |
|---|---|---|
| 1.1 | 从线上 API 抓两份 fixture:搜索页 reed_search.json、职位详情 reed_job.json |
internal/ingest/sources/testdata/reed_job.json、reed_search.json |
| 1.2 | 写红灯测试:Provider()=="reed"、boardless/aggregator 标记、仅在 REED_API_KEY 设置时注册、board file 校验、以及一个覆盖去重/认证/URL 回退/详情描述四条断言的 fetch 测试 |
internal/ingest/sources/reed_test.go |
| 1.3 | 实现 reed 结构体、NewReed、标记方法、精选 IT 关键词表、搜索分页 + 详情抓取、日期布局 02/01/2006、描述清洗 |
internal/ingest/sources/reed.go |
| 1.4 | 在 sources.All 中按 REED_API_KEY 环境变量注册,位置紧邻 usajobs;补 sources/reed.yml 占位 |
internal/ingest/sources/registry.go#L593-L595 |
| 2.1 | go test ./internal/sources/ 通过;go build ./... && go vet ./... |
包路径实际为 internal/ingest/sources |
| 2.2 | gofmt 无差异 |
仓库根 Makefile 与 CI 约束 |
| 2.3 | 带真实 key 对线上 API 冒烟:确认产出带真实 externalUrl 与完整描述的 IT 职位(有界样本) |
人工验证步骤,不可在仓库内自动化 |
两份 fixture 的路径说明了一个细节:任务清单里写的 internal/sources/ 是简写,实际包目录是 internal/ingest/sources/,包内所有适配器(约 300 个 provider)共享同一套 Source 接口与工具函数。
为什么 Reed 必须走 API,而不是抓网页
归档提案 proposal.md 给出了三条硬约束,这决定适配器的形状而不只是实现细节:
- 站点与 API 都被 robots.txt 禁止抓取(
/jobs/与/api/均为Disallow),因此不能像普通 ATS 适配器那样"顺着列表页爬"; - Jobseeker API 由(免费)API Key 保护,认证方式是 HTTP Basic:key 作用户名、密码留空;
- API 只支持自由文本
keywords,没有行业(sector)过滤器,而 freehire 是 IT 招聘聚合站,所以必须用一组人工精选的 IT 关键词去"切"出一个主题切片。
此外,API 列表接口有两个数据缺陷,直接催生了"详情水合"设计:列表结果不含雇主真实投递地址 externalUrl,且描述被截断。真正的 externalUrl 与完整 jobDescription 只有 /jobs/{id} 详情端点才有(见 reed.go#L22-L33 的注释)。
规范增量 spec.md 把上述约束固化成了可验收的三条 Scenario:key 未配置时 All() 不注册 reed;同一 jobId 被多个关键词命中时只产出一次;详情的 externalUrl 优先于 Reed 列表页 URL,缺失时回退到 jobUrl。
1.1 抓 fixture:把线上契约冻结进仓库
TDD 的第一步不是写代码,而是把外部 API 的真实响应保存成测试夹具。tasks.md 要求两份:一份搜索页、一份详情。详情 fixture 使用了一条真实的 Tesco 招聘记录,包含 employerId、salaryType、expirationDate、externalUrl、jobUrl、contractType 等字段,其中关键片段是:
{
"employerName": "Tesco",
"jobId": 57029285,
"jobTitle": "HGV Class 2 Driver",
"datePosted": "17/06/2026",
"externalUrl": "https://careers.tesco.com/en_GB/careers/JobDetail/HGV-Class-2-Driver/190529",
"jobUrl": "https://www.reed.co.uk/jobs/hgv-class-2-driver/57029285",
"jobDescription": " <p>About the role </p> ..."
}
这份 fixture 被测试 TestReedDetailFixtureMaps 直接消费,用来防止解码层漂移:
raw, err := os.ReadFile("testdata/reed_job.json")
var d reedJob
json.Unmarshal(raw, &d)
job, ok := d.toJob()
// 断言 URL 前缀为 https://careers.tesco.com/,Company == "Tesco",Description 非空
值得注意的是,这条 fixture 的职位是 HGV 司机而非 IT 职位——它验证的是字段映射的正确性(尤其是 externalUrl 覆盖 jobUrl),而不是关键词切片的有效性。切片有效性的验证在 2.3 的线上冒烟阶段完成。
1.2 红灯:测试先行的四组断言
tasks.md 的 1.2 把测试拆成了五类断言。逐一对应到 reed_test.go:
类型与标记
func TestReedProvider(t *testing.T) {
if got := NewReed(nil, "k").Provider(); got != "reed" { ... }
}
func TestReedIsBoardlessAggregator(t *testing.T) { /* boardless + aggregator 两个标记 */ }
boardless 与 aggregator 是本包里两个空方法接口(marker interface),只用于类型断言。它们不是装饰:Config.Validate 依靠 boardless 决定"是否允许该 provider 的条目省略 board id"(config.go),而 aggregator 决定它在源分面(source facet)与聚合覆盖率抑制逻辑中的身份。
Key 门控注册
clearCrawlCredentials(t)
if _, ok := All(NewClient())["reed"]; ok { /* 不应注册 */ }
t.Setenv("REED_API_KEY", "test-key")
if _, ok := All(NewClient())["reed"]; !ok { /* 应注册 */ }
这条测试锁定的是"凭证只影响爬取注册表,不影响分类注册表"。同包 taxonomy_test.go 进一步说明:Taxonomy() 走 All(nil),即使没有任何凭证,也必须把所有 provider 的分类答案注册齐——因为 reindex、ghost-crosscheck、状态页和源分面都读它,无 key 的主机必须与有 key 的主机给出相同的"这是什么类型的源"。
水合而非流式
func TestReedIsHydratingNotStreaming(t *testing.T) {
// 应当实现 HydratingSource
// 必须 NOT 实现 StreamingSource
}
这条断言背后是一个调度顺序陷阱:流水线先判断 StreamingSource,再判断 HydratingSource。如果 Reed 同时实现了 streaming,FetchStream 会被优先派发,seen 谓词根本不会被传进来,水合逻辑被整体绕过,每个爬取周期都会为每条存量职位重新抓详情——对按小时配额计费的 Reed 来说等于慢性自杀。所以测试显式要求"不能实现 StreamingSource",这不只是代码风格,而是正确性约束。
Fetch 的四条核心断言
fakeReed 对每个关键词都返回同样的两结果搜索页,从而能证明去重真的发生:
| 断言 | 期望行为 |
|---|---|
(a) jobId 跨关键词去重 |
30 个关键词 × 2 条结果 → 仍只有 2 个 job |
| (b) 携带 Basic Auth | Authorization == "Basic " + base64(key + ":") |
(c) externalUrl → URL,jobUrl 兜底 |
1001 用雇主站点,1002 回退到 Reed 列表页 |
| (d) 描述来自详情 | Description 含详情中的正文片段,且 PostedAt 解析为 2026-06-17 |
此外还有两条故障语义测试,它们是这份清单里最容易被忽略、但在生产中价值最高的部分:
TestReedPartialKeywordFailureStillReturnsJobs:单个关键词搜索失败被容忍(跳过),其余关键词的并集仍可入库,与"单条详情失败被丢弃"的语义一致;TestReedAllSearchesFailReturnsError:所有关键词都失败时必须返回 error,否则一次 key 失效导致的 401 会被伪装成"Reed 今天没有职位",进而把一次空爬取持久化下去。
TestReedFetchNewHydratesOnlyUnseen 则是"配额"这件事的直接测试:传入 seen 判定 1001 已入库,断言 1001 被标记 SeenRefresh 且详情请求次数为 0,而新职位 1002 必须被抓详情并携带内容。
1.3 绿灯:reed.go 的实现拆解
结构体与常量
type reed struct {
http HeaderJSONGetter
apiKey string
}
const (
reedSearchURL = "https://www.reed.co.uk/api/1.0/search"
reedJobURL = "https://www.reed.co.uk/api/1.0/jobs/"
reedPageSize = 100 // API 允许的最大分页大小
reedMaxSkip = 5000 // 单关键词分页上限,兜住失控的 feed
reedDetailWorkers = 6 // 克制的详情并发;共享客户端会重试 429/5xx
reedDateLayout = "02/01/2006" // API 的日粒度日期,如 "17/06/2026"
)
这些常量在原文清单里只出现了一个(02/01/2006),其余是清单"分页 + 并发"意图的具体取值。reedDetailWorkers = 6 低于包内默认的 defaultDetailWorkers = 8(helpers.go),理由写在注释里:Reed 有每小时请求配额,并发压低一点、依靠共享客户端的 429/5xx 重试更稳。
reed 依赖的是 HeaderJSONGetter 而不是普通 JSONGetter——因为认证头必须随每次请求注入,这也是整个适配器不需要自己管 HTTP 细节、却能携带 Basic Auth 的原因。
Basic Auth:key 当用户名,密码留空
func (r reed) authHeaders() map[string]string {
token := base64.StdEncoding.EncodeToString([]byte(r.apiKey + ":"))
return map[string]string{"Authorization": "Basic " + token}
}
需要手工验证 key 是否有效时,等价的命令行形式是(-u 的冒号后留空即空密码):
curl -s -u "$REED_API_KEY:" \
"https://www.reed.co.uk/api/1.0/search?keywords=software%20engineer&resultsToTake=1"
FetchNew 在开头还有一道防御:apiKey == "" 直接返回 errors.New("reed: missing API key (set REED_API_KEY)"),让"配置漏了"表现为明确错误而不是一串 401。
精选 IT 关键词表
API 没有 sector 过滤,所以切片方式就是"枚举一组关键词":reed.go#L53-L61 定义了 30 个词条,覆盖软件工程、前后端、移动端、DevOps/SRE/平台、云、数据/机器学习、QA、安全,以及按语言/框架划分的开发者角色(Python/Java/Go/JS/TS/React/Node/.NET/PHP/Ruby)和解决方案架构师。
最关键的一条注释是:故意省略裸词 IT。它会把 "IT support" 以及大量零散提及全部捞进来,约 3.3 万条噪声结果,远超真实的技术岗位范围。残留的非 IT 职位交由后续的 classify/skilltag 词典丢弃——这是"宁可多抓一点再由下游过滤"与"关键词过窄导致漏抓"之间的权衡。
搜索:分页、去重、失败容忍
for skip := 0; skip < reedMaxSkip; skip += reedPageSize {
u := fmt.Sprintf("%s?keywords=%s&resultsToTake=%d&resultsToSkip=%d",
reedSearchURL, url.QueryEscape(kw), reedPageSize, skip)
...
if len(resp.Results) == 0 { break }
// 按 JobID 去重后追加
if skip+reedPageSize >= resp.TotalResults { break }
}
三个边界条件值得注意:
- 关键词必须
url.QueryEscape——".net developer"、".NET" 这类词直接拼进 query 会破坏参数; - 三重终止:空页、
skip达到reedMaxSkip、或本页已覆盖totalResults。前者防止 API 忽略resultsToSkip时死循环,后者避免无谓的翻页; JobID == 0跳过,避免无效记录进入后续详情抓取。
searchIDs 用 seen map[int64]struct{} 做跨关键词去重,并统计成功的关键词数:
if succeeded == 0 {
return nil, fmt.Errorf("reed: all %d keyword searches failed: %w", len(reedKeywords), firstErr)
}
这段是"部分失败可接受、全量失败必须报错"的实现落点,对应 1.2 的两条故障语义测试。
详情映射:toJob 的字段契约
func (j reedJob) toJob() (Job, bool) {
if j.JobID == 0 || j.EmployerName == "" {
return Job{}, false
}
return Job{
ExternalID: strconv.FormatInt(j.JobID, 10),
URL: firstNonEmpty(j.ExternalURL, j.JobURL),
Title: j.JobTitle,
Company: j.EmployerName,
Location: j.LocationName,
Description: sanitizeHTML(j.JobDescription),
Remote: isRemote(j.LocationName),
PostedAt: parseLayout(reedDateLayout, j.DatePosted),
}, true
}
逐字段的取值理由:
| Job 字段 | 来源 | 说明 |
|---|---|---|
ExternalID |
jobId 十进制字符串 |
流水线会再用 board 命名空间包装成 :<id>(board 为空) |
URL |
externalUrl,否则 jobUrl |
雇主自有投递页优先,符合 spec 的第三条 Scenario |
Company |
employerName |
缺失即丢弃:空公司名会破坏 company slug |
Description |
sanitizeHTML(jobDescription) |
详情正文是 HTML,统一走 internal/platform/htmltext 清洗 |
Remote |
isRemote(locationName) |
仅基于地点文本的启发式,命中 "remote"/"удал" |
PostedAt |
parseLayout("02/01/2006", datePosted) |
日期格式错误返回 nil,而不是报错 |
日期布局是 Reed 特有的坑:17/06/2026 是日/月/年,与英美常见格式相反,写成 Go 布局就是 02/01/2006。parseLayout 内部还会过一道 NotFuture(dates.go),把明显落在未来的时间戳(比如把过期日误读成发布时间)判为 nil,避免脏数据霸占"最新优先"排序。
注意 toJob 只填了 Job 的一小部分字段:WorkMode、Seniority、Category、Skills 等结构化分面全部留空,交由流水线的词典与分类器推导——这符合 Job 类型的约定:"适配器只在平台给出结构化字段时才设置,否则交给词典"。
并发详情抓取
return fetchDetails(ids, reedDetailWorkers, func(id int64) (Job, bool) {
extID := strconv.FormatInt(id, 10)
if seen(extID) {
return Job{ExternalID: extID, SeenRefresh: true}, true
}
return r.detail(ctx, id)
}), nil
fetchDetails 是包内共享的有界工作池(helpers.go#L30-L59):ok=false 的条目被丢弃,一条详情失败不会中断整轮采集,返回值保持输入顺序。Reed 的 detail 正是这样做的——失败即 return Job{}, false。
从 FetchStream 到 FetchNew:清单与实现的一处设计演进
原文 1.3 写的是"FetchStream(按关键词分页搜索 → 唯一 jobId → fetchDetailsStream 抓详情)+ 缓冲式 Fetch",提案里也沿用了这个方案(对标 eightfold)。但最终代码落地的是另一条路径:FetchNew + HydratingSource,并且测试明确禁止实现 StreamingSource。这不是遗漏,而是一次有据可查的设计修正:
| 维度 | StreamingSource(原计划) | HydratingSource(最终实现) |
|---|---|---|
| 主要收益 | 边抓边写,长爬取可断点续存 | 只对未入库职位抓详情,压住配额 |
| 是否感知 seen-set | 否 | 是,流水线注入 seen(externalID) |
| Reed 的痛点匹配度 | 解决"中断丢失进度" | 解决"每小时配额被存量职位耗尽" |
| 是否可同时实现 | — | 不可以:派发顺序 streaming 优先,会绕过水合 |
配额才是 Reed 的真正瓶颈:列表接口便宜,详情接口贵,而 Reed 按小时计请求数,超限返回 403 "exceeded your per-hour request limit"。上一节那段 seen 分支就是解药——已入库职位以 SeenRefresh 身份重新出现,不发详情请求。
它与流水线侧的契约在 pipeline.go#L742-L772:
SeenRefresh的 Job 只带身份、不带内容。注释写明了原因:一次无内容的 re-upsert 会抹掉该职位当初新入库时水合出来的描述与分面(空描述会重新推导出空分面),所以必须走touch而不是save;touch只刷新 liveness(pipeline.go#L1103-L1110,经由Toucher端口),保持职位"仍然在线";- 即便是一次刷新,也要过目录过滤器,且判断依据是已存储的技术证据而非这次的空内容——否则标题里不含技术词的工程岗位会被自己的重新上架"刷死"。
FetchNew 的派发条件在 pipeline.go#L1016-L1058:适配器实现了 HydratingSource 且 Store 能提供该 board 的 seen-set 时才用它(ExistingExternalIDs),否则回退到 Fetch。两个安全阀值得一提:
- seen-set 查询失败 fail-open:
set = nil,所有职位当作新职位处理,宁可贵一点也不能因健康检查抖动而跳过整块 board; Fetch保留为"列表即全量"的兜底路径(seen恒为 false),用于非 DB 调用方与测试,对应测试中"Fetch 回退路径下任何职位都不得出现SeenRefresh"的断言。
1.4 注册:一行环境变量门控
if key := os.Getenv("REED_API_KEY"); c == nil || key != "" {
registry["reed"] = NewReed(c, key)
}
它紧挨着 usajobs 的注册块(registry.go#L585-L595),条件分两种:
c != nil(爬取路径):只有 key 非空才注册,避免一个每条 board 都会 401 的 provider 进入爬取表;c == nil(Taxonomy()路径):无条件注册(key 可为空),保证分类答案在任何主机上一致。
关于 1.4 的"补 sources/reed.yml 占位":这个文件在当前仓库中已不存在。Source 类型的注释仍以 sources/<provider>.yml 描述 CompanyEntry 的来源,但看板配置已由 internal/ingest/boardcatalog 承载——catalog.go 明确写着它"replaces sources/*.yml",Validate 也复用同一份 sources.Config 做 provider 与 board 校验。因此 reed 的"无 board"特性在 catalog 层面的意义是:新增条目时 board 可留空(BoardDedupeKey 对 boardless 条目直接返回 ok=false,它永远不会与别的条目重复)。
board 为空还决定了去重键的形态。externalid.Namespace 的格式是 <board>:<externalID>,于是 Reed 的职位存为 :1001 这样的 key;它与 source 字段 reed 一起构成 (source, external_id) 去重键。这也是为什么所有写入路径(采集流水线、Telegram 链接抽取)都必须经过同一个 Namespace 函数——否则同一条职位会以两种命名空间重复入库。
阶段二:验证清单的执行方式
清单 2.1–2.3 对应三组动作,可直接在仓库根目录执行(注意包路径是 internal/ingest/sources,不是清单简写的 internal/sources):
# 2.1 单元测试 + 构建 + 静态检查
go test ./internal/ingest/sources/ -run 'TestReed' -v
go build ./...
go vet ./...
# 2.2 格式检查(无输出即通过)
gofmt -l internal/ingest/sources/reed.go internal/ingest/sources/reed_test.go
2.3 的 "live smoke" 无法在仓库内自动化,因为有界样本依赖真实凭证与线上数据。可执行的验证方式是把 key 放进环境后直接打两个端点(搜索一次 + 详情一次),确认 externalUrl 非空、jobDescription 长度接近完整正文、datePosted 能被 02/01/2006 解析。这也是唯一能验证"关键词切片是否真的产出 IT 岗位"的手段——单元测试里的 fixture 是 HGV 司机,刻意不承担这个职责。
生产观察与排障对照
归档时 docs/sources.md 的统计快照(2026-10-20)显示 reed 有 6,078 条在架职位,位于聚合器分组的第 22 位。提案里预估首次采集约 1–1.5 万条 IT 职位,实际在架数低于预估是正常的:后续周期会按 (source, external_id) 归并、按目录过滤器淘汰非技术岗、并按未刷新扫描关闭已下线职位。
按症状定位问题的路径:
| 症状 | 可能原因 | 代码位置 |
|---|---|---|
reed: missing API key (set REED_API_KEY) |
适配器被直接构造但环境变量为空 | reed.go#L129-L132 |
reed: all 30 keyword searches failed: ... 401 |
key 失效/未注入,Basic 凭证构造错误 | searchIDs 的 succeeded == 0 分支 |
403 ... per-hour request limit |
配额打满:通常是水合路径未生效(例如误加了 StreamingSource) | TestReedIsHydratingNotStreaming 所防护的场景 |
| 一次爬取"零职位"且无报错 | 所有关键词都返回空页但请求成功;或 board 冷却 | 空页是正常终止,未见过的 board 会进冷却逻辑 |
| 存量职位的描述/分面被清空 | 对 SeenRefresh 记录执行了内容写入 |
应走 touch,见 pipeline.go#L750-L772 |
| 同一职位出现两行 | 命名空间不一致(如详情里用了 Reed 的 jobUrl 作为 id) |
必须用 jobId 作 ExternalID |
这份任务清单的可复用价值
回到清单本身,它能作为"新增一个 keyed 聚合器源"的通用模板,其结构值得原样借鉴:
- 先抓 fixture 再写代码——把外部契约冻结成可重放的数据,让后续所有断言都有稳定地基;
- 把"不该做的事"写进测试——
must NOT implement StreamingSource、all searches fail must error、Fetch 路径下不得出现 SeenRefresh,这三条都是防止未来重构造成静默错误的护栏; - 用精选词表代替不存在的过滤器——当上游 API 缺少维度时,枚举 + 去重 + 下游词典兜底,比试图精确匹配更可靠;
- 把成本模型写进类型系统——
HydratingSource这个 marker interface 让"只为新职位花钱"成为编译期可判定的能力,而不是散落在业务逻辑里的 if; - 区分"脏数据"与"故障"——单条详情失败丢弃、单个关键词失败跳过、全量失败报错,三层语义各自对应一种真实故障域。
配合阅读的延伸路径:proposal.md 给出决策背景,spec.md 给出可验收的需求语义,reed.go 与 reed_test.go 是最终的实现与证据,而 registry.go、source.go 与 pipeline.go 则解释了适配器在整条采集链路上的位置。