freehire 分析面(Analytics Facets)实现指南:基于 Meilisearch 分面统计构建公开市场看板
freehire 分析面(Analytics Facets)实现指南:基于 Meilisearch 分面统计构建公开市场看板
本文以 freehire 仓库中 openspec/changes/archive/2026-07-01-analytics-facets/tasks.md 这份实施清单为主线,完整拆解"分面统计(facet distribution)"能力从搜索层、HTTP 接口、SvelteKit 前端到上线运维的四个落地阶段。读完后你将掌握:如何用一次 limit: 0 的 Meilisearch 查询拿到"每个分面值对应多少职位",如何把索引内部属性名反向映射成公开查询参数,以及如何做出一个可 SSR、可钻取(drill-down)、URL 可分享的分析页面。
一、任务清单的上下文:为什么需要分面统计接口
原清单标题为 ## 1. Search layer (internal/search) 到 ## 4. Verify & ops,是一条典型的"后端 → 接口 → 前端 → 验收"纵向切片。它的动机在 提案文档 中被明确写为:目录中每个职位都已携带地区、国家、工作模式、技能、类目、资历、薪资等维度,Meilisearch 也已在与搜索完全相同的过滤语义下实时计算单维度分面分布,但没有任何接口把这些计数暴露出来。于是:
- 新增公开接口
GET /api/v1/jobs/facets,接受与/jobs/search完全一致的查询参数(q+ 全部过滤参数),返回每个分面值的职位数以及数值型分面的 min/max,而不是一页职位。 - 在搜索层新增独立方法
FacetCounts,与返回排序命中的Search互不侵入。 - 提高索引的
maxValuesPerFacet,避免skills、countries这类高基数字段被引擎默认上限截断。 - 新增公开
/analytics页面(SvelteKit SSR),左侧复用既有筛选面板,右侧用纯 CSS 横向条形图渲染各分面分布,点选某个值即可收窄过滤条件并重算全部分布。
需要记住的边界:设计文档 明确这是三阶段计划中的 Phase 1。时间趋势(Phase 2,基于 Postgres date_trunc)与交叉表(Phase 3,二维分布)不在本阶段范围内;"自身排除计数"(self-exclude,即某分面不因自身选择而收窄)也被推迟为预留接缝(seam)。清单本身没有引入任何表结构变更或新依赖。
二、阶段 1:搜索层的分面计数能力
2.1 新增 FacetStat 类型与纯解码函数(任务 1.1)
清单要求先落地 FacetStat 类型和把 Meilisearch 原始 FacetDistribution / FacetStats JSON 转成强类型 map 的纯函数,并用表驱动测试覆盖空值与高基数场景。当前实现位于 internal/search/search/facets.go:
// FacetStat is the numeric range of a facet over the matched set, as reported by
// Meilisearch's facetStats (e.g. salary min/max).
type FacetStat struct {
Min float64 `json:"min"`
Max float64 `json:"max"`
}
两个解码函数刻意保持"纯"且宽容——这是可单测的前提:
decodeFacetDistribution:把json.RawMessage解成map[string]map[string]int64(属性 → 值 → 计数)。空载荷返回nil, nil而不是错误,因为"没有请求分面"和"没有匹配"在语义上都不是失败。decodeFacetStats:解成map[string]FacetStat(属性 →{min,max}),同样对空载荷宽容。
两者在解析失败时用 fmt.Errorf("search: decode facet distribution: %w", err) 包装后返回,便于定位是引擎返回体异常还是下游逻辑问题。对应单测见 internal/search/search/facets_test.go。
2.2 FacetCounts:一次 limit:0 查询,不动 Search(任务 1.2)
清单特别强调"FacetParams/FacetResult 与使用它们的方法一起在 1.2 落地",并把 Search 保持原样。实现如下:
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}
}
FacetCounts 的核心只有一步——把参数转成一次无文档返回的搜索请求:
resp, err := c.facetSearch(ctx, p.Query, p.Filter, p.Facets)
facetSearch 负责真正发请求,并复用与 Search 相同的查询算子解析(ParseQuery):
- 单条查询分支:
Facets: facets、Limit: 0、AttributesToSearchOn: alts[0].Fields,再加Filter。Limit: 0是关键,它让引擎只算分布、不取文档。 - 多查询分支:走
MultiSearchWithContext的联邦(federated)请求,合并后的计数按文档去重统计。相关合并逻辑与maxValuesPerFacet的一致性在 internal/search/search/federated.go 中维护,并有Test...MergeFacets校验联邦侧的MaxValuesPerFacet必须与索引设置一致。
为什么不让 Search 兼任?设计文档给出的理由是职责不同:分面计数没有排序、没有混合向量检索、limit 恒为 0,输出也不是文档。把 Facets 塞进 SearchParams/SearchResult 会让大部分字段对分析调用毫无意义。
落地演进:在最初的单次查询之上,仓库还追加了
DisjunctiveFacetCounts与FacetReq(facets.go),用于"每个分面在去掉自身选择的过滤条件下计数"。它用sync.WaitGroup并发跑 N+1 条查询(N 个分面 + 1 个总量),因此延迟取决于最慢的单条查询而不是总和;错误用首次错误(firstErr)短路返回。这正是设计中预留的 self-exclude 接缝的正式实现。
2.3 提高 maxValuesPerFacet,别让高基数分面被截断(任务 1.3)
清单的原始数字是 Faceting{MaxValuesPerFacet: 300},理由是 skills/countries 不该被 Meili 默认的 100 截断。当前代码把上限进一步放宽到常量 maxValuesPerFacet = 1200,并在索引设置里同时指定按计数排序:
Faceting: &meilisearch.Faceting{
MaxValuesPerFacet: maxValuesPerFacet,
SortFacetValuesBy: map[string]meilisearch.SortFacetType{"*": meilisearch.SortFacetTypeCount},
},
见 internal/search/search/client.go 与 client.go 的 facetSettings。源码注释解释了两个容易踩的坑:
- 截断是静默的。引擎在客户端按计数排序之前,就按
maxValuesPerFacet先做一次截断;如果默认按字母序,排在后半段的热门城市(如 1000+ 职位的城市)会被直接丢弃,客户端再怎么排序也救不回来。因此这里把sortFacetValuesBy设为count,让上限优先保留最常出现的值,同时自然丢掉长尾噪声(邮编碎片、一次性字符串)。 - 上限要留足冗余。1200 是按退役的角色目录规模定的,注释明确写"降低它没有收益,而它防止的错误是静默的",所以保持不动。
TestIndexSettings_FacetingRaisesValueCap 之类的单测会断言 MaxValuesPerFacet > 100,防止回归到默认值。
三、阶段 2:HTTP 端点 GET /api/v1/jobs/facets
3.1 facetAttributes():与搜过过滤器共享同一份分面词汇(任务 2.1)
接口能统计哪些字段,不应是另一份手写清单。facetAttributes 直接从搜索层的 search.StringFacets(查询参数 → 索引属性的唯一事实来源,见 internal/search/search/query_filter.go)派生,再叠加少量额外分面:
| 类别 | 例子 | 说明 |
|---|---|---|
| 字符串等值分面 | regions、work_mode、skills、seniority、category、countries、cities、metros、company_type、source、reality 等 |
部分映射到嵌套属性点路径(如 enrichment.seniority),地理/技能等解析型分面则是顶层裸属性 |
| 布尔分面 | visa_sponsorship |
保留分布 |
| 连续数值分面 | salary_min、salary_max、experience_years_min |
statOnly: true,只出 min/max |
源码里 facetExtraParams 就是这张"额外分面"表(internal/api/handler/facets.go),而 facetsNoDistribution 把 company_slug 排除在分布之外——它值有数千个,UI 用的是 GET /api/v1/companies 类型提前量,Meili 也只会返回被截断的字母序片段。
facetAttributes 还支持一个性能开关:可变参数 only ...string,只统计被点名的公开参数。源码注释给了实测依据:在生产环境、?work_mode=remote 条件下,全量分面约 284ms,单个属性约 10ms。因此"只读一个键的调用方不该为另外二十六个分面付费"。
3.2 facetCounter 接口与 JobFacets 处理器(任务 2.2)
处理器依赖的是一个小接口,而不是完整的 searcher:
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)
}
这带来两个工程好处:一是软接口便于在单测里注入 fake(internal/api/handler/facets_test.go 中的 fakeFacetCounter 会记录收到的 FacetParams);二是 h.facets == nil 直接等价于"未配置 Meilisearch",此时返回 503,与 /jobs/search 的行为一致。
处理流程(internal/api/handler/facets.go)可以概括为:
h.facets == nil→503 search is not available。- 读取
q,解析可选facets=子集(requestedFacets)。未知分面名直接 400,而不是静默忽略——因为调用方从 map 里读不到键时,无法区分"拼写错误"和"被 Meili 每个分面的上限截掉了",静默会长期掩盖错误。 - 若
disjunctive=1,用facetReqs(vals)为每个属性构造"去掉自身参数(含_exclude/_mode变体)"的过滤条件,并调用DisjunctiveFacetCounts;总量仍用完整过滤条件。facets=与disjunctive互斥(400),因为后者按选择集派生查询,收窄输出并不能省下任何一条查询。 - 否则走普通模式:
cachedFacetCounts(ctx, search.FacetParams{Query: q, Filter: buildSearchFilter(c), Facets: facetAttributes(only...)})。这里复用的正是/jobs/search的参数解析函数buildSearchFilter,见 internal/api/handler/search.go——"查询参数 → Meili 过滤表达式"是共享的解析关注点,不该写两遍。
最后 facetView(res) 做一次词汇表反转:把索引属性(enrichment.seniority)改回公开参数名(seniority),并把 statOnly 的连续数值分面从 facets 中剔除、只保留在 stats 里。这样"客户端用什么名字过滤,就用什么名字读计数",索引内部点路径结构永远不会泄漏到公开 API。
3.3 响应形状与真实调用示例
响应使用单条目信封 {"data": ...}(与仓库其他读取接口一致):
{
"data": {
"total": 390000,
"facets": {
"seniority": { "senior": 120000, "mid": 90000, "junior": 40000 },
"regions": { "eu": 150000, "us": 130000 },
"work_mode": { "remote": 180000, "hybrid": 60000 }
},
"stats": {
"salary_min": { "min": 30000, "max": 250000 }
}
}
}
典型请求:
# 全量分面(无过滤)
curl 'http://localhost:8080/api/v1/jobs/facets'
# 在已有过滤条件下统计,并只统计两个分面(省掉宽值分面的开销)
curl 'http://localhost:8080/api/v1/jobs/facets?regions=eu&category=backend&facets=seniority,work_mode'
# 实时筛选面板用的"非自身收窄"模式
curl 'http://localhost:8080/api/v1/jobs/facets?disjunctive=1&seniority=senior®ions=eu'
字段语义与 web/static/openapi.yaml 中的 FacetsEnvelope schema 对应:total 为匹配职位的估算数,facets 为分面名 → 值 → 计数,stats 为连续分面的 min/max。
另外,如果请求里带了不认识的参数(例如把 countries 误写成 country),接口不会静默——ignoredParams(c, facetsParams) 会把它放进响应 meta.ignored_params,并给出 did_you_mean 建议。测试 TestJobFacets_ReportsIgnoredParams 专门守住这一点,理由写在注释里:计数接口最容易被当成"市场规模的权威数字"引用,静默丢一个过滤条件不像是长列表,而像是一个事实。干净请求则保持只有 {"data": ...},不附加空 meta。
3.4 读穿缓存:一分钟 TTL 抹平突发(配套优化)
因为分面计数对任何调用者都相同、只在摄取落盘(每小时数次)时变化,处理器在 facetCounter 外面套了一层尽力而为的读穿缓存,TTL 为 facetCacheTTL = time.Minute。缓存键是 FacetParams 的 JSON 哈希:
sum := sha256.Sum256(raw)
return "jobfacets:v1:" + hex.EncodeToString(sum[:])
细节在于 filter 必须先规范化:search.FilterFromValues 遍历 map 构建 [][]string,组顺序与组内值顺序每次请求都可能不同,若不排序,同一个多分面请求会连续命中不同键,缓存对最需要它的过滤流量完全失效。canonicalFilter 因此对每组内排序、再跨组排序;"组间 AND、组内 OR 都满足顺序无关",所以排序只影响键、不影响真正发给 Meili 的过滤条件。
缓存本身不可能让请求失败:nil 缓存、未命中、读写报错都会直接穿透到实时计算,SetJSON 的错误被显式丢弃。
3.5 路由注册(任务 2.3)
路由在 searchHandlers.register 中与 /jobs/search 相邻注册(internal/api/handler/search.go):
api.Get("/jobs/search", readLimit, mw.optional, h.SearchJobs)
api.Get("/agent/jobs/search", agentSearchLimiter(mw.public), h.AgentSearchJobs)
api.Get("/jobs/facets", readLimit, h.JobFacets)
api.Get("/jobs/:slug/similar", readLimit, h.SimilarJobs)
注意注册顺序:字面量路由排在 /jobs/:slug 参数路由之前,否则 facets 会被当成 slug 解析。接口沿用公开读取限流 readLimit,且不挂可选鉴权中间件——它是匿名可访问的公开读。
四、阶段 3:SvelteKit 分析页面
4.1 类型与 API 客户端(任务 3.1)
前端类型定义在 web/src/lib/types.ts:
export interface FacetCounts {
total: number;
facets: Record<string, Record<string, number>>;
stats: Record<string, { min: number; max: number }>;
}
对应客户端方法 facetCounts(web/src/lib/api.ts)负责拼接参数并归一化空值:facets ?? {}、stats ?? {},让调用方永远不必判 null。它还支持两个可选开关 disjunctive 与 facets,从而与后端能力一一对应。
4.2 SSR 首屏:+page.server.ts(任务 3.2)
清单要求"在 URL 过滤条件下 SSR 加载分面,默认空过滤"。实现极其克制(web/src/routes/analytics/+page.server.ts):
export const load: PageServerLoad = async ({ url, fetch }) => {
const initial = await serverApi(fetch).facetCounts(url.searchParams);
return { initial };
};
url.searchParams 直接透传,意味着URL 就是唯一的状态源:首屏计数与钻取后重新拉取的计数走同一套参数构造,服务端渲染与客户端水合结果一致,页面也天然可被搜索引擎索引、在无 JS 时完成首屏呈现。
4.3 视图组件:AnalyticsView 与 FacetBreakdown(任务 3.3)
web/src/routes/analytics/+page.svelte 只做两件事:写 SEO 元信息(标题 Job market analytics · freehire、canonical 指向 /analytics),并把 data.initial 交给 AnalyticsView。后者(web/src/lib/components/AnalyticsView.svelte)承担了状态同步:
new FilterStore(new URLSearchParams(page.url.search))从 URL 播种筛选状态,与/jobs共用同一个过滤模型。counts用$state.raw保存,因为每次都是整体替换的 API 响应,不需要代理。- 一个
$effect跟踪filters.applied(FilterStore 内部已做防抖),变化即重新facetCounts。它用单调递增的generation而不是定时器来丢弃乱序响应:只有最新一次请求的返回才允许提交。 - 首次运行会跳过,因为 SSR 的
initial已在屏幕上;但如果浅路由导致page.url与地址栏不一致(initialStale),则强制重取。 syncOnNavigation(filters)让浏览器前进/后退重新从 URL 播种筛选,变化的applied再驱动上面的 effect。
薪资展示有一个必须注意的细节:stats 是在整个匹配集上聚合并跨货币计算的,直接把 USD 与 CLP 的 min/max 混在一起没有意义。因此只有当 salary_currency 恰好包含一个值时才显示薪资区间,并用该货币标注。这是一个典型的"统计上正确、业务上会误导"的边界处理。
每个分面由 FacetBreakdown.svelte 渲染:入口经 Object.entries(dist).sort((a,b) => b[1]-a[1]) 按计数降序排列(排序在前端做,而非依赖引擎的 sortFacetValuesByCount,以规避 SDK 对某些设置字段的过度序列化问题);每行一个 <button>,条形宽度按 count / max * 100% 计算,点击调用 store.pick(def.param, value) 切换该值在共享筛选器中的选中状态,从而触发全部分布重算——这就是钻取。
高基数分面用 TOP = 15 封顶,其余以 +N more 汇总,避免技能、国家这类字段撑爆页面。分面的展示清单来自 web/src/lib/facets.ts 的 FACETS 定义(param 与后端公开参数名严格对齐),标签则优先取 def.options 的本地化 label,没有选项的 token 型分面(技能、国家)直接把原始值当标签。
4.4 导航入口(任务 3.4)
清单写的是"在 TopBar.svelte 里加一条 links 项",而当前仓库的导航条目已集中到 web/src/lib/siteNav.ts,由 HeaderMenu.svelte 消费:
{ href: '/analytics', label: 'Analytics', icon: ChartColumn },
可见任务清单记录的是当时的文件位置,实现落地后导航数据源做过一次收敛。这也提醒我们:阅读归档清单时应以现有源码为准,清单是决策记录,不是当前文件布局的索引。
五、阶段 4:验证与上线运维
5.1 构建、静态检查与测试(任务 4.1)
清单给出的验收命令可直接复现:
# Go 侧:编译、静态检查、单测
go build ./... && go vet ./... && go test ./...
# 前端:svelte-check
cd web && npm run check
# 搜索层集成测试:需要一个运行中的 Meilisearch
go test -tags=integration -run TestIntegration_FacetCounts ./internal/search/search/
集成测试 internal/search/search/facets_integration_test.go 用真实引擎端到端验证三件事:分布本身、过滤条件下的收窄、以及数值分面的统计。它通过 EnsureIndex 建索引后写入带 Seniority/Category/Skills/Enrichment(含 SalaryMin/SalaryMax)的职位,再断言返回的分布与 stats——这比用 fake 单测更能证明"分面统计的过滤语义与搜索一致"。
处理器侧的单测覆盖了容易被忽视的行为契约,可直接作为阅读索引:
| 测试 | 守住的行为 |
|---|---|
TestJobFacets_FacetsParamNarrowsTheRequest |
facets= 只收窄"统计什么",绝不收窄"在什么条件下统计"——否则数字回答的就是另一个问题 |
TestJobFacets_UnknownFacetIsRejected |
未知分面名(含 company_slug)返回 400,且不会打到计数器 |
TestJobFacets_FacetsParamRejectedWithDisjunctive |
facets= 与 disjunctive 互斥 |
TestJobFacets_ReportsIgnoredParams |
country=it 这类笔误进入 meta.ignored_params 并给出 did_you_mean |
TestJobFacets_CleanQueryKeepsTheBareDataEnvelope |
干净请求不产生空 meta |
TestJobFacets_CacheServesRepeatedRequestWithoutRecomputing |
第二次相同请求命中缓存,FacetCounts 只被调用一次 |
5.2 部署后必须重建索引(任务 4.2)
这是整份清单里唯一一条"代码合了还不算完"的运维项:maxValuesPerFacet 属于索引设置,只在重建后才会作用到线上索引。清单与提案的 Impact 章节都要求把 make reindex 记为部署步骤(条目同时被记录进 proposal 与 design 的 Risks,以防遗漏)。仓库中的目标定义在 Makefile:
make reindex # 等价于 go run ./cmd/reindex,需运行中的 Postgres + Meilisearch
设计文档把这条风险写成"stale index settings":在重建之前,线上索引仍按旧的上限截断 skills/countries,而由于截断是静默的,表现只是"某些值计数缺失",很难被察觉。同理,若新增了 FilterableAttributes 而设置补丁没有先到达线上索引,携带新分面的二进制会让 /api/v1/jobs/facets 对所有调用者 500——源码注释在 facetSettings 中反复强调了这条上线顺序(设置先行,二进制后翻)。
六、把四个阶段串起来:一次请求的完整链路
以访问 /analytics?seniority=senior 为例:
- SvelteKit
load在服务端把seniority=senior交给serverApi(fetch).facetCounts,得到首屏initial。 - 后端
JobFacets用buildSearchFilter把参数解析成 Meili 过滤表达式,facetAttributes()给出要统计的属性列表。 cachedFacetCounts先查一分钟 TTL 的缓存;未命中则调用search.Client.FacetCounts。FacetCounts以Limit: 0发一次(或多查询时走联邦)请求,buildFacetResult把原始 JSON 解成FacetResult。facetView把属性名反解为公开参数名、丢掉连续数值分面的值分布,输出{total, facets, stats}。- 浏览器水合后,
FilterStore从 URL 取回同一份筛选条件,FacetBreakdown按计数降序画条形图;点击某个值 →store.pick→ 防抖后的applied变化 → 带generation保护地重取 → 全部分布与总量一起刷新。
这条链路里,"一次 Meili 查询、无 DB 聚合、无新依赖、无表结构变更"是设计的核心取舍:Meilisearch 已具备在既有过滤语义下免费计算分面的能力,用 Postgres 重做等于把整套过滤词汇表用 SQL 再实现一遍并保持两套同步;代价是时间桶与交叉表必须留给后续阶段,而这正是三阶段划分的意图。
七、复现与继续探索
想在本仓库核对本文的每个结论,可以按下列顺序阅读:
- 决策背景与边界:proposal.md、design.md
- 行为契约:job-analytics/spec.md、web-frontend/spec.md
- 搜索层实现与测试:internal/search/search/facets.go、facets_test.go、facets_integration_test.go
- 索引设置:internal/search/search/client.go
- 接口与词汇表:internal/api/handler/facets.go、internal/search/search/query_filter.go
- 前端:web/src/routes/analytics/+page.server.ts、AnalyticsView.svelte、FacetBreakdown.svelte
- 对外契约:web/static/openapi.yaml
本地验证时,先确保 Postgres 与 Meilisearch 可用,再执行 make reindex 让索引设置生效,随后启动服务并访问 /api/v1/jobs/facets 与 /analytics 即可对照本文逐项复现。