freehire 岗位公开标识 public_slug 设计与实现:从自增 id 到稳定 slug 路由

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

freehire 岗位公开标识 public_slug 设计与实现:从自增 id 到稳定 slug 路由

freehire 是一个面向求职者的开源职位搜索引擎,其公开 API 早期直接把数据库里的自增主键 jobs.id 当作岗位标识暴露在 URL 与响应体里。本指南围绕 add-job-public-slug 变更的完整落地过程,讲清 public_slug 的生成算法、数据库写读路径、DTO 序列化边界与路由改造方法,并给出可复现的验证清单与踩坑提醒。读完你能独立为一套"自增 ID 暴露"的目录型 API 设计出确定性、可路由、可在重新入库时保持稳定的公开标识方案。

一、问题背景:可枚举的 id 是信息泄漏面

原始实现中,公开的岗位接口直接序列化生成的 db.Job 结构体(c.JSON(fiber.Map{"data": job})),于是结构体的 JSON 编码本身就构成了 API 契约,其中包含顺序自增的 id;GetJob、RecordView、MarkApplied 也都解析数字型 :id 路径参数。

这带来两个问题:

  1. 可枚举:任何人从 1 走到 N 就能爬完整份职位目录;
  2. 增长率即业务指标:id 的增长速度会反映库存规模与填充速度,这是不该对外透露的运营数据。

变更的核心主张在 proposal.md 中写得很清楚:对外暴露一个不可枚举、人类可读的标识,同时不牺牲内部用于 JOIN 的窄整型主键。

明确的目标与非目标

类别 内容
目标 每个岗位由稳定、不可枚举的 public_slug 寻址;任何公开响应与路由都不再出现数字 id
目标 id 继续作为内部 BIGINT 主键与外键目标(user_jobs.job_id),不加宽、不改热路径
目标 slug 由 (source, external_id) 确定性推导,重复入库对 slug 幂等
非目标 从源站解析原生 external_id(当时还没有采集成体系)
非目标 隐藏 source / external_id 本身——只有数字 id 被认定为泄漏
非目标 版本化迁移执行器,仍是 initdb-only

这些边界很关键:它决定了后面每一处改动都只做"换标识",而不是顺手重构数据模型。

二、slug 的形状与生成算法

2.1 三段式:<title>-<company>-<shortcode>

slug 生成落在 internal/normalize(与既有的 Slug 相邻,便于无数据库的单元测试):

func JobSlug(title, company, source, externalID string) string {
	segments := make([]string, 0, 3)
	if t := Slug(title); t != "" {
		segments = append(segments, t)
	}
	if c := Slug(company); c != "" {
		segments = append(segments, c)
	}
	segments = append(segments, shortcode(source, externalID))
	return strings.Join(segments, "-")
}

见 internal/dict/normalize/job_slug.go。三个设计要点:

  • 只拼接非空分段。公司名可能被归一化成空串,如果无条件拼接就会产生 title--code 这样的双连字符;
  • shortcode 永远存在,所以即使标题和公司都归一化为空,slug 也绝不会是空串(此时 slug 就是纯 shortcode,如 5vsxmqi5);
  • 短码只依赖 (source, external_id),不依赖 description 这类易变字段。

2.2 标题与公司的归一化:复用 Slug

Slug 是项目里已有的名字→自然键函数,语义在 internal/dict/normalize/slug.go 中定义:

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(), "-")
}

行为总结:

规则 效果
先做 unidecode 转写 Яндекс → iandeks,小红书 → xiao-hong-shu
字母/数字转小写保留 Senior Go Developer → senior-go-developer
非字母数字连续段折叠为单个 - C++ / Rust → c-rust
去掉尾部连字符 避免 slug 以 - 结尾
不剥离法律后缀 Acme, Inc. 仍是 acme-inc(剥离是 CompanySlug 的职责,两者是不同的键)

最后一条注释值得单独强调:Slug 要忠实于"这个名字本身",因为它是 URL 路径段;而"这是哪家公司"的问题由 CompanySlug 回答(RingCentral 与 RingCentral, Inc. 必须归一到同一个答案)。选错函数会让 slug 语义漂移。

2.3 短码:sha256 + NUL 分隔 + base32 前 8 字符

const shortcodeLen = 8

func shortcode(source, externalID string) string {
	sum := sha256.Sum256([]byte(source + "\x00" + externalID))
	return strings.ToLower(base32.StdEncoding.EncodeToString(sum[:]))[:shortcodeLen]
}

见 internal/dict/normalize/job_slug.go。三个细节:

  1. NUL 分隔符:防止 ("ab","c") 与 ("a","bc") 拼接后哈希相同。这是一个真实存在过的哈希拼接陷阱,测试里专门有 TestJobSlugSeparatorAvoidsCollision 守住它;
  2. 8 个 base32 字符 = 40 bit:在 12.7M 行量级上碰撞概率极低;设计文档的论证是"slug 冲突还需要 title+company 同时匹配",因此实际风险可忽略;
  3. 统一小写:base32.StdEncoding 输出大写,转小写后与 slug 的风格一致,也让短码字符合集收敛为 [a-z2-7]。

为什么不用十六进制?设计文档给出的理由很实际:hex 更长、更难看;而 4–6 位字符碰撞更多。唯一性约束 UNIQUE 是兜底。

2.4 可核验的测试向量

单元测试 internal/dict/normalize/job_slug_test.go 固化了确定性输出,这些值可以直接拿来做线上 spot check:

title company source external_id public_slug
Senior Go Developer Acme manual 42 senior-go-developer-acme-t35nijto
Go Dev (空) s 1 go-dev-5vsxmqi5
(空) (空) s 1 5vsxmqi5
Senior Go Developer Acme manual 43 senior-go-developer-acme-gnhygrtm

它同时覆盖了需求里的三条不变量:相同输入→相同 slug;只有描述变化时 slug 不变(描述根本不是入参);空标题/空公司仍得到非空 slug;不同 (source, external_id) → 不同短码。

2.5 反向解析:JobSlugCode

后面的事故修复依赖一个反向能力——从 slug 尾部取出短码:

func JobSlugCode(slug string) (code string, ok bool) {
	if len(slug) < shortcodeLen {
		return "", false
	}
	head, code := slug[:len(slug)-shortcodeLen], slug[len(slug)-shortcodeLen:]
	if head != "" && !strings.HasSuffix(head, "-") {
		return "", false
	}
	for _, r := range code {
		if (r < 'a' || r > 'z') && (r < '2' || r > '7') {
			return "", false
		}
	}
	return code, true
}

见 internal/dict/normalize/job_slug.go。它刻意做了严格校验,ok=false 时调用方不会拿一个"别的字符串的片段"去查库:

  • 长度不足 8 直接失败;
  • 如果还有前缀,前缀必须以 - 结尾(否则 acmexabcdefgh 这种无分隔符的串会被误判);
  • 短码字符必须落在 base32 小写字集内(1、大写字母都会被拒)。

三、数据库落地:列、约束与三条查询

3.1 schema:NOT NULL UNIQUE

任务清单里的第 2 项要求新增 migrations/0007_job_public_slug.sql,写入 jobs.public_slug TEXT NOT NULL UNIQUE。在当前仓库中,历史迁移已被合并进基线,该列实际出现在 migrations/0001_init.sql,唯一约束在 migrations/0001_init.sql:

public_slug text NOT NULL,
...
ALTER TABLE ONLY public.jobs
    ADD CONSTRAINT jobs_public_slug_key UNIQUE (public_slug);

设计上的三点考量:

  • 无需回填默认值:initdb 时 jobs 表刚由 0001 创建且为空,ADD COLUMN ... NOT NULL 不会触发回填;
  • UNIQUE 自带查找索引:GetJobBySlug 靠它做索引扫描,不必再建独立索引;
  • 冲突是响亮的写失败,而不是静默覆盖。

3.2 写路径:UpsertJob 里"只写一次"

public_slug 作为参数出现在 UpsertJob 的 INSERT 列清单中,但刻意不出现在 DO UPDATE SET 里。SQL 里那段注释是这份设计最重要的约束:

-- public_slug is deliberately NOT in the DO UPDATE SET: the slug is minted once
-- at insert and is the row's stable public identity. Re-ingest of the same
-- (source, external_id) must not rewrite it, so external links stay valid even
-- if the slug builder changes later (that would be a deliberate migration).

见 internal/platform/db/queries/jobs.sql,关键注释在 L399-L403。这形成了 "mint-once(铸一次)" 的语义:slug 是这一行的发布身份,重新采集只更新内容字段,绝不重写 URL。

3.3 读路径:宽读与窄读分开

查询 用途 形态
GetJobBySlug 公开详情页,需要整行(SELECT *) jobs.sql#L161-L164
GetJobIDBySlug view/apply 等交互路径,只要内部 id jobs.sql#L226-L233
ListJobsBySlugCode 用短码反查(旧链接救援) jobs.sql#L166-L175

GetJobIDBySlug 的存在理由写在注释里:交互路径只写 user_jobs 的 FK,不应该在每次静默 view 时把宽大的 description / enrichment 列拖过网络。

3.4 代码生成

任务 2.3 要求执行 make sqlc 并提交重新生成的 internal/db,随后 go build ./... 与 go vet ./... 必须通过。sqlc 的产物在 internal/platform/db(如 jobs.sql.go、querier.go、models.go),类型变更会在这里体现为 UpsertJobParams.PublicSlug 等字段。

3.5 集成测试验证了 SQL 语义

internal/platform/db/jobs_slug_integration_test.go 用真实 Postgres 验证三件事,并且刻意写字面量 slug 而不是调用生产函数:

该包位于依赖图最底层,不能反向依赖 facet 字典;而用生产函数重算 slug 的测试,对它自己的格式什么也没断言。

测试还验证了重复入库不会产生第二行(SELECT count(*) FROM jobs 必须等于 1),以及未知 slug 返回 pgx.ErrNoRows。

四、读序列化:用 DTO 切断 id 泄漏

4.1 从 db.Job 到 jobview.Job

任务 3.1 要求引入 handler 侧的 jobResponse DTO,携带 public_slug、排除数字 id,并保留 enrichment 透传语义(enrichment 为原始对象,未富化时是 {} 而不是 null)。在当前仓库里,这一职责已收敛到公共的 wire 形状 jobview.Job,见 internal/job/jobview/jobview.go:

// Job is the public wire shape of a job. It carries the public_slug and
// deliberately omits the internal numeric id, which must never be exposed: the
// id is enumerable and its growth leaks inventory size and fill rate.
type Job struct {
	PublicSlug string `json:"public_slug"`
	Source     string `json:"source"`
	...
}

映射由 FromRow / FromRows 承担(jobview.go#L161-L176 与 L414-L419):先经 job.FromRow 得到领域对象,再投影成线上形状。这个"投影是唯一事实来源"的结构,比在每个 handler 里手写 fiber.Map 更难漏字段。

设计文档还解释了一个被否掉的替代方案:给 sqlc 模型加 // json:"-" 覆盖 id。否决理由是它会连内部使用者一起藏掉 id(富化 worker 还需要它),并把数据库模型和线上形状耦合死。

4.2 列表、详情、公司页必须走同一条路

任务 6/label 4.4(代码评审补充项)指出:GetCompany 也返回岗位,必须同样走 DTO,否则 id 会从公司详情页漏出去。修复方式是类型安全的 companyDetailResponse{Jobs []jobResponse},并加上回归测试 TestCompanyDetailHidesJobID。

这一点在今天的代码里体现为"一个 wire shape 服务所有读接口":正如 docs/API.md 所述,列表、详情、公司、搜索响应共享同一形状,均以 public_slug 寻址、绝不出现内部 id。

五、路由改造::id → :slug

5.1 路由注册

/jobs 下的参数路由全部改为 slug,见 internal/api/handler/jobs.go:

api.Get("/jobs", readLimit, h.ListJobs)
// Static route registered before /jobs/:slug so it isn't captured as a slug.
api.Get("/jobs/find", readLimit, h.FindJob)
api.Get("/jobs/:slug", readLimit, mw.optional, h.GetJob)
api.Get("/jobs/:slug/copies", readLimit, h.JobCopies)
api.Get("/jobs/:slug/apply-form", readLimit, h.JobApplyForm)

两个容易忽略的工程细节:

  • 静态路由必须在参数路由之前注册,否则 /jobs/find 会被当成 slug find;
  • 所有岗位读共用同一个 public-read 限流预算——注释解释了为什么不能漏掉任何一个:/jobs 与 /jobs/search 返回的是同一份目录,留下一个不设限的入口等于整个限流形同虚设。

5.2 未知 slug → 404 的中央处理

GetJob 只做一件事:拿 slug 换行,然后交给中央错误处理把 pgx.ErrNoRows 映射成 404(jobs.go#L145-L150)。这比每个 handler 各写一遍 if err != nil { return 404 } 更不容易出现状态码不一致。

5.3 交互写入:slug → 内部 id

view/apply 类接口仍需要窄整型 id 才能写 user_jobs,因此 interactionParams 从"解析 int"改成"解析 slug"。落地后的注册代码见 internal/api/handler/user_jobs.go,注释直接写明了契约:

// Per-user job interactions accept either the session cookie or an API key
// (RequireAuthOrKey), so a script holding a key can drive the same flow as the
// browser. Jobs are addressed by their public slug; the handlers resolve it to
// the internal id before writing user_jobs. All writes are idempotent upserts.
api.Post("/jobs/:slug/view", mw.key, h.RecordView)
api.Post("/jobs/:slug/apply", mw.key, h.MarkApplied)

RecordView 把 c.Params("slug") 直接交给领域服务(user_jobs.go#L142-L152),由 repository 完成解析:internal/application/jobtracking/repository.go

func (r *QueriesRepository) JobIDBySlug(ctx context.Context, slug string) (int64, error) {
	id, err := r.q.GetJobIDBySlug(ctx, slug)
	if errors.Is(err, pgx.ErrNoRows) {
		return 0, ErrJobNotFound
	}
	...
}

ErrJobNotFound 再由 trackingError 映射为 404(user_jobs.go#L117-L138)。这一层"哨兵错误 → HTTP 状态"的映射表,是保持 slug 路由行为一致的关键。

实现备注:交互响应 interactionResponse 仍包含 job_id 字段(user_jobs.go#L89-L100)。它属于"已登录用户自己的交互记录",与公开岗位标识是不同层面;从源码结构看,公开岗位读接口才是"绝不出现 id"这条规则的适用范围。

5.4 写入侧接入:jobderive 负责铸 slug

slug 不是由 SQL 算出来的(设计文档明确否决了这个替代方案:SQL 无法复用 normalize.Slug 的 Unicode 行为,会形成两套归一化逻辑)。生成点在派生层:internal/job/jobderive/jobderive.go

return Derived{
	CompanySlug: normalize.CompanySlug(in.Company),
	PublicSlug:  normalize.JobSlug(in.Title, in.Company, in.Source, in.ExternalID),
	...
}

于是 UpsertJob 的 slug 参数由调用方计算并传入,查询层只负责持久化。

5.5 SPA 同步

任务 5.1 要求 web/ 下的 Svelte 应用改用 public_slug 寻址:岗位链接、详情路由、view/apply 调用都不再拼数字 id。当前路由已按 slug 组织,例如 web/src/routes/jobs/[slug]/+page.server.ts](web/src/routes/jobs/[slug]/+page.server.ts) 与 web/src/routes/jobs/[slug]/+page.svelte;类型定义中的 public_slug 见 [web/src/lib/types.ts。

六、当 slug 被改坏:短码兜底与那条不可回退的红线

这套设计最值得学习的部分,不是它第一次做对了,而是它被违反之后如何补。

6.1 事故链

cmd/backfill-derive 是一个重算所有确定性派生列(facet、role_fingerprint、company_slug)的批量任务。某次它把 public_slug 也一起重算了——于是凡是源站给同一 external_id 改过标题的岗位,其已发布 URL 全部失效。迁移文件的注释记录了规模:

Until that fix, cmd/backfill-derive re-derived public_slug from the CURRENT title, so every posting a source retitled under the same external_id lost its published URL — one run on 2026-10-19 moved 42,226 of them before it was stopped.

见 migrations/0183_jobs_public_slug_code_idx.sql。这也解释了为什么 UpsertJob 的 DO UPDATE 里绝不能出现 public_slug——两处是同一条规则的两端。

6.2 救援机制:用短码找回"搬走了的"岗位

短码是 slug 中唯一不受标题/公司变化影响的部分。于是详情读取做了两级查找,见 internal/api/handler/jobs.go:

func (h *jobsHandlers) jobBySlugOrCode(ctx context.Context, slug string) (db.Job, error) {
	job, err := h.queries.GetJobBySlug(ctx, slug)
	if !errors.Is(err, pgx.ErrNoRows) {
		return job, err
	}
	code, ok := normalize.JobSlugCode(slug)
	if !ok {
		return job, err
	}
	jobs, err := h.queries.ListJobsBySlugCode(ctx, code)
	if err != nil {
		return db.Job{}, err
	}
	if len(jobs) != 1 {
		return db.Job{}, pgx.ErrNoRows
	}
	return jobs[0], nil
}

配合的 Query 用 LIMIT 2 就够判断"唯一匹配"还是"歧义":

SELECT *
FROM jobs
WHERE right(public_slug, 8) = sqlc.arg(code)::text
LIMIT 2;

见 internal/platform/db/queries/jobs.sql。

关键取舍写在测试注释里:"a redirect to somebody else's posting is worse than a 404"——歧义短码宁可 404,也不能把用户导向别人的岗位。集成测试 internal/api/handler/job_moved_slug_integration_test.go 覆盖了三种情形:旧 slug 靠短码命中并返回当前 slug(状态 200);歧义短码 404;未知短码 404。

6.3 索引:right(public_slug, 8)

为了让上述查找在千万级表上仍是索引扫描,0183 建了表达式索引:

CREATE INDEX CONCURRENTLY IF NOT EXISTS jobs_public_slug_code_idx
    ON public.jobs (right(public_slug, 8));

两个刻意的决定:

  • CONCURRENTLY(文件头 -- migrate: no-transaction):在 ~12.7M 行上建索引不阻塞读写;
  • 非唯一:40 bit 在这么大规模上会撞几十次,索引不承担唯一性,唯一性由 jobs_public_slug_code 的查找逻辑按"数量必须恰为 1"来判。

6.4 为什么 JobSlug 的入参设计能撑住这套机制

回看 JobSlug(title, company, source, externalID):短码只吃后两个参数,标题和公司只影响前缀。这不是巧合,而是"可救援性"的结构前提。反过来说,任何把描述、时间戳、团队名加入短码输入的"改进",都会立刻破坏这套兜底——TestJobSlugShortcodeIgnoresTitleCompany(job_slug_test.go#L47-L57)就是在守这条线。

七、完整实施清单(继承并展开)

下表完整覆盖任务文件的 12 个交付项,并补充当前的落地位置。

编号 任务 落地证据
1.1 在 internal/normalize 增加确定性 JobSlug,拼接非空标题/公司段与 8 位小写 base32 sha256 短码 job_slug.go、job_slug_test.go
2.1 新增迁移,加 jobs.public_slug TEXT NOT NULL UNIQUE 0001_init.sql#L246、#L541(历史迁移已并入基线)
2.2 UpsertJob 增加 public_slug 入参(只在 INSERT 写,不进 DO UPDATE);新增 GetJobBySlug jobs.sql#L335-L482、#L161-L164
2.3 make sqlc 后提交 internal/db,go build ./...、go vet ./... 通过 internal/platform/db
3.1 引入携带 public_slug、省略 id 的响应 DTO,保留 enrichment 透传({} 非 null)、enriched_at、enrichment_version jobview.go#L22-L30
3.2 在 ListJobs 与单条读取中完成 db.Job → DTO 映射 jobs.go#L71-L104、#L145-L150
4.1 GetJob 改用 GetJobBySlug,未知 slug 由中央处理返回 404 jobs.go#L145-L150
4.2 interactionParams 改为 slug→内部 id 解析(未知→404),user_jobs 仍按 BIGINT 写入 user_jobs.go#L43-L56、repository.go#L36-L47
4.3 路由注册改为 /jobs/:slug、/jobs/:slug/view、/jobs/:slug/apply jobs.go#L46-L69、user_jobs.go#L48-L49
5.1 Svelte SPA 全面改用 public_slug(链接、详情路由、view/apply 调用) web/src/routes/jobs/[slug]/+page.server.ts](web/src/routes/jobs/[slug]/+page.server.ts)、[web/src/lib/types.ts
4.4 GetCompany 返回的岗位也走 DTO;companyDetailResponse{Jobs <a href="https://link.gitcode.com/i/38c73503f605c0f161b0ae39cb9922ce" target="_blank">]jobResponse} + TestCompanyDetailHidesJobID [internal/api/handler/companies_test.go
6.1 go build / go vet / go test / DB 集成测试;重建卷后冒烟校验 见下一节

八、验证与冒烟检查

8.1 常规命令

go build ./...
go vet ./...
go test ./...

单元层重点跑两个包,它们覆盖了算法与序列化两条最容易回归的边界:

go test ./internal/dict/normalize/...
go test ./internal/api/handler/...

8.2 数据库集成测试

写读路径的 SQL 语义必须对真实 Postgres 验证(TestJobPublicSlug 等带 //go:build integration 标签):

go test -tags=integration ./internal/platform/db/

覆盖断言:UpsertJob 持久化调用方算好的 slug;GetJobBySlug 能换回同一行;重复入库不新增行;未知 slug 是 pgx.ErrNoRows;GetJobIDBySlug 的窄查询行为一致。

8.3 卷重建与冒烟

任务 6.1 明确要求重建数据卷再冒烟,因为该阶段没有版本化迁移执行器,NOT NULL 列加在有数据的旧卷上会被拒绝:

docker compose down -v && make up

随后逐条核验:

检查 期望
GET /api/v1/jobs/<slug> 命中 200,响应含 public_slug,不含 id
GET /api/v1/jobs/no-such-slug 404
GET /api/v1/jobs(列表) 数组元素无 id,有 public_slug
GET /api/v1/companies/<company_slug> data.jobs[] 元素同样无 id
POST /api/v1/jobs/<slug>/view(带凭证) 写入成功,幂等重复调用不报错
旧 slug(改标题前) 200 且 public_slug 为当前值(靠短码兜底)
歧义短码 404,绝不重定向到他人岗位

九、权衡与风险

风险 设计中的处置
短码碰撞导致写入失败 40 bit 熵 + title+company 前缀双重条件;UNIQUE 让残余碰撞变成一个响亮的写失败,而非静默覆盖
路由参数是 BREAKING 变更 当时唯一的调用方是同仓库 SPA,随变更一起改;无外部消费者
持久卷上的已有数据拒绝 NOT NULL 约定是重建卷(docker compose down -v && make up),因为尚无版本化迁移执行器
UpsertJob 的 slug 参数长期只有测试覆盖 接受:slug 生成器与查询各自独立测试,写路径已为第一个采集器准备好
有人"顺手"重算 slug 已用注释(DO UPDATE 缺失 + AGENTS 说明)与短码兜底双重防护;backfill-derive 必须永不写该列

其中最后一条已经超出了单纯的技术风险,成为项目级约定。AGENTS.md 里对 backfill-derive 有明确警告:Never public_slug——它是插入时铸一次的发布 URL,不能从后来被改过的标题重推导,并把事故规模与 freehire#3284 的修复方式一并记录。这是一份"设计决策 + 事故复盘 + 运维禁令"三合一的文档化范例。

十、这套方案可复用的三条经验

  1. 公开标识与内部主键应当彻底分离:用 BIGINT 做主键和外键,用 TEXT slug 做对外标识。前者保持 JOIN 性能,后者承担可枚举性与 SEO 责任,两者用一个 UNIQUE 约束和解。
  2. 确定性要选对输入集:slug 的前缀可以随标题变化,但必须有一部分只依赖不可变的去重键。freehire 用 8 位短码承担这个角色,并在事故后把它升级成了"旧链接救援"的基础设施。
  3. "铸一次"的字段要在三层同时守住:SQL 的 DO UPDATE 不写它、批量任务跳过它、AGENTS 文档写下禁令。任何一层缺失,都会在某次"顺手重算"里把已发布的 URL 全部打散。

延伸阅读

登录后查看全文
freehire