为 freehire 接入 Reed 招聘源:基于 TDD 任务清单解析 Keyed 聚合器适配器实现

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

为 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 给出了三条硬约束,这决定适配器的形状而不只是实现细节:

  1. 站点与 API 都被 robots.txt 禁止抓取(/jobs/ 与 /api/ 均为 Disallow),因此不能像普通 ATS 适配器那样"顺着列表页爬";
  2. Jobseeker API 由(免费)API Key 保护,认证方式是 HTTP Basic:key 作用户名、密码留空;
  3. 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 }
}

三个边界条件值得注意:

  1. 关键词必须 url.QueryEscape——".net developer"、".NET" 这类词直接拼进 query 会破坏参数;
  2. 三重终止:空页、skip 达到 reedMaxSkip、或本页已覆盖 totalResults。前者防止 API 忽略 resultsToSkip 时死循环,后者避免无谓的翻页;
  3. 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 聚合器源"的通用模板,其结构值得原样借鉴:

  1. 先抓 fixture 再写代码——把外部契约冻结成可重放的数据,让后续所有断言都有稳定地基;
  2. 把"不该做的事"写进测试——must NOT implement StreamingSource、all searches fail must error、Fetch 路径下不得出现 SeenRefresh,这三条都是防止未来重构造成静默错误的护栏;
  3. 用精选词表代替不存在的过滤器——当上游 API 缺少维度时,枚举 + 去重 + 下游词典兜底,比试图精确匹配更可靠;
  4. 把成本模型写进类型系统——HydratingSource 这个 marker interface 让"只为新职位花钱"成为编译期可判定的能力,而不是散落在业务逻辑里的 if;
  5. 区分"脏数据"与"故障"——单条详情失败丢弃、单个关键词失败跳过、全量失败报错,三层语义各自对应一种真实故障域。

配合阅读的延伸路径:proposal.md 给出决策背景,spec.md 给出可验收的需求语义,reed.go 与 reed_test.go 是最终的实现与证据,而 registry.go、source.go 与 pipeline.go 则解释了适配器在整条采集链路上的位置。

登录后查看全文
freehire