freehire 公开搜索看板(Public Search Boards)实现指南:把私有筛选快照变成可分享链接
freehire 公开搜索看板(Public Search Boards)实现指南:把私有筛选快照变成可分享链接
freehire 的"已保存搜索"原本只是个人私有的筛选快照,本文围绕归档变更 add-public-search-boards 的落地清单,完整拆解如何在不新建实体的前提下,用一列可空 public_slug 把它变成可公开链接访问的"看板",包括数据库迁移、服务层 slug 铸造与碰撞重试、三个 HTTP 端点、SPA 路由与验证脚本。读完后你可以照着这份清单在同类 Go + Postgres + SvelteKit 项目中复刻一套"公开只读分享"能力,并清楚它与后来取代它的 job lists 方案的差异边界。
说明:本清单是归档变更任务清单的逐项实现记录,其设计取舍见设计文档,需求语义见能力规格。该"看板"能力在后续变更中已被 job lists 取代(见文末"当前状态"一节),但这份清单本身仍是一套完整、可复用的公开分享实现范式。
背景:为什么"已保存搜索"具备分享价值
按设计文档的描述,saved_searches 表存的是登录用户命名过的筛选快照,query 字段就是筛选 URL 与 GET /jobs/search 共用的规范查询串,由 /api/v1/me/searches 在 RequireAuth 下提供,只能按内部数字 id 寻址。
要把它变成可分发的链接,只差"解开两把锁":仅所有者可寻址、读请求必须鉴权。仓库里已有现成的同构范式可抄:jobs.public_slug TEXT NOT NULL UNIQUE + GetJobBySlug + 无需鉴权的 GET /jobs/:slug。公开看板就是把这个模式移植到已保存搜索上。
设计阶段确定的三个关键决策:
| 决策点 | 选择 | 被否决的方案 |
|---|---|---|
| slug 形态 | normalize(name) + 4 位随机后缀,如 remote-go-jobs-a3f1 |
纯随机不透明 token(更私密但不易读);纯 id 派生(稳定但难看且可枚举) |
| 作者署名 | 看板行上的可选自由文本 author_label |
新建 users.display_name 个人资料子系统 |
| 共享建模 | 现有行上的可空 public_slug 开关 |
独立的 public_boards 实体表 |
明确不做的事(Non-Goals)同样是边界:没有看板发现/列表/搜索,不承诺不可猜测的隐私强度,没有浏览统计,也没有"共享/未共享"之外的权限模型;私有已保存搜索的行为完全不变。
任务 1:Schema 与生成的 DB 访问层
1.1 迁移脚本
清单要求新增迁移 migrations/00NN_saved_searches_public_slug.sql,内容为两个可空列加一个唯一索引:
ALTER TABLE saved_searches ADD COLUMN public_slug TEXT;
ALTER TABLE saved_searches ADD COLUMN author_label TEXT;
-- Postgres 的普通 UNIQUE 允许多个 NULL 并存,
-- 因此不需要 partial index,私有行天然不参与冲突。
CREATE UNIQUE INDEX saved_searches_public_slug_idx
ON saved_searches (public_slug);
这里的关键语义是 public_slug IS NULL ⇔ 私有。设计文档特意说明:Postgres 的 UNIQUE 对多行 NULL 不生效冲突,所以"plain UNIQUE"就足够,无需 WHERE public_slug IS NOT NULL 的部分索引。
相关约束在基线 schema 中也能找到印证——migrations/0001_init.sql 里 saved_searches 定义了 public_slug text、author_label text 以及 CREATE UNIQUE INDEX saved_searches_public_slug_idx ON public.saved_searches USING btree (public_slug),同时 name 上有 length(trim(name)) BETWEEN 1 AND 100 的 CHECK。也就是说,名字长度上限既有服务层校验,也有数据库兜底。
1.2 sqlc 查询
清单要求新增四条查询,全部落在 internal/db/queries/saved_searches.sql:
| 查询 | 作用 | 作用域 |
|---|---|---|
GetSavedSearch |
按 id 读一条 | owner-scoped |
SetSavedSearchPublicSlug |
写入 slug + author_label | owner-scoped |
ClearSavedSearchPublicSlug |
slug 置 NULL | owner-scoped |
GetPublicBoardBySlug |
按 slug 读 name/query/author_label |
WHERE public_slug = $1,无 owner 条件 |
"owner-scoped"在 SQL 里体现为 WHERE id = $1 AND user_id = $2,这正是"别人的 id 一律 404"的实现位置——服务层不需要额外判断归属。列表与单条查询的 SELECT * 会自动带上新列。
1.3 代码生成
make sqlc 后 internal/db 重新生成、go build ./... 通过,即视为这一层完成。仓库根目录的 sqlc.yaml 描述了生成映射,这也是后续所有 repository 代码的类型来源。
任务 2:服务层 internal/savedsearch
这一层现在位于 internal/search/savedsearch/savedsearch.go,负责校验与用例编排,持久化交给 Repository 接口(repository.go)。原有约束在源码中可直接读到:
- 名字:
strings.TrimSpace后按 rune 计数限制 1..100(maxNameLen = 100),与数据库 CHECK 的字符语义对齐,注释里明确提到"名字常常是西里尔字母"; - 查询串:按 rune 限制
maxQueryLen = 4000,注释解释了从 2000 提升的原因(由 profile 派生、包含长技能列表的查询曾触顶),空白query合法,代表"显示全部"; - 每用户上限
maxPerUser = 50,在插入前先Count判断; - 哨兵错误:
ErrInvalidName→400、ErrDuplicateName→409、ErrCapExceeded→409、ErrNotFound→404、ErrQueryTooLong→400、ErrProfileSearchExists→409。
2.1 slug 生成与碰撞重试
清单 2.1 要求 normalize(name) + 短随机后缀,并对唯一冲突做有界重试。这段逻辑在后续重构中被抽成了共享包 internal/dict/slugmint/slugmint.go,其注释明确指出它"从 internal/search/savedsearch 的看板分享代码迁移而来",算法与原实现一致:
const (
SuffixLen = 4 // 随机后缀长度
BaseMaxLen = 60 // 名字派生部分上限,避免超长 URL
)
const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789" // URL 安全、与转写主体视觉一致
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) // crypto/rand 取样
if err != nil {
return "", err
}
return base + "-" + suffix, nil
}
两个实现细节值得注意:
- 随机后缀来自
crypto/rand而非math/rand,注释说明目的是让 slug 不可按序列枚举; - 截断后要
TrimRight(base, "-"),避免foo-bar-这种以连字符结尾的半截 slug。
重试策略在有界循环中体现。作为同一套方案的现存实现,internal/application/joblists/share.go 展示了完整写法:maxShareAttempts = 5(见 internal/application/joblists/joblists.go),每次冲突都用新后缀重铸;repository 把唯一冲突翻译成 ErrSlugTaken,重试耗尽后原样上抛。
单元测试要求覆盖"碰撞重试"和"可读 slug 形状"两件事——前者用假 repository 让第一次 SetPublicSlug 返回冲突、第二次成功,后者断言生成结果匹配 base-suffix 形态。
2.2 – 2.4 三个用例
清单把服务层拆成三个方法,语义边界非常清晰:
// 分享:校验/裁剪 author_label(裁剪后 ≤60 字符),
// 无 slug 则铸造,已有 slug 则保留(重复分享不改链接),
// 非本人或不存在 → ErrNotFound。
Share(ctx, userID, id int64, authorLabel string) (SavedSearch, error)
// 取消分享:清空 slug,owner-scoped,已私有则幂等无操作。
Unshare(ctx, userID, id int64) error
// 公开读:仅返回 name/query/author_label,未知或已取消分享 → ErrNotFound。
GetPublicBySlug(ctx, slug string) (PublicBoard, error)
"重复分享保留 slug"是有意的产品语义:用户第二次点分享只想改署名,不该让已发出的链接失效。而取消后重新分享会铸造新 slug,旧链接永久失效——这是撤销的应有之义,规格里也把它写成了显式场景。
配套单元测试清单(清单 2.2/2.3/2.4 逐条列出):分享、重复分享保留 slug、超长署名、非本人、取消分享、取消已是私有、公开读命中与未命中。
任务 3:HTTP 处理器与路由
3.1 扩展响应结构
savedSearchResponse 增加 public_slug(NULL 时为空串)与 author_label,toSavedSearchResponse 同步映射。注意 owner 字段 user_id 从来不在 wire 上——internal/api/handler/me_searches.go 的注释写得很直白:user_id 属于内部归属信息,作用域由 SQL 强制。
3.2 分享 / 取消分享端点
POST /api/v1/me/searches/:id/share body: {"author_label": "..."} → 200 {"data": {...}}
DELETE /api/v1/me/searches/:id/share → 204
两个端点都注册在 RequireAuth(cookie-only)分组下。仓库现有代码里,保存搜索的整组路由正是这样注册的:
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)
注释解释了为什么只用 cookie:已保存搜索是浏览器端便利功能("My filters" 选择器),不是脚本原语。分享类写操作沿用同一策略,避免把状态变更能力暴露给 API key。
错误映射统一走 savedSearchError,每个哨兵一条 case。源码注释强调了一条工程纪律:包里声明的每个哨兵都必须列在这里,并且有测试遍历这张表——漏一个不只是状态码错了,而是会把调用方的输入错误报成服务端故障。动手实现时,新增 ErrAuthorLabelTooLong(→400)与 ErrNotFound(→404)必须同步补进该 switch。
3.3 公开看板端点
GET /api/v1/boards/:slug (无鉴权)
响应体只包含三项:
{"data": {"name": "Remote Go jobs", "query": "q=go&remote=1", "author_label": "strelov"}}
这里最省事也最正确的做法是不写 per-handler 的重映射:GetPublicBySlug 在未命中时返回 pgx.ErrNoRows 或 ErrNotFound,交由中央 ErrorHandler 处理。仓库的 internal/api/handler/errors.go 明确把 errors.Is(err, pgx.ErrNoRows) 归入 404 分支,注释写着"数据库层的 not-found 映射为 404,因此读取类处理器无需自行判断"。这也意味着"未知 slug"与"已取消分享的 slug"两条路径自动得到一致结果。
3.4 路由注册
三个路由在 handler.go 中注册:两个随 /me/searches 鉴权组走,一个与 /jobs/:slug 一样以公开身份注册。当前仓库的 newSavedSearchHandlers(queries) 在 internal/api/handler/handler.go 中被构造,处理器文件的路径已从清单里写的 internal/handler/ 迁移到 internal/api/handler/——这是归档清单与当前目录结构的路径漂移,按代码实际位置为准。
任务 4:Web(SvelteKit SPA)
清单把前端拆成四步,核心思路是"复用一个已存在的查询解析器,只新增路由外壳"。
4.1 契约与客户端。 重新生成/扩展 TS 契约,SavedSearch 类型加 public_slug、author_label,新增看板 wire 类型;在 web/src/lib/api.ts 中按既有 saved-search 客户端模式添加 shareSavedSearch(id, authorLabel) 与 unshareSavedSearch(id)。列表状态直接从每项的 public_slug 读取——不额外请求"是否共享"。
4.2 公开路由 /b/[slug]。 拉取 GET /api/v1/boards/:slug,渲染看板名与作者标签,并把存下来的 query 交给现有 query→filter 解析去列职位;未知 slug 走 not-found 状态。设计文档特意强调要"复用现有查询→筛选解析",而不是新写一套参数映射——否则同一份 query 在两个地方解析,行为迟早分叉。
4.3 账户区 /my/searches。 先从 savedSearches store(web/src/lib/savedSearches.svelte.ts)取列表,提供分享/取消分享/重命名/删除,共享时给出可复制的 /b/:slug 链接;未登录则提示登录。设计文档说明了放置逻辑:/my/* 是一组平级的兄弟页面,没有共享 +layout,所以新页面就是"一个目录 + HeaderMenu.svelte 的 menuItems 里一行"。
4.4 "My filters" 面板。 SavedSearches.svelte 增加分享(可选署名)→ 展示可复制链接、取消分享 → 回到私有的轻量控件;共享态同样来自 public_slug。创建动作仍只留在这个面板,因为当前筛选状态在它手上;账户区是纯管理页。
任务 5:验证
清单给出的验证口径是四条命令加一个端到端用例:
go build ./... && go vet ./...
go test ./... # 含 integration build tag 的 handler/db 测试
# web
npx svelte-check # 0 errors / 0 warnings
npm run build # 生产 SSR 构建
API 级端到端由 TestSavedSearchBoardsEndToEnd 对真实 Postgres 跑完整链路,断言点值得逐条抄进自己的测试:
- 创建 → 分享,拿到 slug;
- 匿名访问
/api/v1/boards/:slug,断言响应中不含user_id/id/email; - 重复分享后 slug 不变;
- 取消分享后同一 slug 变 404;
- 任意未知 slug 也是 404。
清单还诚实标注了残余风险:"未在本机执行浏览器走查 /my/searches 与 /b/:slug(需要 seed 过的 Docker 栈),建议部署前做一次冒烟"。这种"哪些已验证、哪些没验证"的显式区分,比笼统的"测试通过"更有价值。
这套方案复用到别的项目时要盯住的四个点
- NULL 即私有。一个可空列同时承担"状态开关"和"公开标识符",避免了两张表之间同步
query的一致性成本。 - 铸造 slug 的随机性来自 CSPRNG,后缀只是降低可猜测性,不构成隐私保证;真正的保证是"只有显式分享期间才可达"以及"公开面不暴露任何 owner PII"。
- owner 作用域下沉到 SQL,服务层只做校验与编排,处理器只做映射,三层职责不重叠。
- 未命中走中央错误映射,不要在每个 handler 里写
if errors.Is(...) 404,否则同一语义会在多处出现不一致的状态码。
当前状态:该能力已被 job lists 取代
阅读归档清单时必须知道它的生命周期终点,否则会照着不存在的代码找实现。migrations/0137_drop_saved_search_sharing.sql 已明确写清:
Public saved-search sharing(
GET /api/v1/boards/:slug与 web/b/:slug)已退役,改由 job_lists(0135/0136)承接,后者共享的是一组固定职位而非实时查询。既有公开看板链接直接不再解析,且不做自动迁移,因为"查询"不等于"职位集合"。
同期迁移做了两件事:DROP INDEX public.saved_searches_public_slug_idx,以及 ALTER TABLE saved_searches DROP COLUMN public_slug, DROP COLUMN author_label。当前仓库中 internal/search/savedsearch 只剩 List/Count/Create/Update/Delete 五个仓储方法与对应用例,没有 Share/Unshare/GetPublicBySlug;web/src/routes 下已无 b/ 目录;web/src/routes/my/searches/+page.ts 现在只做 308 重定向到 /my/notifications/searches(搜索提醒管理并入了通知中心)。
替代方案的差异可以对照着看:
| 维度 | 公开搜索看板(已退役) | Job lists(现行) |
|---|---|---|
| 共享内容 | 实时 query,每次访问重跑筛选 |
固定职位集合,读时直接返回物料化结果 |
| 署名 | 独立 author_label(≤60 字符) |
不设,复用列表自身的 description(≤2000 字符) |
| slug | 转写名 + 4 位随机后缀,冲突有界重试 | 同一套方案,maxShareAttempts = 5,兜底 base list |
| 公开路由 | /b/:slug(已删除) |
/l/[slug],见 web/src/routes/l/[slug]/+page.server.ts |
| 未命中 | 404 | 404,由 +error 页渲染 not-found |
| 上限 | 每用户 50 条已保存搜索 | 每用户 50 个列表、每列表 200 个职位 |
新版公开读还解决了一个旧方案固有的漂移问题:看板页每次都在重跑查询,职位上下架会让同一个链接的内容不断变化;而列表返回的是用户亲手挑选并记录下来的集合,已关闭的职位仍保留并标注状态。slug 铸造逻辑被抽到 internal/dict/slugmint 的原因也写在那个包的注释里——它原来只有一个调用方(看板),迁移后也只有一个调用方(job lists),所以这是"搬家"而不是提前建设共享基础设施。
因此,如果你要在自己的项目里复刻这套能力:照着这份清单实现"可空 public_slug + 转写 slug + 中央 404 + owner 作用域下沉"四件事是稳妥的;但如果你要共享的是"一组人挑出来的东西"而不是"一个会变化的查询",那么 job lists 的建模才是更贴合的答案。