基于 freehire 实现公开求职板块:把私有 saved search 变成可分享的 /b/:slug 页面
基于 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
}
四个实现要点,正好对应四条设计约束:
- 后缀来自
crypto/rand而非数学随机,注释写明目的是"不能按序列枚举"。这比math/rand更贴合"公开链接"这个威胁模型。 - base 有 60 字符上限,且截断后用
TrimRight(base, "-")清理尾随连字符,避免出现foo--a3f1这类脏 URL。 - fallback base:名字若规范化后为空(例如全是符号),仍能得到可用 slug——job lists 时代传入的是
"list",board 时代同理需要一个兜底词。 - 后缀是 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®ion=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®ion=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 都单独写了:
- "label 超长"要求"不修改集合"——意味着校验必须发生在写入之前,不能"先写 slug 再报错"。
- "取消分享未分享的集合"返回 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账户页:复用既有savedSearchesstore 取列表,加上新的 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 把工作拆成五组并全部勾选,其顺序本身就是一份可复用的交付路径:
- Schema & 生成代码:加迁移(两列 +
public_slug唯一索引)→ 加四条 sqlc 查询 →make sqlc确认internal/db重新生成且 build 通过。 - 服务层:先做 slug 生成(单测冲突重试与可读 slug 形状),再
Share(单测:分享、重分享保 slug、label 超长、非本人),再Unshare(含幂等),最后GetPublicBySlug(found / not-found)。 - HTTP 层:扩展
savedSearchResponse加两字段 → 加两个写 handler(含 share/unshare/not-owned/401/超长 label 的集成测试)→ 加公开GetBoard(读 + 404)→ 在handler.go注册三条路由(两条在/me/searches鉴权组,一条公开、与/jobs/:slug并列)。 - Web:契约与
SavedSearch类型加字段 + board 线缆类型 →/b/[slug]→/my/searches+ 菜单入口 → 过滤器控件 share/unshare。 - 验证:
go build ./... && go vet ./...、go test ./...、带 integration tag 的 handler/db 测试、websvelte-check零错误零告警、生产 SSRnpm run build。
第 5.2 条尤其值得抄作业:它用一个真 Postgres 上的端到端测试串起完整生命周期——
create → share → 匿名打开
/api/v1/boards/:slug(断言无 owner PII:user_id/id/
同时任务清单诚实地标注了一个残余项:/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 故意断链、重分享铸新链"的态度形成了有趣的对照:对用户主动撤销的链接,断得干脆;对系统自身演进造成的链接变化,接得稳当。
复用到自己项目时的检查清单
把这份提案抽象成可迁移的工程模式,落地上前建议逐项确认:
- 确认"零件已就位":你要分享的载荷是否已有规范化的字符串表示?仓库是否已有 public-read-by-slug 的先例可照抄?两者都成立时,这个改造才真的只是"拆两把锁"。
- 用可空唯一列表达状态,别建第二张表:
public_slug IS NULL ⇔ 私有省掉了一次 join 和一份同步生命周期。记住 Postgres 的UNIQUE允许多个 NULL。 - slug = 转写基名 + CSPRNG 短后缀:基名要限长并清理尾随连字符,后缀用
crypto/rand,冲突要有界重试,且把冲突做成内部信号而非客户端状态码。 - 重分享幂等、取消分享断链:这是两条独立语义,测试要分别覆盖,并额外覆盖"取消未分享的集合返回 204"与"操作他人集合返回 404"。
- 公开查询里不要出现 owner 条件之外的用户数据:靠 SQL 选择性返回字段,而不是靠 handler 事后删除;再用一条端到端断言把"响应里没有 user_id/email"钉死。
- 校验先于写入:label 超长必须"400 且不修改",否则会留下半分享状态。
- 公开读不转发 cookie:SSR 侧显式使用不带凭据的客户端,避免把用户身份带进公开页面。
- 想清楚"可读"与"不可猜"的取舍并写在文档里:这是 public-by-link,不是 secret-by-link;如果业务要求后者,本模式不适用。
- 给自己留明确的退役路径:本特性的退役证明,只要把"分享机制"与"分享对象"解耦,换业务对象时机制可原样复用;反之则会被业务细节焊死。
以上结论均可回溯到仓库内的提案、设计、任务、规范文件,以及 internal/search/savedsearch、internal/dict/slugmint、internal/application/joblists 与相关迁移/前端路由的源码。若要把这套模式迁移到自己的服务,建议先读 proposal.md 把握边界,再用 design.md 对照每个被否决的替代方案,最后用 spec.md 的 WHEN/THEN 逐条写测试。