freehire 的 /jobs/facets 端点:基于 Meilisearch 面向分面计数的公开市场分析 API 设计
freehire 的 /jobs/facets 端点:基于 Meilisearch 面向分面计数的公开市场分析 API 设计
本文围绕 freehire 仓库中 job-analytics 能力的规范文档 openspec/changes/archive/2026-06-15-analytics-facets/specs/job-analytics/spec.md 展开,讲清楚这个职位聚合站是如何把一个公开、免鉴权的 GET /api/v1/jobs/facets 端点构建在 Meilisearch 的 facet distribution 能力之上的:它如何复用 /jobs/search 的整套过滤词汇、如何用 limit: 0 的查询只取计数不取文档、如何通过 re-key 让 API 只暴露公开参数名、以及如何调高 maxValuesPerFacet 避免高基数分面被引擎默认值静默截断。读完后,你将掌握一个"计数类"搜索 API 的完整契约、分层实现(搜索层 → HTTP 层 → 前端)与缓存/并发细节,并能对照源码验证规范中每一条 Scenario。
1. 背景:把已有数据变成"一眼可见的市场视图"
规范所在变更目录的提案文档 openspec/changes/archive/2026-06-15-analytics-facets/proposal.md 说明了动机:访客和运营方想知道 freehire 收录的职位市场的"形状"——满足某组条件的职位有多少,并按地区、类别、资历、工作方式、技能、薪资等维度拆解。目录中每条职位已经携带这些维度,Meilisearch 也早已把它们全部索引为可过滤属性,并且能在与搜索完全相同的过滤语义下即时计算单维度 facet 分布(value → count),只是没有任何端点把这些计数暴露出来。
设计文档 openspec/changes/archive/2026-06-15-analytics-facets/design.md 进一步明确了定位与边界:
- 这是三阶段分析仪表盘的 Phase 1:先做分面计数;趋势(Phase 2,基于 Postgres
date_trunc)与交叉统计(Phase 3)明确列为非目标。 - 后端成本接近零:每个页面状态只发一条 Meili 查询,不做任何 DB 聚合。
- 无 schema 变更、无新依赖、无破坏性改动;
Search(返回带排序的职位命中)保持不变。
任务清单 openspec/changes/archive/2026-06-15-analytics-facets/tasks.md 记录了落地路径:搜索层新增 FacetCounts 方法与 FacetParams/FacetResult/FacetStat 类型、handler 层新增 JobFacets、前端新增 /analytics 页面,并标注了部署后需要 make reindex 才能让新的 maxValuesPerFacet 生效这一运维步骤。
2. API 契约:GET /api/v1/jobs/facets
规范第一条 Requirement("Facet distribution endpoint")定义了端点的完整契约,逐条对应如下。
2.1 请求:与 /jobs/search 完全相同的查询词汇
端点为 GET /api/v1/jobs/facets,公开、免鉴权,接受与 GET /api/v1/jobs/search 相同的查询参数并以相同语义应用:全文 q、所有 facet 过滤参数(含重复值)、<param>_mode、<param>_exclude 以及数值范围过滤。这一点在官方 API 文档 docs/API.md 中有独立成节的说明:"These parameters apply to GET /jobs/search and GET /jobs/facets",过滤词汇的核心规则包括:
- 逗号分隔列表表示 OR:
skills=go,rust匹配任一;重复参数(skills=go&skills=rust)等效; <param>_mode=and要求所有选中值同时成立;<param>_exclude=<value>排除匹配项;- 不同 facet 之间 AND 组合,但地理分面是例外:
regions、countries、metros、cities共享同一个 OR 组(选两个地点读作"或",避免"既在欧洲又在巴西"这种空交集); - 特殊值
regions=none匹配无已解析地理信息的职位,映射为 Meilisearch 的IS EMPTY。
这些词汇在搜索层有一个单一事实来源:internal/search/search/query_filter.go 中的 StringFacets 映射(公开参数名 → 索引属性),例如 seniority 对应 enrichment.seniority、work_mode 对应顶层属性 work_mode、regions 直接对应 regions;同文件 L76 的 locationFacets 声明了四个地理参数共享一个 OR 组。重复参数在该文件中被注释为 "Repeated params (?seniority=a&seniority=b) are ORed"。
2.2 响应:单对象信封 + total/facets/stats
响应使用单对象信封 {"data": ...},data 包含三个键:
| 键 | 含义 |
|---|---|
total |
满足过滤条件的职位估算数量(来自 Meilisearch 的 estimatedTotalHits) |
facets |
facet → (值 → 计数) 的分布映射 |
stats |
数值型 facet → {min, max} 映射 |
两个映射都以公开 facet 参数名为键——即客户端用来过滤时使用的名字(seniority、salary_min),绝不使用内部索引属性名(enrichment.seniority)。连续型数值 facet(薪资、经验)只出现在 stats 中,不作为逐值分布出现在 facets 里。
一个典型的响应形态(依据 internal/api/handler/facets_test.go 中 TestJobFacets_ShapesResponse 断言的结构):
{
"data": {
"total": 1234,
"facets": {
"regions": { "eu": 800 },
"work_mode": { "remote": 300 }
},
"stats": {
"salary_min": { "min": 0, "max": 400000 }
}
}
}
2.3 四个规范的 Scenario 及其验证方式
| Scenario(规范) | 行为 | 仓库内验证 |
|---|---|---|
| Counts under no filter | 无查询参数时返回 200,data.total 已填充,data.facets 含每个可分面属性的值→计数映射 |
facets_test.go 断言 handler 会请求 regions、enrichment.category、enrichment.seniority、enrichment.visa_sponsorship、enrichment.salary_min 等全部可分面属性的分布 |
| Counts under an active filter | ?regions=eu&category=backend 时计数只反映同时满足两个条件的职位,过滤语义与 /jobs/search 相同 |
同上测试断言 Filter 组合同时含 enrichment.seniority = "senior" 与 regions = "eu" |
| Numeric stats | data.stats 以公开参数名报告数值 facet 的 min/max,这些 facet 不出现在 data.facets |
facets_test.go TestJobFacets_PrunesNumericDistributionAndRekeys:后端返回的 enrichment.salary_min 逐值分布被剪掉,stats 被 re-key 为 salary_min |
| Search not configured | 未配置 Meilisearch 时返回 503 错误信封,与 /jobs/search 行为一致 |
facets_test.go TestJobFacets_DisabledReturns503:facets 后端为 nil 时状态码必须是 fiber.StatusServiceUnavailable |
规范之外的实现细节还包括两块"防御性契约"(同样来自 handler 测试):
meta.ignored_params报告:无法识别的过滤参数不会被拒绝,而是被忽略并通过meta.ignored_params上报(带did_you_mean提示),防止"一个被静默丢弃的过滤器看起来像一个更宽的真实结果集"。例如?country=it会上报country -> countries。干净的请求则保持裸{"data": ...}信封,不生成空meta块(facets_test.go)。facets=子集参数:允许用逗号分隔的公开参数名只统计指定分面(如?facets=seniority,regions),因为按属性逐个计费、宽值属性(cities、skills)耗时占绝对多数。未知名称直接返回 400 而非静默忽略——调用方本就无法区分"该值没有计数"与"引擎按分面截掉了它",静默会让拼写错误永远藏下去(facets_test.go)。
3. 搜索层:FacetCounts 与"只做计数"的查询
3.1 独立的参数/结果类型
规范决策之一是新增专职 FacetCounts 方法而不是重载 Search:Search 返回带排序的职位命中,而 facet 计数没有排序、没有混合向量、且 limit: 0,输入输出都不同。对应实现见 internal/search/search/facets.go:
// FacetParams is a facet-distribution request: it reports the count of matching
// jobs per facet value (and numeric min/max) under a filter, with none of the
// ranking/pagination concerns of a SearchParams.
type FacetParams struct {
Query string
Filter any
Facets []string
}
type FacetResult struct {
Total int64
Facets map[string]map[string]int64 // attr → value → count
Stats map[string]FacetStat // attr → {min,max}
}
type FacetStat struct {
Min float64 `json:"min"`
Max float64 `json:"max"`
}
FacetCounts 本身(facets.go)只做两件事:发起 limit: 0 的 Meili 查询,以及把原始响应解码为类型化映射。解码被拆成纯函数 decodeFacetDistribution 与 decodeFacetStats(facets.go):空载荷返回 nil map 而非错误,高基数载荷(测试构造 250 个不同的 skill 值)必须全部存活——"引擎的 maxValuesPerFacet 决定发多少,但解码层从不丢"。
3.2 单索引与联邦(federated)两条路径
facetSearch(facets.go)按 q 解析出的"备选词"(alternatives)决定路径:单个备选走今天的单索引请求;多个备选打包成一次 /multi-search 联邦请求,合并计数按文档去重。联邦路径的构造在 internal/search/search/federated.go,其注释点明了两个陷阱:
- 联邦查询内每个子查询携带 per-query 的
facets/limit会直接 400,所以 facet 列表只能放在联邦级FacetsByIndex; - 联邦自己的合并默认值是每个 facet 100 个值且静默截断,因此
MergeFacets.MaxValuesPerFacet必须显式传与索引设置一致的值;联邦Limit用 1 而不是 0,因为 SDK 会省略零值 limit,联邦会把它读作 20 个命中。
3.3 Disjunctive(析取)计数:规范遗留"seam"的最终实现
design.md 把"self-exclude 计数"(某个 facet 在除去自身选择的过滤下计数)记为 Phase 1 的延迟接缝。当前代码库中这个接缝已被实现为 disjunctive=1 模式:DisjunctiveFacetCounts(facets.go)为每个分布属性发起一次"自身选择被剔除"的查询,并在完整过滤下并行计算总量;所有查询并发执行,延迟取决于最慢的单个 facet 查询而非它们的总和。
Handler 侧的构造逻辑 facetReqs(internal/api/handler/facets.go)有一个值得注意的细节:地理分面共享同一个 OR 组,因此对任一地理 facet 做析取计数时必须整组剔除 regions/countries/cities/metros,否则选中一个国家会把同级所有 region 的计数清零——这正是析取模式想要避免的反效果(facets_test.go 有专门的回归测试)。析取模式还被明确拒绝与 facets= 组合(400):析取的查询从"选择"派生而非从输出列表派生,裁剪输出并不能省掉任何一次查询。
4. HTTP 层:JobFacets handler 的四个关键机制
路由注册与 /jobs/search 相邻,见 internal/api/handler/search.go:api.Get("/jobs/facets", readLimit, h.JobFacets),走读限流、公开端点。
4.1 facetCounter 接口:职责在接缝处解耦
Handler 依赖一个刻意与 searcher 分离的小接口(facets.go):
type facetCounter interface {
FacetCounts(ctx context.Context, p search.FacetParams) (search.FacetResult, error)
DisjunctiveFacetCounts(ctx context.Context, query string, reqs []search.FacetReq, totalFilter any) (search.FacetResult, error)
}
计数分布与返回排序命中是两种职责,*search.Client 同时满足两个接口;nil 计数器即"搜索未配置",端点直接 503——这就是规范 "Search not configured" Scenario 的实现点(facets.go)。
4.2 facetAttributes:与搜索共享的单一事实来源
facetAttributes(only ...string)(facets.go)按如下规则生成要请求分布的索引属性列表:search.StringFacets 中全部字符串分面(新增分面会自动被计入)+ 布尔/数值额外项 − facetsNoDistribution,排序后输出。两处裁剪有明确理由:
facetsNoDistribution(目前仅company_slug):它有数千个值,侧边栏公司过滤走的是服务器端类型ahead(GET /api/v1/companies,按计数排序),Meili 也只会返回按字母截断的片段;该参数保留在StringFacets里,?company_slug=过滤仍可用,只是不再计算无人读取的分布。facetExtraParams(facets.go):visa_sponsorship是保留逐值分布的布尔项;salary_min、salary_max、experience_years_min标记为statOnly: true——Meili 对分面属性总会附带逐值分布,但"每个不同薪资一个桶"纯属噪声,所以只取 min/max。
4.3 Re-key:内部点路径永不泄漏进公开 API
规范强调"以公开参数名为键,绝不使用内部索引属性"。实现是 facetParamByAttr()(反转 StringFacets 与 facetExtraParams 得到属性 → 参数名映射)加上 facetView()(facets.go):遍历后端以索引属性为键的结果,逐一把 enrichment.seniority 换成 seniority,同时剪掉 statOnly 数值的逐值分布。该函数被 HTTP 端点与助手(agent)的 facets 工具共享,保证"agent 用来过滤的词汇与 API 发布的词汇完全一致"。前端因此可以直接读 facets[facet.param]。
4.4 缓存:1 分钟 TTL 与规范化缓存键
由于 facet 计数对所有调用者相同、且只在 ingest 落库时(数小时一次)变化,handler 在 FacetCounts 之上加了一层 best-effort 读穿透缓存(facets.go):TTL 为 1 分钟,注释解释了度量背景——该端点曾占到 API handler 总耗时的 55%,缓存的目标是"吸收同一请求的突发,而不是长期持有计数"。缓存永不失败请求:cache 为 nil、miss 或任何缓存错误都直通实时计算。
缓存键的设计值得展开:facetCacheKey 将 FacetParams 序列化为 JSON 后取 SHA-256。关键前提是 FilterFromValues 通过遍历 map 构造 <a href="https://link.gitcode.com/i/dd5ba3881ad54df8e2d985cb2206c045" target="_blank">][]string,组序每次请求都会随机化——若不先做 canonicalFilter(组内排序、组间再排序,AND/OR 本身与顺序无关),同一多分面请求每次都会哈希出不同键,恰恰在它瞄准的过滤流量上失效缓存。[facets_test.go 用 8 次相同多分面请求必须只计算 1 次、不同过滤不得共享键等测试固化了这一行为;析取路径不走缓存(交互式的 live-modal 体验、低频、且每个 facet 扇出难以做键)。
5. 高基数分面不被截断:maxValuesPerFacet 的完整故事
规范第二条 Requirement 要求搜索索引被配置为"facet 分布返回足够多的值,使 skills、countries 这类高基数分面不被引擎默认值(100)截断",并给了一个 Scenario:当过滤集存在超过 100 个不同 skill 值时,skills 分布应返回超过 100 个值(以配置的 maxValuesPerFacet 为界)。
当前代码库中的实现比规范定稿时更激进。internal/search/search/client.go 中的常量:
// maxValuesPerFacet raises the per-facet value cap above Meili's default of
// 100 so the analytics facet distribution is not truncated for high-cardinality
// facets (skills, cities, countries).
// Meili truncates to this cap ALPHABETICALLY (sortFacetValuesBy defaults to
// "alpha") BEFORE the client sorts by count, so a cap below the value count
// silently drops the busiest values past the alphabetical cut — the failure
// leaves no trace, which is why the headroom is generous rather than measured.
// It was sized for the retired role catalogue (~1,200 values) and is kept there
// on purpose: lowering it buys nothing and the mistake it prevents is silent.
maxValuesPerFacet = 1200
规范与 design.md 当时提议的值是 300,当前常量已提升到 1200 并刻意保留。它通过索引设置生效(client.go):
Faceting: &meilisearch.Faceting{
MaxValuesPerFacet: maxValuesPerFacet,
SortFacetValuesBy: map[string]meilisearch.SortFacetType{"*": meilisearch.SortFacetTypeCount},
},
这里同时回答了"为什么还要 SortFacetValuesBy: count":Meili 默认按字母序截断,截断发生在客户端按计数排序之前——一旦上限低于实际值数量,排在字母后段的热门值(注释举例:Florianópolis,1000+ 职位)会被静默丢掉,而"客户端按计数排序无法找回引擎从未返回的值"。count 排序让上限保留的是最常见的值,同时顺带甩掉长尾噪声(邮编碎片、一次性字符串)。sortFacetValuesBy 是 Meili v0.28 起支持的查询期设置,在仓库锁定的服务器版本上是安全的(与 TypoTolerance 那条 SDK 过度序列化问题不同)。
配套的测试有三处:
- internal/search/search/facets_test.go
TestIndexSettings_FacetingRaisesValueCap:断言Faceting非 nil、MaxValuesPerFacet > 100、且SortFacetValuesBy["*"]为 count——"上限必须保留最忙的值,而不是字母序最靠前的值"; - 同文件解码测试:250 个不同 skill 值必须全部通过
decodeFacetDistribution存活; - internal/search/search/federated_test.go
TestFederatedFacetsMergeWithTheIndexValueCap:联邦路径的MergeFacets.MaxValuesPerFacet必须等于索引常量,因为"联邦默认 100 且静默截断,正是 maxValuesPerFacet 要防的失败模式"。
运维前提(适用限制):索引设置在运行中的索引上是惰性的——新 maxValuesPerFacet 必须经过 make reindex 才能到达线上索引。这一运维步骤被记录在提案的 Impact 与 design.md 的 Risks 中,并列为 tasks 4.2。另一个相关约束见 internal/search/search/query_filter.go 的注释:某个属性进入 StringFacets 就自动进入 /jobs/facets 的分布请求,因此声明该属性可过滤的 Meilisearch settings patch 必须先于携带该行的二进制到达线上索引,否则所有 facets 请求都会 500。
6. 前端消费:/analytics 页面与 facetCounts 客户端
提案把 /analytics 页面(SvelteKit SSR)作为同一变更的 web-frontend 能力:一侧复用既有 URL 同步的 FilterStore 与 FiltersPanel,另一侧是每个 facet 的纯 CSS 横向条形分布;点击某个值会收窄过滤并重算所有分布。前端 API 客户端方法见 web/src/lib/api.ts:
async function facetCounts(
params: URLSearchParams,
opts?: { disjunctive?: boolean; facets?: string[] }
): Promise<FacetCounts> {
const p = new URLSearchParams(params);
if (opts?.disjunctive) p.set('disjunctive', '1');
if (opts?.facets?.length) p.set('facets', opts.facets.join(','));
const res = await request<{ data: FacetCounts }>(`/api/v1/jobs/facets?${p}`);
return { total: res.data.total, facets: res.data.facets ?? {}, stats: res.data.stats ?? {} };
}
注释解释了 facets 参数的客户端动机:"计数按 facet 逐个计费,宽值属性(cities、skills)占大头,只读取特定键的调用方应当指名道姓"——与 handler 侧 ?work_mode=remote 全量统计耗时远高于单属性的实测注释相呼应。按计数排序在前端完成,这延续了 design.md 决策 5 的取向(避免经由 sortFacetValuesBy 的 SDK 序列化问题;而当前索引设置已用 count 排序解决"保留谁"的问题,前端排序只影响展示顺序)。
7. 验证方式:如何在仓库内复现这些事实
tasks 4.1 记录了当时的验证基线,仍然可以作为对照:go build ./... && go vet ./... && go test ./... 通过;web/ 下 npm run check(svelte-check 0 错误)零告警;以及 go test -tags=integration -run TestIntegration_FacetCounts ./internal/search/ 在活体 Meilisearch 上端到端验证"分布 + 过滤收窄 + 数值 stats"(集成测试位于 internal/search/search/facets_integration_test.go)。handler 侧的单元测试(internal/api/handler/facets_test.go)用 fakeFacetCounter 固定了全部行为契约:参数解析 → 过滤器透传 → 分布按公开名暴露;nil 后端 → 503;析取模式对每个 facet 生成"去掉自身选择"的过滤;role 这类已退役参数被忽略并通过 meta.ignored_params 上报而非悄悄生效。
8. 小结:一个计数端点如何"诚实"
回顾规范的两条 Requirement 与仓库实现,可以提炼出这条 API 的几条工程原则:
- 词汇统一:公开端点、
/jobs/search与索引设置共享同一份 facet 词汇(search.StringFacets),新分面自动进入分布统计,不存在第二套需要同步的映射; - 职责分离:计数(
FacetCounts/facetCounter)与命中(Search/searcher)在类型与接口层面分离,limit: 0的查询不携带任何排序与混合向量负担; - 静默失败零容忍:未知
facets=名称 400、被忽略参数进meta.ignored_params、maxValuesPerFacet取"宁宽勿缺"的值并用 count 排序保证截断丢的是长尾而非热门值、联邦路径显式对齐合并上限——所有"看起来像事实"的数字都不允许无声地少算; - 边界如实声明:
total是估算值(来自estimatedTotalHits),缓存允许 1 分钟陈旧,析取与自包含计数的取舍都写进了注释与规范,读者可以据此判断数据的时效与精度。
规范原文位于 openspec/changes/archive/2026-06-15-analytics-facets/specs/job-analytics/spec.md,当前生效能力快照见 openspec/specs/job-analytics/spec.md;深入阅读建议从 internal/api/handler/facets.go 与 internal/search/search/facets.go 两个文件入手,它们分别覆盖了端点契约与引擎交互的全部细节。