项目主要面向中国用户,用户可见文案、文档和代码注释优先使用中文;协议字段、配置项、日志 event、依赖 feature 和代码标识保持英文原文
src/包含完整 Rust 应用:订阅 API、WebSocket 监听、订阅匹配、Bark 推送和 Web 页面路由web/index.html是唯一 Web 界面源文件,由build.rs压缩后通过include_str!编译进二进制- 仓库不维护特定平台的反向代理、进程守护或静态托管配置
服务端行为和 Web 交互尽量分开改,跨层改动需要说明数据流如何变化
开发入口:
cp .env.example .env
cargo run提交前至少跑:
cargo fmt --check
cargo check
cargo test如果改动涉及依赖、并发、错误处理、HTTP/WebSocket 或共享模型,也跑:
cargo clippy --all-targets --all-featuresCargo.toml 已启用严格 lint,新增代码不要使用 unwrap()、expect()、dbg!()、println!()、todo!()、unimplemented!(),也不要引入 unsafe
新增或升级依赖时,默认保持 default-features = false,只开启实际用到的 feature,不要启用 tokio/full、TLS 双栈或框架默认全量功能来省配置,依赖变更后检查:
cargo tree -e features
cargo check
cargo test后端统一使用 tracing,日志面向排障,动态值放字段里;用户可见文案继续中文
tracing::info!(
event = "subscription.stored",
device_key = %mask_device_key(&device_key),
"subscription.stored"
);约定:
event使用稳定英文标识,格式为domain.action- Bark ID、token、URL 中的敏感部分必须脱敏
- 错误日志保留
error = ?error,不要只写字符串 - 高频心跳、pong、重复事件使用
debug
注释只解释代码本身看不出的内容,例如上游字段拼写、时区、算法边界、平台限制和业务规则来源,不要写「创建变量」「保存数据」这类逐行复述,也不要写没有指标支撑的「高并发」「百万级」「优化版」
这个项目会保存 Bark Key、监测地点和通知级别,任何相关改动都要先确认下面几条约束:
- 只允许通过
POST /api/subscribe创建或覆盖订阅,通过DELETE /api/unsubscribe删除订阅 - 不提供「输入 Bark Key 查询订阅详情」的接口,Bark Key 不能作为反查用户位置、地点名称、通知级别或订阅时间的凭据
- 退订接口只返回操作结果,不回显订阅内容
- 统计接口只返回聚合数量,不返回 Bark Key、位置或通知规则
- 日志中只输出
mask_device_key处理后的 Bark Key,不输出完整 Bark Key、精确位置和原始订阅请求体 - 示例、测试、截图和 issue 不使用真实 Bark Key 或真实用户位置
- 不提交真实
.env、数据库文件、Bark key、访问 token 或生产私密配置 - 修改 CORS、反代或静态托管规则时,确认不会新增订阅详情读取面
涉及隐私边界的 PR 或提交说明里,需要明确写出是否新增了读取接口、是否回显订阅数据、日志里是否可能出现完整 Bark Key 或位置