Boop 开源贡献指南:代码结构、测试规范与如何为它写出自己的客户端库
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 再用设备凭证拉取完整事件详情。
💡 交互式版本在 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、data256 KB)delivery— 把事件扇出到所有已注册设备并记录推送结果,见 server/internal/delivery/delivery.goapns/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 很短,但每条都是项目的气质:
- 日志:一律用
slog,事件名用点分(event.created、push.failed,可参考 server/cmd/boop/main.go 的写法)。绝不记录密钥、凭证或完整事件负载。 - UI 文案:句子首字母大写(Sentence case)、不用感叹号、不用 emoji。
- 设计令牌:Web 用 server/web/src/app.css 的 CSS 变量(
--up-*),iOS 对应 ios/Boop/Design/DS.swift,不要硬编码颜色。 - 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 的三条路径
- 改服务端 / Web:读 CONTRIBUTING.md →
make run+make dev本地起环境 → 新功能补 server/internal/api/api_test.go 风格的真实 handler 测试 →make test跑绿 → Changelog 加一行。 - 写客户端库:以 integration-llms.md 为唯一契约,先 curl 打基准请求,再对齐 11 条行为准则,测试用桩服务覆盖重试矩阵。
- 提 iOS 侧改动:工程文件由 XcodeGen 从 ios/project.yml 生成,改完记得
xcodegen generate;构建签名流程见 ios/README.md。
Boop 的设计哲学是"拒绝复杂",贡献代码时也是如此:小步、有测试、不引入新依赖设施。祝你的第一个 PR 顺利合入 🚀
