Boop 开源贡献指南:代码结构、测试规范与如何为它写出自己的客户端库

原创2026-10-17 20:10:391,916 阅读

Boop 开源贡献指南:代码结构、测试规范与如何为它写出自己的客户端库

Boop 是一个极简的、可自托管的开发者通知收件箱(notification inbox):你的应用只要 POST 一个事件,Go 服务端就会存库并直接推送到你的 iPhone。整个项目刻意保持"一个小"——一个 Go 二进制、一个 SQLite 文件、一个 Docker 容器,没有中继、没有账号系统、没有遥测。正因如此,它的代码量适中、边界清晰,非常适合作为学习 Go + Svelte 工程结构、以及如何为一个极简 HTTP API 编写多语言客户端库的开源项目。

本文将带你看懂 CONTRIBUTING.md 背后的完整上下文:代码结构地图、本地开发与测试规范,并附一份可直接执行的"客户端库开发清单"。

🗺️ 项目结构速览:三大模块一分钟看懂

Boop 由三块组成,各自独立、职责单一:

模块 路径 说明
Go 服务端 server/ API、SQLite、APNs 推送、内嵌 Web UI
Web 管理界面 server/web/ Svelte + Vite,构建后打进 Go 二进制
iOS 客户端 ios/ SwiftUI,自己编译签名,含通知服务扩展

整体数据流如下:应用用项目 API Key 把事件 POST 给服务端 → 服务端脱敏后存入 SQLite → 用你的 .p8 密钥直连 Apple APNs 推送到 iPhone → iOS App 再用设备凭证拉取完整事件详情。

Boop 通知收件箱架构图:应用 POST 事件到 Go 服务端,SQLite 存储,推送至 Apple APNs,iOS 应用拉取详情

💡 交互式版本在 docs/architecture/index.html,在浏览器打开即可缩放查看。

服务端内部:一个包一个职责

server/ 采用 Go 的经典"每关注点一个包"布局,入口在 server/cmd/boop/main.go,main 只做装配:加载配置 → 打开数据库 → 启动推送分发器 → 挂上 HTTP handler。internal/ 下每个包只做一件事:

  • api — HTTP 路由与鉴权分发
  • events — 事件校验、脱敏、存储(字段上限定义在 server/internal/events/events.go:标题 200、正文 4000、data 256 KB)
  • delivery — 把事件扇出到所有已注册设备并记录推送结果,见 server/internal/delivery/delivery.go
  • apns / pairing / devices / projects / settings / silences / auth — 各自领域
  • web — go:embed 内嵌的前端产物

数据库变更全部走 SQL 迁移文件,按文件名顺序在启动时自动执行,见 server/migrations/,例如 server/migrations/0001_initial.sql 定义了 projects、devices、events 三张核心表。

前端如何"塞进"Go 二进制

Web UI 是 Svelte 单页应用,npm run build 会把产物写到 server/internal/web/dist,由 Go 的 go:embed 直接打进可执行文件——这就是为什么最终交付物只有一个二进制。开发时则用 Vite dev server 代理 /api 到 :8080,前后端可并行热更新。

🚀 本地开发环境搭建:两步跑通前后端

1. 准备工具链

项目要求 Go 1.27 和 Node 24(见 .tool-versions)。SQLite 驱动是纯 Go 实现(modernc.org/sqlite),CGO_ENABLED=0 也能构建,无需装 C 依赖。

git clone https://gitcode.com/gh_mirrors/boop2/boop
cd boop

2. 两个终端,各自跑一半

# 终端 1:Go 服务端,API 起在 :8080
cd server && BOOP_DATABASE_PATH=./data/boop.db go run ./cmd/boop

# 终端 2:Web 前端,:5173 并代理 /api 到 :8080
cd server/web && npm install && npm run dev

或者用 Makefile 一键化:make run、make dev、make build(构建出内嵌 UI 的单文件二进制到 bin/boop)。

⚠️ 不设 BOOP_DATABASE_PATH 时数据库会写到默认的 /data/boop.db,本地开发记得按上面命令指定仓库内路径。

3. (可选)用 Docker 体验完整产品

server/Dockerfile + docker-compose.yml 可以直接起容器,数据落在 ./data/boop.db,APNs 的 .p8 密钥通过只读卷挂载。第一次访问会进入设置向导:服务端检查 → APNs → 配对手机 → 建第一个项目 → 发测试通知。

✅ 测试规范:一条 make test 覆盖 Go + Web

Boop 的测试入口只有一条命令,由 Makefile 拆成两个子任务:

make test            # = go vet + go test + svelte-check + vitest
  • Go 侧:go vet ./... && go test ./...。核心约定是——测试会启动真实的 HTTP handler 对接一个临时 SQLite 文件,而不是 mock 数据库。典型写法见 server/internal/api/api_test.go:newEnv 在 t.TempDir() 里建库、组装完整 Server 结构体、用 httptest.NewServer 起真实 HTTP 服务,再用 fakeSender 替代 APNs 记录"本应发出"的推送。server/internal/api/api_test.go 里覆盖了鉴权、脱敏、游标分页、配对过期、推送扇出、静默规则、分组列表等场景——每新增一个端点或行为,都应当加对应测试,这是 CONTRIBUTING.md 的硬性要求。
  • Web 侧:npm run check(svelte-check 类型检查)+ npx vitest run。前端测试以纯函数断言为主,例如 server/web/src/lib/format.test.ts 验证时间相对格式(2m ago)、时长缩写、数字压缩(12k)等工具函数的边界输入。
  • CI:.github/workflows/ci.yml 按 web → go → docker 三段流水线执行,最终还会以 CGO_ENABLED=0 做一次静态构建验证。本地提交前把 make test 跑绿即可对齐 CI。

📐 代码规范与发布约定:别踩的四个坑

CONTRIBUTING.md 很短,但每条都是项目的气质:

  1. 日志:一律用 slog,事件名用点分(event.created、push.failed,可参考 server/cmd/boop/main.go 的写法)。绝不记录密钥、凭证或完整事件负载。
  2. UI 文案:句子首字母大写(Sentence case)、不用感叹号、不用 emoji。
  3. 设计令牌:Web 用 server/web/src/app.css 的 CSS 变量(--up-*),iOS 对应 ios/Boop/Design/DS.swift,不要硬编码颜色。
  4. Changelog:任何用户可感知的变更(新端点、新字段、UI、配置、迁移)都要在 CHANGELOG.md 的 Unreleased 下加一行;发版时同步升版本号(服务端、Web、iOS 三者共用一个版本)。

另有一条"准入红线":任何需要额外基础设施(消息队列、托管中继、外部数据库)的改动基本不会被接受——这是项目保持"一个二进制"的底线。

📦 如何为 Boop 写出自己的客户端库

Boop 官方客户端(Elixir、Node.js 等)都放在独立仓库,且全部遵守同一份规范。好消息是:这份规范就在仓库里,而且它本身就是一份"可以直接喂给 AI 的提示词"——integration-llms.md。

第一步:记住客户端只需要一个端点

发送型客户端唯一需要的是 POST /api/v1/events,Bearer 鉴权(boop_proj_ 开头的项目 Key)。读事件、管理设备都是 Web UI / iOS App 的事,不要做进发送客户端里。

先用 curl 打通基准请求,你的库必须能复现它:

curl -i "$BOOP_URL/api/v1/events" \
  -H "Authorization: Bearer $BOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello from curl", "level": "info", "source": "curl"}'

期望得到 201 Created 和事件 id。事件字段只需 title(1–200 字符)必填,其余 body、level(info/success/warning/error/critical)、source、fingerprint、data(自由 JSON,≤256 KB)、actions(最多 3 个 {label, url} 按钮)都可选,完整限制表见 integration-llms.md。

第二步:对齐"好客户端"的 11 条行为准则

integration-llms.md 列出了所有官方客户端共同遵守的行为,浓缩版清单:

# 准则 要点
1 绝不拖垮宿主应用 发送失败只降级为返回错误/日志,任何情况下不抛异常
2 同步 + 异步双 API send() 返回 ok/error;send_async() 后台执行、永不抛出,热路径推荐它
3 有界重试 只重试网络错误和 5xx,2–3 次带抖动的退避(如 200 ms → 800 ms),4xx 永不重试
4 处处设超时 建议默认连接 5 s + 总计 10 s,且可配置
5 发送前脱敏 password、token、api_key、cookie 等密钥字段在客户端就替换为 [REDACTED],别只依赖服务端
6 截断而非失败 超长就截断;data 超 256 KB 时丢弃最大值并在 body 里注明,而不是丢整个事件
7 地道的参数形式 接受语言原生类型(如 enum/字符串)并序列化;单参调用 send("Backup complete") 必须可用
8 默认配置友好 支持 BOOP_URL / BOOP_API_KEY 环境变量兜底 + 可选的默认 source 和 enabled 开关
9 不泄露密钥 默认日志里只有事件 id 和状态,没有 API Key 和完整负载
10 生态惯用法 用标准 HTTP 客户端与测试工具;README 附安装、配置与最小/富文本/异步三个示例
11 测试 单测覆盖序列化、脱敏、截断,HTTP 层用桩服务验证 201 解析、401/422 不重试、5xx 重试、异步不抛异常

第三步:让 AI 帮你起个头

仓库作者把 integration-llms.md 设计成可直接交给 LLM 的提示词,例如对 Claude 说:

"build me a Boop client for Python following integration-llms.md"

它会带着完整的事件字段限制、错误码表(400/401/413/422/5xx 各自的客户端动作)和参考 API 形状生成初稿,你再按上面的准则打磨测试即可。

验收标准:与官方客户端同级

写完后对照一下官方客户端的共同点:同一个端点、发送前脱敏、截断而非拒绝、只重试网络错误和 5xx、永不崩溃宿主应用。做到了,你的客户端就达到了与 README.md 中列出的官方库同等的水准——发布到自家仓库,然后在 README 的 Integrations 一节提个 PR 挂上链接,就是对这个项目最有价值的贡献之一。

🎯 总结:贡献 Boop 的三条路径

  1. 改服务端 / Web:读 CONTRIBUTING.md → make run + make dev 本地起环境 → 新功能补 server/internal/api/api_test.go 风格的真实 handler 测试 → make test 跑绿 → Changelog 加一行。
  2. 写客户端库:以 integration-llms.md 为唯一契约,先 curl 打基准请求,再对齐 11 条行为准则,测试用桩服务覆盖重试矩阵。
  3. 提 iOS 侧改动:工程文件由 XcodeGen 从 ios/project.yml 生成,改完记得 xcodegen generate;构建签名流程见 ios/README.md。

Boop 的设计哲学是"拒绝复杂",贡献代码时也是如此:小步、有测试、不引入新依赖设施。祝你的第一个 PR 顺利合入 🚀

登录后查看全文
boop