freehire 企业实体建模:从 jobs 自由文本到 slug 键控 companies 表的完整设计与实现
freehire 企业实体建模:从 jobs 自由文本到 slug 键控 companies 表的完整设计与实现
本文以 freehire 的 add-companies-table 变更提案为主线,讲清一件具体的事:如何把原本只存在于 jobs.company 自由文本字段里的"公司",升级为一等实体——用自然 slug 作为主键建立 companies 表,同时在 jobs 上反范式化出链接键 company_slug,从而让"公司列表"和"公司详情 + 该公司职位"这两条热读路径完全不产生 companies ↔ jobs 的 JOIN。读完后你将掌握该方案的建表与索引细节、写入路径的原子性实现、读取端点的路由与降级策略,以及在当前仓库中这些设计决策是如何被源码和迁移文件证实的。
一、问题起点:公司为什么必须成为实体
变更提案开篇只讲了一句核心矛盾:Company 目前只是 jobs 上的一个自由文本字段,因此系统既无法展示公司列表,也无法展示单个公司及其职位。
在设计文档中这一点被展开为三个具体事实:
jobs.company是自由文本,由UpsertJob写入,而UpsertJob是(当时即将出现的)采集流水线的唯一写入路径;- 因为不存在公司实体,所以"列出公司"和"展示某公司的职位"这两件事在数据模型上无从表达;
- 用户给出的硬约束是:公司必须是真实的表,但常见读路径必须避免
companies与jobs的 JOIN。
据此该变更确立了指导原则:最大简单性(maximum simplicity)——只构建最小的正确实现,并明确标注出"接缝"(seam),等真正需要时再补。这一原则贯穿全文:它在 schema 上体现为自然主键、无外键;在读取上体现为"先不维护计数器,查询时聚合"。
二、变更总览
提案的 "What Changes" 一共五条,构成了整个方案骨架:
| # | 变更 | 目的 |
|---|---|---|
| 1 | 新增 companies 表,以自然 slug(归一化后的公司名)为主键,不使用代理 id |
让公司成为可独立寻址的实体 |
| 2 | 新增 jobs.company_slug 作为归一化链接键,与既有的 jobs.company(展示名)并存,并为其建索引 |
让"某公司的职位"退化为单表索引过滤 |
| 3 | 写入路径 UpsertJob 从公司名推导 slug,并在同一个工作单元内 upsert 公司行 |
保证表自动保持有数据,不依赖额外任务 |
| 4 | 新增读端点 GET /api/v1/companies(列表)与 GET /api/v1/companies/:slug(公司 + 其职位) |
对外暴露公司目录与详情 |
| 5 | 两个端点均为 join-free:公司元数据来自 companies,其职位来自对 jobs.company_slug 的单表过滤;列表的职位数暂时实时计算 |
守住热读路径不 JOIN 的约束 |
被刻意推迟(作为接缝,而非遗漏)的有三项:反范式化的 job_count 计数器、公司元数据(logo / 网站)、以及在 slug 归一化时剥离法定后缀。
能力边界:新增 companies 能力
提案在 "Capabilities" 中把上述内容收敛为一个新能力 companies,其定义是:以 slug 为键存储公司、通过反范式键把职位链接到公司、并在不 JOIN jobs 的前提下提供公司列表与公司详情读取。
值得注意的是 "Modified Capabilities" 一栏的处理:当时尚无既有 spec,因此"职位行为的变化"(jobs 多出一个 company_slug)也被归并进这个新能力来记录,而没有硬造一个 modify jobs 的条目。
三、数据模型:自然 slug 主键
3.1 表结构
在当时的计划中,这一步落在 migrations/0002_companies.sql。当前仓库的迁移目录已采用"单一初始化 schema"的组织方式,companies 表定义位于 migrations/0001_init.sql(docker-compose.yml 将 ./migrations 挂载为 Postgres 的 docker-entrypoint-initdb.d,即由 initdb 在首次初始化卷时执行):
CREATE TABLE public.companies (
slug text NOT NULL,
name text NOT NULL,
created_at timestamp with time zone DEFAULT now() NOT NULL,
updated_at timestamp with time zone DEFAULT now() NOT NULL,
collections text[] DEFAULT '{}'::text[] NOT NULL,
job_count integer DEFAULT 0 NOT NULL,
regions text[] DEFAULT '{}'::text[] NOT NULL,
countries text[] DEFAULT '{}'::text[] NOT NULL,
domains text[] DEFAULT '{}'::text[] NOT NULL,
company_types text[] DEFAULT '{}'::text[] NOT NULL,
company_sizes text[] DEFAULT '{}'::text[] NOT NULL,
industries text[] DEFAULT '{}'::text[] NOT NULL,
year_founded integer,
employee_count integer,
hq_country text,
organization_type text,
tagline text,
company_info jsonb DEFAULT '{}'::jsonb NOT NULL,
is_reference boolean DEFAULT false NOT NULL,
company_info_at timestamp with time zone
);
ALTER TABLE ONLY public.companies
ADD CONSTRAINT companies_pkey PRIMARY KEY (slug);
其中与提案直接对应的是前四列:slug(自然主键)、name(展示名)、created_at / updated_at(与 jobs 表约定保持一致)。其余数组列、job_count、company_info 等属于该表后续演进中长出来的部分,恰好对应提案里被推迟的几个接缝,后文第七节会逐一交代。
3.2 为什么坚持"自然键、无代理 id"
设计文档把这一决策写成了明确的第一条决定,并给出了被否决的替代方案:
公司的身份就是它归一化后的名字。代理 id 会引入一层用户明确拒绝的间接,在这里没有任何收益。
被否决的是"代理 id + 外键"方案,理由同样具体:更多的列,并且强制在热路径上做一次 JOIN 或一次 company_id 查询。而这两点恰恰与"读路径不 JOIN"的硬约束正面冲突。
由此产生的直接后果是:公司的对外标识是一个可读字符串,例如 acme,而不是 /companies/42。这对 URL、缓存键、以及后文的 301 重定向机制都是前提。
四、jobs.company_slug:反范式化的链接键
4.1 双列并存
第二条决定是:把归一化键反范式化到 jobs 行上,同时保留 company 作为展示名。
这一设计同时解决了两件事:
- "某公司的职位"变成单表索引过滤
WHERE company_slug = $1,而不是 JOIN; - 职位卡片渲染时直接读
company原样展示,同样不需要 JOIN。
用设计文档的原话概括:这是用户要求的反范式化,但施加在"链接"上,而不是施加在"公司元数据"上。
在当前 schema 中,该列定义与索引均可见:
- 列:migrations/0001_init.sql,
company_slug text DEFAULT ''::text NOT NULL; - 索引:migrations/0001_init.sql:
CREATE INDEX jobs_company_slug_idx ON public.jobs
USING btree (company_slug, posted_at DESC NULLS LAST, id DESC);
索引的实际列序已从提案时代的"单列 (company_slug)"演进为按 posted_at、id 排序的复合索引;同一文件里还有一个部分索引 jobs_open_company_created_at_id_idx,其谓词为 closed_at IS NULL,服务于"公司页只要在招职位且按创建时间倒序"的读取。
4.2 有意不建外键
第三条决定非常值得单独强调,因为它常被误认为疏漏:
不加
FOREIGN KEY (company_slug) REFERENCES companies(slug)。真正的外键会强制插入顺序(先公司行、后职位行),在这个数据规模下增加僵硬性却收益甚微;写入路径本来就会把两者都写进去。
取舍被如实记录下来:理论上可能出现某条职位携带着没有对应公司行的 company_slug;但实践中由写入路径"先 upsert 公司"来防止。当前仓库中 jobs.company_slug 相关约束检索不到外键,与该决策一致。
作为后续加固,仓库在需要跨来源匹配时另辟蹊径:新增了存储列 company_slug_folded(即 replace(company_slug,'-',''))。原因写在 migrations/0109_jobs_company_slug_folded.sql 里——当批量值以查询参数传入时,规划器无法为表达式谓词估算选择性,实测每批 500 家公司要读约 92.7 万行、耗时 271 秒;而对普通列使用同样谓词形态只需 491 毫秒。这条演进说明:"链接键"这个设计点后来被继续加压使用,而"无外键、由写入路径保证一致性"的约定也被 internal/platform/db/folded_slug_rule_test.go 用测试固化下来——任何写 company_slug 却忘记写折叠列的新语句都会被该测试抓出。
五、归一化:从最小 slugify 到 normalize.CompanySlug
5.1 提案当时的规则
第四条决定规定:归一化放在 Go 写入路径 中完成,产出规则是"小写、去首尾空白、折叠连续空白、去标点",暂不剥离法定后缀;空公司名 → 空 slug → 不 upsert 公司。
选择放在 Go 而非数据库触发器或生成列的理由是可见性与可测试性,且流水线本身就是归一化的天然归属地。
5.2 当前仓库的实现
当前实现位于 internal/dict/normalize/slug.go。Slug 的职责被严格限定为"忠实地把名字变成本身可作 URL 路径段的键":
func Slug(name string) string {
name = unidecode.Unidecode(name)
var b strings.Builder
prevHyphen := false
for _, r := range name {
switch {
case unicode.IsLetter(r) || unicode.IsDigit(r):
b.WriteRune(unicode.ToLower(r))
prevHyphen = false
case b.Len() > 0 && !prevHyphen:
b.WriteByte('-')
prevHyphen = true
}
}
return strings.TrimRight(b.String(), "-")
}
其文档注释明确了三条关键事实:非拉丁名会被罗马化("Яндекс" → iandeks,"小红书" → xiao-hong-shu),因此结果恒为 ASCII——因为 company_slug 会被用作 URL 路径段;空名或无法转写时返回空串,写入路径将其视为"无公司";并且它刻意不剥离法定后缀。
真正用于"公司键"的是同目录的 internal/dict/normalize/company.go 中的 CompanySlug——也就是提案中"推迟"的那项工作后来被落地的地方:
var legalSuffixes = map[string]struct{}{
"corporation": {}, "limited": {}, "gmbh": {}, "corp": {}, "llc": {}, "ltd": {},
"inc": {}, "incorporated": {}, "plc": {}, "llp": {}, "lp": {}, "cic": {}, "cio": {},
"srl": {}, "pty": {}, "pte": {}, "bv": {}, "nv": {}, "aps": {},
"ab": {}, "ag": {}, "kg": {}, "oy": {}, "sa": {}, "as": {}, "se": {}, "co": {},
}
func CompanySlug(name string) string { return trimTail(name, IsLegalForm) }
两个关键点,对理解"为什么公司键与 URL slug 必须是两个函数"很重要:
- 匹配发生在名字的"词"上,而不是
Slug的输出上。 因为Slug已把 "B.V." 拆成booking-b-v,在那里再也认不出任何法定形式;而把每个词归约为 ASCII 字母后,无论标点如何都能识别。 - 后缀剥离是重复进行的,因为复合形式很常见("Acme GmbH & Co. KG"、"Atlassian Pty Ltd"),单次剥离会留下一半;单词名永不剥离("Limited" 保持
limited),因为空 slug 会静默地匹配不到任何东西,而一个看起来奇怪的公司行至少能被发现并修正。
测试用例把规则钉得很死,internal/dict/normalize/company_slug_test.go 中的关键样例:
| 输入 | 输出 | 说明 |
|---|---|---|
RingCentral, Inc. |
ringcentral |
常规法定后缀 |
Booking B.V. |
booking |
带标点的形式按字母识别 |
Acme S.A. |
acme |
罗曼语系形式 |
Trafalgar A/S |
trafalgar |
北欧形式 |
Acme GmbH & Co. KG |
acme |
复合形式,跨过 & 整体剥离 |
Tiffany & Co. |
tiffany |
& Co. 形式 |
Acme Holdings Ltd |
acme-holdings |
遇到非形式词即停止剥离 |
Limited Brands |
limited-brands |
形式词在名字中间时保留 |
Limited |
limited |
全名即形式时不擦除 |
Яндекс ООО |
iandeks-ooo |
非拉丁语形式不被剥离(只转写) |
Kohl's / Domino's |
kohls / dominos |
撇号不是词边界 |
5.3 Slug 与 CompanySlug 的分工
仓库中的 docs/agents/company-identity.md 把这条规则列为"恒为真"的第一条:normalize.CompanySlug 才是公司键,normalize.Slug 不是。 前者回答"这是哪一家雇主",因此 "RingCentral" 与 "RingCentral, Inc." 不能给出两个不同答案;后者忠于输入名称,供 URL 路径段与职位的 public_slug 使用。此外还有 FoldSlug(去连字符)用于跨拼写匹配:
func FoldSlug(slug string) string {
return strings.ReplaceAll(slug, "-", "")
}
六、写入路径:一条语句里原子地写公司 + 职位
第五条决定是:UpsertJob 在同一次写入中 upsert 公司并在冲突时更新 name 与 updated_at,并优先使用单条带 CTE 的 SQL,以维持既有的"一次写入 = 一条职位"性质;若 CTE 损伤可读性,则退回事务包裹两条查询。当 slug 为空时完全跳过公司 upsert。
当前实现见 internal/platform/db/queries/jobs.sql:
WITH existing AS (
SELECT content_hash AS old_hash, true AS existed FROM jobs
WHERE source = sqlc.arg(source) AND external_id = sqlc.arg(external_id)
),
company_upsert AS (
INSERT INTO companies (slug, name)
SELECT sqlc.arg(company_slug), sqlc.arg(company)
WHERE sqlc.arg(company_slug) <> ''
ON CONFLICT (slug) DO UPDATE SET
name = EXCLUDED.name,
updated_at = now()
WHERE companies.name IS DISTINCT FROM EXCLUDED.name
)
INSERT INTO jobs (
source, external_id, url, title, company, company_slug, company_slug_folded, ...
) VALUES (...)
ON CONFLICT (source, external_id) DO UPDATE SET
company = EXCLUDED.company,
company_slug = EXCLUDED.company_slug,
company_slug_folded = EXCLUDED.company_slug_folded,
...
这里能看到提案设计的三个要点都还在,并且各自被后续经验加固:
WHERE sqlc.arg(company_slug) <> ''精确对应"空 slug 不创建公司"的规格要求——空公司名的职位存空company_slug,且不会产生公司行。- 单语句 CTE 而非两条语句的事务,落实了"保持一次写入等于一条职位"的取舍。
ON CONFLICT上新增的WHERE companies.name IS DISTINCT FROM EXCLUDED.name是对"每条职位都会重写公司行"这一副作用的修补。该注释记录了实测数据:没有这个守卫时,一个 5,000 职位的板块每轮会更新公司 5,000 次;生产上实测为 286M 次更新对 305k 行,使该表死元组占到 32%。守卫只加在 UPDATE 分支,因此新公司仍会被正常创建。
同一注释还指出 companies.updated_at 会被当作招聘公司 sitemap 的 <lastmod> 使用,所以这个守卫同时阻止了"每次抓取都宣称所有公司都变了"。
在流水线层面,slug 的推导位置也被固定下来。internal/ingest/pipeline/pipeline.go 中的 canonicalCompanySlug 会先算 normalize.CompanySlug(company),再与别名注册表的解析结果比对;当注册表没有意见时返回空串,调用方 job.Draft 将其理解为"保留推导出的 slug"。同一文件的 distinctSlugs 注释强调:用于覆盖度探针与用于写入的推导必须是同一个函数,否则"问的是 acme-inc、判的是 acme",这个门就答非所问。
七、读路径:join-free 的列表与详情
7.1 路由注册
端点注册在 internal/api/handler/companies.go:
func (h *companiesHandlers) register(api fiber.Router, mw middleware) {
readLimit := publicReadLimiter(mw.public)
api.Get("/companies", readLimit, h.ListCompanies)
api.Get("/companies/subindustries", readLimit, h.CompanySubindustries)
api.Get("/companies/:slug", readLimit, mw.optional, h.GetCompany)
api.Get("/companies/:slug/hiring", readLimit, h.CompanyHiring)
api.Get("/companies/:slug/closed-jobs", readLimit, h.CompanyClosedJobs)
}
提案要求的两个端点都在其中。注意 /companies/:slug 挂的是 mw.optional(可选鉴权):因为详情会叠加调用者自己的点赞投票 my_vote,但绝不能因为未登录而拒绝读取。
7.2 列表:从"实时计数"到反范式计数
提案第六条决定明确写着:列表的职位数在查询时用聚合计算,而不是维护计数器;"按页对公司聚合职位在目录变热之前都很便宜",计数器被记为接缝。
当前实现已经越过该接缝,读的是反范式列 —— internal/platform/db/queries/companies.sql 中的 ListCompanies:
SELECT slug, name, job_count, tagline, industries, hq_country, collections,
feedback_count, feedback_rating_avg, ai_interview_reports
FROM companies
WHERE job_count > 0
AND (sqlc.arg('search')::text = '' OR name ILIKE '%' || sqlc.arg('search') || '%'
OR slug ILIKE '%' || sqlc.arg('search') || '%')
AND (coalesce(cardinality(sqlc.arg('collections')::text[]), 0) = 0
OR collections && sqlc.arg('collections')::text[])
...
ORDER BY
CASE WHEN sqlc.arg('sort')::text = 'rating' THEN feedback_rating_avg END DESC NULLS LAST,
job_count DESC, name
LIMIT sqlc.arg('limit') OFFSET sqlc.arg('offset');
这段 SQL 与提案设计之间的关系值得逐条对照:
- 仍然是 join-free:整条语句只读
companies,职位数来自列而非子查询或 JOIN。 job_count > 0是"招聘中"范围:注释说明它排除由 YC 与公司信息回填导入的约 9.2 万条"无职位参考行",并让列表与计数都走部分索引companies_hiring_job_count_idx(migrations/0023_companies_hiring_idx.sql),而不是扫描整张堆表。q同时匹配name与slug:所以带连字符的查询(ge-vernova)也能找到名字里带空格的公司("GE Vernova")。- 每个 facet 都是"空数组短路"的数组重叠(
&&):单个 facet 内 OR,facet 之间 AND,并与q组合。 sort=rating用CASE保持默认排序字节级不变:未请求 rating 时该CASE对每行都是 NULL,ORDER BY退化成job_count DESC, name。CountCompanies必须与ListCompanies的 WHERE 完全一致,注释以大写强调,否则过滤后的总数与分页页内容会不一致。
处理函数侧还有一层与提案精神一致的设计:无过滤的目录总数用 O(1) 的规划器估算,有过滤时用精确计数。见 internal/api/handler/companies.go,其注释记录了理由:生产上无过滤的 count(*) 是冷缓存堆扫描(约 17 秒),而任何 facet 或搜索过滤都会收窄到索引。这条"两条路径"的分工与提案"列表计数暂时实时算"的朴素做法形成了清晰的演进对照。
7.3 详情:两次单表读 + 301 重定向
GetCompany 见 internal/api/handler/companies.go,流程可拆成四步:
limit, offset, err := pageParams(c) // 先校验分页窗口,再碰数据库
company, redirected, err := h.lookupCompany(c, slug)
jobs, err := h.queries.ListJobsByCompany(c.Context(), db.ListJobsByCompanyParams{
CompanySlug: slug,
Limit: int32(limit),
Offset: int32(offset),
})
三点实现细节都值得记录:
- 分页窗口先于公司查找校验:被拒绝的请求不该有任何成本,因此越界翻页连数据库都不会碰,且该拒绝语义在所有列表端点间保持一致。
- 公司元数据与职位是两次独立的单表读,
ListJobsByCompany的候选 SQL 见 internal/platform/db/queries/jobs.sql:
SELECT *
FROM jobs
WHERE company_slug = $1 AND closed_at IS NULL AND duplicate_of IS NULL AND NOT is_private
ORDER BY created_at DESC, id DESC
LIMIT $2 OFFSET $3;
其中三个谓词各有来由:duplicate_of IS NULL 把角色簇的转载折叠为规范行,与 /jobs 列表一致;NOT is_private 排除"粘贴 JD 定制简历"产生的私有职位——否则一个匿名调用者就能在公开公司页读到别人粘贴的全文,且因为它按 created_at DESC 排序会排在最前;closed_at IS NULL 则保证只展示在招职位。
- 未命中时的 301 重定向:
lookupCompany(同文件 L350-L365)先按 slug 查公司,只有在ErrNoRows之后才去查别名表;命中别名则 301 到规范 slug。注释特意区分了两种失败:数据库故障不等于"没有这家公司",把前者报成 404 会让爬虫丢弃一个真实存在的页面,并把故障从错误率里藏起来。
这与 migrations/0112_company_slug_aliases.sql 的设计一脉相承:别名表是公司相关表中唯一不由 jobs 派生的表,且刻意不建 canonical_slug → companies(slug) 外键——因为那个"直觉上该加"的约束会删掉这张表存在的全部意义。读取顺序也是刻意的:"先查公司、后查别名",这样一个后来恢复的公司永远不会被那条曾让它退役的别名行遮蔽。
八、API 形态与调用方式
两个端点的对外契约记录在 docs/API.md,均为公开、无需鉴权,可跨域调用。
8.1 GET /companies
按最活跃优先返回公司页,带职位数与反范式 facet,支持可选过滤。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
q |
string | 否 | 公司名大小写不敏感子串过滤(如 acme) |
collections |
string | 否 | 精选集合 slug(如 yc、bigtech),可重复 |
regions |
string | 否 | 公司招聘区域(如 eu),可重复 |
countries |
string | 否 | ISO 3166-1 alpha-2 国家(如 DE),可重复 |
industries |
string | 否 | 精选行业;通过公司自身行业或等价职位派生 domain 匹配 |
domains |
string | 否 | 原始职位派生 domain |
company_type |
string | 否 | 公司类型(如 product、outstaff) |
company_size |
string | 否 | 规模桶(如 51-200) |
remote_regions |
string | 否 | 职位派生的远程招聘区域 |
yc_batch / yc_status / yc_stage / yc_flags |
string | 否 | YC 目录相关 facet |
maturity |
string | 否 | 公司阶段/成熟度 |
subindustries |
string | 否 | YC 子行业叶子节点 |
limit / offset |
integer | 否 | 分页,limit 为 1–100 |
curl "https://freehire.me/api/v1/companies?q=acme&collections=yc"
{
"data": [
{
"slug": "acme",
"name": "Acme",
"job_count": 12,
"collections": ["yc"],
"regions": ["eu"],
"countries": ["DE"],
"company_types": ["product"],
"company_sizes": ["51-200"],
"tagline": "Payments for builders",
"maturity": "growth"
}
],
"meta": { "total": 1, "limit": 20, "offset": 0 }
}
8.2 GET /companies/{slug}
返回公司本体 + 一页在招职位。slug 为路径参数(如 acme),limit / offset 控制职位列表分页。
curl "https://freehire.me/api/v1/companies/acme"
{
"data": {
"company": { "slug": "acme", "name": "Acme", "job_count": 12, "tagline": "Payments for builders" },
"jobs": [ { "public_slug": "...", "title": "...", "...": "..." } ]
}
}
读到这两个端点时,可以对照源码确认一处刻意的类型设计:companyDetailResponse.Company 的类型是 companyView 而非原始 db.Company,Jobs 是 []jobview.Job 而非 []db.Job。注释说明了原因——前者防止内部记账列(created_at、updated_at、is_reference、company_info_at)泄漏到响应,后者防止内部职位 id 泄漏。这种"用 DTO 类型而非注释来保证不泄漏"的做法,比逐字段检查更难出错。
此外还有两个与本变更同源的扩展端点:/companies/:slug/hiring(招聘信号)与 /companies/:slug/closed-jobs(已关闭职位,采用与 ListJobsByCompany 相同的排除条件、把 closed_at 谓词反转,并由 jobs_closed_company_closed_at_idx 支撑)。
8.3 被忽略参数的显式反馈
公司端点只识别自己的 facet 词表。若调用方把 /jobs 的 facet 发到 /companies,参数不会被拒绝而是被忽略,并在 meta.ignored_params 中回报(最多 10 条),必要时给出 did_you_mean(当它只是某个真实 facet 的单数形式时)。文档对此的判断标准很实际:一个被悄悄丢掉的过滤器,看起来就像一次真正宽泛的搜索。
九、落地步骤与验证
提案的 "Impact" 与设计文档的 "Migration Plan" 给出了完整的执行路径。需要特别注意的是本次变更的迁移只在全新卷上生效:schema 由 Postgres initdb 从 migrations/ 执行,每个文件只在首次卷初始化时跑一次,且当时尚无版本化迁移运行器。
9.1 五个阶段
- Schema:新增迁移文件,创建
companies、添加jobs.company_slug、添加索引。 - 重建开发卷:
docker compose down -v && make up——因为 initdb 不会在既有卷上重跑。 - DB 层:新增
companies查询文件;在jobs查询中补company_slug与按公司的职位查询;执行make sqlc并提交生成代码。 - 归一化与写路径:加入 slug 助手并覆盖文档化用例;让
UpsertJob计算 slug、非空时 upsert 公司、并在职位上同时写company与company_slug,作为一个原子单元。 - API 与验证:加两个 handler(沿用既有的
{data, meta}/{data}响应形状),在handlers.Register中接线;最后go build ./... && go vet ./...并手工验证两个端点。
9.2 任务清单
变更的 tasks.md 把上述阶段拆成 5 组共 11 项,全部标记完成,且每项都能在仓库中找到对应物:
| 任务 | 当前仓库对应位置 |
|---|---|
1.1 建 companies(slug 主键、name、created_at/updated_at) |
migrations/0001_init.sql |
1.2 加 jobs.company_slug TEXT NOT NULL DEFAULT '' 与索引 |
migrations/0001_init.sql、#L746-L749 |
2.1 UpsertCompany / ListCompanies / GetCompany 查询 |
internal/platform/db/queries/companies.sql |
2.2 jobs.sql 增加 company_slug 与按公司过滤的职位查询 |
internal/platform/db/queries/jobs.sql |
2.3 make sqlc 并提交生成代码 |
Makefile、sqlc.yaml |
| 3.1 slug 助手 + 用例覆盖 | internal/dict/normalize/company_slug_test.go |
| 3.2 写路径原子写 | internal/platform/db/queries/jobs.sql |
| 4.1 两个 handler | internal/api/handler/companies.go、#L370 |
| 4.2 路由接线 | internal/api/handler/companies.go |
命令层面,仓库提供的相关目标包括:
make sqlc # 通过 Docker/Podman 运行 sqlc 1.31.1 生成 internal/platform/db 下的代码
make up # 启动 app + postgres
make psql # 打开数据库 shell 核对表与列
make migrate # 对"既有卷"手动按序应用 migrations/*.sql
make sqlc 的实现值得一读,因为它说明生成代码无需本地安装工具链:
sqlc: ## Generate code from SQL (via Docker/Podman, no local sqlc needed)
$(DOCKER) run --rm -v "$(PWD):/src" -w /src docker.io/sqlc/sqlc:$(SQLC_VERSION) generate
而 sqlc.yaml 中 schema: "migrations"、queries: "internal/platform/db/queries"、out: "internal/platform/db" 的配置,正好解释了为什么"改 SQL → 跑 make sqlc"是这一层变更的固定动作。同文件里还有一条与公司详情直接相关的 override:companies.company_info 被映射为 encoding/json.RawMessage,因为普通 []byte 会把 JSONB 在响应里 base64 编码。
9.3 验证手段
除提案要求的 go build / go vet 与手工调用端点外,仓库中有一组可直接阅读的回归测试作为行为证据:
- internal/api/handler/companies_integration_test.go:覆盖列表搜索、Meilisearch 回退、无过滤时不走 Meili、facet 过滤、子行业 facet、远程区域 facet、YC 系列 facet,以及
TestGetCompanyOmitsPrivateJobs(详情不泄漏私有职位)。 - internal/api/handler/companies_alias_integration_test.go:覆盖退役 slug 的 301 重定向。
- internal/api/handler/companies_test.go:详情端点的字节级 golden body 固定。
- internal/platform/db/folded_slug_rule_test.go:遍历查询目录,确保任何写
company_slug的语句同时写了折叠列。
其中"列表无过滤时不走 Meili"这条测试对应的实现细节尤其能说明读路径的稳健性设计:只有当 companySearcher 非空、且请求带 q 或任一 facet 时才走 Meilisearch;未过滤的目录保持 Postgres 的 job_count DESC, name 排序与 O(1) 总数估算;任何 Meili 错误都会回落到 Postgres 子串路径。处理函数注释的原话是:/companies 永不依赖 Meilisearch 处于可用状态。
十、接缝的兑现:三个"刻意推迟"后来怎么样了
提案把三项工作明确标为"等需要时再建"。把它们与当前仓库对照,是理解这份设计文档价值的最好方式——它没有猜错方向,只是把顺序留给了后面。
10.1 反范式的 job_count 计数器
提案当年选择"实时聚合",并预测"目录变热后会变慢"。当前的 companies.job_count 是 NOT NULL DEFAULT 0 的真实列(migrations/0001_init.sql),由周期任务重算而非写入路径触发器维护。
重算逻辑位于 cmd/recount-companies/main.go 与 RefreshCompanyFacets(internal/platform/db/queries/companies.sql)。它在一个基于集合的 pass 中同时重算:在招职位数,以及从这些在招职位派生的 facet 数组(regions / countries / remote_regions / domains / company_types / company_sizes)。要点如下:
- 最终一致,而非事务内一致:职位被写入或被关闭都会改变这些值,因此由定时重算维护;重复运行只重写真正发生变化的行(每列都有
IS DISTINCT FROM守卫),受影响行数即真实变更量。 - 计数范围 = 职位搜索索引的范围:
ojCTE 叠加了closed_at IS NULL、duplicate_of IS NULL、company_slug <> ''、NOT is_private、description <> ''以及分类可解析等谓词,注释明确要求与cmd/reindex的splitJobs保持一致。原因写在注释里:计数范围放得太宽曾导致 sitemap 里 294,021 个公司 URL 中大多数渲染出"0 个在招职位",以及 Stripe 在/companies显示 570 而在自己页面显示 444。 oj被钉为MATERIALIZED,否则规划器可能内联它并让八个聚合各自重扫一遍在招职位集合。
列表总数也随之后续优化为双路径:无过滤时走 EstimateHiringCompanies(内部是对 EXPLAIN (FORMAT JSON) 取规划器估算,见 migrations/0034_estimate_hiring_companies.sql),有过滤时走与 ListCompanies 同构的精确 CountCompanies。
10.2 公司元数据(logo / 网站 / 描述)
提案把 logo、website、description 列为非目标。当前 companies 表已有 tagline、company_info jsonb、year_founded、employee_count、hq_country、organization_type 等列,并且写入口被细分为多种"所有权"语义,这些语义集中体现在 UpsertYCCompany 的长注释里:YC 目录拥有 name、job_count、collections 等列;tagline 只填空、company_info 按键合并(已存值优先);industries 取并集并排序去重;而 subindustry / year_founded / employee_count / hq_country 在存在活跃雇主账号时整体让位——因为公司自述比导入的目录条目更权威。
另一条与"公司描述"相关的路径是 FillCompanyDescriptionFromIngest 与 MarkCompanyDescriptionChecked:前者应用 ATS 适配器随板块抓取一并产出的公司级描述(同样是"只填空、按键合并"),后者记录"问过了但是空的",避免每轮重复询问。
10.3 法定后缀剥离
提案第四条决定明写"暂不剥离法定后缀",风险一节也据此判断"碰撞会保持稀少"。前文第五节的 normalize.CompanySlug 就是这一接缝的兑现,而 company_slug_aliases(migrations/0112_company_slug_aliases.sql)则承接了纯函数不该承担的判断:合并(merge)属于"判断",必须能展示 dry run、按职位数选举、并写入可回滚的别名,而不是由一个静默应用于每条新职位的纯函数完成。
十一、风险与权衡
设计文档列出的四条风险,每一条都配了缓解措施,且都可以在今天的状态里核对:
| 风险 | 提案中的判断 | 缓解 / 现状 |
|---|---|---|
| slug 碰撞(两个不同公司归一化到同一 slug) | 会被合并到同一公司下;对聚合器 MVP 可接受;刻意不剥离后缀以保持碰撞稀少 | 接缝兑现:CompanySlug + cmd/merge-companies 的别名注册表 |
孤儿 company_slug(无外键) |
只有当写入路径之外的代码插入职位时才可能发生 | 写入路径对非空 slug 总是先 upsert 公司;folded_slug_rule_test.go 守住新写入路径 |
| 实时计数随目录变热变慢 | 到那时再引入 job_count 接缝 |
已引入反范式列 + 周期重算 + 部分索引 |
| 迁移只在全新卷生效 | 开发环境用 docker compose down -v && make up;记录在案但不在此解决 |
make migrate 提供对既有卷手动按序应用的能力 |
还有一个提案未列、但被设计文档点明的取舍:无外键换来的写入顺序自由度。它让 UpsertJob 可以在一条语句里同时处理公司与职位,代价是"一致性靠约定"。仓库对此的处理方式很典型:把约定写成注释(说明为什么可以接受),再写成测试(说明怎样才能不破坏它)。
十二、回滚与适用前提
设计文档给出的回滚策略与它的实现风格一致,因为改动是增量式的:
回滚:移除新端点与查询,以及对应的
migrations/0002_*;company_slug是附加列,可以留在原地,也可以在重建卷时去掉。
需要明确的适用前提有四条,均可在仓库中验证:
- schema 由 initdb 应用:
docker-compose.yml将./migrations挂到/docker-entrypoint-initdb.d,因此首次初始化之后不会再自动重跑;对既有卷请用make migrate(它会按文件名顺序逐个psql -f)。当前仓库的迁移文件命名带序号前缀,且存在少量同序号不同主题的文件(如0009_*、0034_*、0128_*),按文件名排序执行是该目标的行为依据。 - 代码生成是强制步骤:任何对
internal/platform/db/queries/*.sql的修改都必须make sqlc,否则 Go 侧类型与 SQL 脱节。 - slug 有两个函数、用途不同:给公司键一律用
normalize.CompanySlug,给 URL 路径段与职位public_slug用normalize.Slug。混用会造成"看起来只是多一个-inc"的重复公司。 - 计数是最终一致的:
companies.job_count与 facet 数组由周期重算维护,读取端不应假设它与jobs表在同一瞬间严格一致;若需要即时一致性,应直接查jobs(代价是失去 join-free 的读性能)。
十三、小结
这份变更提案的价值不在于它预测了未来,而在于它把不可逆的决策与可延后的决策分开了。不可逆的三件事——自然 slug 主键、jobs.company_slug 这个反范式链接键、以及读路径不 JOIN——被一次做对,并在后续演进中一直被保留:今天的 ListCompanies 依然只读 companies,ListJobsByCompany 依然是 WHERE company_slug = $1 的单表过滤,GetCompany 依然是两次单表读加一次可能的重定向。可延后的三件事——计数器、元数据、后缀剥离——被显式标注为接缝,随后各自以可验证的方式落地,且都没有破坏最初那条读路径的形状。
如果要继续深入,建议的阅读顺序是:先看 openspec/specs/companies/spec.md 了解被固化的需求与场景,再看 internal/platform/db/queries/companies.sql 理解读侧的全部约束,最后看 internal/api/handler/companies.go 与 internal/api/handler/companies_integration_test.go 把行为与断言对上。公司身份的完整规则另见 docs/agents/company-identity.md,公司 facet 的派生规则另见 docs/agents/company-facets.md。