freehire 公开搜索看板(Public Search Boards)实现指南:把私有筛选快照变成可分享链接

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

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
}

两个实现细节值得注意:

  1. 随机后缀来自 crypto/rand 而非 math/rand,注释说明目的是让 slug 不可按序列枚举;
  2. 截断后要 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 跑完整链路,断言点值得逐条抄进自己的测试:

  1. 创建 → 分享,拿到 slug;
  2. 匿名访问 /api/v1/boards/:slug,断言响应中不含 user_id/id/email;
  3. 重复分享后 slug 不变;
  4. 取消分享后同一 slug 变 404;
  5. 任意未知 slug 也是 404。

清单还诚实标注了残余风险:"未在本机执行浏览器走查 /my/searches 与 /b/:slug(需要 seed 过的 Docker 栈),建议部署前做一次冒烟"。这种"哪些已验证、哪些没验证"的显式区分,比笼统的"测试通过"更有价值。

这套方案复用到别的项目时要盯住的四个点

  1. NULL 即私有。一个可空列同时承担"状态开关"和"公开标识符",避免了两张表之间同步 query 的一致性成本。
  2. 铸造 slug 的随机性来自 CSPRNG,后缀只是降低可猜测性,不构成隐私保证;真正的保证是"只有显式分享期间才可达"以及"公开面不暴露任何 owner PII"。
  3. owner 作用域下沉到 SQL,服务层只做校验与编排,处理器只做映射,三层职责不重叠。
  4. 未命中走中央错误映射,不要在每个 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 的建模才是更贴合的答案。

登录后查看全文
freehire