基于 freehire 实现公开求职板块:把私有 saved search 变成可分享的 /b/:slug 页面

原创2026-10-24 12:16:271,747 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

基于 freehire 实现公开求职板块:把私有 saved search 变成可分享的 /b/:slug 页面

在 freehire 这个面向求职者的开源搜索引擎中,saved search(保存的搜索)原本是"仅本人可见、按内部数字 id 寻址"的私有资产。本文以 openspec/changes/archive/2026-07-01-add-public-search-boards/proposal.md 为骨架,完整拆解该提案提出的"公开搜索板块(public search boards)"设计:如何用两个可空列、一个随机后缀 slug 和三条路由,把个人过滤器变成可分发的链接,同时保证公开读接口不泄露任何所有者身份信息。读完你将掌握这套"public-read-by-slug"改造的完整数据模型、Slug 生成算法、服务层与 HTTP 契约、前端路由落点,以及它在后续版本中为何被 job lists 取代。

导读:提案要解决的到底是什么问题

原提案的第一句话就把动机说得很清楚:今天的 saved search 是私有的、cookie 作用域的、用内部数字 id 寻址的——用户能重放自己的过滤器,却没法把链接交给别人。而"把一组精选的职位视图(例如 remote Go jobs in the EU)分享出去"是一个常见且成本很低的需求,它能把"个人便利"变成"分发入口"。

更关键的一句判断是:所需的零件已经全部就位。规范化的 query 字符串本身就是现成的可分享载荷,仓库里也早已跑着一套 job 的 public-read-by-slug 模式。因此这次变更只需从 saved search 上"拆掉两把锁":owner-only 寻址 与 auth-guarded 读取。这个"只拆两把锁"的思路贯穿了整份提案,也是它技术含量最高的地方——不新造实体、不新造子系统,只做既有模式的移植。

变更全景:五项能力变化

提案 What Changes 一节列出的五条,构成了完整需求面,这里逐条展开并标注对应的实现落点:

提案要求 语义要点 代码/接口落点
分享自己的某个 saved search,生成稳定公开 slug 可读、由 name 派生 + 短随机后缀,如 remote-go-jobs-a3f1 POST /api/v1/me/searches/:id/share
分享时接受可选 author label,空则为匿名 自由文本,存在 board 上;不触碰 users 表 请求体 {author_label?}
取消分享,清空 slug 回到私有 旧链接失效是设计意图;重新分享铸新 slug DELETE /api/v1/me/searches/:id/share
新增公开、免鉴权按 slug 读取 只返回 name、canonical query、author label,永不返回 owner id/email GET /api/v1/boards/:slug
SPA 新增公开 /b/:slug 路由 加载 board,并用存储的 query 渲染既有 jobs 列表 web/src/routes/b/[slug]

提案还补充了两个容易被忽略的产品化细节:

  • 账户区新增独立的 "Saved searches" 小节(/my/searches),入口放在 header 账户菜单里,与其它 /my/* 平级;该页支持 share/unshare、复制公开链接、重命名、删除。新建 saved search 仍然留在 "My filters" 控件里,因为当前过滤器状态只存在于那里。
  • 列出自己的 saved searches 时,要一并回报每条的共享状态(slug + author label),UI 才能显示"哪些已公开"。这一条直接改写了既有的 list 契约。

在 Capabilities 层面,提案明确"没有新增能力",而是修改 saved-searches 能力域,并且刻意声明既有私有行为(create/list/update/delete、owner 作用域、名称校验、每用户上限)保持不变。这种"扩展而非重写"的定界,是后续能安全回滚的前提。

三个关键设计决策及其被否决的替代方案

设计文档(design.md)把决策过程记录得很完整,它们是本文最有价值的部分,因为每个决策都附带了"为什么不选另一种"。

决策一:Slug 用 normalize(name) + 短随机后缀,在分享时铸一次

  • 复用 internal/normalize(当时也已用于 job/company slug)对集合名做规范化,追加 4 位小写 base36 字符,既消歧又降低可猜测性,同时 URL 仍然可读:remote-go-jobs-a3f1。
  • 唯一性由 UNIQUE 索引兜底;"罕见"的插入冲突就换后缀重试,且重试次数有界。
  • Slug 铸一次即保留:重复分享沿用旧 slug(老链接不失效);unshare 清空,之后再次分享铸新的 slug。

被否决的两个替代方案同样值得记住:纯随机不透明 token(更私密但不可读,用户选择了可读性),以及纯由 id 派生(稳定但丑陋且可枚举)。

决策二:模型上用两列挂在 saved_searches 上,而不是新建 public_boards 表

  • public_slug TEXT(带 UNIQUE 索引)+ author_label TEXT,两者皆可空。
  • 关键不变量一句话:public_slug IS NULL ⇔ 私有。一个实体、一个 query 真相来源,无需跨表同步。
  • 设计文档特别指出:Postgres 的普通 UNIQUE 允许多个 NULL,所以"部分唯一索引还是普通唯一索引"这个问题不需要纠结,普通 UNIQUE (public_slug) 足够且最简单。

被否决的方案是独立 public_boards(slug, saved_search_id, ...) 表:要么复制 query,要么被迫 join,还引入一份需要持续同步的生命周期状态,在这个体量下没有收益。

决策三:端点完全复刻既有约定

  • POST /api/v1/me/searches/:id/share(RequireAuth)→ owner 作用域;body {author_label?};返回更新后的 savedSearchResponse(此时已包含 public_slug、author_label)。
  • DELETE /api/v1/me/searches/:id/share(RequireAuth)→ owner 作用域;204。
  • GET /api/v1/boards/:slug(无鉴权)→ 公开读;只返回 {data: {name, query, author_label}},形态参照 GetJob/GetJobBySlug。
  • 错误处理不写特例:缺失或已取消分享的 slug 返回 pgx.ErrNoRows,由中央 ErrorHandler 统一映射成 404,遵循仓库既有约定(不在 handler 内二次重映射)。

数据层:两列、一个唯一索引、四条 SQL

提案的 Impact 一节给出的 DB 变更就一句话:saved_searches.public_slug TEXT UNIQUE(可空)与 saved_searches.author_label TEXT(可空),新迁移 + sqlc 重新生成。

从仓库当前的迁移文件可以读到这条变更的实际形态。基线快照 migrations/0001_init.sql 中 saved_searches 的定义已经包含这两列,并配有:

-- migrations/0001_init.sql
CREATE UNIQUE INDEX saved_searches_public_slug_idx
    ON public.saved_searches USING btree (public_slug);

而 migrations/0137_drop_saved_search_sharing.sql 又显式地把索引与两列 drop 掉,注释写明这是"分享能力退役"的迁移。从源码结构看,这两个文件记录的是不同时间点的 schema 快照,实际演进顺序应以迁移编号为准:先加列加索引,后由 0137 删除。

语义上有一条必须记住的边界:author_label 是自由文本、作者自填、可空,空值即匿名渲染;提案与设计文档都反复强调"不从 email 推导",也不新增 users.display_name 档案子系统。作者归属因此是 per-board 的、自包含的。

sqlc 查询侧当时新增了四条(见 internal/platform/db/queries/saved_searches.sql 的既有写读风格可对照):

查询名 作用域 语义
SetSavedSearchPublicSlug owner 作用域 写入 slug + author_label
ClearSavedSearchPublicSlug owner 作用域 slug → NULL,回到私有
GetPublicBoardBySlug 无 owner 条件 仅 WHERE public_slug = $1,即只读"当前处于分享态"的行
ListSavedSearches / GetSavedSearch owner 作用域 因使用 SELECT *,regen 后自动带上两列

这里的设计细节很值得借鉴:公开读的 SQL 只有 slug 一个条件,刻意不 join 用户表——"不泄露 owner"不是靠 handler 删字段,而是靠查询根本取不到 owner 信息。

Slug 生成:可读性、不可枚举性与长度上限的三角平衡

提案只说"复用 internal/normalize,追加短随机后缀,冲突有界重试"。在仓库里,这段逻辑后来被抽成了独立包 internal/dict/slugmint/slugmint.go,从它的包注释可以确认这段代码原本就住在 internal/search/savedsearch 的 board-sharing 代码里,是"搬家而非新造共享基础设施"。因此它精确反映了当年的铸 slug 规则:

const (
	// SuffixLen 是随机后缀长度:足以区分同名条目、让 slug 不易猜测,同时保持 URL 简短。
	SuffixLen = 4
	// BaseMaxLen 限制由名字派生的可读部分,避免长名字产生难以阅读的 URL。
	BaseMaxLen = 60
)

const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"

func New(name, fallbackBase string) (string, error) {
	base := normalize.Slug(name)
	if base == "" {
		base = fallbackBase
	}
	if len(base) > BaseMaxLen {
		base = strings.TrimRight(base[:BaseMaxLen], "-")
	}
	suffix, err := randomSuffix(SuffixLen)
	if err != nil {
		return "", err
	}
	return base + "-" + suffix, nil
}

// randomSuffix 从 CSPRNG 取字符,使 slug 不能按序列枚举。
func randomSuffix(n int) (string, error) {
	buf := make([]byte, n)
	if _, err := rand.Read(buf); err != nil {
		return "", err
	}
	for i, b := range buf {
		buf[i] = alphabet[int(b)%len(alphabet)]
	}
	return string(buf), nil
}

四个实现要点,正好对应四条设计约束:

  1. 后缀来自 crypto/rand 而非数学随机,注释写明目的是"不能按序列枚举"。这比 math/rand 更贴合"公开链接"这个威胁模型。
  2. base 有 60 字符上限,且截断后用 TrimRight(base, "-") 清理尾随连字符,避免出现 foo--a3f1 这类脏 URL。
  3. fallback base:名字若规范化后为空(例如全是符号),仍能得到可用 slug——job lists 时代传入的是 "list",board 时代同理需要一个兜底词。
  4. 后缀是 4 位 base36,即约 36⁴ 量级空间,配合唯一索引与有界重试即可。

base 部分的规范化由 internal/dict/normalize/slug.go 提供,其行为是:先 unidecode 转写,再转小写,把每段非字母数字折叠为单个连字符,去掉首尾连字符。文档注释给出了直观例子——"Яндекс" → iandeks,"小红书" → xiao-hong-shu。这一点对 freehire 尤其重要,因为职位与公司名大量是非拉丁字符,而 public_slug 是 URL 路径段,西里尔或 CJK 字符会破坏路由。

重试上界在 job lists 的同一套逻辑里明文写着 maxShareAttempts = 5,并与一个内部信号 sentinel 配合:

// ErrSlugTaken 是 share 时 public slug 唯一冲突。它是内部重试信号
// (Share 重新生成后缀再试),不是面向客户端的状态码。
ErrSlugTaken = errors.New("joblists: public slug already taken")

也就是说,冲突在服务层被"消化"掉,不会作为 409 漏给用户;只有重试耗尽才向上返回。这与 internal/search/savedsearch/savedsearch.go 里把每个 sentinel 明确标注映射状态码的风格一脉相承。

服务层与 HTTP 契约

服务层新增三个方法 + 一个生成器

设计文档规定 internal/savedsearch 增加:

  • Share(ctx, userID, id, authorLabel):校验并 trim label(≤60),无 slug 时铸一个,已有则保留(重复分享幂等于 slug),并写入 label;owner 作用域内找不到/非本人 → ErrNotFound。
  • Unshare(ctx, userID, id):清空 slug,owner 作用域,已是私有则幂等 no-op;非本人 → ErrNotFound。
  • GetPublicBySlug(ctx, slug):返回当前分享态 board 的 name/query/author_label;未知或未分享 → ErrNotFound(或直接 pgx.ErrNoRows)。

这套方法与既有 Service 的写法完全一致:校验在 service、持久化与 Postgres 条件到 sentinel 的映射在 repository。可以对照现有的 internal/search/savedsearch/repository.go:

// fromRow 把生成的 db 行映射为包内领域类型,丢弃用例不需要的 owner 列。
func fromRow(row db.SavedSearch) SavedSearch {
	return SavedSearch{
		ID:                 row.ID,
		Name:               row.Name,
		Query:              row.Query,
		DerivedFromProfile: row.DerivedFromProfile,
		CreatedAt:          pgconv.TimePtr(row.CreatedAt),
		UpdatedAt:          pgconv.TimePtr(row.UpdatedAt),
	}
}

注意领域类型 SavedSearch 的注释明确写着"内部 owner 列 user_id 被丢弃——它从不上线,作用域在 SQL 里强制"。board 特性正好复用这条既有不变量:公开读取不到 user_id,是因为领域层压根没有这个字段。

三个端点一览

方法 路径 鉴权 归属校验 请求体 成功响应
POST /api/v1/me/searches/:id/share RequireAuth(cookie-only) 是 {"author_label": "..."}(可省) 200 + 更新后的 saved search
DELETE /api/v1/me/searches/:id/share RequireAuth(cookie-only) 是 无 204
GET /api/v1/boards/:slug 无 否 无 200 + {data:{name,query,author_label}}

分享成功的响应形如(字段取自 spec 的场景定义):

{
  "data": {
    "id": 42,
    "name": "Remote Go Jobs",
    "query": "q=go&remote=1&region=eu",
    "public_slug": "remote-go-jobs-a3f1",
    "author_label": "alex",
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:20:00Z"
  }
}

公开读的响应则刻意"瘦"到极致——只有三个字段:

{ "data": { "name": "Remote Go Jobs", "query": "q=go&remote=1&region=eu", "author_label": "alex" } }

注意 public_slug 在私有态下的线缆表示:设计文档规定它是 string,NULL 时为空字符串。这样前端只需判空即可渲染共享态,不必处理 null 分支——与 job lists 后来采用的"空 PublicSlug 即未分享"是同一个约定。

cookie-only 的边界为什么要保持

提案强调两个写端点"both RequireAuth, cookie-only, like the rest of /me/searches"。仓库里这条约定写在 handler 注册处(internal/api/handler/me_searches.go):

// Saved searches 是 cookie-only(RequireAuth),与 API key 管理一致:
// 它们是浏览器便利功能("My filters" 选择器),不是脚本原语。
// 每个操作都是 owner 作用域;不属于调用者的 id 一律 404。
api.Get("/me/searches", mw.cookie, h.ListSavedSearches)
api.Post("/me/searches", mw.cookie, h.CreateSavedSearch)
api.Patch("/me/searches/:id", mw.cookie, h.UpdateSavedSearch)
api.Delete("/me/searches/:id", mw.cookie, h.DeleteSavedSearch)

share/unshare 就插在这组里,用同一个 mw.cookie。契约上的含义是:不能拿 API key 脚本化发布 board。这个取舍是刻意的——saved search 被定义为浏览器便利功能,而公开读那一侧才需要无鉴权。

完整行为矩阵:spec 里的六个场景

规范文件 specs/saved-searches/spec.md 用"WHEN/THEN"把边界钉死了,这实际上就是一份可执行的验收清单:

场景 触发条件 期望结果
分享私有集合 本人、无 slug 200,生成 name 派生 + 随机后缀的 slug
带 author label 分享 非空 label 存储 trim 后的值并回显
重复分享 已有 slug 保留原 slug,仅更新 label,200
label 超长 trim 后 > 60 字符 400,且不修改集合
分享他人集合 id 属他人 404,且不铸 slug
未登录分享 无有效 session cookie 401,无副作用
取消分享 本人、已有 slug 清空 slug,204,链接随即不可达
取消分享未分享的 本人、无 slug 204(幂等 no-op)
取消分享他人集合 id 属他人 404,目标不变
公开读取 当前分享态 200,仅 name/query/author_label
未知或已取消 slug 不存在/已清空 404
匿名 board 无 author label author_label 为空串,匿名渲染

两处最容易被实现者做错的地方,spec 都单独写了:

  1. "label 超长"要求"不修改集合"——意味着校验必须发生在写入之前,不能"先写 slug 再报错"。
  2. "取消分享未分享的集合"返回 204 而不是 404——幂等 no-op,与"他人集合 → 404"形成对照。两者的区别是"目标存在但不属于你"与"目标存在且就是你的,只是状态已经是目标状态"。

前端落点:一个公开路由 + 一个账户小节 + 一处过滤器控件

设计文档对前端结构的判断非常具体,而且基于一次真实的代码勘察:账户区 /my/* 是扁平的兄弟页面集合(/my/jobs、/my/profiles、/my/notifications、/my/api-keys、/my/submissions),它们各自从 HeaderMenu.svelte 的 menuItems 数组里挂一个入口,没有共享的 /my/+layout。因此新增 "Saved searches" 的方式就是:加一个 web/src/routes/my/searches/+page.svelte,再往 menuItems 里加一行。不要臆造并不存在的布局层。

三处 UI 的职责切分很清晰:

  • /b/:slug 公开页:取 GET /api/v1/boards/:slug,渲染 board 名与作者 label,然后用 board 的 query 复用既有的 query→filter 解析(也就是"应用一个 saved search"流程已经在用的那段解析),把职位列表刷出来。未知 slug 渲染 404 状态,而不是"空职位列表"——spec 明确要求区分这两者。
  • /my/searches 账户页:复用既有 savedSearches store 取列表,加上新的 share/unshare 客户端调用;支持重命名、删除、已分享时复制 /b/:slug;匿名访问则提示登录。不支持新建——新建留在过滤器控件里,因为只有那里持有当前过滤器态。
  • My filters 控件:在原 create/apply/update/delete 之外增加 share/unshare,分享成功后给出可复制的 /b/:slug。共享态一律从 public_slug 字段读取。

api.ts 侧新增两个函数,命名与既有 saved-search 客户端保持一致:shareSavedSearch(id, authorLabel)(返回带 slug 的更新后集合)与 unshareSavedSearch(id)。设计文档还提到 TS 契约在适用处通过 cmd/gen-contracts 重新生成。

值得一提的是,后来 job lists 的前端完全延续了这个模式,只是把"二次执行 query"换成了"一次拿到物化结果",其公开页的服务端 load 注释就写着这个差异:

// 一个公开 job list:按 slug 加载并直接渲染它的职位——与共享 board(一次实时
// query)不同,公开读已经返回物化好的集合,所以不需要第二次调用去重跑查询。
// 未知或未分享的 slug 是 404 → 应用的 +error 页面渲染 not-found 状态。
// 公开读:不转发 cookie。
export const load: PageServerLoad = async ({ params, fetch }) => { ... }

见 web/src/routes/l/[slug]/+page.server.ts。"公开读不转发 cookie"这一行注释,正是整个特性隐私承诺在代码里的最后一道保险。

隐私模型:哪些是保证,哪些只是缓解

提案的 Privacy note 写得相当坦率,值得原样理解后再落到工程判断上:

  • 可读 slug 被设计成"部分可猜"。这是在"URL 友好"与"不可猜测"之间明确选了前者。缓解手段有两个:后缀不是纯名字派生、以及"只有显式分享期间才可达"这条不变量。
  • 不泄露任何 owner PII。即使猜中,拿到的也只有 name/query/author_label——三者全部由作者自己撰写。user id、email 都不在公开响应里(Tasks 5.2 的端到端断言正是"user_id/id/email 均不存在")。
  • author label 是自选的轻量 PII。可选、作者自填、为空即匿名,且永不从 email 推导。
  • 明确不做的事:没有 board 发现页、没有他人 board 的列表/搜索、没有 view 分析、没有"分享"之外的访问控制层。

把它写成一句话:这是"public-by-link",不是"secret-by-link"。如果你的场景需要真正的不可枚举保证或访问控制,这个设计不适用——提案自己也这么写。

验证与上线:任务清单给出的顺序

tasks.md 把工作拆成五组并全部勾选,其顺序本身就是一份可复用的交付路径:

  1. Schema & 生成代码:加迁移(两列 + public_slug 唯一索引)→ 加四条 sqlc 查询 → make sqlc 确认 internal/db 重新生成且 build 通过。
  2. 服务层:先做 slug 生成(单测冲突重试与可读 slug 形状),再 Share(单测:分享、重分享保 slug、label 超长、非本人),再 Unshare(含幂等),最后 GetPublicBySlug(found / not-found)。
  3. HTTP 层:扩展 savedSearchResponse 加两字段 → 加两个写 handler(含 share/unshare/not-owned/401/超长 label 的集成测试)→ 加公开 GetBoard(读 + 404)→ 在 handler.go 注册三条路由(两条在 /me/searches 鉴权组,一条公开、与 /jobs/:slug 并列)。
  4. Web:契约与 SavedSearch 类型加字段 + board 线缆类型 → /b/[slug] → /my/searches + 菜单入口 → 过滤器控件 share/unshare。
  5. 验证:go build ./... && go vet ./...、go test ./...、带 integration tag 的 handler/db 测试、web svelte-check 零错误零告警、生产 SSR npm run build。

第 5.2 条尤其值得抄作业:它用一个真 Postgres 上的端到端测试串起完整生命周期——

create → share → 匿名打开 /api/v1/boards/:slug(断言无 owner PII:user_id/id/email 均不存在)→ 重复 share 保持 slug → unshare → slug 变 404 → 未知 slug 也 404。

同时任务清单诚实地标注了一个残余项:/my/searches 与 /b/:slug 的浏览器走查尚未在此执行,建议部署前在种子化的 Docker 栈上做一次冒烟。这种"哪些验证过、哪些没验证"的分野,是技术文档可信度的来源。

设计文档另有一条与仓库现状相关的提醒:当时仓库还没有版本化的 migration runner(已知接缝),因此采用了"先手工在生产执行两条可空 ADD COLUMN,再发代码"的部署约定。两条语句都是附加且可空的,对旧代码完全兼容,所以这个顺序是安全的。回滚路径同样明确:unshare 本身可逆;要彻底退出,drop 两列即可,私有 saved search 从不填这两列,因此不丢数据。

后续演进:这套设计最终被 job lists 取代

只读提案会误以为 /b/:slug 永远存在,但仓库现状给出了更完整的答案。迁移 0137_drop_saved_search_sharing.sql 的注释直接说明:

公开 saved-search 分享("boards",GET /api/v1/boards/:slug 与 web /b/:slug)已退役,让位给 job lists(0135/0136)——后者分享的是一组具体职位,而不是一条实时查询。已有的公开 board 链接会直接停止解析;没有自动化迁移进 job list,因为一条查询不是一组职位。

替代方案的动机写在 replace-board-sharing-with-collections 提案 里,逻辑很干净:board 让用户发布"一条查询的未鉴权重放",但这个用法很少见,并且把两件事混在同一个 slug 下——"我喜欢的过滤条件"与"我想让别人看到的具体职位"。后者才是人们真正想分享的东西;而 query replay 会随目录变化而漂移。

对照实现可以清楚看到哪些设计被继承、哪些被替换:

维度 public search boards(已退役) job lists(现行)
分享对象 一条 live query 一组固定职位(job_lists + job_list_items)
数据模型 saved_searches 上加两列 新表 + 多对多关联表(0135、0136)
作者归属 独立 author_label 复用列表自身的 description("再加一个归属字段是冗余的")
Slug 规则 转写名 + 4 位随机后缀,冲突有界重试 完全一致,生成本身被抽到 internal/dict/slugmint
写端点 POST/DELETE /me/searches/:id/share POST/DELETE /me/lists/:id/share(job_lists.go)
公开读 GET /api/v1/boards/:slug GET /api/v1/lists/:slug
公开页面 /b/[slug] /l/[slug]

现役实现的公开读 handler 注释几乎就是当年 GetBoard 的翻版:

// GetPublicList 按公开 slug 提供共享 job list——未鉴权、无 owner 作用域。
// 未知或未分享的 slug 是 404(由 job-list not-found sentinel 映射而来)。
func (h *jobListHandlers) GetPublicList(c *fiber.Ctx) error {
	list, err := h.joblists.GetPublicList(c.Context(), c.Params("slug"))
	if err != nil {
		return jobListError(err)
	}
	return c.JSON(fiber.Map{"data": toPublicJobListResponse(list)})
}

而 internal/application/joblists/share.go 里的 Share/Unshare 与当年 board 的语义逐字对应——重分享保留旧 slug("已分享过的链接继续有效")、冲突换后缀重试、unshare 幂等。这本身就是提案设计质量的最好证明:换掉业务对象后,分享机制一行逻辑都不用改。

同样地,/my/searches 这个账户小节也没有消失,而是被重定向进通知中心(web/src/routes/my/searches/+page.ts):

// Saved-search 提醒管理已并入通知中心的一个 tab。
// 用 308 以保留书签和外部入链。
export function load() {
  redirect(308, '/my/notifications/searches');
}

用 308 而非 301/302,就是为了让收藏夹和历史外链继续有效——这与"unshare 故意断链、重分享铸新链"的态度形成了有趣的对照:对用户主动撤销的链接,断得干脆;对系统自身演进造成的链接变化,接得稳当。

复用到自己项目时的检查清单

把这份提案抽象成可迁移的工程模式,落地上前建议逐项确认:

  1. 确认"零件已就位":你要分享的载荷是否已有规范化的字符串表示?仓库是否已有 public-read-by-slug 的先例可照抄?两者都成立时,这个改造才真的只是"拆两把锁"。
  2. 用可空唯一列表达状态,别建第二张表:public_slug IS NULL ⇔ 私有 省掉了一次 join 和一份同步生命周期。记住 Postgres 的 UNIQUE 允许多个 NULL。
  3. slug = 转写基名 + CSPRNG 短后缀:基名要限长并清理尾随连字符,后缀用 crypto/rand,冲突要有界重试,且把冲突做成内部信号而非客户端状态码。
  4. 重分享幂等、取消分享断链:这是两条独立语义,测试要分别覆盖,并额外覆盖"取消未分享的集合返回 204"与"操作他人集合返回 404"。
  5. 公开查询里不要出现 owner 条件之外的用户数据:靠 SQL 选择性返回字段,而不是靠 handler 事后删除;再用一条端到端断言把"响应里没有 user_id/email"钉死。
  6. 校验先于写入:label 超长必须"400 且不修改",否则会留下半分享状态。
  7. 公开读不转发 cookie:SSR 侧显式使用不带凭据的客户端,避免把用户身份带进公开页面。
  8. 想清楚"可读"与"不可猜"的取舍并写在文档里:这是 public-by-link,不是 secret-by-link;如果业务要求后者,本模式不适用。
  9. 给自己留明确的退役路径:本特性的退役证明,只要把"分享机制"与"分享对象"解耦,换业务对象时机制可原样复用;反之则会被业务细节焊死。

以上结论均可回溯到仓库内的提案、设计、任务、规范文件,以及 internal/search/savedsearch、internal/dict/slugmint、internal/application/joblists 与相关迁移/前端路由的源码。若要把这套模式迁移到自己的服务,建议先读 proposal.md 把握边界,再用 design.md 对照每个被否决的替代方案,最后用 spec.md 的 WHEN/THEN 逐条写测试。

登录后查看全文
freehire