freehire 接入 getmatch.ru:从任务清单到源码实现的招聘源适配器全解

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

freehire 接入 getmatch.ru:从任务清单到源码实现的招聘源适配器全解

freehire 是一个面向求职者的开源职位搜索引擎,它通过大量「源适配器」把各家招聘平台与 ATS 的职位抓取、归一化后写入统一目录。本文以 openspec/changes/archive/2026-06-19-add-getmatch-source/tasks.md 这份任务清单为骨架,逐条讲解为俄罗斯 IT 招聘市场 getmatch.ru 新增 getmatch 源适配器的完整落地过程:从可测试的假 HTTP 客户端与真实形态的 JSON 夹具,到分页枚举、详情描述回退、结构化工作模式派生,再到注册、配置与验收命令。读完后你可以独立复现这一类「无 board 的多公司聚合源」适配器,并理解 freehire 中适配器与流水线之间的职责边界。

一、背景:为什么需要一个新的聚合源

根据同目录的 proposal.md,getmatch.ru 是一个策展式(curated)的俄罗斯 IT 职位市场,职位列表页 /vacancies 背后是一个公开、无需密钥的 JSON API。它已经在聚合约 760 条活跃职位,雇主包括 X5、Т-Банк、VK、МегаФон、CIAN、Островок 等多家公司——因此它属于市场型聚合器(marketplace aggregator),而不是单一公司的招聘板。

freehire 已经覆盖了俄罗斯市场的一批单一来源(yandex、vk、tbank、sber、telegram 等),getmatch 属于该细分市场中的覆盖缺口,接入后可以复用既有的抓取流水线与写入路径,不需要任何 schema 变更。

1.1 侦察得到的 API 表面

设计文档 design.md 记录了对该站点的接口侦察结果,这是整个适配器设计的依据:

端点 行为 用途
GET /api/offers?offset=N&limit=M 返回 { meta: {total, offset, limit}, offers: [...] };limit 默认 20;侦察时 total ≈ 760(755 条 vacancy + 5 条 one_day_offer) 列表枚举
GET /api/offers/{id} 返回同一 offer 对象,并附加更丰富的字段,尤其是 description(完整 HTML,样本约 1155 字符)与列表里的短字段 offer_description(约 459 字符) 详情补全
GET /api/vacancies 返回 401 {"detail":"Login required"} 不使用(个性化接口)

每个 offer 自带 company.name,所以配置项里的公司名只是校验占位符——真正的雇主来自每条职位本身。这与仓库中已有的 tecla、jobstash 适配器同构。

1.2 工作模式字段的分布

location_items[].format 给出了按地点粒度的工作模式,取值来自整个目录观测到的词表:

  • remote(447)
  • hybrid(609)
  • office(124)
  • relocation_company(77)
  • relocation_candidate(6)

760 条中有 614 条只包含单一工作模式,146 条混合了两种或三种。这个统计直接决定了「仅在无歧义时才输出结构化工作模式」的设计取舍(见第四节)。

1.3 目标与非目标

目标很明确:把 getmatch.ru 以 source = "getmatch" 纳入目录,带完整 HTML 描述,并在无歧义时给出干净的结构化工作模式;实现上沿用既有的 boardless 聚合器模式,做到「一个新适配器文件 + 一行注册 + 一个 board 配置」。

非目标(design.md 明确列出)包括:薪资摄取、从 skills_objects 抽取技能(项目用自己的 internal/skilltag 词典派生)、StreamingSource 增量持久化、以及部门/专业化/资历/团队规模等分类字段的映射(分类由下游确定性派生)。

二、任务清单总览

原始任务清单把工作拆成四组、七个可勾选项,全部标记为完成:

分组 任务 产出
1. Test fixtures 1.1 路由感知的测试 fake + 内联真实形态 JSON 夹具 覆盖单模式、混合模式、仅搬迁+单模式、一日活动卡,以及 /api/offers/{id} 详情体
2. Adapter core 2.1 响应/offer 结构与 getmatch 适配器类型,含 Provider()、boardless()、aggregator()、NewGetmatch(c JSONGetter) 适配器骨架,对齐 tecla
2.2 Fetch 分页,遇到 meta.total 停止,受 maxPages 约束;字段映射;首页失败报错、后续页失败结束枚举 枚举逻辑
2.3 抓取 /api/offers/{id},使用清洗后的 HTML description,空或失败时回退到列表 offer_description 描述补全
2.4 从 location_items[].format 派生结构化 WorkMode,忽略 relocation_*,仅在单一工作模式时输出;Remote 仅当模式为 remote 工作模式
3. Registration and config 3.1 在 sources.All 注册 getmatch(一行 NewGetmatch(c)) 注册
3.2 添加 sources/getmatch.yml,含一个 boardless 占位条目 配置(注意:仓库现状已迁移,见第六节)
4. Verification 4.1 go build ./... && go vet ./... && go test ./internal/sources/ 全绿,并对真实 API 做一次冒烟运行 验收

下面按这四组逐条展开,并把实现细节落到具体源码位置。

三、任务 1:路由感知的测试替身

适配器有两个形态完全不同的请求:分页列表与按 id 的详情。测试里用 JSONGetter 接口做替身,接口本身只有一个方法:

// internal/ingest/sources/http.go
type JSONGetter interface {
	GetJSON(ctx context.Context, url string, v any) error
}

测试替身 getmatch_test.go 定义了 getmatchHTTP:

type getmatchHTTP struct {
	pages      map[int]string // list body keyed by requested offset
	details    map[int]string // detail body keyed by offer id
	failList   bool           // every list request fails
	failPage   map[int]bool   // a specific offset's list request fails
	detailErr  map[int]bool   // a specific offer's detail request fails
	gotOffsets []int
	gotDetails []int
}

关键设计点:

  1. 按 URL 形态路由,而不是按调用顺序。两条正则 getmatchDetailRE = /api/offers/(\d+) 与 getmatchOffsetRE = offset=(\d+) 决定这次请求是详情还是列表。这样测试就不依赖适配器的调用顺序,后续把「逐页列表后统一抓详情」改成「交错抓取」时测试依然成立。
  2. 记录请求轨迹。gotOffsets 与 gotDetails 让测试可以断言「分页在 meta.total 处停止」以及「每个 offer 都抓了一次详情」——这正是任务 2.2 与 2.3 的验收点。
  3. 缺省返回空页。当某个 offset 没有登记夹具时,返回 {"meta":{"total":0,"offset":0,"limit":100},"offers":[]},于是分页逻辑在遇到空页时自然终止,测试不必为每一页都铺夹具。
  4. 细粒度故障注入。failList(全部列表失败)、failPage[offset](某一页失败)、detailErr[id](某个 offer 的详情失败)分别对应三类错误路径。

夹具采用内联的真实形态 JSON(而非独立的 testdata 文件),并镜像 tecla_test.go 的写法。样例包含 id: 34895、published_at: "2026-06-19T12:55:17.948391"、company.name、以及两条重复的 Москва/office 地点项——重复项正好用来验证地点去重。

四、任务 2:适配器核心

4.1 类型定义与标记方法

getmatch.go 的骨架极简,只有一个字段:

type getmatch struct {
	http JSONGetter
}

func NewGetmatch(c JSONGetter) Source { return getmatch{http: c} }

func (getmatch) Provider() string { return "getmatch" }

// getmatch is a marketplace with one global feed, so its config entries carry no board.
func (getmatch) boardless() {}

// getmatch aggregates postings from many companies, so it stays in the source facet.
func (getmatch) aggregator() {}

两个空方法不是装饰,它们在仓库里有确切语义(source.go):

  • boardless() 标记适配器的 API 没有按租户划分的 board id,因此 config.go 中的 Config.Validate 允许其条目省略 board 字段;非 boardless 的 provider 缺失 board 会直接报错。
  • aggregator() 标记这是「多公司」的 boardless 适配器。注册表的 filterableProviders(registry.go)会剔除「单公司 boardless」源,因为单公司源与公司过滤器冗余;但聚合器必须保留在 source facet,否则用户无法按 getmatch 过滤。

设计文档也记录了被否决的备选方案:不做「一公司一 board」模型,因为该 API 没有按公司划分的 board id,且 feed 是全局的。

4.2 常量与时间布局

getmatch.go 集中了所有端点与边界:

const (
	getmatchBaseURL   = "https://getmatch.ru"
	getmatchListURL   = "https://getmatch.ru/api/offers?offset=%d&limit=%d"
	getmatchDetailURL = "https://getmatch.ru/api/offers/%d"
	getmatchPageLimit = 100
	// getmatchMaxPages bounds pagination so a wrong or missing meta.total cannot loop.
	getmatchMaxPages = 200
	// getmatchDateLayout matches the zone-less published_at getmatch emits
	// ("2026-06-19T12:55:17.948391"). The .9 fractional form parses any sub-second width.
	getmatchDateLayout = "2006-01-02T15:04:05.999999999"
)

published_at 是无时区时间戳,小数位数可达 6 位。Go 的布局串中 .999999999 会吃掉可变宽度的小数部分并按 UTC 解析;如果换成 .000000 之类的定宽写法,948391(6 位)之外的样本就会解析失败。maxPages = 200 配 limit = 100,理论上限 2 万条,远超当前约 760 条的目录,同时保证 meta.total 缺失或异常时不会无限循环——这就是任务清单里「with a maxPages bound」的落地。

4.3 分页枚举 Fetch

getmatch.go:

func (g getmatch) Fetch(ctx context.Context, _ CompanyEntry) ([]Job, error) {
	var jobs []Job
	for page := 0; page < getmatchMaxPages; page++ {
		offset := page * getmatchPageLimit
		var resp getmatchListResponse
		if err := g.http.GetJSON(ctx, fmt.Sprintf(getmatchListURL, offset, getmatchPageLimit), &resp); err != nil {
			if offset == 0 {
				return nil, fmt.Errorf("getmatch: list offset %d: %w", offset, err)
			}
			break // a later page failing ends enumeration with the jobs gathered so far
		}
		if len(resp.Offers) == 0 {
			break
		}
		for _, o := range resp.Offers {
			jobs = append(jobs, g.toJob(ctx, o))
		}
		if resp.Meta.Total > 0 && offset+getmatchPageLimit >= resp.Meta.Total {
			break
		}
	}
	return jobs, nil
}

这里有四条互相独立的终止条件,构成一个「怎么都不会卡死」的循环:

  1. page < getmatchMaxPages:硬上限兜底。
  2. 请求失败:首屏(offset == 0)失败必须作为 board 级错误返回,让流水线把这次抓取记为失败;后续页失败则 break,带回已收集的职位,不报错。这个不对称是刻意的——如果吞掉首屏错误并返回空列表,目录看起来会像「这个源今天没有职位」,比显式失败危险得多。
  3. 空页:即便 meta.total 缺失或撒谎,空 offers 也能自然收尾。
  4. offset + limit >= meta.total:正常路径,按源自己声明的总数精确停止。

resp.Meta.Total > 0 的判据保证了 total 为 0 或缺失时不会在首页就误停(首页仍然会因为 len(resp.Offers) == 0 或后续页码推进而收敛)。

请求参数中 Fetch 的 CompanyEntry 被显式忽略(_ CompanyEntry)——聚合器不需要 board,也不需要配置里的公司名。

4.4 单条映射 toJob 与详情回退

getmatch.go:

func (g getmatch) toJob(ctx context.Context, o getmatchOffer) Job {
	mode := getmatchWorkMode(o.LocationItems)
	detail, _ := g.detail(ctx, o.ID)
	desc := o.OfferDescription
	if strings.TrimSpace(detail.Description) != "" {
		desc = detail.Description
	}
	return Job{
		ExternalID:         strconv.Itoa(o.ID),
		URL:                getmatchBaseURL + o.URL,
		Title:              o.Position,
		Company:            o.Company.Name,
		Description:        sanitizeHTML(desc),
		Location:           distinctJoin(o.LocationItems, ", ", func(l getmatchLocation) string { return l.Label }),
		Remote:             mode == "remote",
		WorkMode:           mode,
		PostedAt:           parseLayout(getmatchDateLayout, o.PublishedAt),
		Seniority:          getmatchSeniority(detail.Seniority),
		Category:           getmatchCategory(detail.Specializations),
		Skills:             getmatchSkills(detail.SkillsObjects),
		ExperienceYearsMin: detail.RequiredYearsOfExperience,
	}
}

字段映射与任务 2.2 的清单逐项对应:ExternalID 用数字 id 转字符串,URL 用 https://getmatch.ru 拼相对路径,Title 取自 position,Company 取自每条职位自己的 company.name,Location 是各地点的 label 去重后以 ", " 连接,PostedAt 用上面那个无时区布局解析。

描述回退链是这里最容易出错的部分,它有三个层次:

场景 结果
详情返回非空 description 用详情 HTML(完整正文)
详情 description 为空(典型是一日活动卡 one_day_offer) 回退列表的 offer_description
详情请求失败 同样回退列表摘要,绝不丢弃该职位

detail() 的注释把这个契约写得很直白:

// detail fetches the per-offer detail endpoint, returning a zero offer and false on a failed
// request so the caller falls back to the list summary and leaves the structured facets empty —
// an offer is never dropped over a missing detail.
func (g getmatch) detail(ctx context.Context, id int) (getmatchOffer, bool) {
	var detail getmatchOffer
	if err := g.http.GetJSON(ctx, fmt.Sprintf(getmatchDetailURL, id), &detail); err != nil {
		return getmatchOffer{}, false
	}
	return detail, true
}

注意 toJob 里写的是 detail, _ := g.detail(...):布尔返回值被忽略,因为「失败」与「成功但字段为空」在描述回退上走的是同一条路径。而结构化 facet 在失败时自然保持零值,符合仓库对结构化字段「不知道就留空,永不猜测」的全局契约(source.go)。

HTML 清洗走包内统一入口 sanitize.go:

func sanitizeHTML(s string) string { return htmltext.Sanitize(s) }

真正的实现位于 internal/platform/htmltext:先修复被双重转义的字面 \n,剥离自我标注的锚点,再经 bluemonday 策略清洗,最后修补孤立列表项。效果是活动内容被剥离、段落与列表结构保留——测试用 <script>x()</script> 验证了这一点。

地点去重复用泛型工具 helpers.go:

func distinctJoinT any string) string

它按首次出现顺序保留非空且未重复的标签。夹具里两条 Москва 因此只输出一次「Москва」,否则位置字符串会变成「Москва, Москва」。

4.5 结构化工作模式派生

getmatch.go:

func getmatchWorkMode(items []getmatchLocation) string {
	var mode string
	for _, it := range items {
		m := workplaceTypeMode(it.Format)
		if m == "" {
			continue
		}
		if mode == "" {
			mode = m
		} else if mode != m {
			return ""
		}
	}
	return mode
}

映射本身由共享函数 helpers.go 提供:

func workplaceTypeMode(t string) string {
	switch strings.ToLower(strings.TrimSpace(t)) {
	case "remote":
		return "remote"
	case "hybrid":
		return "hybrid"
	case "on-site", "onsite", "on site", "office":
		return "onsite"
	default:
		return ""
	}
}

行为要点:

  • office → onsite,remote → remote,hybrid → hybrid。
  • relocation_company / relocation_candidate 落到 default 分支返回 "",于是被跳过而不是被当作冲突。所以「office + 两个 relocation 标记」仍判定为 onsite。
  • 只有单一去重后的工作模式才输出;一旦出现 remote 与 office 混排就返回 "",把决定权交给流水线的地点字符串解析器。
  • Remote 严格等价于 mode == "remote",即「当且仅当」。

设计文档解释了为何不把「remote + office」塌缩成 hybrid:那是一种推断,会污染结构化字段的来源可信度。代价是 146/760 条混合模式的职位失去结构化工作模式,这个损失被显式接受。

4.6 详情端点提供的结构化 facet

任务清单与 design 的「非目标」都只提到描述与工作模式,但当前 getmatch.go 已经利用同一个详情响应补齐了四个结构化 facet——这是实现相对早期设计文档的增量扩展,值得单独说明:

资历(Seniority):不做猜测式映射,而是用词表成员判定:

func getmatchSeniority(grade string) string {
	g := strings.ToLower(strings.TrimSpace(grade))
	if slices.Contains(vocab.SeniorityValues, g) {
		return g
	}
	return ""
}

internal/dict/vocab/vocab.go 中 SeniorityValues 为 intern/junior/middle/senior/lead/staff/principal/c_level;getmatch 的 junior/middle/senior/lead/c_level 是它的子集且拼写一致,所以「词表成员即映射」成立,trainee 这类不在词表里的值被丢弃而不是猜测。

类别(Category):getmatchSpecializationCategory 是一张只收高置信度代码的显式映射表(python/golang/java_scala/c_sharp/php/ruby/js_backend → backend,android/ios/cross_platform_flutter_react_native → mobile,dev_ops/system_administrator → devops,sre、data_engineering、dwh_data_warehouse、data_science、data_analyst_bi、qa_auto、qa_manual、information_security、embedded、blockchain_crypto、product_design、product_management、project_management、engineering_management → software_engineering、sales、marketing、support_engineer → support 等)。无法干净对应的代码(business_analyst、system_analyst、product_analyst、architect、c_cpp、dba、招聘/写作类)故意不进表,交给标题词典判断。

解析函数 getmatchCategory 与工作模式同构:只统计能映射的代码,全部一致才输出,冲突返回 "";无法映射的代码被忽略而不是算作冲突。测试 TestGetmatchCategoryMapTargetsAreValid 会遍历整张表,断言每个目标值都在 vocab.CategoryValues 中,防止映射表随词表演进而漂移。

技能(Skills):走 skilltag.Canonicalize(internal/dict/skilltag/canonicalize.go)而非 Parse。原因写在注释里:skills_objects 已经是离散的、被平台断言过的名字,不是需要从散文里挖掘的文本,Parse 的「需要第二个强词佐证」规则会误杀单词技能名。因此 Golang → go、Docker → docker,而 Kiss 这类噪音被丢弃。

最低经验年限(ExperienceYearsMin):直接指向 required_years_of_experience,用 *int 保留「未声明」与「0 年」的区别。

五、任务 3:注册与配置

5.1 注册表

注册是真正的一行,位于 registry.go 的「Multi-company aggregators (boardless)」分组:

		// Multi-company aggregators (boardless): one global feed, company per posting.
		NewTecla(c),
		NewTeamex(c),
		NewTopco(c),
		NewGetmatch(c),
		NewGetmanfred(c),

All(c HTTPClient) 负责把注册表装配起来,并把同一个 HTTP 客户端共享给所有适配器;c == nil 时构建的是无传输的分类注册表 Taxonomy(),只用于回答「这个 provider 属于哪一类」,绝不允许经它发起抓取。仓库的 AGENTS.md 特别强调这条不变量:FilterableProviders、状态页的 provider kind、去重流程的聚合器集合都读 Taxonomy,否则分类结果会随部署主机是否配置了密钥而变化。

5.2 board 配置:任务清单与仓库现状的差异

原任务 3.2 要求「添加 sources/getmatch.yml,含一个 boardless 占位条目」。但在当前仓库中 sources/ 目录与所有 board 文件都已被移除,board 目录迁移到了 Postgres 的 boards 表。这一点在 AGENTS.md 中有明确记载:

The board catalog lives in Postgres, not in sources/. cmd/ingest <provider> reads the boards table through internal/ingest/boardcatalog; a board is added with cmd/add-board --provider=… --board=… --company=… --apply, which reports by default and writes only under --apply. The argument is a PROVIDER KEY, not a path.

所以今天复现 task 3.2 的做法是(boardless 条目可省略 --board):

go run ./cmd/add-board --provider=getmatch --company="getmatch" 
# 确认输出无误后再真正写入:
go run ./cmd/add-board --provider=getmatch --company="getmatch" --apply

--provider 传的是 provider key,不是文件路径;误传路径会导致读到 0 个 board、日志打印 providers=0 并以 0 退出,看起来像「目录为空」——这是仓库文档点名的常见坑。

公司名在这里只是校验占位符:Config.Validate 要求 Company 非空,但适配器从不使用它——每条职位的雇主来自 company.name,测试里那句注释「The marketplace posting carries its OWN employer, not the configured placeholder」就是为了钉住这个行为。

5.3 抓取命令与调度

抓取按 provider 执行:

go run ./cmd/ingest getmatch

cmd/ingest 会通过 sources.All(sources.NewClient()) 装配注册表,从 boards 表加载该 provider 的条目,校验后交给流水线;运行结束打印一行汇总日志(ingest done: provider=… providers=… ingested=… failed=… skipped=…)。生产上按仓库文档,调度是按「有活跃 board 的 provider」生成的(freehire-ops 的生成器枚举 SELECT provider FROM boards WHERE status IN ('pending','active')),所以不需要手写 yml 条目。

六、任务 4:验证

验收命令与任务清单一致:

go build ./...
go vet ./...
go test ./internal/sources/

只跑本适配器相关用例时可以收窄:

go test ./internal/sources/ -run Getmatch -v

测试覆盖与任务清单的对应关系:

测试 验证点
TestGetmatchProvider Provider() 返回 "getmatch"
TestGetmatchFetchMapsOffer 全字段映射:ExternalID、绝对 URL、Title、per-offer 雇主、详情来源且已清洗的描述(<script> 被剥离)、office → onsite 且 Remote=false、地点去重、无时区时间解析到 2026-06-19T12:55:17.948391Z
TestGetmatchWorkMode 单 remote / 全 hybrid / 全 office / remote+office 混合为空 / office+relocation 标记 / 仅 relocation / 空列表,共 7 组
TestGetmatchRemoteFlagSetOnlyForRemote Remote 当且仅当 WorkMode == "remote"
TestGetmatchDescriptionFallback 详情描述为空 → 回退列表摘要;详情请求失败 → 也回退且职位未被丢弃
TestGetmatchPaginatesAndStopsAtTotal total=150、limit=100 时只请求 offset 0 与 100,共 2 页 2 条
TestGetmatchFirstPageErrorFailsBoard 首屏失败返回 error
TestGetmatchLaterPageErrorEndsEnumeration 第二页失败返回 1 条且无 error
TestGetmatchSeniority senior/middle/lead/c_level 通过,大小写与空格容错,trainee 与空值丢弃
TestGetmatchCategory 单映射、android → mobile、同类别重复、冲突丢弃、无法映射丢弃、无法映射与可映射混排保留可映射值
TestGetmatchCategoryMapTargetsAreValid 映射表每个目标值都属于 vocab.CategoryValues
TestGetmatchSkills Golang、Kiss、Docker → [docker go],噪音被丢弃,空输入为空切片
TestGetmatchFetchSetsStructuredFacets 详情提供 seniority/specializations/skills/experience 时正确落到 Job
TestGetmatchFetchStructuredFacetsAbsentOnDetailError 详情失败时四个 facet 保持零值
TestGetmatchRegisteredInAllAndBoardless 注册存在、同时实现 boardless 与 aggregator、出现在 FilterableProviders() 中

最后一项尤其关键:它把「类型断言」和「facet 可见性」都纳入了回归保护。如果哪天有人误删 aggregator(),source facet 会静默失去 getmatch 这个筛选项——这种缺陷在运行时几乎不可见,只有测试能兜住。

任务清单的最后一项还包括对真实 API 的冒烟运行,即用真实客户端跑一次适配器,确认产出的是带完整描述的归一化职位。这属于需要网络的人工验证,不在单元测试范围内。

七、字段映射总表

把实现与规格合并,一张表可完整描述 offer → Job 的映射:

源字段 目标字段 处理方式
id(数字) ExternalID strconv.Itoa 转字符串,随后由流水线按 board 命名空间隔离
url(相对) URL https://getmatch.ru + url
position Title 直传
company.name Company 每条职位自己的雇主,不是配置里的占位公司
详情 description / 列表 offer_description Description 优先详情;为空或失败回退列表;统一 sanitizeHTML
location_items[].label Location 去空、去重、首次出现顺序、", " 连接
location_items[].format WorkMode remote/hybrid/office → remote/hybrid/onsite,忽略 relocation_*,仅单一模式时输出
上者 Remote WorkMode == "remote"
published_at PostedAt 2006-01-02T15:04:05.999999999(无时区)
详情 seniority Seniority 词表成员判定,否则空
详情 specializations Category 高置信映射表,全一致才输出
详情 skills_objects[].name Skills skilltag.Canonicalize,只保留可解析技术词
详情 required_years_of_experience ExperienceYearsMin *int,保留 null 语义

所有结构化字段都遵循同一条全局契约:平台以结构化字段声明时才填,否则留空让流水线词典决定。WorkMode 尤其如此——它永不由地点字符串启发式填充。

八、风险与权衡

设计文档列出了四条主要权衡,代码里都有对应的缓解措施:

  1. 每次爬取约 755 次详情请求。这是为「完整描述」付出的代价——列表侧的 offer_description 只有约 459 字符的摘要,而描述质量同时驱动搜索与 AI 富化。缓解手段是共享 HTTP 客户端的限速,以及「跑一次即退出」的 cron worker 模型;如果目录继续增长,StreamingSource(增量持久化)的接缝已经预留(参见 source.go)。
  2. API 形态漂移(端点未公开文档化)。适配器只反序列化需要的字段;列表解码失败会让 board 大声失败,而不是静默清空目录。测试用内联的真实形态 JSON 钉住映射,任何形态变化都会先在测试中暴露。
  3. HTML 描述。统一走 htmltext.Sanitize,与其他产出 HTML 的适配器一致,活动内容被剥离、结构保留。
  4. 混合模式职位丢失结构化工作模式(146/760)。已接受:地点字符串解析器仍能给出提示,而结构化字段的来源保持干净。

九、部署与回滚

变更本身是纯增量的:没有 schema 改动,没有流水线改动。部署即重建镜像(新适配器编译进去),再为该 provider 配置一条调度;回滚即移除调度与注册表里的一行。已写入的行是惰性的(source = "getmatch"),若停止抓取,会通过既有的未见职位清扫机制自然软关闭。

关于清扫,值得补充一条来自 docs/agents/job-lifecycle.md 的背景:ingest 写入会为每次抓取盖 last_seen_at,运行后的清扫在 48 小时未见后关闭职位,且范围限定在本次实际抓到的 company_slug 上。getmatch 未声明需要自定义 sweepGrace,即沿用默认窗口;又因为它每次抓取都枚举全局 feed,正常情况下所有公司都会落进本次抓取范围。

十、复现这份任务清单时的检查要点

如果你要照此新增一个同类「无 board 的多公司聚合器」,可以按下面的顺序自检:

  1. 先探测接口:确认列表端点无需鉴权、有可用的总数或分页信号、每条记录自带雇主。若存在「需要登录」的相似端点(如 getmatch 的 /api/vacancies),明确记录为不使用。
  2. 写路由感知的 fake,按 URL 形态而不是调用顺序路由,并记录请求轨迹,让「分页在哪停」和「详情抓了几次」变成可断言的事实。
  3. 给分页加硬上限,并把「首屏失败」与「后续页失败」区别对待——前者是 board 错误,后者是部分成功。
  4. 详情失败永不丢职位:描述回退到列表摘要,结构化 facet 保持空值。
  5. 结构化工作模式只在无歧义时输出,把混合情况交还给流水线的字符串解析,保持字段来源可信。
  6. 同一行注册 + 标记方法成对出现:boardless() 决定配置能否省略 board,aggregator() 决定 source facet 里还能不能看到它。
  7. board 配置走数据库:cmd/add-board --provider=<key>,先报告后 --apply,别把 provider key 当文件路径传。
  8. 验收跑全量:go build ./... && go vet ./... && go test ./internal/sources/,再做一次真实 API 冒烟。

参考资料

登录后查看全文
freehire