freehire 企业实体建模:从 jobs 自由文本到 slug 键控 companies 表的完整设计与实现

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

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 中,该列定义与索引均可见:

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 必须是两个函数"很重要:

  1. 匹配发生在名字的"词"上,而不是 Slug 的输出上。 因为 Slug 已把 "B.V." 拆成 booking-b-v,在那里再也认不出任何法定形式;而把每个词归约为 ASCII 字母后,无论标点如何都能识别。
  2. 后缀剥离是重复进行的,因为复合形式很常见("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,
    ...

这里能看到提案设计的三个要点都还在,并且各自被后续经验加固:

  1. WHERE sqlc.arg(company_slug) <> '' 精确对应"空 slug 不创建公司"的规格要求——空公司名的职位存空 company_slug,且不会产生公司行。
  2. 单语句 CTE 而非两条语句的事务,落实了"保持一次写入等于一条职位"的取舍。
  3. 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),
})

三点实现细节都值得记录:

  1. 分页窗口先于公司查找校验:被拒绝的请求不该有任何成本,因此越界翻页连数据库都不会碰,且该拒绝语义在所有列表端点间保持一致。
  2. 公司元数据与职位是两次独立的单表读,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 则保证只展示在招职位。

  1. 未命中时的 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 五个阶段

  1. Schema:新增迁移文件,创建 companies、添加 jobs.company_slug、添加索引。
  2. 重建开发卷:docker compose down -v && make up——因为 initdb 不会在既有卷上重跑。
  3. DB 层:新增 companies 查询文件;在 jobs 查询中补 company_slug 与按公司的职位查询;执行 make sqlc 并提交生成代码。
  4. 归一化与写路径:加入 slug 助手并覆盖文档化用例;让 UpsertJob 计算 slug、非空时 upsert 公司、并在职位上同时写 company 与 company_slug,作为一个原子单元。
  5. 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 与手工调用端点外,仓库中有一组可直接阅读的回归测试作为行为证据:

其中"列表无过滤时不走 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 守卫),受影响行数即真实变更量。
  • 计数范围 = 职位搜索索引的范围:oj CTE 叠加了 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 是附加列,可以留在原地,也可以在重建卷时去掉。

需要明确的适用前提有四条,均可在仓库中验证:

  1. schema 由 initdb 应用:docker-compose.yml 将 ./migrations 挂到 /docker-entrypoint-initdb.d,因此首次初始化之后不会再自动重跑;对既有卷请用 make migrate(它会按文件名顺序逐个 psql -f)。当前仓库的迁移文件命名带序号前缀,且存在少量同序号不同主题的文件(如 0009_*、0034_*、0128_*),按文件名排序执行是该目标的行为依据。
  2. 代码生成是强制步骤:任何对 internal/platform/db/queries/*.sql 的修改都必须 make sqlc,否则 Go 侧类型与 SQL 脱节。
  3. slug 有两个函数、用途不同:给公司键一律用 normalize.CompanySlug,给 URL 路径段与职位 public_slug 用 normalize.Slug。混用会造成"看起来只是多一个 -inc"的重复公司。
  4. 计数是最终一致的: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。

登录后查看全文
freehire