sem 是一个语义版本控制工具，构建在 Git 之上。它不显示代码行的变更，而是显示实体级别的变更（函数、方法、类等）。

核心特点

• 语义级别差异对比：显示"函数 blahh 被修改"而非"第 x-y 行变更"
• 零配置：在任何 Git 仓库中直接使用，无需设置
• 支持 26 种编程语言：使用 tree-sitter 解析代码
• 实体重命名检测：自动识别函数/类的重命名

主要命令

• sem diff：实体级别的差异对比，支持重命名检测、结构化哈希和词级高亮

  • 支持多种输出格式：plain、JSON、Markdown
  • 可比较工作区、暂存区、提交、任意两个文件

• sem impact：跨文件依赖图分析，显示实体变更的影响范围

  • 可查看依赖关系、受影响的测试等

• sem blame：实体级别的代码归属，显示谁最后修改了每个函数/类

• sem log：追踪单个实体在 Git 历史中的演变过程

• sem entities：列出文件或目录下的所有实体

• sem context：为 LLM 生成符合 token 预算的上下文（包含实体及其依赖）

原文链接：https://github.com/Ataraxy-Labs/sem

Rust workspace 自动发布包的困境

问题背景

开发者在尝试自动发布 Rust workspace 中的多个包时遇到了两难问题：

遇到的具体问题

方案一：cargo publish --workspace

• 如果任何包已经发布过，命令会直接中止
• 无法跳过已发布的包继续发布其他包

方案二：cargo workspaces publish --from-git

• 使用第三方工具 cargo-workspaces（https://github.com/pksunkara/cargo-workspaces）
• 存在严重缺陷：当发布失败时（非"包已存在"的原因），无法正确返回错误码
• 这在 CI/CD 流程中依赖退出码判断时会造成问题

开发者困惑

作者认为这是一个非常基础的需求，对于没有现成解决方案感到惊讶，怀疑是否自己的使用方式有问题。

原文链接：https://www.reddit.com/r/rust/comments/1tg2hlc/is_there_a_solution_to_automatically_publish/

Concord v2.0.0 发布 - Rust 编写的 Discord 终端 UI 客户端

Concord 是一个使用 Rust 和 Ratatui 框架开发的 Discord 终端用户界面客户端。最新的 v2.0.0 版本带来了重要更新。

主要新功能

• 语音支持：现在可以加入语音频道并播放接收到的语音音频

其他核心功能

• 导航功能：支持服务器(Guild)、频道、帖子、论坛和私信(DM)的导航
• 消息操作：可以发送、编辑、删除、回复、置顶消息以及添加表情反应
• 媒体预览：在支持的终端中提供内联图片预览
• 桌面通知：支持桌面通知功能
• 快捷操作：提供 Vim 风格的键盘导航

项目信息

• GitHub 仓库：https://github.com/chojs23/concord
• 更多功能详情可查看项目的 README 文档

原文链接：https://github.com/chojs23/concord

Gecko - GameCube/Wii 模拟器

Gecko 是一个用 Rust 编写的跨平台 GameCube/Wii 模拟器和调试器。

项目状态

• 仍在开发中
• 许多游戏可以运行，但大多数存在不同程度的视觉故障或完全无法运行
• 提供 GameCube 和 Wii 游戏的截图数据库以评估兼容性
• 注意：目前仅追踪 NTSC 游戏

主要特性

• 开发目标：专注于自制软件开发和逆向工程，同时提供流畅的游戏体验
• 核心技术：
  • PowerPC JIT（使用 Cranelift）
  • DSP JIT 和 GX 顶点解码 JIT
  • 基于 wgpu 的渲染后端，支持所有主流平台
  • 专用着色器编译器、JIT 和着色器缓存
• 音频系统：模块化音频后端，支持混音和导出 .wav 文件
• 调试功能：
  • 基于 egui 的高级调试界面

原文链接：https://github.com/ioncodes/gecko

hi_sparse_bitset 这次更新最值得看的点，是把“稀疏位集”继续往更适合预计算和大数据场景的方向推了一步。v0.9.0 新增了 ImmutableBitset，同时让 DirectBitset 真正支持零拷贝读取，对需要序列化、落盘和内存映射的大规模位集场景会很有吸引力。

这次版本的几个重点

• 新增 ImmutableBitset，采用线性数据结构，适合中间结果收集和预计算数据存储
• DirectBitset 配合新的序列化格式后，可以直接走真正的 zero-copy
• 所有位集容器都加入了内部“大小提示”，减少物化和原地 union 时的分配开销
• 增加对 wide::u64x8 的优化
• 配置层现在可以选择性配置数据块类型

需要注意的地方

这次版本改了序列化格式，旧数据如果依赖之前的编码方式，升级时要顺手检查兼容性。但换来的收益也很直接：更低的拷贝成本、更适合 mmap 的使用方式，以及更清晰的不可变数据路径。

原文链接：https://github.com/tower120/hi_sparse_bitset/releases/tag/v0.9.0

DualCacheFF v0.2.0 发布

DualCacheFF 是一个面向极端读写比例和抗扫描场景的并发缓存库，主打 wait-free 读路径、极低延迟和更克制的内存占用。v0.2.0 这一版把性能和工程可用性都继续往前推了一截。

版本亮点

• 核心设计基于 QSBR / RCU 思路，强调 CPU 局部性和高吞吐
• 吞吐基准里，Zipf 工作负载下可达约 6078 万 ops/s
• P99.9 延迟约 708ns，内存开销约 54.62 字节 / 项
• 移除了 crossbeam 依赖，改用自定义 wait-free 原语
• 核心引擎新增 no_std 支持，在需要 alloc 的环境里也能使用

为什么值得看

Rust 缓存库不少，但把“极端场景下的吞吐、尾延迟和内存效率”同时摆到台面上对比，并且明确说明自己牺牲了什么、换来了什么，这类项目通常更有参考价值。对做高并发基础设施的人来说，这种实现思路本身就值得研究。

原文链接：https://crates.io/crates/dualcache-ff

Raygeo：MIT 许可的 Rust/PyO3 几何库发布

Raygeo 最初是为 Rayforge 激光切割应用开发的几何库，现在已经迁移到 Rust，并继续通过 PyO3 对 Python 暴露能力。它覆盖的不是一个单点小功能，而是一整套几何处理能力：路径构建、布尔运算、曲线拟合、裁剪、轮廓分析，甚至还保留了原先项目积累下来的大量测试资产。

这个项目有几个看点

• 用 Rust 重写核心后，继续通过 PyO3 提供 Python 接口
• 支持 2D / 3D 几何路径、曲线、轮廓和多边形操作
• 集成裁剪、平滑、圆弧拟合等更偏工程侧的能力
• 设计上尽量避免把数据封装成高层 Python 对象，更强调底层性能
• 采用 MIT 许可，已有文档、GitHub 和 PyPI 发布路径

为什么它容易传播

Rust 做几何计算和图形前处理并不新鲜，但这种“Rust 做核心 + Python 做落地接口”的组合，一直都很有现实价值。尤其是当它背后已经有真实应用和大量测试时，可信度会比纯 demo 型项目高不少。

原文链接：https://github.com/barebaric/raygeo/blob/main/docs/raygeo.md

ee-editor：快速的终端文本编辑器

ee-editor 是一个用 Rust 写的终端优先文本编辑器，重点不是“又一个 TUI 编辑器”，而是把大文件能力、语言感知和插件式架构一起打包成一个更完整的工程形态。

它现在公开出来的几个重点

• 面向大文件场景设计，支持持久化 rope 存储和流式工作流
• 终端界面基于 ratatui 和 crossterm
• 语言能力由 tree-sitter 驱动，可做解析、高亮和语言感知处理
• 支持 LSP 与插件集成
• 编辑器核心与前端分离，通过 JSON/RPC 通信，便于扩展和复用

为什么这条值得收进日报

Rust 生态里的编辑器项目不少，但真正把“可扩展核心”“终端体验”和“超大文件处理”同时放在第一优先级的并不多。对喜欢终端工具链、又关心编辑器架构的人来说，这类项目通常很容易引起兴趣。

原文链接：https://github.com/ffimnsr/ee

这两年我尝试过各种 Vibe Coding 编程工具，到现在用的最多的还是 Claude Code 这种 CLI 工具，以前 PyCharm, Goland 这些 IDE 现在很大多时候就只用来看代码了。

虽然现在开七八个终端可以同时 Vibe Coding 好几个项目，但是当我真的开始这么做的时候我发现我的脑子转不过来了，每个终端都在写代码，有时候还需要点 Yes,  而且还要在不同的 IDE, 编辑器，终端中来回切换, 上了一天班代码虽然都是 AI 写的但是人却是累到了，第二个开很多 IDE 我 16G 内存的电脑也有点吃力了。

为了解决自己的困扰，我开发了 NeZha 这个 AI 开发工具, NeZha 的思路很简单, 那就是去掉 AI 时代过去 IDE 那些臃肿的功能(即使不臃肿我也做不出来), 做一个 Agent 优先的编程工具，把重心放在如何管理多个项目下的 VibeCoding 任务和会话管理上，同时保留终端的功能和易用性。

NeZha 集成了 Git, CodeReview 视图, 简单的代码编辑器(支持 markdown 预览, 代码高亮), 终端，会话管理，Git Worktree 这些功能。

中间是一个原生的虚拟终端，使用 xterm 和 pty 实现，因此使用的时候基本和使用 claude code 或者 codex cli 是一样的。

任务完成之后会话会被自动可视化，之后你可以选择重新启动这个任务

NeZha 使用 Tauri 开发(说实话现在有一丢丢后悔了), 后端使用 Rust 实现, 支持 Windows, Linux 和 Macos 平台, 最早 NeZha 是为了解决我自己的问题而开发的，慢慢发现身边也有一些人也有这样的痛点，所以就选择把它开源了出来，NeZha 由于完全不会上报用户信息，所以我也不知道有多少人在用它，不过我偶然会收到一些反馈和issue, 应该还是有人在用的，能帮助到其他人本身也是一件有价值的事情，我自己还是很开心的

说实话，我感觉 NeZha 可能不是 VibeCoding 的最终形态，不过现阶段我还是会继续迭代下去~

开源地址: https://github.com/hanshuaikang/nezha

MoteDB 是一款专为边缘端设备设计的嵌入式数据库，不需要单独的服务器进程，可以直接集成到你的 Rust 应用中，为家庭机器人、AR 眼镜、工业机械臂等边缘设备提供原生多模态数据支持。

本次更新聚焦真实机器人、物理世界交互与多模态数据（向量、全文、时空、键值等）的深度融合，整体性能较上一代提升 2～10 倍，部分关键场景实现数量级飞跃。无论您是具身智能研究员、机器人系统工程师，还是对高性能数据库感兴趣的 Rust 开发者，都欢迎体验这一全新成果。

• GitHub 仓库：https://github.com/motedb/motedb
• crates.io 地址：https://crates.io/crates/motedb

🚀 性能提升一览

我们在 v0.2.0 中完成了多个关键优化，以下是核心指标的测试结果：

括号内“原 xx”为上一版本典型延迟/QPS。所有测试在标准云服务器（16C/64G，NVMe SSD）上完成。

🧠 为什么选择 MoteDB？

具身智能体（如人形机器人、自动驾驶车辆、智能家居中枢）需要同时处理：

• 传感器流（图像、点云、惯性数据）→ 向量嵌入检索
• 环境语义（物体、人物、位置）→ 全文 + 空间查询
• 实时状态（关节角度、电量、任务队列）→ 毫秒级读写
• 长期记忆（历史交互、轨迹日志）→ 高效压缩与恢复

MoteDB 从底层存储引擎到查询优化器，原生设计为同时理解向量、文本、时空、标量，并允许你在一次查询中自由组合：“在 10 米范围内找到所有红色物体的最近向量匹配，并按时间排序返回前 5 条”。

项目提供了五大索引类型，针对不同场景进行专门优化：

⚡ Rust 带来的硬核优势

整个数据库内核完全使用 Rust 编写，代码中 Rust 占比 100.0%。我们选择 Rust 的原因很简单：既要 C++ 级的极致性能，又要内存安全和无畏并发。具体收益包括：

• 零成本抽象：向量索引（采用 FreshDiskANN 算法与 Rerank 重排序策略）、全文索引（BM25 + 分词插件）、空间索引（R-Tree）与 B+Tree 共存于同一存储引擎，无 GC 停顿。
• 无惧数据竞争：多线程查询、写入、后台合并同时进行，绝无悬空指针或 use-after-free。
• 轻量化嵌入式：核心数据结构内存占用 < 100MB，事务吞吐量可达 10,000 TPS，批插入吞吐量高达 737,112 rows/sec（10,000 条记录），向量检索延迟 < 5ms（95% 召回率）。
• 跨平台编译：一个 --target 参数即可轻松交叉编译到 ARM、RISC-V 等嵌入式架构。

我们还将数据库的客户端驱动、CLI 工具也基于 Rust 构建，从而为 RustCC 社区提供一个 端到端的高性能数据库样板。

🛠️ 核心特性一览

• 完整 SQL 支持：包含子查询、聚合函数、JOIN 和索引管理，使用熟悉的 SQL 语法完成多模态数据操作。
• MVCC 事务：完整的事务支持，包括保存点（Savepoint）和 WAL 预写日志，确保数据强一致性。
• 高性能批操作：批插入比单条插入 快 10-20 倍，适合大批量数据加载场景。
• 内存友好：极致轻量化，可在树莓派等低功耗设备上流畅运行，内存占用低至 35MB。

📦 如何获取与体验？

• GitHub 仓库：https://github.com/motedb/motedb

• crates.io 安装：

  cargo add motedb
  

  当前版本 v0.2.0。

• Rust 快速示例：

  use motedb::{Database, Value};
  
  fn main() -> Result<(), Box<dyn std::error::Error>> {
      let db = Database::open("data.mote")?;
      db.execute("CREATE TABLE users (id INT, name TEXT, email TEXT)")?;
      db.execute("INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')")?;
      let results = db.query("SELECT * FROM users WHERE id = 1")?;
      Ok(())
  }
  

• 批操作示例（10-20x 性能提升）：

  let mut rows = Vec::new();
  for i in 0..10000 {
      let mut row = HashMap::new();
      row.insert("id".to_string(), Value::Integer(i));
      row.insert("name".to_string(), Value::Text(format!("User{}", i)));
      rows.push(row);
  }
  let row_ids = db.batch_insert_map("users", rows)?;
  // 吞吐量：737,112 rows/sec
  

• 完整文档：项目 docs 目录包含了从快速入门、安装配置、各类索引使用到性能调优的完整文档体系。

📢 致 RustCC 开发者

作为一款完全由 Rust 构建的数据库系统，我们深切受益于 Rust 社区的无私共享与严谨精神。本次 v0.2.0 发布不仅是产品迭代，更是向社区展示“Rust 能做到什么”的一个范例：从无锁数据结构到异步 I/O，从过程宏生成 SQL 解析器到基于 rayon 的并行扫描。

欢迎大家：

• Star & Watch：关注 GitHub 仓库，第一时间获取更新
• 试用反馈：在实际项目中尝试 MoteDB，提交 Issue 或 PR
• 参与贡献：项目还有很多有趣的技术挑战等待解决（存储引擎优化、更多索引算法、分布式扩展等）

立即体验，开启 AI 原生多模态数据库的新纪元！

GitHub 地址：https://github.com/motedb/motedb
crates.io：https://crates.io/crates/motedb
讨论反馈：GitHub Issues / Discussions

让具身智能拥有原生记忆，让 Rust 定义数据库未来。

（本文欢迎转发，感谢 RustCC 社区的支持！）

Burn ONNX 是一个在构建时把 ONNX 模型导入 Burn 深度学习框架的工具。0.21.0 是它从 tracel-ai/burn 单体仓库拆出后的首个独立版本，这次不只是发了个新包，而是把测试、仓库、发布节奏和模型覆盖能力都一起拉起来了。

这次版本里最值得看的点

• 项目已经独立托管在 tracel-ai/burn-onnx，有自己的 CI、issue 跟踪和发布周期
• 支持 201 个标准算子中的 160 个，注册了 174 个节点类型处理器
• 集成了 1,615 个上游 ONNX 后端测试，当前有 717 个测试通过，占可比较集合的大约 80%
• 对 ONNX opset 1 到 24 的 472 个算子 / 规范版本检查全部通过
• 真实模型验证覆盖 SDXL、Qwen、YOLO、ResNet-50、CLIP 等常见模型

它的工作方式也很 Rust

在 build.rs 里指向 .onnx 文件后，工具会生成 model.rs 和 model.bpk，运行时直接加载生成结果即可，不需要额外的图解释器。对想把模型部署进纯 Rust 工程的人来说，这条路线很有吸引力。

迁移也很直接

旧的 burn-import 现在可以切到 burn-onnx = "0.21"。如果你之前就在关注 Burn 的模型导入能力，这次独立发布基本可以看成它进入更成熟阶段的信号。

原文链接：https://burn.dev/blog/release-burn-onnx-0.21.0/

Toasty 0.6.0 - 新功能发布

Toasty 是 Tokio 生态里一款同时面向 SQL 和 NoSQL 的异步 ORM。它从 4 月第一次发到 crates.io 之后，更新节奏相当快，0.6.0 这一版继续把“易用但不玩具”的路线往前推。

0.6.0 的几个重点更新

• 新增延迟字段（deferred fields）和 .select()，可以更精细地控制查询时到底加载哪些字段
• Vec<标量> 集合字段现在有了更正式的支持：PostgreSQL 用数组，其他 SQL 数据库走 JSON，DynamoDB 走原生列表
• 增加更多查询表达式、数据库原生枚举类型、乐观版本控制和 TLS 支持

这类更新为什么值得看

不少 ORM 在功能越堆越多之后，会变得越来越重。Toasty 现在更像是在补那些真正影响工程体验的能力：字段裁剪、跨数据库一致行为，以及对结构化数据的更自然建模。如果它后面把文档存储能力也补齐，可玩的空间还会更大。

原文链接：https://tokio.rs/blog/2026-05-15-announcing-toasty-0-6-0

Rustrak v0.2.2 发布：移动端 UI、Base UI 迁移

Rustrak 是一个自托管错误追踪服务器，兼容 Sentry SDK，主打单个 Rust 二进制、低空闲占用和可选的 Next.js 仪表板。v0.2.2 这次更新的重点不在“加一个小功能”，而是在把产品体验和依赖底座一起往前推。

这次版本更新了什么

• 仪表板现在完整支持移动端响应式布局
• 问题页和事件详情页增加骨架屏，减少加载时的布局跳动
• UI 组件从 Radix UI / shadcn 迁移到 Base UI
• 修掉了过期下拉菜单状态、侧边栏粘性高度、API 文档链接等几个实际使用中的问题
• JavaScript 侧升级到 TypeScript 6、Node.js 22+，Rust 侧更新到 actix-web 4.13、tokio 1.52、sqlx 0.8.6、sentry 0.48.2

为什么它值得进日报

Sentry 替代品并不少，但“自托管、兼容现有 SDK、单二进制、资源占用克制”这个组合始终有吸引力。Rustrak 这种项目每往前走一步，都会让 Rust 在内部平台和运维工具链里的存在感更强一些。

原文链接：https://github.com/AbianS/rustrak/releases/tag/v0.2.2

Stella Nova - 纯 Rust 开发的 N 体引力模拟器

作者 Dave 分享了自己的项目 Stella Nova：一个完全用 Rust 和 wgpu 构建的太空殖民地管理模拟器。它最抓人的地方，是把“游戏演示”之外的那部分工程难题也一起摆到了台前。

目前公开出来的几个亮点

• 所有天体都遵循真实的 N 体引力物理系统
• 自研的 WarpCore 引擎可以稳定处理数千个实体
• 支持霍曼转移轨道规划、模块化空间站建造、公民 AI 和时间膨胀控制
• 安装包体积控制在 500MB 以下

为什么这条会让人多看一眼

Rust 游戏项目并不罕见，但把渲染、模拟、实体规模和系统设计一起拧成一个能展示出来的个人项目，传播性会强很多。对社区来说，这种作品既能证明语言生态的上限，也更容易吸引圈外开发者点进去看看到底做到了什么程度。

原文链接：https://www.reddit.com/r/rust/comments/1tdz2qn/built_an_nbody_gravity_simulator_entirely_in_rust/

• DataGrip：好用但开机吃 800MB
• TablePlus：免费版只能开两个连接
• Another Redis Desktop：能用，但和 DataGrip 一起跑机器就开始喘
• Sequel Pro 早就不维护了

每次开发都要在好几个 Electron 之间切来切去，风扇起飞，键盘发烫

所以我做了一个：Ramag

设计理念就两句话：minimal by design · local by default

GitHub：https://github.com/Linyuqiz/ramag

它能做什么

一个 macOS 原生应用，目前装了两个工具：

数据库客户端（MySQL / PostgreSQL）

• 连接管理 + 表结构树
• SQL 编辑器：关键字 + 表名 + 列名补全，语法高亮
• 多语句执行，可中断（点查询出去就能 Cancel）
• 结果集行内编辑：双击单元格就改，自动生成 INSERT / UPDATE / DELETE
• 排序 / 过滤 / 导出 CSV / JSON / Markdown / SQL
• 查询历史

Redis 客户端

• 6 种类型全支持：String / List / Hash / Set / ZSet / Stream
• Key Trie 树：自动按 : 分组（比如 user:1001:profile 会折叠成层级）
• TTL 可视化编辑
• 内存估算（每个 key 占多少字节一眼看到）
• DB 切换

为什么值得一试

不吃内存：原生 Rust 二进制，常驻 < 100MB（DataGrip 是它 8 倍）

开机快：1 秒内就启动了，不用看着 splash 转圈

密码安全：连接密码存 macOS 钥匙串 + AES-GCM 加密落盘，不是明文 JSON

离线可用：不联网、不收集、不上传，所有数据本地

技术栈

• Rust nightly + GPUI（来自 Zed，原生 macOS UI）
• sqlx（MySQL / Postgres）+ redis-rs
• redb 本地存储 + macOS 钥匙串 + aes-gcm
• 单二进制 < 20MB，DMG 安装

详细架构见 docs/architecture.md

Bun 项目用 Rust 重写的分支已经正式合并进主代码库。这不是一个“概念验证”式的小实验，而是 Bun 主线工程演进的一次明确落地。

这条消息值得关注的点

• Rust 重写分支已经合并，说明相关工作进入了更接近主线交付的阶段
• 官方表示后续会发布更详细的技术博客，解释这次重写背后的设计与实现细节
• 在进入非 canary 正式版本前，仍然还有一些性能优化工作要完成
• 此外还会有一批后续 PR 继续做清理和收尾

对 Rust 社区来说，这类成熟项目把关键部分逐步迁到 Rust，通常比“新项目发布”更容易形成外溢影响：既能带来工程信号，也更容易让圈外开发者重新关注 Rust 在基础设施里的位置。

原文链接：https://www.reddit.com/r/rust/comments/1tcrmjs/rewrite_bun_in_rust_has_been_merged/

Zyx v0.153 发布：用 Rust 从零开始构建的机器学习库

作者分享了他花费数年开发的 Rust 机器学习库 Zyx。这个项目的目标不小：从底层后端到高级神经网络模块，尽量用一套纯 Rust 技术栈把完整 ML 框架搭起来。

目前最有看点的部分

• 已完整实现 CUDA、OpenCL、WGPU 后端，PTX、HIP 和 SPIR-V 也已有部分实现
• 提供 Python 绑定，而且 wheel 体积只有约 4MB
• 借鉴 tinygrad 的思路，仅用 9 类基础节点表达全部 PyTorch 操作
• 项目与依赖总代码量大约 5 万行，整体依赖相当克制

设计上的亮点

• 支持动态图与分支，但采用延迟执行模型
• 优化流程可选且可自由组合，包括寄存器分块、CSE、DCE、LICM 等
• 自动微分能力已经具备
• 作者希望它最终成为一个“能在各种硬件上正确运行各种模型”的精简运行时

现阶段的现实情况

性能还没有彻底打磨完成。作者给出的例子里，在 RTX 2060 上跑 MNIST 时，Zyx 每步约 0.9ms，编译后的 PyTorch 约 0.7ms。接下来它还会继续补自动调优、图分割和模式匹配这几块。

原文链接：https://www.reddit.com/r/rust/comments/1td7242/zyx_v0153_released_ml_from_scratch_in_rust/

Scena 1.0.1 发布：Rust 原生 3D 场景图渲染器

Scena 是一个 Rust 原生 3D 场景图渲染器，目标很直接：把类似 Three.js 的模型查看与场景组织工作流，带进 Rust 的原生与浏览器图形开发环境。

它现在已经具备的能力

• 支持 glTF / GLB 加载
• 提供类型化的场景图状态管理
• 采用显式的 prepare() / render() 生命周期
• 支持原生与浏览器两条渲染路径
• 可运行在 WebGPU / WebGL2 环境中
• 支持无头渲染，适合测试与 CI 场景

为什么这类项目值得看

Rust 图形生态里一直不缺底层能力，但“易上手、结构清晰、面向真实场景工作流”的 3D 场景层并不算多。Scena 想补的正是这块空白：不是只展示某个底层 API，而是把资源、场景、渲染器和交互整合成一套更完整的开发体验。

原文链接：https://www.reddit.com/r/rust/comments/1tden04/scena_a_rustnative_3d_scenegraph_renderer/

优化 image-rs 中的模糊算法，实现 5 倍性能提升

作者对 Rust image 库里的 fast_blur 做了一轮很漂亮的性能优化。在处理 u8 像素图像时，多个典型参数下都实现了大约 5 倍的加速。

优化结果

• σ=3：从 51.1ms 降到 8.6ms，约 5.9 倍
• σ=7：从 51.5ms 降到 9.0ms，约 5.7 倍
• σ=50：从 52.2ms 降到 10.2ms，约 5.1 倍

关键思路

作者做完 profile 之后发现，热点主要集中在浮点转换、roundf 和 min/max 这些操作上。于是核心优化方向很明确：在 u8 图像场景里，尽量用整数运算替代浮点运算。

这样做之后：

• 省掉了大量浮点转换
• 避免了高频 roundf 调用
• 也减少了范围限制相关的额外开销

这类文章的价值不只是“某个函数更快了”，而是再次提醒大家：很多性能瓶颈并不在算法名字本身，而在实现细节里的数据表示与运算方式。

原文链接：https://apas.tel/blog/optimizing-image-rs-blur

Batata 是一个基于 Rust 实现的高性能动态服务发现、配置管理和服务管理平台。完全兼容 Nacos V2/V3、grpc API 和 Consul API，可作为云原生应用的理想替代方案。

特性

核心能力

• 配置管理 - 集中式动态配置，支持实时更新
• 服务发现 - 服务注册、发现和健康检查
• 命名空间隔离 - 基于命名空间的多租户资源隔离
• 集群模式 - 基于 Raft 共识协议的高可用方案

API 兼容性

• Nacos API - 完全兼容 Nacos V2 和 V3 API（V1 API 不支持）
• Consul API - 兼容 Consul Agent、Health、Catalog、KV 和 ACL API
• gRPC 支持 - 高性能双向流式通信，支持 SDK 客户端

高级特性

• 配置导入/导出 - 支持 Nacos ZIP 和 Consul JSON 格式的批量配置迁移
• 灰度发布 - 支持配置的渐进式发布
• 认证与授权 - 基于 JWT 的认证和 RBAC 权限模型，支持 LDAP、OAuth2/OIDC
• 限流 - 可配置的 API 限流保护
• 熔断器 - 故障容错的弹性模式
• 监控与可观测性 - 兼容 Prometheus 的指标端点
• 服务网格 - xDS 协议支持 (EDS, CDS, LDS, RDS, ADS)
• 多数据中心 - 地域感知复制与跨数据中心同步
• DNS 服务 - 基于 UDP 的 DNS 服务发现
• 分布式锁 - 基于 Raft 的分布式锁
• AI 集成 - MCP (模型内容协议) 和 A2A (Agent-to-Agent) 注册中心

性能优势

• 快速启动 - 约 1-2 秒（对比 Java 版 Nacos 的 30-60 秒）
• 低内存占用 - 约 50-100MB（对比 Java 版 Nacos 的 1-2GB）
• 高吞吐量 - 基于 Tokio 运行时的异步 I/O 优化
• 高效存储 - 使用 RocksDB 持久化存储，配合优化的缓存策略

与 Nacos 功能对比

Batata 已实现 ~98% 的 Nacos 功能，可作为生产环境的替代方案。

Pyrefly 是一个用 Rust 编写的 Python 类型检查器和语言服务器，如今已经来到稳定的 v1.0，可正式用于生产环境。这个项目自 2025 年中发布 alpha、同年 11 月进入 beta 之后，已经连续迭代了 60 多个小版本。

这次 1.0 值得关注的点

• 已被 Meta 的 Instagram 开发团队采用，也进入了 PyTorch、NumPy、Pandas、JAX 等大型代码库的工作流
• 相比 beta 阶段，PyTorch 上的完整类型检查速度提升约 34%
• 编辑器里的增量诊断更新最高可快 125 倍，官方给出的 PyTorch 实测延迟从 2.4 秒降到 19 毫秒
• 新增 basic / legacy / strict 等预设，降低首次接入门槛，也更方便从 mypy / pyright 迁移
• 继续扩展对 Pydantic、Django、IDE 场景以及 AI 编码工作流的适配

为什么它会成为今天的头条

一方面，这是一个 Rust 写成、并且真正打进主流 Python 开发生态的基础工具；另一方面，Pyrefly 这次已经不只是“又一个类型检查器”，而是在性能、误报控制和 IDE 体验上，开始形成自己的产品辨识度。

原文链接：https://pyrefly.org/blog/v1.0/

gpu-video 0.4.0 发布：新增 H.265 编码器，AV1 也在路上

gpu-video（原名 vkvideo）是一个与 wgpu 集成的硬件视频编解码库，核心目标是把 Vulkan Video 的能力以更顺手的 Rust API 暴露出来。这次 0.4.0 更新，最值得看的有两件事：编码器架构重构，以及 H.265 编码支持正式落地。

主要更新

• 编码器代码被拆成“驱动决策层 + 编解码器特定 trait”两部分，后续扩展其他编码格式会容易很多
• 新增 H.265 / HEVC 编码器，在低码率下相比 H.264 有明显画质优势
• 项目团队已经把下一步目标放到 AV1 编码支持上
• 这是项目改名为 gpu-video 之后的首个版本，也意味着它的目标不再只局限在 Vulkan 这个品牌名称之下

一个值得继续观察的方向

这类“视频编解码 + wgpu + 不离开 GPU 内存”的 Rust 基础设施，正在慢慢变成图形、多媒体和实时处理场景里的关键拼图。对做播放器、转码链路、视频合成或可视化工具的人来说，gpu-video 的可用性会越来越有意思。

原文链接：https://www.reddit.com/r/rust/comments/1tc21kd/gpuvideo_formerly_vkvideo_040_a_new_encoder/

QRISM：8 色二维码把容量拉到传统 QR 的 3 倍

QRISM 是一个很抓眼球的实验项目：它不满足于传统黑白二维码，而是把黑、白、蓝、黄、红、绿、品红、青 8 种颜色一起拉进编码系统里。因为每种颜色可以表示 3 比特信息，理论上就能把单个二维码的容量提升到传统 QR 的 3 倍。

这个想法为什么有意思

• 它没有完全推翻 QR 体系，而是尽量沿用现有 ISO QR 规范里的码字结构、纠错块、掩码和对齐图案
• 读码器实现也不是停留在概念验证，作者强调自己在可靠性和性能上做了很多工作
• 按作者描述，当前读取器在测试中已经优于 rqrr，并接近 zxing 的基准质量

现阶段要怎么理解它

这还不是一个“明天就能用手机相机扫起来”的标准替代品，更像是一个很典型的 Rust 社区项目：把底层编码、图像处理和工程实现缝在一起，做出一个足够完整、又足够有想象力的原型。

原文链接：https://www.reddit.com/r/rust/comments/1tb272i/qrism_a_high_capacity_qr_code/

mpsc 通道的隐藏成本：Tokio 每条通道默认先吃掉 32 个槽位

这篇文章不是新库发布，而是一篇非常有含金量的性能分析。作者在排查 Rust 反向代理的内存占用时发现，Tokio 的 mpsc 通道即使只设容量 1，实际也会先为 32 个元素预分配空间。

文章里最关键的发现

• BigStruct 大小约 1024 字节时，创建通道后实际直接吃掉约 32KB，而不是直觉里的 1KB
• 初始内存成本近似等于“消息大小 × 32 + 额外固定开销”
• 这个行为来自 Tokio mpsc 内部按 32 个元素为一个 block 进行分配
• 对低吞吐、但通道数量很多的系统来说，这个默认策略可能带来相当可观的内存浪费

为什么值得 Rust 开发者看

很多人会把通道容量理解成“我想缓冲多少条消息”，但底层实现的真实成本经常不是这么算的。这篇文章把问题拆得很清楚，也提醒了我们：性能优化里，抽象背后的实现细节往往比 API 名字更重要。

原文链接：https://blog.howardjohn.info/posts/mpsc-cost/

IBM s390 成为最新获得 Linux 内核 Rust 支持的 CPU 架构，排在 x86_64、ARM、ARM64、LoongArch 和 RISC-V 之后，成为第六个进入这一名单的架构。

关键进展

• IBM 工程师 Jan Polensky 提交了首批补丁系列
• 这批改动规模不大，主要是把 s390 配置成支持 Rust 的 64 位架构
• 同时补上 Rust 所需的汇编接口，用于 WARN / BUG 报告以及静态分支
• 还调整了 bindgen 参数，以避免结构体布局冲突

当前状态

• s390 目前仍需要 nightly rustc，因为还依赖 -Zpacked-stack
• 补丁正在审查中
• 由于修改量相对克制，有机会进入接下来的 Linux v7.2 内核开发周期

原文链接：https://www.phoronix.com/news/IBM-s390-Linux-Kernel-Rust

ALint：代码仓库结构和规范检查工具

ALint 是一个用 Rust 编写的仓库结构与规范检查工具，关注的是文件系统层面的约束，而不是传统代码语法或风格检查。它填补了 Repolinter 在 2026 年初停止维护后留下的空白。

核心能力

• 通过单个 .alint.yml 文件声明仓库应有的结构、命名、内容和跨文件关系
• 支持 60 种规则类型，覆盖文件存在性、内容、命名、结构、安全、编码、Git 规范等场景
• 内置 19 个规则集，包含 rust、node、python、go、java、GitHub Actions、monorepo 等常见生态
• 支持 JSONPath 规则、跨文件关系检查，以及面向 AI 代理的结构化输出
• 提供 12 种自动修复操作，可先 --dry-run 预览再实际应用

性能表现

• 10 万文件规模的工作区大约 1.1 秒完成检查
• 100 万文件规模大约 12 秒
• 在真实仓库场景里，完整检查甚至可以做到比一次 git status 还快

原文链接：https://alint.org

AudioNimbus v0.14.0 发布：加入 Bevy 集成与多线程工具箱

AudioNimbus 是 Steam Audio 的 Rust 安全包装器，这次 0.14.0 更新把重点放在 Bevy 集成和仿真管线能力上。

主要更新

• 新增 bevy 模块，提供与 Bevy ECS 的一流集成
• SpatialAudioPlugin 会自动处理核心资源插入、仿真运行器生成，以及场景、探针、监听器和音源同步
• 新增 wiring 模块，用来构建符合最佳实践的多线程仿真管线
• 提供不同抽象层级，既能覆盖简单用例，也能满足更复杂的高级场景

破坏性变更

• 反射算法类型从原有设置改为类型化结构体
• 增加 *_subset 方法，只对请求的仿真类型进行阻塞
• 多个类型不再携带生命周期参数，改为拥有数据
• 回调函数现在要求 Fn + Send + Sync

原文链接：https://github.com/MaxenceMaire/audionimbus/releases/tag/0.14.0

cloakrs：超快速的 PII 检测和脱敏工具

cloakrs 是一个用 Rust 编写的库和命令行工具，用来检测并屏蔽文本、日志、JSON、CSV 以及数据库转储文件中的个人身份信息（PII）。

主要特性

• 支持识别电子邮件、信用卡号、电话号码、IBAN、社会安全号等常见敏感信息
• 同时覆盖多种地区特定标识符，不只是通用字段匹配
• 可以处理文本、JSON、CSV、日志文件和 SQL 转储文件
• 不仅依赖正则，还会结合实际校验机制（如 Luhn、MOD 97、MOD 11）来降低误报率

性能与状态

• 在 M2 芯片上扫描 10 万行数据约需 0.5 秒
• 适合本地快速扫描和分享前脱敏场景
• 项目刚发布 v0.1.0，作者正在收集反馈

原文链接：https://github.com/kadir/cloakrs

Features Async-First Design: Built from ground up for async/await with Tokio integration Zero-Copy: Efficient buffer management using the bytes crate Lock-Free Buffer Pool: High-performance memory management with crossbeam Connection-Oriented: High-level connection abstractions (KcpStream, KcpListener) Protocol Compatible: Compatible with original C KCP implementation Observability: Integrated tracing and metrics support Memory Efficient: Object pooling and buffer reuse Multiple Performance Modes: Normal, Fast, Turbo, Gaming presets Installation Add this to your Cargo.toml:

[dependencies] kcp-tokio = "0.4" tokio = { version = "1.0", features = ["full"] } Quick Start Client use kcp_tokio::{KcpConfig, KcpStream}; use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main] async fn main() -> Result<(), Box> { let config = KcpConfig::new().fast_mode(); let mut stream = KcpStream::connect("127.0.0.1:12345".parse()?, config).await?;

// Send data
stream.write_all(b"Hello, KCP!").await?;

// Receive response
let mut buffer = [0u8; 1024];
let n = stream.read(&mut buffer).await?;
println!("Received: {}", String::from_utf8_lossy(&buffer[..n]));

Ok(())

} Server use kcp_tokio::{KcpConfig, KcpListener}; use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main] async fn main() -> Result<(), Box> { let config = KcpConfig::realtime(); let mut listener = KcpListener::bind("127.0.0.1:12345".parse()?, config).await?;

println!("Server listening on 127.0.0.1:12345");

while let Ok((mut stream, addr)) = listener.accept().await {
    println!("New connection from {}", addr);
    tokio::spawn(async move {
        let mut buf = [0u8; 1024];
        while let Ok(n) = stream.read(&mut buf).await {
            if n == 0 { break; }
            let _ = stream.write_all(&buf[..n]).await;
        }
    });
}

Ok(())

} Architecture ┌─────────────────────────────────────────────────────────────┐ │ Application Layer │ │ (User code using KcpStream/KcpListener) │ ├─────────────────────────────────────────────────────────────┤ │ High-Level API Layer │ │ KcpStream KcpListener │ │ (AsyncRead/AsyncWrite, TCP-like interface) │ ├─────────────────────────────────────────────────────────────┤ │ Protocol Core Layer │ │ KcpEngine │ │ (ARQ logic, congestion control, retransmission) │ ├─────────────────────────────────────────────────────────────┤ │ Common Layer │ │ KcpSegment, KcpHeader, BufferPool, Constants │ ├─────────────────────────────────────────────────────────────┤ │ Transport Layer │ │ Generic Transport trait (UDP default) │ └─────────────────────────────────────────────────────────────┘ Configuration Performance Presets // Gaming - ultra-low latency (3ms update interval) let config = KcpConfig::gaming();

// Real-time communication (8ms update interval) let config = KcpConfig::realtime();

// File transfer - high throughput let config = KcpConfig::file_transfer();

// Testing with packet loss simulation let config = KcpConfig::testing(0.1); // 10% packet loss Performance Modes Mode Update Interval Resend Congestion Control Use Case Normal 40ms 0 Yes General purpose Fast 8ms 2 Yes Low latency Turbo 4ms 1 No Maximum speed Gaming 3ms 1 No Real-time games Custom Configuration use std::time::Duration;

let config = KcpConfig::new() .fast_mode() .window_size(128, 128) .mtu(1400) .connect_timeout(Duration::from_secs(10)) .keep_alive(Some(Duration::from_secs(30))) .stream_mode(true); Examples

Run performance test server

cargo run --example perf_test_server -- 127.0.0.1:12345 gaming

Run performance test client

cargo run --example perf_test_client -- 127.0.0.1:12345

Run simple echo example

cargo run --example simple_echo Testing

Run all tests

cargo test

Run resilience tests (packet loss, reorder, concurrent connections)

cargo test --test resilience_test

Run benchmarks

cargo bench

Run with logging

RUST_LOG=debug cargo test -- --nocapture

Run clippy

cargo clippy --all-targets -- --deny clippy::all Documentation Detailed documentation is available in the doc/ directory:

Document Description ARCHITECTURE.md System architecture and design MODULES.md Module reference and APIs USAGE.md Usage guide and examples TESTING.md Testing guide Performance KCP provides significant latency improvements over TCP:

30-40% lower latency in typical network conditions Better performance on lossy networks Configurable trade-offs between latency and bandwidth Optimizations in this Implementation Actor-based lock-free architecture: KcpEngine runs in a single dedicated tokio task, eliminating Arc<Mutex<>> contention Generic Transport trait: Associated Addr type with RPITIT — zero heap allocation on hot path (no Pin<Box>) DashMap for packet routing: Listener uses lock-free concurrent hashmap on the hot path Lock-free buffer pools: crossbeam::queue::ArrayQueue for zero-allocation fast path BTreeMap receive buffer: O(log n) insertion for out-of-order packets (vs O(n) linear scan) Zero-copy segment encoding: Flush avoids cloning segments, encodes by reference Cached timestamps: Single syscall per input() call instead of 3+ Pre-allocated buffers: VecDeque::with_capacity based on window sizes, avoiding grow overhead on send burst Zero-copy packet handling with bytes crate Grouped state structs for better cache locality Configurable update intervals (3-40ms) Batch ACK processing Use Cases Gaming: Ultra-low latency for real-time multiplayer VoIP/Video: Real-time communication Live Streaming: Low-latency data delivery File Transfer: Reliable bulk data transfer IoT: Efficient communication for constrained devices Compatibility Protocol: Compatible with original C KCP Rust: Edition 2021, stable toolchain Tokio: 1.0+ License MIT License - see LICENSE file.

Contributing Contributions are welcome! Please feel free to submit a Pull Request.

Resources Original KCP Protocol KCP Protocol Documentation Tokio Documentation Benchmarks Criterion benchmarks measure engine-level throughput and latency:

cargo bench Benchmark Description engine_throughput 10/100/500 x 1KB messages engine_small_messages 1000 x 64B messages engine_large_message Single 16KB/64KB message fragmentation + reassembly Version History v0.4.0: Extract kcp-core as standalone protocol crate, restructure source layout (src/ → kcp/, flatten async_kcp/) v0.3.7: Fix ACK window/UNA fields, generic Transport trait with RPITIT, resilience tests, criterion benchmarks v0.3.4: Engine refactoring, lock-free buffer pools, documentation v0.3.3: Performance optimizations, sub-millisecond latency v0.3.1: Full async support, comprehensive configuration v0.2.x: Performance improvements and bug fixes v0.1.x: Initial implementation

核心能力

• 混合架构：兼顾 B+ 树读速与 LSM 树写吞吐
• MVCC 并发：非阻塞的并发读写
• 闪存优化：面向 SSD/NVMe 的 log-structured 设计
• 大值分离：独立 Blob 存储，减少写放大
• ACID 事务：完整的事务支持

性能数据

注：以上为与 RocksDB 对比的中位数倍数。

适用场景

• 需要高并发读写的嵌入式服务（尤其是 mixed/read-heavy 负载）
• 写入吞吐敏感的本地存储层（中小 value 场景优势更明显）
• 混合读写 + 扫描的业务
• 需要本地事务和 MVCC 的 Rust 应用

地址

• 源码：https://github.com/abbycin/mace
• Benchmark 脚本：https://github.com/abbycin/kv_bench（scale 分支）

mace 还在非常早期的阶段，目前还在努力提升稳定性以及对特定workload进行优化...

0.0.29 版更新

Rudis 是一个采用 Rust 语言编写得高性能键值存储系统，旨在利用 Rust 语言的优势来重新复现 Rudis 的核心功能，以满足用户对高性能、可靠性和安全性的需求，同时保证与 Rudis API 的兼容。

跨平台，兼容 windows、linux 系统架构。 兼容 字符串、集合、哈希、列表、有序集合数据结构。 提供 rdb 与 aof 机制以支持数据备份和恢复。 拥有卓越的处理速度和即时响应能力。 兼容 Rudis 的命令和协议规范。

欢迎在 GitHub 上关注我们的项目发展轨迹：

👉 https://github.com/lunar-landing/rudis

更新日志：

• 新增 List 数据结构 Blpop、Brpop 命名。
• 新增 Hash 数据结构 HSCAN 命令，支持 MATCH 和 COUNT 参数。
• 新增 String 数据结构 SETEX、PSETEX、SETNX、SETBIT、GETBIT、BITCOUNT、BITOP 命令。
• 新增 Set 数据结构 SRANDMEMBER、SDIFFSTORE、SINTERSTORE、SMOVE 命令。
• 新增 HyperLogLog 数据结构及 PFADD、PFCOUNT、PFMERGE 命令。
• 重构 SortedSet 底层实现，采用 HashMap + SkipList 架构提升性能，并支持 bincode 序列化。
• 修复 SETEX/PSETEX 过期记录清理逻辑以及系统时间倒退导致的 RDB 调度 Panic 问题。

这几年接私活、做外包、做独立项目，有一个问题一直困扰我：

我们其实不知道一个项目「合理的价格」是多少。

不是技术难度不知道，而是——
你不知道别人真实成交是多少，只能靠猜、靠平台最低价、靠「听说」。

需求方会说：

「别人比你便宜一半。」

开发者只能纠结：

「我是报高了，还是别人报低了？」

时间久了，就变成大家都在往下试探，
内卷不是某个人的选择，而是信息不透明的结果。

我已经做了什么

我先从自己开始。

我把自己这几年做过的一些真实项目整理出来，包括：

• 项目类型
• 实际成交价格
• 大概工期
• 是否反复改需求
• 是否包含售后

做成了一个 独立开发者行情板。

目前一共 23 个案例：

• 大部分是我自己的真实成交
• 少部分是朋友的
• 也有几个是匿名提交的

我不回避这个事实：
数据现在还很少，而且并不「漂亮」。

但它至少是真实的。

为什么我需要更多人，而不是「更多数据」

我一个人的案例，其实没什么意义。

但如果有：

• 50 个
• 100 个
• 200 个

来自不同背景、不同技术栈、不同城市的真实案例，
至少可以做到一件事：

让后来的人，在报价时有一个不被平台最低价绑架的参考。

你不需要证明你多厉害，
也不需要报一个「体面」的价格，
真实比好看重要。

关于匿名和安全

我知道大家最担心什么，所以我一开始就做了两件事：

• 提供 匿名提交
• 不要求任何可追溯身份信息

目前有两个入口：

飞书表单 行情板网站

不署名、不展示来源、不做商业售卖。
你可以只写你愿意写的字段。

说一句更远一点的想法（不画饼）

行情板不是终点。

我真正想做的，是一个 不竞价、不抽佣、不负责售后 的撮合平台，
只做一件事：

把预算真实的需求方，和愿意按合理价格做事的开发者，匹配到一起。

行情板只是前战，是定价共识的基础。
如果连「合理价格区间」都没有，
任何撮合都会退化成比谁便宜。

我不确定这条路能走多远，
但至少想先试一次。

最后

如果你愿意贡献一个案例：

• 成功的
• 失败的
• 觉得自己报低了的
• 或者被压价压得很难受的

都可以。

如果你不想提交，也没关系，
至少希望这个东西能让你下次报价时，心里多一点底气。

• 算力层聚合：广泛接入全球闲散 GPU 算力资源，通过标准化调度技术实现算力的统一管理与高效利用；

• 服务层赋能：在聚合算力之上深度部署 MaaS 模型服务，客户无需投入高昂成本搭建算力与模型架构，只需通过简洁的大模型接口，即可按需调用 AI 能力，快速赋能业务创新。

算纽（GPUNexus）打通算力资源与模型应用的壁垒，让 AI 服务更便捷、更普惠。

2. 产品形态

2.1. 算力资产分享

算纽算力资产分享产品，核心打破算力孤岛，依托智能调度技术，实现各类计算资源一键接入、整合与统一调度，激活分散算力价值。

产品支持全场景接入，覆盖算力中心、企业服务器等专业设备及个人电脑、手机等终端，实现“云-边-端”全域覆盖。无论闲置算力拥有方（企业/机构/个人）还是算力需求方，均可通过平台精准匹配、高效流转。

无需复杂配置即可快速上线，智能调度实现供需实时匹配，既提升算力利用率，又帮助需求方降本、分享方变现，构建互利共赢的算力生态。

2.2. MAAS服务

算纽 MaaS服务，一站式整合30 余款主流开源大模型矩阵，囊括 DeepSeek、Qwen、GLM、Kimi、MiniMax 等明星模型，深度覆盖编程开发、学术研究与论文创作、数学推理、视觉处理与多模态交互、对话与长文本处理五大核心场景。

2.3. 开发者套餐

算纽开发者套餐，专为学生、独立开发者及中小团队量身定制，以超高性价比解锁顶级大模型编程能力，让每一份开发需求都能高效落地。

套餐核心优势直击开发痛点：成本颠覆性降低，计费低至传统tokens计费的一折，大幅压缩开发成本；模型自由切换，无需冗余购买多平台会员，一键直达GLM-4.7、MiniMax-M2.1、Kimi-K2三大顶级编程模型，最新最强的模型能力随心选；高效创作不等待，生成速度媲美同类高级套餐，助力快速完成代码编写、调试、优化等核心工作。

更有7天免费体验限时开启！零成本即可抢先体验顶级模型的强悍编程能力，轻松开启高效开发新体验。

​

• 官方网址：https://gpunexus.com/
• 咨询电话：010-53650986
• 联系邮箱：data@chengfangtech.com

一个终端看板应用，灵感来自 Helix 编辑器的键位设计。

预览

特性

• 📁 基于文件存储 - 使用 Markdown 文件和 TOML 配置，易于版本控制
• 🎯 多项目支持 - 支持全局项目和本地项目（.kanban/）
• ⌨️ Helix 风格键位 - 符合直觉的键盘快捷键
• 🪟 窗口管理 - 支持垂直/水平分屏，同时查看多个项目，自动保存和恢复工作区布局
• 🎨 现代 TUI - 基于 ratatui 的美观终端界面
• 📝 Markdown 支持 - 任务使用 Markdown 格式，支持外部编辑器
• 🔍 任务预览 - 内置预览和外部预览工具支持
• ⚙️ 自动配置 - 首次运行自动检测编辑器和预览器

安装

从 crates.io 安装

cargo install helix-kanban

从源码构建

git clone https://github.com/menzil/helix-kanban.git
cd helix-kanban
cargo build --release

快速开始

首次运行会显示欢迎对话框，自动检测系统编辑器和 Markdown 预览器：

hxk

输入法切换（macOS）

为了更好的输入体验，在正常模式下自动切换到英文输入法，在对话框模式（如创建/编辑任务）时保持用户的输入法。

推荐安装 im-select 工具：

# 使用 Homebrew 安装
brew install im-select

# 或者使用 curl 安装
curl -Ls https://raw.githubusercontent.com/daipeihust/im-select/master/install_mac.sh | sh

注意：如果不安装 im-select，程序仍可正常运行，只是不会自动切换输入法。

配置管理

查看当前配置：

hxk config show

设置编辑器：

hxk config editor nvim
hxk config editor "code --wait"

设置 Markdown 预览器：

hxk config viewer glow
hxk config viewer "open -a Marked 2"

键位绑定

基础导航

任务操作

项目管理

窗口管理

命令模式

按 : 进入命令模式，支持的命令：

• :q / :quit - 退出应用
• :open / :po - 打开项目
• :new / :pn - 创建新项目（全局）
• :new-local / :pnl - 创建新项目（本地）
• :add / :tn - 创建新任务
• :edit / :te - 编辑任务
• :view / :tv - 预览任务
• :reload / :r / :refresh - 重新加载当前项目
• :reload-all / :ra / :refresh-all - 重新加载所有项目
• :vsplit / :sv - 垂直分屏
• :hsplit / :sh - 水平分屏
• :help / :h - 显示帮助

数据存储

全局项目

全局项目存储在 ~/.kanban/projects/ 目录下。

本地项目

在任何目录下按 n 创建本地项目，会在当前目录的 .kanban/ 下存储：

your-project/
├── .kanban/
│   └── kanban-project/
│       ├── .kanban.toml
│       ├── todo/
│       ├── doing/
│       └── done/
└── ... (你的其他文件)

项目结构

project-name/
├── .kanban.toml          # 项目配置
├── todo/                 # Todo 任务
│   ├── 001.md
│   └── 002.md
├── doing/                # 进行中任务
│   └── 003.md
└── done/                 # 完成的任务
    └── 004.md

任务文件格式

任务以 Markdown 格式存储：

# 任务标题

created: 2025-12-10T10:30:00+08:00
priority: high

任务的详细描述内容...

## 子任务

- [ ] 子任务 1
- [x] 子任务 2

配置文件

应用配置存储在 ~/.kanban/config.toml：

editor = "nvim"
markdown_viewer = "glow"

# 隐藏的全局项目列表（软删除）
hidden_projects = ["old-project", "archived-project"]

工作区状态保存

应用会自动保存窗口布局和工作状态，下次启动时恢复：

保存内容：

• 分屏结构（垂直/水平分割）
• 每个窗格打开的项目
• 当前选中的列和任务
• 聚焦的窗格

保存位置：

• 全局工作区：~/.kanban/workspace.toml - 在任何目录启动时使用
• 本地工作区：.kanban/workspace.toml - 在项目目录下启动时优先使用

使用场景：

• 经常需要同时查看多个项目？设置好分屏布局后，下次启动自动恢复
• 在不同项目目录工作？每个目录都有自己独立的工作区布局
• 想要重置布局？使用命令 :reset-layout 恢复默认单窗格

示例工作区配置 (workspace.toml)：

# 自动生成，通常无需手动编辑
focused_pane = 2
next_pane_id = 4

[[panes]]
id = 0
type = "horizontal_split"
left = 1
right = 2

[[panes]]
id = 1
type = "leaf"
project = "work-project"
selected_column = 1
selected_task_index = 0

[[panes]]
id = 2
type = "leaf"
project = "personal-project"
selected_column = 0
selected_task_index = 2

开发

# 运行开发版本
cargo run

# 运行测试
cargo test

# 构建 release 版本
cargo build --release

致谢

• 键位设计灵感来自 Helix Editor
• UI 框架使用 ratatui

许可证

MIT OR Apache-2.0

今天的核心主题是：如何利用 Rust 过程宏的强大能力，将这些繁琐的持久化逻辑自动化，让开发者只需声明字段，即可获得健壮的乐观锁支持。

宏架构：分治与协作

实现一个完整的、自动化的乐观锁流程，需要宏在两个不同的代码层面进行注入和协作：

1. 数据变更层 (ActiveModelBehavior)：负责在数据写入数据库前，自动管理版本号 (version) 和时间戳 (updated_at) 的递增/更新。
2. 持久化操作层 (Repository::save)：负责实现核心的原子更新逻辑，即 CAS 检查。

Part 1: ActiveModel 的预处理钩子 (before_save)

这是我们实现乐观锁的第一步：确保在更新操作中，版本号能够正确地 自增。

我们通过宏注入或修改 sea-orm::ActiveModelBehavior Trait 的 before_save 钩子。

宏注入逻辑概览：

// 宏片段：insert_active_model_behavior_impl 的核心逻辑
if need_version {
    let version_stmt = quote! {
        if insert {
            // 插入 (insert=true) 时，版本号初始化为 1
            self.version = Set(1);
        } else if self.is_changed() {
            // 更新 (insert=false) 且模型有业务字段变化时，版本号自增
            let current_version = match self.version {
                Set(v) => *v,
                _ => 0,
            };
            self.version = Set(current_version + 1);
        }
    };
}
// updated_at 逻辑类似：非插入且 is_changed 时设置为当前时间

关键成果： 当我们在 Repository 中执行更新操作时，ActiveModel 已经通过 before_save 确保了两个重要事实：

1. 它携带着我们从数据库中读出的 旧版本号。
2. 它将尝试写入的 version 值，是 旧版本号 + 1。

Part 2: Repository 的原子 CAS 更新 (save 方法)

这是乐观锁实现的核心战场，由 fn create_tenant_save_impl 宏片段生成。其逻辑必须严格遵循 三步走 策略，以处理成功、冲突和首次插入三种情况。

Step 1: 原子 UPDATE (Compare-and-Swap)

我们使用 sea-orm 的 update_many 配合 filter 条件，来实现原子性检查。

我们从聚合根 (entity) 中取出 旧版本（即 current_version），并将其作为 WHERE 子句的一部分。

// 宏片段：create_tenant_save_impl 的核心 CAS 逻辑

// 从聚合获取当前版本（即期望的旧版本）
let current_version = entity_model.#optimistic_lock_field_ident();

// 1) 原子 UPDATE（带 version CAS）
let res = models::Entity::update_many()
    #id_filters // 主键和 TenantId 过滤
    // ⬇️ 核心：只有当数据库中的版本号等于旧版本号时，才允许更新 ⬇️
    .filter(models::Column::#optimistic_lock_col_ident.eq(current_version)) 
    .set(update_model.clone())
    .exec(&conn)
    .await?;

if res.rows_affected > 0 {
    // 成功！说明版本匹配，且更新成功写入
    // ... 事件处理并返回 Ok(())
    return Ok(());
}

如果 rows_affected > 0，任务圆满完成。如果 rows_affected == 0，则进入下一步判断。

Step 2 & 3: 冲突检测与首次插入

如果 CAS 更新失败（rows_affected == 0），我们需要区分是 版本冲突（记录存在但版本号不匹配）还是 首次插入（记录根本不存在）。

// 2) UPDATE 未命中，检查记录是否存在
if models::Entity::find()
    #id_filters // 仅按主键和 TenantId 查找
    .one(&conn)
    .await?
    .is_some()
{
    // 记录存在，但 Step 1 未命中 -> 乐观锁冲突！
    return Err(#crate_root::domain::RepositoryError::optimistic_lock_error(
        "Optimistic lock conflict: Version mismatch".to_string(),
    ));
}

// 3) 记录不存在，执行首次插入
let insert_model: models::Model = entity_model.clone().try_into()?;
let mut active_model = insert_model.into_active_model();
active_model.insert(&conn).await?;
// ... 事件处理并返回 Ok(())

Talk is cheap, show me the code

before_save

fn insert_active_model_behavior_impl(input: &mut ItemMod, model_config: &ModelConfig) {
  let Some((_, items)) = &mut input.content else {
      return;
  };

  let mut has_active_model_behavior = false;
  for item in items.iter_mut() {
      if let syn::Item::Impl(item_impl) = item
          && let Some((_, path, _)) = &item_impl.trait_
          && path.segments.last().unwrap().ident == "ActiveModelBehavior"
      {
          has_active_model_behavior = true;
          break;
      }
  }

  if !has_active_model_behavior {
      let active_model_behavior_impl = quote! {
          #[async_trait]
          impl ActiveModelBehavior for ActiveModel {
              async fn before_save<C>(mut self, db: &C, insert: bool) -> Result<Self, DbErr>
              where
                  C: ConnectionTrait,
              {
                  Ok(self)
              }
          }
      };
      items.push(parse_quote!(#active_model_behavior_impl));
  }

  for item in items.iter_mut() {
      if let syn::Item::Impl(item_impl) = item
          && let Some((_, path, _)) = &item_impl.trait_
          && path.segments.last().unwrap().ident == "ActiveModelBehavior"
      {
          let mut has_before_save = false;
          for item in item_impl.items.iter_mut() {
              if let syn::ImplItem::Fn(method) = item
                  && method.sig.ident == "before_save"
              {
                  has_before_save = true;
                  break;
              }
          }

          if !has_before_save {
              let before_save_method = quote! {
                  async fn before_save<C>(mut self, db: &C, insert: bool) -> Result<Self, DbErr>
                  where
                      C: ConnectionTrait,
                  {
                      Ok(self)
                  }
              };
              item_impl.items.push(parse_quote!(#before_save_method));
          }

          let need_created_at = model_config
              .fields
              .iter()
              .any(|f| f.ident.as_ref().unwrap() == "created_at");
          let need_updated_at = model_config
              .fields
              .iter()
              .any(|f| f.ident.as_ref().unwrap() == "updated_at");

          let need_version = model_config
              .fields
              .iter()
              .any(|f| f.ident.as_ref().unwrap() == "version");

          if !(need_created_at || need_updated_at || need_version) {
              return;
          }

          for item in item_impl.items.iter_mut() {
              if let syn::ImplItem::Fn(method) = item
                  && method.sig.ident == "before_save"
              {
                  let mut stmts = Vec::new();
                  stmts.push(quote! {
                      let now = chrono::Utc::now();
                  });

                  if need_created_at {
                      let created_at_stmt = quote! {
                          if insert {
                              self.created_at = Set(now);
                          }
                      };
                      stmts.push(created_at_stmt);
                  }
                  if need_updated_at {
                      let updated_at_stmt = quote! {
                          if insert {
                              self.updated_at = Set(now);
                          } else if self.is_changed() {
                              self.updated_at = Set(now);
                          }
                      };
                      stmts.push(updated_at_stmt);
                  }

                  if need_version {
                      let version_stmt = quote! {
                          if insert {
                              self.version = Set(1);
                          } else if self.is_changed() {
                              let current_version = match self.version {
                              Set(v) => *v,
                              _ => 0,
                          };
                              self.version = Set(current_version + 1);
                          }
                      };
                      stmts.push(version_stmt);
                  }

                  let stmts = parse_quote!({#(#stmts)*});

                  // 插入到方法体的开头
                  method.block.stmts.insert(0, stmts);
              }
          }
      }
  }
}

宏生成的代码示例

 impl ActiveModelBehavior for ActiveModel {
        #[allow(
            elided_named_lifetimes,
            clippy::async_yields_async,
            clippy::diverging_sub_expression,
            clippy::let_unit_value,
            clippy::needless_arbitrary_self_type,
            clippy::no_effect_underscore_binding,
            clippy::shadow_same,
            clippy::type_complexity,
            clippy::type_repetition_in_bounds,
            clippy::used_underscore_binding
        )]
        fn before_save<'life0, 'async_trait, C>(
            self,
            db: &'life0 C,
            insert: bool,
        ) -> ::core::pin::Pin<
            Box<
                dyn ::core::future::Future<Output = Result<Self, DbErr>>
                    + ::core::marker::Send
                    + 'async_trait,
            >,
        >
        where
            C: ConnectionTrait,
            C: 'async_trait,
            'life0: 'async_trait,
            Self: 'async_trait,
        {
            Box::pin(async move {
                if let ::core::option::Option::Some(__ret) =
                    ::core::option::Option::None::<Result<Self, DbErr>>
                {
                    #[allow(unreachable_code)]
                    return __ret;
                }
                let mut __self = self;
                let insert = insert;
                let __ret: Result<Self, DbErr> = {
                    {
                        let now = chrono::Utc::now();
                        if insert {
                            __self.created_at = Set(now);
                        }
                        if insert {
                            __self.updated_at = Set(now);
                        } else if __self.is_changed() {
                            __self.updated_at = Set(now);
                        }
                    }
                    Ok(__self)
                };
                #[allow(unreachable_code)]
                __ret
            })
        }
    }

Repository::save

fn create_tenant_save_impl(
    crate_root: &Path,
    aggregate: &Path,
    args: &RepositoryStructArgs,
    id_filters: &TokenStream,
) -> TokenStream {
    // 若指定了乐观锁字段，准备字段名/Column ident
    let optimistic_lock_field = args.optimistic_lock_field.as_ref().map(|lit| {
        let optimistic_lock_field_name = lit.value();
        let optimstic_lock_field_ident = new_id(&optimistic_lock_field_name); // 用于 ActiveModel/Model 字段访问
        let optimistic_lock_col_ident = new_id(&to_pascal_case(&optimistic_lock_field_name)); // 用于 models::Column::Xxx
        (
            optimistic_lock_field_name,
            optimstic_lock_field_ident,
            optimistic_lock_col_ident,
        )
    });

    // 根据是否指定乐观锁字段，生成 save 的实现
    if let Some((
        optimistic_lock_field_name,
        optimistic_lock_field_ident,
        optimistic_lock_col_ident,
    )) = optimistic_lock_field
    {
        if optimistic_lock_field_name == "version" {
            quote! {
                async fn save(
                    &self,
                    txn: &mut TC,
                    entity: &mut #crate_root::domain::EventSourcedEntity<#aggregate>,
                ) -> Result<(), #crate_root::domain::RepositoryError> {
                    use #crate_root::domain::SeaOrmModelUpdater;
                    use sea_orm::{ActiveModelTrait, ColumnTrait, EntityTrait, IntoActiveModel, QueryFilter};
                    use sea_orm::ActiveValue::Set;

                    let conn = txn.get_connection();
                    let entity_model: &#aggregate = entity;

                    let id = entity_model.id();
                    let tenant_id = entity_model.tenant_id();

                    // 从聚合获取当前版本与期望旧版本
                    let current_version = entity_model.#optimistic_lock_field_ident();

                    // 构造用于原子更新的 ActiveModel（只写回必要列）
                    let mut update_model = models::Model::from(entity_model.clone()).into_active_model();

                    // 1) 原子 UPDATE（带 version CAS）
                    let res = models::Entity::update_many()
                        #id_filters
                        .filter(models::Column::TenantId.eq(*tenant_id))
                        .filter(models::Column::#optimistic_lock_col_ident.eq(current_version))
                        .set(update_model.clone())
                        .exec(&conn)
                        .await?;

                    if res.rows_affected > 0 {
                        entity.move_event_to_context(txn);
                        return Ok(());
                    }

                    // 2) UPDATE 未命中，检查记录是否存在（按主键 + tenant）
                    if models::Entity::find()
                        #id_filters
                        .filter(models::Column::TenantId.eq(*tenant_id))
                        .one(&conn)
                        .await?
                        .is_some()
                    {
                        return Err(#crate_root::domain::RepositoryError::optimistic_lock_error(
                            "Optimistic lock conflict: Version mismatch".to_string(),
                        ));
                    }

                    // 3) 记录不存在，插入数据
                    let insert_model: models::Model = entity_model.clone().try_into()?;
                    let mut active_model = insert_model.into_active_model();
                    active_model.insert(&conn).await?;
                    entity.move_event_to_context(txn);
                    Ok(())
                }
            }
        } else {
            // treat as timestamp update_at
            quote! {
                async fn save(
                    &self,
                    txn: &mut TC,
                    entity: &mut #crate_root::domain::EventSourcedEntity<#aggregate>,
                ) -> Result<(), #crate_root::domain::RepositoryError> {
                    use #crate_root::domain::SeaOrmModelUpdater;
                    use sea_orm::{ActiveModelTrait, ColumnTrait, EntityTrait, IntoActiveModel, QueryFilter};
                    use sea_orm::ActiveValue::Set;
                    use chrono::Utc;

                    let conn = txn.get_connection();
                    let entity_model: &#aggregate = entity;

                    let id = entity_model.id();
                    let tenant_id = entity_model.tenant_id();

                    // 读取实体携带的旧时间戳与准备新的时间戳
                    let current_ts = entity_model.#optimistic_lock_field_ident();

                    // 构造用于原子更新的 ActiveModel
                    let mut update_model = models::Model::from(entity_model.clone()).into_active_model();

                    // 1) 原子 UPDATE（带 updated_at CAS）
                    let res = models::Entity::update_many()
                        #id_filters
                        .filter(models::Column::TenantId.eq(*tenant_id))
                        .filter(models::Column::#optimistic_lock_col_ident.eq(current_ts))
                        .set(update_model.clone())
                        .exec(&conn)
                        .await?;

                    if res.rows_affected > 0 {
                        entity.move_event_to_context(txn);
                        return Ok(());
                    }

                    // 2) UPDATE 未命中，检查记录是否存在
                    if models::Entity::find()
                        #id_filters
                        .filter(models::Column::TenantId.eq(*tenant_id))
                        .one(&conn)
                        .await?
                        .is_some()
                    {
                        return Err(#crate_root::domain::RepositoryError::optimistic_lock_error(
                            "Optimistic lock conflict".to_string(),
                        ));
                    }

                    // 3) 记录不存在，直接插入数据
                    let insert_model: models::Model = entity_model.clone().try_into()?;
                    let mut active_model = insert_model.into_active_model();

                    active_model.insert(&conn).await?;
                    entity.move_event_to_context(txn);
                    Ok(())
                }
            }
        }
    } else {
        // no optimistic lock field -> simple update/insert behavior (原始实现)
        quote! {
            async fn save(
                &self,
                txn: &mut TC,
                entity: &mut #crate_root::domain::EventSourcedEntity<#aggregate>,
            ) -> Result<(), #crate_root::domain::RepositoryError> {
                use #crate_root::domain::SeaOrmModelUpdater;
                use sea_orm::{ActiveModelTrait, ColumnTrait, EntityTrait, IntoActiveModel, QueryFilter};

                let conn = txn.get_connection();

                let entity_model: &#aggregate = entity;

                let id = entity_model.id();
                let tenant_id = entity_model.tenant_id();

                if let Some(mut model) = models::Entity::find()
                    #id_filters
                    .filter(models::Column::TenantId.eq(*tenant_id))
                    .one(&conn)
                    .await?
                {
                    if &model.tenant_id != tenant_id {
                        return Err(#crate_root::domain::RepositoryError::mapping_error(
                            format!(
                                "Tenant ID mismatch: expected {}, found {}, id: {}",
                                tenant_id, model.tenant_id, id
                            ),
                        ));
                    }

                    // 更新逻辑
                    model.update_from_aggregate_root(entity_model).await?;

                    let active_model = model.into_active_model();
                    active_model.update(&conn).await?;
                } else {
                    // 创建新记录
                    let model: models::Model = entity_model.clone().try_into()?;
                    let active_model = model.into_active_model();
                    active_model.insert(&conn).await?;
                }

                entity.move_event_to_context(txn);
                Ok(())
            }
        }
    }
}

宏生成的代码示例

  async fn save(
        &self,
        txn: &mut TC,
        entity: &mut core_common::domain::EventSourcedEntity<TenantUser>,
    ) -> Result<(), core_common::domain::RepositoryError> {
        use core_common::domain::SeaOrmModelUpdater;
        use sea_orm::{
            ActiveModelTrait, ColumnTrait, EntityTrait, IntoActiveModel, QueryFilter,
        };
        use sea_orm::ActiveValue::Set;
        use chrono::Utc;
        let conn = txn.get_connection();
        let entity_model: &TenantUser = entity;
        let id = entity_model.id();
        let current_ts = entity_model.update_at();
        let mut update_model = models::Model::from(entity_model.clone())
            .into_active_model();
        let res = models::Entity::update_many()
            .filter(models::Column::Id.eq((id.tenant_id(), id.user_id())))
            .filter(models::Column::UpdateAt.eq(current_ts))
            .set(update_model.clone())
            .exec(&conn)
            .await?;
        if res.rows_affected > 0 {
            entity.move_event_to_context(txn);
            return Ok(());
        }
        if models::Entity::find()
            .filter(models::Column::Id.eq((id.tenant_id(), id.user_id())))
            .one(&conn)
            .await?
            .is_some()
        {
            return Err(
                core_common::domain::RepositoryError::optimistic_lock_error(
                    "Optimistic lock conflict".to_string(),
                ),
            );
        }
        let insert_model: models::Model = entity_model.clone().try_into()?;
        let mut active_model = insert_model.into_active_model();
        active_model.insert(&conn).await?;
        entity.move_event_to_context(txn);
        Ok(())
    }

兼容性处理

宏的另一个优势是其灵活性。它能根据字段名称自动适配不同的乐观锁策略：

• 如果检测到字段为 "version"，则执行版本号的 CAS 逻辑。
• 如果检测到其他时间戳字段如 "updated_at"，则执行基于时间戳的 CAS 逻辑。

结论

通过将 before_save 中的版本递增逻辑，与 Repository::save 中的原子 CAS 检查完美结合，我们使用 Rust 过程宏实现了一个 高内聚、低耦合 的乐观锁基础设施。

开发者现在可以专注于业务逻辑，而将并发控制的复杂性和样板代码完全交给宏来处理。这不仅极大地提高了开发效率，同时也确保了底层持久化操作的健壮性和一致性。

一、乐观锁：不是不锁，而是“巧”锁

数据库的并发控制主要分为悲观锁和乐观锁。

• 悲观锁（Pessimistic Locking）： 假设冲突一定会发生。在读取数据时就对数据行进行锁定，直到事务完成。
• 乐观锁（Optimistic Locking）： 假设冲突很少发生。在整个事务过程中不锁定资源，而是通过检查数据是否被修改来确认。

乐观锁的核心思想是：通过一次原子性的操作来检查并修改数据，而不是依赖两次独立的数据库操作。

二、没有锁的陷阱：丢失更新的竞态条件

让我们以一个 version: i32 字段为例，来看看缺乏原子性操作会导致什么问题。

场景：多人同时更新同一条记录

1. 查询（事务 A/B）： 事务 A 和事务 B 都读取了 ID=1 的记录，其 version 都为 1。
2. 更新（事务 B 提交）： 事务 B 完成修改，执行 无版本检查 的 UPDATE 语句，数据库中的 version 变为 2。
3. 更新（事务 A 提交）： 事务 A 完成修改，也执行 无版本检查 的 UPDATE 语句。

结果： 事务 B 的业务变更被事务 A 的修改覆盖，导致 丢失更新（Lost Update） 的竞态条件。

乐观锁的解决之道：单次原子操作

要解决这个问题，必须让 “检查旧版本” 和 “设置新值” 成为一个原子操作，即在 UPDATE 语句中加入版本过滤条件：

UPDATE records
SET title = '新标题', version = version + 1
WHERE id = 1 AND version = 1; -- 关键：只有旧版本为 1 时才允许更新

在 SeaORM 中，我们使用 update_many() 配合 filter() 来构造这个原子操作，并通过检查 rows_affected 来判断操作是否成功。

三、Upsert 流程的抉择：先 Update 再 Insert 的优势

实现 Upsert 功能主要有两种策略：“先 Update 再 Insert” 和 “先 Insert 再 Update”。在涉及乐观锁的业务中，“先 Update 再 Insert” 模式是更优的选择。

1. 模式一：先 Update 再 Insert（推荐）

这种模式总是优先处理最常见的情况：更新现有记录。

优势分析：

• 天然支持乐观锁： 乐观锁检查（WHERE version = ?）直接集成在 UPDATE 语句中，利用了数据库的原子性，保证了在单次操作中完成检查和修改。
• 高效处理更新： 在高并发的更新场景中，大部分操作都是更新。这种模式只需执行一次成功的 UPDATE 就能完成任务，避免了不必要的 INSERT 尝试。

2. 模式二：先 Insert 再 Update

流程： 尝试 INSERT $\to$ 如果失败（主键冲突），执行 UPDATE。

劣势分析：

• 乐观锁实现复杂： 如果 INSERT 失败，转到 UPDATE 时，必须确保 UPDATE 操作是带有乐观锁检查的，这增加了流程的复杂性。
• 高更新场景效率低： 如果大部分操作是更新，这种模式会强制执行一次注定会失败的 INSERT 操作（抛出主键冲突错误），然后再执行一次 UPDATE，浪费了数据库资源。

总结：选择 “先 Update 再 Insert” 的理由

在处理带有乐观锁的聚合根持久化时，“先 Update 再 Insert” 模式是首选方案。它能够利用 UPDATE 的原子性高效地处理最常见的更新操作，并天然地将乐观锁检查与数据库写操作绑定。

四、SeaORM 中的 Upsert 流程：UPDATE $\to$ FIND $\to$ INSERT

基于 “先 Update 再 Insert” 的策略，我们构建一个清晰的 "原子 UPDATE + FIND + INSERT" 三步流程，以可靠地处理成功更新、并发冲突和成功插入三种情况。

核心实现代码

// 假设 entity.version 是更新后的新版本，expected_old_version = entity.version - 1
async fn save<T: TransactionContext>(
    &self,
    callback: &mut EventSourcedEntity<Callback>,
    txn: &mut T,
) -> Result<(), RepositoryError> {
    let conn = txn.get_connection();
    let entity: &Callback = callback;
    let id = entity.channel.0.clone(); 
    let expected_old_version = entity.version - 1; 

    // 准备 ActiveModel，设置新的 version
    let mut active_model_for_update: ActiveModel = entity.clone().into_active_model();
    active_model_for_update.version = Set(entity.version); 

    // ----------------------------------------------------
    // 第一步：尝试原子 UPDATE（带乐观锁）
    // ----------------------------------------------------
    let res = callback_model::Entity::update_many()
        .set(active_model_for_update)
        .filter(callback_model::Column::Channel.eq(id.clone())) 
        .filter(callback_model::Column::Version.eq(expected_old_version)) // 乐观锁检查
        .exec(conn)
        .await?;

    if res.rows_affected > 0 {
        // 更新成功：影响行数 > 0，说明乐观锁条件满足。
        callback.move_event_to_context(txn);
        return Ok(());
    }

    // ----------------------------------------------------
    // 第二步：UPDATE 失败。使用 FIND 检查记录是否存在（判断是否为并发冲突）
    // ----------------------------------------------------
    if callback_model::Entity::find_by_id(id.clone())
        .one(conn)
        .await?
        .is_some()
    {
        // 记录存在。UPDATE 失败且记录存在，必然是版本不匹配，即并发冲突。
        return Err(RepositoryError::optimistic_lock_error(
            "Optimistic lock conflict: Record exists, but old version did not match."
        ));
    }

    // ----------------------------------------------------
    // 第三步：记录不存在，尝试 INSERT
    // ----------------------------------------------------
    let active_model_for_insert: ActiveModel = entity.clone().into_active_model();
    
    active_model_for_insert.insert(conn).await
        .map_err(|e| {
             // 如果 INSERT 失败，则视为并发冲突（在 FIND 之后被其他事务插入）。
             match e {
                 DbErr::RecordNotInserted | DbErr::Custom(_) => RepositoryError::optimistic_lock_error(
                    "Concurrency conflict: Record inserted after non-existence check."
                 ),
                 _ => e.into(),
            }
        })?;

    callback.move_event_to_context(txn);
    Ok(())
}

结论：告别竞态，拥抱原子性

通过本文的分析和实践，我们可以得出以下关键结论：

1. 乐观锁是高并发的基石： 放弃“先查后改”的传统模式，将版本检查与数据修改集成到一次原子性的 UPDATE 操作中，是避免丢失更新等竞态条件的根本方法。
2. 选择正确的 Upsert 策略： “先 Update 再 Insert” 模式凭借其对乐观锁的天然支持和对更新操作的高效处理，成为处理聚合根持久化的首选。
3. 利用数据库的原子性： 无论是通过检查 rows_affected，还是依赖主键约束错误来区分更新失败的原因，都是在充分利用数据库底层机制来确保数据一致性。

在您的 Rust DDD/CQRS 架构中，将这种原子化逻辑封装进仓储（Repository）层的 save() 方法中，是确保数据完整性和系统高可用性的关键。

问题背景

使用 snafu 进行错误处理时，我们通常需要：

1. 为每个错误变体手动添加 location 字段
2. 添加相应的属性（#[snafu(implicit)]、#[serde(skip)]）
3. 为复杂的 source 字段添加 #[snafu(source(false))]
4. 手动实现工厂方法来创建错误实例

这导致了大量的样板代码：

#[derive(Debug, Serialize, Snafu)]
#[serde(tag = "type")]
pub enum ApiError {
    #[serde(rename = "validate_error")]
    ValidateError {
        message: String,
        #[serde(skip)]
        #[snafu(implicit)]
        location: snafu::Location,
    },
    
    #[serde(rename = "internal_error")]
    InternalError {
        message: String,
        #[serde(skip)]
        #[snafu(source(false))]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
        #[serde(skip)]
        #[snafu(implicit)]
        location: snafu::Location,
    },
}

impl ApiError {
    #[track_caller]
    pub fn validate_error(message: String) -> Self {
        ApiError::ValidateError {
            message,
            location: GenerateImplicitData::generate(),
        }
    }
    
    #[track_caller]
    pub fn internal_error(message: String) -> Self {
        ApiError::InternalError {
            message,
            source: None,
            location: GenerateImplicitData::generate(),
        }
    }
    
    #[track_caller]
    pub fn internal_error_with_source(message: String, source: Option<Box<dyn std::error::Error + Send + Sync>>) -> Self {
        ApiError::InternalError {
            message,
            source,
            location: GenerateImplicitData::generate(),
        }
    }
}

解决方案：#[with_err_location] 宏

#[with_err_location] 宏可以自动化所有这些工作，让您只需要定义核心的错误结构：

#[with_err_location]
#[derive(Debug, Serialize, Snafu)]
#[serde(tag = "type")]
pub enum ApiError {
    #[serde(rename = "validate_error")]
    ValidateError {
        message: String,
    },
    
    #[serde(rename = "internal_error")]
    InternalError {
        message: String,
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },
}

核心特性

1. 自动添加 Location 字段

宏会为每个枚举变体自动添加 location: snafu::Location 字段，并配置必要的属性：

• #[snafu(implicit)]：让 snafu 自动填充位置信息
• #[serde(skip)]：在序列化时跳过该字段（默认行为）

2. 智能 Source 字段处理

宏能识别复杂的 source 字段类型，并自动添加 #[snafu(source(false))] 属性：

// 自动识别并处理
source: Option<Box<dyn std::error::Error + Send + Sync>>

3. 自动生成工厂方法

宏为每个变体生成相应的工厂方法：

普通变体

// 生成：
pub fn validate_error(message: String) -> Self { ... }

复杂 Source 字段变体

对于包含 Option<Box<dyn Error + Send + Sync>> 类型的 source 字段，宏会生成两个方法：

// 基础方法（source = None）
pub fn internal_error(message: String) -> Self { ... }

// 带 source 的方法
pub fn internal_error_with_source(message: String, source: Option<Box<dyn std::error::Error + Send + Sync>>) -> Self { ... }

4. 灵活的配置选项

全局配置

#[with_err_location(serde = true)]  // 不添加 #[serde(skip)]
#[derive(Debug, Snafu)]
pub enum ApiError { ... }

变体级别配置

#[with_err_location]
#[derive(Debug, Snafu)]
pub enum ApiError {
    #[location(serde = true)]  // 此变体不添加 #[serde(skip)]
    SpecialError {
        message: String,
    },
}

实现细节

宏的工作流程

1. 解析输入：解析枚举定义和宏参数
2. 字段分析：检查每个变体的字段类型和现有属性
3. 添加 Location 字段：为没有 location 字段的变体添加
4. 属性处理：添加必要的 snafu 和 serde 属性
5. 工厂方法生成：基于字段类型生成相应的工厂方法

关键函数

字段类型检测

fn should_add_source_false(field: &syn::Field) -> bool {
    let type_str = field.ty.to_token_stream().to_string();
    let is_option_box_dyn_error = type_str.starts_with("Option < Box < dyn");
    let is_source_field = field.ident.as_ref().map(|name| name == "source").unwrap_or(false);
    is_source_field && is_option_box_dyn_error
}

工厂方法生成

fn generate_factory_methods(input_enum: &ItemEnum) -> darling::Result<TokenStream> {
    // 检测复杂 source 字段
    let has_complex_source = fields_named.named.iter().any(should_add_source_false);
    
    if has_complex_source {
        // 生成两个方法：基础方法和带 source 的方法
    } else {
        // 生成单个方法
    }
}

使用示例

基本使用

#[with_err_location]
#[derive(Debug, Snafu)]
pub enum MyError {
    NetworkError { url: String },
    ValidationError { field: String, message: String },
}

// 使用生成的工厂方法
let error = MyError::network_error("https://api.example.com".to_string());

复杂 Source 字段

#[with_err_location]
#[derive(Debug, Snafu)]
pub enum ComplexError {
    DatabaseError {
        query: String,
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },
}

// 两种使用方式
let error1 = ComplexError::database_error("SELECT * FROM users".to_string());
let error2 = ComplexError::database_error_with_source(
    "SELECT * FROM users".to_string(),
    Some(Box::new(io_error))
);

配置选项

#[with_err_location(serde = true)]  // 全局配置
#[derive(Debug, Snafu)]
pub enum ApiError {
    #[location(serde = false)]  // 变体级别覆盖
    InternalError { message: String },
    
    PublicError { message: String },  // 使用全局配置
}

完整代码

#[proc_macro_attribute]
pub fn with_err_location(
    args: proc_macro::TokenStream,
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let args = args.into();
    with_err_location::with_err_location_impl(args, input.into())
        .unwrap_or_else(darling::Error::write_errors)
        .into()
} 

use darling::{Error, FromMeta, ast::NestedMeta};
use proc_macro2::TokenStream;
use quote::{ToTokens, quote};
use syn::{Attribute, Field, Fields, ItemEnum, Meta, punctuated::Punctuated, token::Comma};

#[derive(Debug, FromMeta, Default)]
struct WithErrLocationArgs {
    pub serde: bool,
}

pub fn with_err_location_impl(
    args: TokenStream,
    input: TokenStream,
) -> darling::Result<TokenStream> {
    let mut input_enum: ItemEnum = match syn::parse2(input) {
        Ok(v) => v,
        Err(e) => return Err(Error::from(e)),
    };

    // 解析全局参数
    let global_args = if args.is_empty() {
        WithErrLocationArgs::default()
    } else {
        let attr_args = match NestedMeta::parse_meta_list(args) {
            Ok(v) => v,
            Err(e) => return Err(Error::from(e)),
        };
        WithErrLocationArgs::from_list(&attr_args).unwrap_or_default()
    };

    // 遍历枚举的所有变体
    for variant in &mut input_enum.variants {
        // 查找并解析 #[location(...)] 属性
        let (location_config, remaining_attrs) =
            parse_and_remove_location_attrs(&variant.attrs, &global_args)?;

        // 移除 location 属性，保留其他属性
        variant.attrs = remaining_attrs;

        match &mut variant.fields {
            Fields::Named(fields_named) => {
                // 检查是否已经有 location 字段
                let location_field_index = fields_named.named.iter().position(|field| {
                    field
                        .ident
                        .as_ref()
                        .map(|ident| ident == "location")
                        .unwrap_or(false)
                });
                match location_field_index {
                    Some(index) => {
                        // 如果已经有 location 字段，确保它至少有 #[snafu(implicit)]
                        let existing_field = &mut fields_named.named[index];
                        ensure_location_field_has_snafu_implicit(existing_field, &location_config);
                    }
                    None => {
                        // 如果没有 location 字段，则添加一个新的（总是带有 #[snafu(implicit)]）
                        let location_field = create_location_field(&location_config);
                        fields_named.named.push(location_field);
                        fields_named.named.push_punct(Comma::default());
                    }
                }
                // 如果有source 且类型是Option<Box<dyn std::error::Error + Send + Sync>>
                // 需要为其加上#[snafu(source(false))]
                for field in &mut fields_named.named {
                    if should_add_source_false(field) {
                        ensure_source_false_attribute(field);
                    }
                }
            }
            _ => {
                return Err(Error::unsupported_format(
                    "Only named fields variants are supported",
                ));
            }
        }
    }

    // 生成工厂方法
    let factory_methods = generate_factory_methods(&input_enum)?;

    Ok(quote! {
        #input_enum
        #factory_methods
    })
}

/// 解析并移除 location 属性，返回配置和剩余属性
fn parse_and_remove_location_attrs(
    variant_attrs: &[Attribute],
    global_args: &WithErrLocationArgs,
) -> darling::Result<(LocationConfig, Vec<Attribute>)> {
    let mut config = LocationConfig {
        serde: global_args.serde,
    };

    let mut remaining_attrs = Vec::new();

    for attr in variant_attrs {
        if attr.path().is_ident("location") {
            // 解析 location 属性的参数
            match &attr.meta {
                Meta::List(meta_list) => {
                    let nested = meta_list.parse_args_with(
                        Punctuated::<NestedMeta, syn::Token![,]>::parse_terminated,
                    )?;
                    let location_args =
                        WithErrLocationArgs::from_list(&nested.into_iter().collect::<Vec<_>>())?;

                    config.serde = location_args.serde;
                }
                _ => {
                    // 如果没有参数，使用默认配置
                }
            }
        } else {
            // 保留非 location 属性
            remaining_attrs.push(attr.clone());
        }
    }

    Ok((config, remaining_attrs))
}

#[derive(Debug)]
struct LocationConfig {
    serde: bool,
}

/// 确保现有的 location 字段至少有 #[snafu(implicit)] 属性
fn ensure_location_field_has_snafu_implicit(field: &mut Field, config: &LocationConfig) {
    // 根据配置添加或确保有 #[serde(skip)]
    if !config.serde {
        let has_serde_skip = field.attrs.iter().any(|attr| {
            if attr.path().is_ident("serde")
                && let Meta::List(meta_list) = &attr.meta
            {
                return meta_list.tokens.to_string().contains("skip");
            }
            false
        });

        if !has_serde_skip {
            let serde_skip_attr: Attribute = syn::parse_quote! {
                #[serde(skip)]
            };
            field.attrs.push(serde_skip_attr);
        }
    }
    let has_snafu_implicit = field.attrs.iter().any(|attr| {
        if attr.path().is_ident("snafu")
            && let Meta::List(meta_list) = &attr.meta
        {
            return meta_list.tokens.to_string().contains("implicit");
        }
        false
    });

    // 如果没有 #[snafu(implicit)]，则添加它
    if !has_snafu_implicit {
        let snafu_implicit_attr: Attribute = syn::parse_quote! {
            #[snafu(implicit)]
        };
        field.attrs.push(snafu_implicit_attr);
    }
}

/// 检查字段是否需要自动添加 #[snafu(source(false))]
fn should_add_source_false(field: &syn::Field) -> bool {
    let type_str = field.ty.to_token_stream().to_string();

    // 检查是否是 Option<Box<dyn std::error::Error + Send + Sync>> 类型
    let is_option_box_dyn_error = type_str.starts_with("Option < Box < dyn");

    // 检查字段名是否为 "source"
    let is_source_field = field
        .ident
        .as_ref()
        .map(|name| name == "source")
        .unwrap_or(false);

    is_source_field && is_option_box_dyn_error
}

/// 确保复杂 source 字段有 #[snafu(source(false))] 属性
fn ensure_source_false_attribute(field: &mut Field) {
    // 检查是否已经有 #[snafu(source(false))] 属性
    let has_source_false = field.attrs.iter().any(|attr| {
        if attr.path().is_ident("snafu")
            && let Meta::List(meta_list) = &attr.meta
        {
            let tokens_str = meta_list.tokens.to_string();
            return tokens_str.contains("source")
                && (tokens_str.contains("false") || tokens_str.contains("( false )"));
        }
        false
    });

    // 如果没有，则添加 #[snafu(source(false))]
    if !has_source_false {
        let source_false_attr: Attribute = syn::parse_quote! {
            #[snafu(source(false))]
        };
        field.attrs.push(source_false_attr);
    }
}

/// 根据配置创建 location 字段
fn create_location_field(config: &LocationConfig) -> Field {
    if !config.serde {
        syn::parse_quote! {
            #[serde(skip)]
            #[snafu(implicit)]
            location: snafu::Location
        }
    } else {
        syn::parse_quote! {
            #[snafu(implicit)]
            location: snafu::Location
        }
    }
}

/// 为枚举生成工厂方法
fn generate_factory_methods(input_enum: &ItemEnum) -> darling::Result<TokenStream> {
    let enum_name = &input_enum.ident;
    let mut methods = Vec::new();

    for variant in &input_enum.variants {
        let variant_name = &variant.ident;

        // 将变体名转换为 snake_case
        let method_name = convert_to_snake_case(&variant_name.to_string());
        let method_ident = syn::Ident::new(&method_name, variant_name.span());

        match &variant.fields {
            Fields::Named(fields_named) => {
                // 检查是否有复杂的 source 字段
                let has_complex_source = fields_named.named.iter().any(should_add_source_false);

                if has_complex_source {
                    // 生成两个方法：基础方法（source = None）和带 source 的方法

                    // 1. 基础方法：source 为 None
                    let (base_params, base_assignments) =
                        analyze_fields_for_source_method(fields_named, true);
                    let base_method = quote! {
                        #[track_caller]
                        pub fn #method_ident(#(#base_params),*) -> Self {
                            #enum_name::#variant_name {
                                #(#base_assignments,)*
                            }
                        }
                    };
                    methods.push(base_method);

                    // 2. 带 source 的方法
                    let source_method_name = format!("{}_with_source", method_name);
                    let source_method_ident =
                        syn::Ident::new(&source_method_name, variant_name.span());
                    let (source_params, source_assignments) =
                        analyze_fields_for_source_method(fields_named, false);

                    let source_method = quote! {
                        #[track_caller]
                        pub fn #source_method_ident(#(#source_params),*) -> Self
                        {
                            #enum_name::#variant_name {
                                #(#source_assignments,)*
                            }
                        }
                    };
                    methods.push(source_method);
                } else {
                    // 分析字段，确定需要的参数
                    let (params, field_assignments) = analyze_fields(fields_named);

                    // 生成基础方法
                    let method = quote! {
                        #[track_caller]
                        pub fn #method_ident(#(#params),*) -> Self {
                            #enum_name::#variant_name {
                                #(#field_assignments,)*
                            }
                        }
                    };

                    methods.push(method);
                }
            }
            _ => continue,
        }
    }

    Ok(quote! {
        impl #enum_name {
            #(#methods)*
        }
    })
}

/// 将 PascalCase 转换为 snake_case
fn convert_to_snake_case(s: &str) -> String {
    let mut result = String::new();
    for (i, ch) in s.chars().enumerate() {
        if ch.is_uppercase() && i > 0 {
            result.push('_');
        }
        result.push(ch.to_lowercase().next().unwrap());
    }
    result
}

/// 分析字段，生成参数和字段赋值
fn analyze_fields(fields: &syn::FieldsNamed) -> (Vec<TokenStream>, Vec<TokenStream>) {
    let mut params = Vec::new();
    let mut assignments = Vec::new();

    for field in &fields.named {
        let field_name = field.ident.as_ref().unwrap();
        let field_type = &field.ty;

        if field_name == "location" {
            assignments.push(quote! { #field_name: snafu::GenerateImplicitData::generate() });
            continue;
        }

        // 普通字段作为参数
        params.push(quote! { #field_name: #field_type });
        assignments.push(quote! { #field_name });
    }

    (params, assignments)
}

/// 分析字段，为带 source 的方法生成参数和字段赋值
fn analyze_fields_for_source_method(
    fields: &syn::FieldsNamed,
    is_base: bool,
) -> (Vec<TokenStream>, Vec<TokenStream>) {
    let mut params = Vec::new();
    let mut assignments = Vec::new();

    for field in &fields.named {
        let field_name = field.ident.as_ref().unwrap();
        let field_type = &field.ty;

        if field_name == "location" {
            assignments.push(quote! { #field_name: snafu::GenerateImplicitData::generate() });
            continue;
        }

        if is_base && should_add_source_false(field) {
            // 复杂 source 字段设为 None，不作为参数
            assignments.push(quote! { #field_name: None });
        } else {
            // 普通字段作为参数
            params.push(quote! { #field_name: #field_type });
            assignments.push(quote! { #field_name });
        }
    }

    (params, assignments)
}

优势总结

1. 减少样板代码：自动生成重复的字段和方法定义
2. 类型安全：在编译时确保正确的类型处理
3. 灵活配置：支持全局和变体级别的配置选项
4. 智能处理：自动识别复杂类型并生成相应的方法
5. 向后兼容：可以与现有的 snafu 代码无缝集成

结论

#[with_err_location] 宏通过自动化错误处理中的重复工作，显著提升了开发效率和代码质量。它不仅减少了样板代码，还通过智能的类型检测和方法生成，提供了更加优雅和类型安全的错误处理解决方案。

无论是简单的错误类型还是复杂的带源错误的场景，这个宏都能提供恰到好处的自动化支持，让开发者能够专注于业务逻辑而不是重复的错误处理代码。

每个实体都需要一个仓储接口，以及对应的实现。find_by_id, find_by_email, exists_by_name, delete_by_id... 这些简单却重复的方法，我们一遍又一遍地编写，不仅枯燥，还容易出错。

痛点分析：传统仓储层的重复劳动

下面是 UserRepository 在没有自动化工具时的完整面貌：

1. Trait 定义 - 接口膨胀

// src/domain/repositories/user_repository.rs
pub trait UserRepository {
    // 基础CRUD
    async fn find_by_id(&self, txn: &mut Txn, id: &UserId) -> Result<Option<User>>;
    async fn save(&self, txn: &mut Txn, user: &mut User) -> Result<()>;
    async fn delete_by_id(&self, txn: &mut Txn, id: &UserId) -> Result<()>;
    
    // 各种查询方法
    async fn find_id_by_email(&self, txn: &mut Txn, email: &Email) -> Result<Option<UserId>>;
    async fn find_id_by_user_name(&self, txn: &mut Txn, user_name: &str) -> Result<Option<UserId>>;
    async fn exists_by_email(&self, txn: &mut Txn, email: &Email) -> Result<bool>;
    async fn find_by_status(&self, txn: &mut Txn, status: UserStatus) -> Result<Vec<User>>;
    // ... 更多类似方法，接口越来越庞大
}

2. 实现类 - 重复的SQL模板

// src/infrastructure/repositories_impl/user_repository_impl.rs
pub struct UserRepositoryImpl;

#[async_trait::async_trait]
impl UserRepository for UserRepositoryImpl {
    async fn find_by_id(&self, txn: &mut Txn, id: &UserId) -> Result<Option<User>> {
        // 每个方法都要写几乎相同的模板代码
        txn.query_sql_one("SELECT * FROM ua_user WHERE id = $1", [id.into()]).await
    }

    async fn find_id_by_email(&self, txn: &mut Txn, email: &Email) -> Result<Option<UserId>> {
        // 只是表名、字段名、参数位置变化，结构完全一样
        txn.query_sql_one("SELECT id FROM ua_user WHERE email = $1", [email.into()]).await
    }

    async fn find_id_by_user_name(&self, txn: &mut Txn, user_name: &str) -> Result<Option<UserId>> {
        // 重复第三次...
        txn.query_sql_one("SELECT id FROM ua_user WHERE user_name = $1", [user_name.into()]).await
    }

    async fn exists_by_email(&self, txn: &mut Txn, email: &Email) -> Result<bool> {
        // 稍微复杂一点，但模式仍然固定
        txn.query_sql_one("SELECT EXISTS(SELECT 1 FROM ua_user WHERE email = $1)", [email.into()]).await
    }
    
    // 保存逻辑更复杂，但也是固定模式
    async fn save(&self, txn: &mut Txn, user: &mut User) -> Result<()> {
        if user.is_new() {
            // INSERT 逻辑
            let sql = "INSERT INTO ua_user (id, email, user_name, ...) VALUES ($1, $2, $3, ...)";
            txn.execute_sql(sql, params![user.id(), user.email(), ...]).await?;
        } else {
            // UPDATE 逻辑  
            let sql = "UPDATE ua_user SET email = $1, user_name = $2, ... WHERE id = $3";
            txn.execute_sql(sql, params![user.email(), user.user_name(), user.id()]).await?;
        }
        Ok(())
    }
}

3. 测试类 - 更多的重复

// tests/user_repository_test.rs
// 还需要为每个方法编写测试，Mock 各种依赖...

这种模式的问题很明显：

• 代码重复：每个查询方法都是相似的模板
• 维护困难：表结构变更需要修改多个地方
• 容易出错：手写SQL容易有拼写错误
• 效率低下：花费大量时间在机械性编码上

✨ 解决方案：#[repository] 宏的威力

现在让我们看看使用 #[repository] 宏之后的变化：

// src/domain/repositories/user_repository.rs
use core_common::repository;

#[repository(aggregate = User, table_name = "ua_user")]
pub trait UserRepository: Send + Sync {
    // 复杂的、需要特殊逻辑的查询，保持手写实现
    async fn get_all_permissions(
        &self,
        user_id: &UserId,
        tenant_id: Option<TenantId>,
    ) -> Result<PermissionIdHashSet, RepositoryError> {
        // 这里仍然可以手写复杂实现
        // 比如联表查询、特殊业务逻辑等
    }

    // 简单查询：只需定义方法签名，空函数体 {}
    // 宏会自动生成完整的SQL实现！
    
    // 根据ID查询
    async fn find_by_id(&self, id: &UserId) -> Result<Option<User>, RepositoryError> {}
    
    // 根据各种字段查询ID
    async fn find_id_by_user_name(&self, user_name: &str) -> Result<Option<UserId>, RepositoryError> {}
    async fn find_id_by_email(&self, email: &Email) -> Result<Option<UserId>, RepositoryError> {}
    async fn find_id_by_phone(&self, phone: &Phone) -> Result<Option<UserId>, RepositoryError> {}
    
    // 存在性检查
    async fn exists_by_email(&self, email: &Email) -> Result<bool, RepositoryError> {}
    async fn exists_by_user_name(&self, user_name: &str) -> Result<bool, RepositoryError> {}
    
    // 复杂条件查询
    async fn find_by_email_and_status(&self, email: &Email, status: UserStatus) -> Result<Vec<User>, RepositoryError> {}
    async fn find_by_email_or_phone(&self, email: &Email, phone: &Phone) -> Result<Vec<User>, RepositoryError> {}
    
    // 统计查询
    async fn count_by_status(&self, status: UserStatus) -> Result<i64, RepositoryError> {}
    
    // 删除操作
    async fn delete_by_id(&self, id: &UserId) -> Result<(), RepositoryError> {}
    
    // 保存操作 - 宏会自动处理INSERT/UPDATE逻辑
    async fn save(&self, user: &mut User) -> Result<(), RepositoryError> {}
}

宏的魔法效果详解：

1. 自动实现生成

   • 编译时自动为每个空方法生成完整的SQL实现
   • 无需手动编写 UserRepositoryImpl
   • 生成的代码与手写代码质量相当，但零错误

2. 智能参数注入

   • 自动添加事务参数 txn: &mut TC
   • 自动处理参数类型转换（如 Email → 数据库类型）
   • 最终方法签名实际上是：find_id_by_email(&self, txn: &mut TC, email: &Email)

3. CRUD 功能继承

   • 通过 aggregate = User 自动继承 CrudRepository<User, TC>
   • 免费获得：find_by_id, save, delete_by_id, exists_by_id 等标准方法
   • 无需重复定义基础CRUD操作

4. 完整的测试支持

   • 自动利用 mockall 生成Trait的Mock实现
   • 在测试中可以直接：let mut mock = MockUserRepository::new();
   • 极大简化单元测试的编写

🧙♂️ 魔法揭秘：命名约定解析引擎

宏的核心是一个强大的方法名解析器，它将自然语言风格的方法名转换为精确的SQL查询。

查询类型推断规则

条件运算符映射

逻辑连接符处理

排序和分页支持

实际解析示例

简单查询：

async fn find_id_by_email(&self, email: &Email) -> Result<Option<UserId>> {}

↓ 生成 SQL：

SELECT id FROM "ua_user" WHERE email = $1

复杂查询：

async fn find_id_by_email_and_status_order_by_created_at_desc(
    &self, 
    email: &Email, 
    status: UserStatus
) -> Result<Option<UserId>> {}

↓ 生成 SQL：

SELECT id FROM "ua_user" 
WHERE email = $1 AND status = $2 
ORDER BY created_at DESC

存在性检查：

async fn exists_by_email_and_tenant_id(
    &self, 
    email: &Email, 
    tenant_id: &TenantId
) -> Result<bool> {}

↓ 生成 SQL：

SELECT EXISTS(
    SELECT 1 FROM "ua_user" 
    WHERE email = $1 AND tenant_id = $2
)

⚙️ 灵活的配置选项

宏支持丰富的配置参数来适应不同场景：

// 基础配置
#[repository(aggregate = User, table_name = "ua_user")]

// 多租户支持
#[repository(aggregate = User, table_name = "ua_user", tenant = true)]

// 禁用Mock生成（用于性能敏感场景）
#[repository(aggregate = User, table_name = "ua_user", mock = false)]

// 自定义事务上下文
#[repository(
    aggregate = User, 
    table_name = "ua_user", 
    context = "db: &Db"  // 使用自定义的db参数而非默认txn
)]

// 复杂配置组合
#[repository(
    aggregate = User,
    table_name = "ua_user",
    tenant = true,
    mock = true,
    context = "conn: &mut PgConnection"
)]

🎯 最佳实践和适用场景

推荐使用宏的场景：

• 简单CRUD操作：95%的数据库查询都适合
• 标准查询模式：等值查询、范围查询、存在性检查等
• 快速原型开发：快速验证业务逻辑，后期可替换为手写优化SQL
• 团队规范统一：确保所有开发者使用一致的查询模式

建议手写实现的场景：

• 复杂联表查询：涉及多个表的复杂JOIN操作
• 自定义聚合查询：GROUP BY、HAVING等复杂聚合
• 数据库特定优化：需要数据库特定语法或优化提示
• 存储过程调用：调用数据库存储过程或函数

📊 实际效果对比

代码量减少：

• 传统方式：每个查询方法需要 5-10 行实现代码
• 宏方式：每个查询方法只需 1 行声明
• 节省比例：约 80-90% 的代码量

开发效率提升：

• 新查询方法：从 5分钟/个 减少到 30秒/个
• 维护成本：表结构变更时，只需修改宏参数，无需改动多个方法
• 错误率：编译时检查替代运行时SQL错误

总结

#[repository] 宏不仅仅是一个代码生成工具，它代表了一种声明式数据访问的新范式。通过将开发者的重心从"如何实现"转移到"想要什么"，它真正实现了：

• ⚡ 极致效率：声明即实现，开发速度提升5-10倍
• 🔒 绝对安全：编译时检查确保所有查询的类型安全
• 📚 规范统一：强制执行一致的代码标准和命名约定
• 🧪 测试友好：开箱即用的Mock支持，测试编写效率大幅提升
• 🛠 灵活演进：复杂场景仍可手写实现，兼顾简单与复杂需求

在Rust强大的元编程能力支持下，我们能够构建出这样既智能又实用的开发工具。这不仅是技术的进步，更是开发体验的革新——让我们能够更专注于业务逻辑本身，而不是重复的机械性工作。