freehire 公开搜索看板(Public Search Boards)规格解析:把私有保存搜索变成可分享链接
freehire 公开搜索看板(Public Search Boards)规格解析:把私有保存搜索变成可分享链接
本文以 freehire 中归档的变更规格 openspec/changes/archive/2026-07-01-add-public-search-boards/specs/saved-searches/spec.md 为主线,逐条拆解"把一条私有 saved search 发布成公开看板"这一能力的接口契约、slug 铸造规则、权限与隐私边界,以及 Web 端三条触点(公开页、账户区、筛选面板)的职责划分。读完后你将掌握:一套"私有实体 + 可空 public_slug 开关"的分享模式如何在既有的 owner-scoped 资源上自然生长出来,以及它为何在后续重构中被 job lists 取代——这本身是一份关于分享语义设计的完整案例。
一、需求来源:为什么要把"我的筛选"变成链接
保存搜索(saved search)在 freehire 里是"命名后的筛选快照":saved_searches 表里存 name 与 query,其中 query 就是搜索页 URL 与 GET /jobs/search 共用的规范查询串。它天生私有、只按内部数字 id 寻址,用户能重放自己的筛选,却无法把"欧盟远程 Go 岗位"这样一份策展视图递给别人。
变更提案把动机写得非常直接:分享一份策展视图是低频但合理的诉求,而"把个人便利变成分发入口"所需的所有原料都已存在——query 本身就是一份可分享的载荷,仓库里也已经跑着一套"公开按 slug 读取"的模式(jobs.public_slug + GetJobBySlug + 无鉴权的 GET /jobs/:slug)。因此这次变更要做的事情极其克制:只从 saved search 上卸下两把锁——owner-only 寻址与鉴权读取保护;其余私有行为(创建/列表/更新/删除、owner 作用域、名称校验、每人配额)一律不动。
这也解释了规格的组织方式:整个文档分为 ADDED(新增 5 条需求)与 MODIFIED(改写 1 条已有需求)两部分,而不是重写整个 saved-searches 能力。
二、核心概念:slug 即开关,NULL 即私有
规格没有引入"公开看板"这张新表,而是在原有行上增加"是否已发布"的状态:
| 决策点 | 规格中的选择 | 备选方案与取舍 |
|---|---|---|
| 发布状态载体 | saved_searches.public_slug 可空列,NULL 即私有 |
独立 public_boards 表会复制 query 或强制 join,并新增一份需要同步的生命周期 |
| 作者归属 | 板级可选 author_label 自由文本(trim 后 1–60 字符) |
不新建 users.display_name 画像子系统;空值即匿名渲染 |
| slug 形态 | normalize(name) + 短随机后缀,如 remote-go-jobs-a3f1 |
拒绝纯随机不可猜 token(更私密但不好看);拒绝纯 id 派生(稳定但难看且可枚举) |
| 撤销语义 | 取消分享即清空 slug,旧链接立刻失效;再次分享铸新 slug | 明确不接受"复活旧链接",撤销就要真的断链 |
规格对可空列的表述很精确:public_slug IS NULL ⇔ 私有;而 Postgres 的普通 UNIQUE 索引天然容忍多个 NULL,因此一条最简的 UNIQUE (public_slug) 就够用,不需要额外的 partial index 条件。
需要说明仓库的当前状态,以免读者误判:这个特性已经被完整实现过,随后又在 0137_drop_saved_search_sharing.sql 中被移除——该迁移删掉了 saved_searches_public_slug_idx 以及 public_slug、author_label 两列,理由是"公开保存搜索分享(/b/:slug 看板)被 job_lists 取代"。所以后文出现的列定义与 handler 代码,都属于"曾经落地过的事实",当前仓库的快照里能在 0001_init.sql 的建表语句中看到它们的原貌。
三、接口契约:三条路由与状态码表
规格把写入与读取彻底分开,写入全部走 cookie-only 的鉴权路由,读取则完全匿名:
| 方法 | 路径 | 鉴权 | 成功状态 | 说明 |
|---|---|---|---|---|
POST |
/api/v1/me/searches/:id/share |
需要会话(RequireAuth) |
200 |
返回更新后的 savedSearchResponse,含 public_slug 与 author_label |
DELETE |
/api/v1/me/searches/:id/share |
需要会话 | 204 |
清空 slug;已私有则为幂等 no-op |
GET |
/api/v1/boards/:slug |
无 | 200 |
只返回 {name, query, author_label} |
分享(POST)的语义细节
规格对此有四个独立场景,值得逐条对照实现:
- 首次分享:为一个尚无 slug 的自有集合生成 slug 并落库,响应体是完整的 saved search 结构(
{"data": {id, name, query, public_slug, author_label, ...}})。 - 带作者标签分享:请求体里的
author_label非空时,保存 trim 后的值并回显。 - 重复分享保持 slug:对已分享集合再次调用,保留原 slug,只更新作者标签。这条是保证"已经发出去的链接不会因为用户改了署名而失效"。
- 超长标签拒绝:trim 后超过 60 字符返回
400,并且不改动集合的任何字段——校验必须发生在写库之前。
取消分享(DELETE)的语义细节
- 清空 slug,看板按 slug 不可达,返回
204。 - 对未分享的集合调用同样返回
204,即幂等。 - 对他人集合调用返回
404,且目标行不变。
公开读取(GET)的字段白名单
GET /api/v1/boards/:slug 的响应被严格限定为 {"data": {name, query, author_label}}。规格用 MUST NOT 措辞强调:owner 的身份信息(user id、email)不得出现。slug 不存在、或曾经存在但 slug 已被清空,一律 404;这一点在实现上依赖仓库既有约定——查询无行时返回 pgx.ErrNoRows,由全局错误处理映射成 404,handler 不做二次改写。
为对照"这份需求当初是怎么落到 Go 代码里的",可以看同构的 saved search 响应结构与错误映射:internal/api/handler/me_searches.go 中 savedSearchResponse 显式省略 user_id,savedSearchError 把 ErrInvalidName 映射 400、ErrDuplicateName/ErrCapExceeded 映射 409、ErrNotFound 映射 404。规格里 share 端点"复用 savedSearchError 映射哨兵错误"的做法,正是延续了这条约定,也意味着"超长 author_label"这类新错误必须补进同一张映射表,否则会被误报成 500。
四、slug 的铸造算法:可读、可辨、可重试
规格对 slug 的定义是"可读的名称派生 + 短随机后缀",并给出唯一性由 UNIQUE 索引兜底、冲突时"换后缀有界重试"。这部分逻辑后来被抽成独立的铸造工具 internal/dict/slugmint/slugmint.go,其注释明确写着它"从 internal/search/savedsearch 的看板分享代码迁移而来",因此可以拿它当作该规格参数的最佳佐证:
SuffixLen = 4:后缀长度 4,足以区分同名条目、让 slug 不那么容易被穷举,同时保持 URL 短小。BaseMaxLen = 60:名称派生的可读部分上限 60,超长时截断并去掉尾部的-,避免冗长 URL。- 字符集
abcdefghijklmnopqrstuvwxyz0123456789:小写字母+数字,URL 安全且与转写后的基座视觉一致。 randomSuffix使用crypto/rand而非math/rand:注释写得很直白——"用 CSPRNG,slug 就不再能按序列枚举"。- 名称为空(例如全是符号导致转写为空)时回退到
fallbackBase:在 job lists 版本里这个回退值是"list"。
切割基座时用的是 strings.TrimRight(base[:BaseMaxLen], "-"):先按字节截断再清理尾部连字符,避免生成 remote-go- 这样的悬空分隔符——这是一个容易在小工具里漏掉的边界。
重试策略在 job lists 的 internal/application/joblists/share.go 里可以看到完整形态,逻辑与规格同构:先读集合(缺失或非本人 → ErrNotFound),若已有 slug 则直接复用;否则循环铸造,遇到 ErrSlugTaken(唯一约束冲突)就换一个后缀重试,maxShareAttempts = 5 次后返回错误。ErrSlugTaken 被明确标注为"内部重试信号,不是面向客户端的状态码",所以它不出现在 HTTP 错误映射里。
一个必须接受的权衡
设计文档把风险写得很坦白:可读 slug 天然部分可猜、可枚举。缓解手段有三层——后缀是随机而非名称派生、slug 只在显式分享期间可达、即使猜中也只会拿到 name/query/author_label(全部由作者自己撰写)。这是一个"以 URL 友好换一点不可猜性"的显式取舍,而不是遗漏。
五、公开看板页 /b/:slug
规格要求 Web 应用提供一条无需登录的公开路由 /b/:slug:加载看板,把其存储的 query 应用到 jobs 列表上渲染,展示看板名与(存在时的)作者标签;未知 slug 必须渲染"未找到"状态,而不是一个空列表。
这里的关键设计是"零新增渲染路径":看板页并不实现一套新的检索逻辑,它复用"应用一条保存搜索"时已有的 query → 筛选条件解析,把 query 塞进既有的 jobs 列表组件。因此公开页面的复杂度几乎全部转移到"如何把 slug 变成一次查询"上,而不是"如何再写一个搜索页"。
同一模式在替代者身上的实现可以直接对照:web/src/routes/l/[slug]/+page.server.ts 在服务端 load 中调用公开读取客户端,捕获 ApiError 且 status === 404 时 throw error(404, ...),从而落到应用统一错误页;注释还点出了看板与 job list 的一个本质差异——看板的公开读只返回查询串,需要第二次请求重跑查询;而 job list 的公开读直接返回物化好的作业集合,一次调用即可。
可以顺带对比同一页面在求职者眼中的呈现:web/src/routes/l/[slug]/+page.svelte 用 Seo 设置 robots="noindex"(分享链接不应进入搜索发现),标题为"列表名 — freehire",正文只渲染名称、描述、条数与作业行列表。这套"公开但不可索引"的姿态,同样适用于规格里 /b/:slug 的定位。
六、账户区 /my/searches 与筛选面板的双触点
规格把"管理"和"创建"刻意拆到两个地方:
- 创建留在筛选器的 "My filters" 控件里——因为"当前筛选"只在那里存在;
- 管理新增为账户区独立分区
/my/searches,可从头部账户菜单进入,与其他/my/*并列。
/my/searches 的职责被列举得很具体:列出已保存搜索;对每条提供分享(可填作者标签)、取消分享、在已分享时复制 /b/:slug 链接、重命名、删除;未登录访客看到登录提示而不是列表。规格还特意声明"该分区不负责创建",避免两个入口产出同一实体。
设计文档解释了这种扁平化的原因:/my/* 下并没有共享的 +layout,每个页面都是兄弟页面,靠 HeaderMenu.svelte 的 menuItems 数组登记。所以"新增一个账户分区"的标准做法就是"新增一个路由文件 + 往数组里加一项",无需改动布局。
第二个触点是筛选面板:规格要求 "My filters" 控件在既有 create/apply/update/delete 之上,再提供 share/unshare 以及已分享时的公开链接。两个触点共享状态来源——都从列表项的 public_slug 判断是否已分享,并调用同一组 API 客户端方法。
这条规格在实现上最容易被实现者忽略的一点是"列表接口必须回传分享状态"。因此 MODIFIED 部分改写了"List saved searches"需求:GET /api/v1/me/searches 返回的每一项都要带 public_slug(私有时为空字符串而非 null)与 author_label,排序仍为 updated_at 倒序。把可空列在线上形态统一压成空字符串,能让前端只写一次 if (slug) 判断,而不用区分 null 与 ""。
值得补充一个仓库事实:这条账户区的路由后来还经历过一次迁移——web/src/routes/my/searches/+page.ts 现在只做 redirect(308, '/my/notifications/searches'),保存搜索的告警管理被并入通知中心的一个标签页。规格里"独立账户分区"的形态因此也成为历史;这提醒我们读归档 spec 时要区分"当时的需求"与"当前的实现"。
七、鉴权与所有权:用 404 而不是 403
规格在三个需求里反复使用同一条规则:非本人集合一律 404,而不是 403。这不是偷懒,而是避免"存在性泄露"——若返回 403,攻击者就能通过状态码差异判断某个 id 是否存在。同一套 owner-scoped 思路在 Go 侧体现为 SQL 里始终带 user_id 条件,例如 saved search 的取单条查询:
-- name: GetSavedSearch :one
SELECT * FROM saved_searches
WHERE id = $1 AND user_id = $2;
见 internal/platform/db/queries/saved_searches.sql。分享与取消分享的更新语句同样以 (id, user_id) 为条件,"没有匹配行"就被仓储层映射为 ErrNotFound,再由 handler 变成 404。这种"作用域下沉到 SQL"的做法,比在 handler 里先查再判断更不容易漏。
未鉴权请求则统一 401 且不产生任何变更——规格对 share 端点专门写了这条场景,也与 /me/searches 其余端点"cookie-only、非脚本原语"的定位一致。
八、验证方式:一条端到端用例收口
任务清单 5.1 要求 go build ./... && go vet ./...、go test ./... 以及带 integration build tag 的 handler/db 测试通过,前端 svelte-check 零错误零告警、生产 SSR 构建成功;5.2 则用 TestSavedSearchBoardsEndToEnd 在真实 Postgres 上串起完整生命周期:
create → share → 匿名 GET /api/v1/boards/:slug
→ re-share(slug 不变)
→ unshare → slug 变 404
→ 未知 slug 变 404
其中"匿名读取"这一步额外断言响应里不存在 user_id / id / email 等 owner 字段——把隐私要求写成可执行的断言,而不是只写在文档里的口号。任务清单也诚实标注了残余项:/my/searches 与 /b/:slug 的浏览器走查未在该变更内执行,只建议部署前补一次冒烟。
九、退场原因:查询会漂移,短名单不会
规格的生命周期不长。在 openspec/changes/archive/2026-09-08-replace-board-sharing-with-collections/proposal.md 中,退役理由是"使用量小"与"一个 slug 承担了两种语义":
- "我喜欢的筛选项"(一条活查询);
- "我想让别人看的那几个岗位"(一份人工短名单)。
后者才是人们真正想分享的东西,而查询重放会随目录变化而漂移——同一条链接今天展示 40 个岗位,下周可能只剩 12 个,作者无法对它负责。取而代之的 job lists 分享的是一组固定岗位。
对照表如下,便于理解"分享什么"这个决策如何牵动整条实现链:
| 维度 | 公开搜索看板(已退役) | Job lists(替代实现) |
|---|---|---|
| 分享内容 | 一条 query,读取时重跑 |
一组具体 job_id |
| 存储 | saved_searches.public_slug / author_label |
job_lists.public_slug,作者信息由 description 承担 |
| 公开读 | GET /api/v1/boards/:slug → {name, query, author_label} |
GET /api/v1/lists/:slug → {name, description, jobs[]} |
| 公开页 | /b/:slug(再发一次搜索) |
/l/:slug(直接渲染物化集合) |
| 写入接口 | POST/DELETE /me/searches/:id/share |
POST/DELETE /me/lists/:id/share |
| 迁移路径 | 无自动迁移:查询不是岗位集合,旧链接直接 404 | — |
数据结构上,job lists 用两张表承接:0135_job_lists.sql 定义 job_lists(名称 1–100、描述 ≤2000、UNIQUE (user_id, name)、public_slug 上的普通唯一索引容纳大量 NULL),0136_job_list_items.sql 定义多对多成员表(PRIMARY KEY (list_id, job_id),两端 FK 均 ON DELETE CASCADE,并按 (list_id, added_at DESC) 建索引支撑"新加的在前"的公开读)。一个细节值得注意:job lists 没有 author_label 列,迁移注释给出的理由是"共享列表本身就带自由文本 description,再加一个归属字段是冗余"。
服务层也随之收敛:internal/application/joblists/joblists.go 把约束集中成常量——每人最多 50 个列表、单表最多 200 个岗位、slug 重试 5 次;其中 maxJobsPerList = 200 的注释直接写明动机之一:公开、无鉴权的读取会渲染每个岗位的摘要,必须有上界才能保证单请求成本可预期。这条约束在看板时代是不需要的(查询天然有分页),换成"物化集合"后才浮现出来——这正是分享语义变化带来的连锁影响。
十、可复用的设计要点
若你要在自己的系统里复刻这套"把私有资源变成公开链接"的模式,这份规格提供了几条可直接照抄的经验:
- 用一个可空唯一列表达发布状态,而不是新建关联表。
NULL语义单一(未发布),普通UNIQUE天然放行多行NULL,撤销只是SET public_slug = NULL。 - slug 铸造与业务解耦:截断基座、清理尾连字符、CSPRNG 后缀、有界重试四件事打包成一个纯函数工具,分享逻辑只负责"读 → 铸 → 落库 → 冲突重试"。
- 幂等优先:重复分享保留旧 slug(链接稳定),取消一个本来就没分享的集合返回
204(重试安全)。 - 校验前置:作者标签超长必须在写库前拒绝,否则会留下"返回 400 但数据已改"的半成品状态。
- 公开响应走字段白名单:不要复用内部响应结构再删字段,而是定义一个只含
name/query/author_label的新类型,让"不泄露 owner"成为类型层面的保证,并在端到端测试中断言这些字段确实不存在。 - 所有权失败统一 404:既防存在性泄露,也让 SQL 层可以只写一条带
user_id条件的语句。 - 先想清楚分享的是"查询"还是"集合":前者的链接会随数据漂移,后者的成本与容量可控。freehire 最终选择了后者——这个选择本身就值得在动手写 slug 之前先做决定。
相关文件索引
- 规格原文:openspec/changes/archive/2026-07-01-add-public-search-boards/specs/saved-searches/spec.md
- 变更动机与影响面:proposal.md
- 设计决策与权衡:design.md
- 实施清单与验收:tasks.md
- 特性退役:0137_drop_saved_search_sharing.sql、替代变更提案
- 替代实现:job_lists 迁移、成员表迁移、joblists 服务、分享逻辑、HTTP 路由与响应
- 共用铸造工具:internal/dict/slugmint/slugmint.go
- 保存搜索基线:服务层校验、sqlc 查询、HTTP handler