dbnexus 0.6.0-rc.4

中文 | English

企业级 Rust 数据库抽象层

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

🗄️ 声明式多数据库访问

通过派生宏定义实体，连接池、权限、审计与缓存由框架内建：

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

DBNexus 基于 Sea-ORM 构建，提供一种声明式的数据库访问方式：一个宏定义实体，一层权限守住每条 SQL，一组特性按需裁剪。

🎯 核心基座（无可选特性依赖）

⚙️ 核心可选特性（default-no-db 聚合）

⚡ 企业级特性（按需启用）

🆕 为 0.6.0-rc.3 新增能力，完整清单见 CHANGELOG。

🚀 快速开始

📦 安装

要求：Rust 1.97.1+（rust-toolchain.toml 锁定，edition 2024），并至少启用一个运行时与一个数据库驱动特性。

cargo add dbnexus --features runtime-tokio-rustls,sqlite,permission,macros
cargo add tokio --features rt-multi-thread,macros

[dependencies]
dbnexus = { version = "0.6.0-rc.3", features = ["runtime-tokio-rustls", "sqlite", "permission", "macros"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

permission 会强制启用 sql-parser 与 cache（编译期校验，防 SQL 注入绕过权限检查）。default = []：所有特性均需显式启用。

💡 最小示例

定义实体并获得宏生成的 CRUD（改编自 examples/src/basic/basic_crud.rs，ActiveModelBehavior 由宏自动实现）：

use dbnexus::{DbPool, db_entity};
use dbnexus::sea_orm::entity::prelude::*;

#[db_entity(table_name = "users", primary_key = "id")]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "users")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 连接池 + admin 会话（RAII：Session 丢弃时连接自动归还）
    let pool = DbPool::new("sqlite::memory:").await?;
    let session = pool.get_session("admin").await?;

    // 宏生成的 CRUD：每条语句都经过解析与表级权限检查
    let user = Model { id: 1, name: "Alice".to_string(), email: "alice@example.com".to_string() };
    Model::insert(&session, user).await?;

    let users = Model::find_all(&session).await?;
    println!("找到 {} 个用户", users.len());
    Ok(())
}

// admin 角色默认放行（无权限配置文件时的安全默认）
let session = pool.get_session("admin").await?;
Model::find_all(&session).await?;

// guest 角色未在策略中定义时被拒绝；策略中未授权的表同样拒绝
let session = pool.get_session("guest").await?;
Model::find_all(&session).await?; // 错误：权限被拒绝

🧭 核心概念

🎨 特性标志

default = []：无任何默认特性，运行时、数据库驱动与功能特性均需显式启用。嵌入式（sqlite/duckdb）与服务器端（postgres/mysql）驱动严格互斥，混用直接编译失败。

运行时（互斥，三选一）

数据库驱动

关系型驱动四选一（编译期互斥）；图数据库驱动可与关系型驱动共存。sqlite / postgres / mysql 基于 sea-orm/sqlx 对应驱动实现，duckdb（嵌入式分析型）、ladybug（原 Kuzu）与 neo4j 为各自的原生绑定；各驱动的数据库、类型与引入版本见数据库支持。

核心能力

数据访问与集成

可观测性

数据管理

分布式能力

安全与合规

特性预设

使用示例

# 嵌入式/边缘设备（最小配置）
dbnexus = { version = "0.6.0-rc.3", features = ["embedded"] }

# 微服务
dbnexus = { version = "0.6.0-rc.3", features = ["microservice"] }

# 单体应用
dbnexus = { version = "0.6.0-rc.3", features = ["monolith"] }

# 企业级（完整功能）
dbnexus = { version = "0.6.0-rc.3", features = ["enterprise"] }

📚 文档

💻 示例

全部示例位于 examples/（独立 crate dbnexus-examples，随 workspace 管理，publish = false），共 51 个二进制目标（截至 0.6.0-rc.3）：

cd examples

# 运行单个示例（每个示例是一个 bin 目标）
cargo run --bin basic_crud --features "sqlite,permission,macros"

# 编译全部示例
cargo build --all-targets

* graph_ladybug 因与 duckdb 存在 mbedtls 链接冲突未注册为 bin，需单独编译：cargo build --bin graph_ladybug --no-default-features --features "runtime-tokio-rustls,sqlite,cache,ladybug"。

完整说明见 examples/README.md。

📝 代码片段

高级配置与环境变量、事务与监控等更多代码片段见用户指南（配置、事务、指标章节）与 API 参考。

🏗️ 架构

DBNexus 采用分层模块设计：foundation 提供配置与错误基座，database 模块承载连接池、Session、迁移、分片、Saga 与 scatter-gather，access 模块集中 SQL 解析、权限引擎、认证与脱敏，domain 模块沉淀权限/审计/迁移的领域抽象，observability 与 reliability 分别提供指标健康与重试容错。所有可选能力经特性门控编译期裁剪，过程宏 dbnexus-macros 在编译期为实体生成带权限检查的 CRUD 代码。

分层模块设计、各层职责与模块全景图的详细设计（设计理念、模块划分、数据流与安全/性能设计）见架构文档。

🔗 核心执行路径

Session::execute_raw 在 sql-parser + permission 特性组合下的真实执行管道：get_session 校验角色后，语句经"拒绝 DDL → 解析 → 逐表权限检查 → 驱动执行"返回；解析失败时 admin 角色放行、非 admin 角色拒绝，JOIN / 子查询涉及的目标表逐一受检（rc.2 补全）；retry 幂等重试、metrics 慢查询观测与 audit 的 admin 绕过记录均挂接于此管道（源码见 src/database/pool/session.rs）。

完整时序图与路径要点见架构文档 · 核心执行管道。

🌐 数据库支持

通过标准协议支持的兼容数据库（无需额外特性，使用对应协议驱动即可）：

已知限制：duckdb 与 ladybug 同时启用存在 mbedtls 重复符号链接冲突，多驱动验证请采用分组特性组合（见路线图）。

🧪 测试

测试策略矩阵

测试分六层承载：src/** 内 #[cfg(test)] 单元测试、tests/** 显式注册的集成测试目标（按 feature 门控）、tests/e2e/ 端到端场景（按 cfg(feature) 隔离）、postgres_testcontainers / mysql_testcontainers 容器级测试（每测试独立容器隔离）、doc tests（CI 单独运行 cargo test --doc）与 benches/ 基准测试（见性能）。金字塔基线、驱动组矩阵与 E2E 场景定义详见 docs/TEST_SCENARIOS.md。

测试规模（截至 0.6.0-rc.3）

运行命令（与 CI 一致）

# 全量测试（CI 标准特性组合；sqlite/postgres/mysql/duckdb 驱动互斥，不使用 --all-features）
cargo test --no-default-features --features sqlite,default-no-db,all-optional --workspace --exclude dbnexus-examples --exclude dbnexus-macros

# 切换数据库后端运行集成测试（CI 以 services 容器提供 PostgreSQL 15 / MySQL 8.0）
cargo test --no-default-features --features postgres,default-no-db,all-optional --workspace --exclude dbnexus-examples --exclude dbnexus-macros

# 文档测试
cargo test --no-default-features --features sqlite,default-no-db,all-optional --doc --workspace --exclude dbnexus-examples --exclude dbnexus-macros

嵌入式（sqlite/duckdb）与服务器端（postgres/mysql）驱动在编译期严格互斥（compile_error!），验证多驱动时按分组特性组合运行。

📊 性能

DBNexus 遵循零成本抽象原则，性能相关能力均为设计层面保证：零成本特性门控（#[cfg(feature = ...)] 编译期裁剪）、无锁热路径（池状态原子维护、权限配置与缓存 Provider 经 ArcSwap 无锁读取、AcqRel 内存序）、异步优先（全部 I/O async/await，读多写少状态用 RwLock）、连接池策略（LRU 复用、最大连接限制、最小连接预热、健康检查剔除死连接），以及 0.5.1 热路径优化（注入检测模式表静态化、Saga 补偿查找预索引、Session 并发读优化、DbConfig Arc 共享）。设计细节见架构文档 · 性能架构。

端到端基准

仓库内置 5 个 criterion 基准：permission_bench、permission_engine_bench、sharding_bench、metrics_bench、e2e_bench（位于 benches/，cargo bench 运行）。端到端基线（2026-09-11 采样，非 SLA）：DbPool::get_session 句柄获取 ≈ 0.24 µs、DbPool::query_rows 单行完整管道 ≈ 480 µs、Session::execute_raw 64 行循环 INSERT ≈ 708 ms/迭代（≈ 11 ms/行）。测量环境、逐项解读与复现命令见性能基线 · 端到端基线。

历史优化对照

两轮平台优化的累计结果（6 项基准全部正向提升、无回退，平均累计提升约 5.5%）见 benches/baseline-after.md 与性能基线 · 历史优化对照。

🔒 安全

DBNexus 从设计之初就以内建安全为目标，纵深防御自下而上分为五层（完整设计见安全文档）：

供应链安全：CI 常开 cargo deny check（许可证/公告/重复依赖，豁免留痕于 deny.toml）与 cargo audit（audit.toml），CodeQL 语义扫描与 Dependabot 自动更新，pre-commit 私钥扫描拦截。

漏洞报告：请勿通过公开 Issue 提交。请使用 GitHub Security Advisories 私密通道（"Report a vulnerability"）。响应承诺：48 小时内确认，7 天内给出初步评估（见 SECURITY.md）。

🗺️ 开发路线图

短期（0.6.0 正式发布）

• 发布 0.6.0 正式版：完成 rc 验证后按工作区传导表更新 trait-kit 0.5.0 / oxcache 0.5.0 依赖要求，cargo publish --dry-run 核对后打 tag 触发 release.yml 自动发布
• 对齐 MSRV 声明与依赖实际要求 — 已按工作区 CONFIG_BASELINE 统一为 1.97.1（2026-09-06），覆盖传递依赖的 1.94 要求
• 恢复 MySQL 集成测试的常规运行（testcontainers 已就绪，当前受数据库服务依赖阻塞）

中期

• 解决 duckdb 与 ladybug 同时启用时的 mbedtls 重复符号链接冲突（当前多驱动验证采用分组特性组合）
• 跟进代码质量审查留档的 Medium 项

条目整理自 CHANGELOG.md 与仓库验收记录。

🤝 参与贡献

欢迎贡献！请先阅读 CONTRIBUTING.md，了解 TDD 工作流、开发环境要求（Rust 1.97.1 工具链、lefthook / pre-commit 钩子——安装脚本 ./scripts/install-pre-commit.sh，禁止 --no-verify 绕过、Conventional Commits 提交信息）与质量门禁（cargo fmt --check、cargo clippy -D warnings、cargo deny check、cargo audit、行覆盖 ≥ 80%），以及提交/PR 流程。

📋 更新日志

完整版本历史见 CHANGELOG.md。

📄 许可证

本项目基于 MIT + Commons Clause 许可证发布：在 MIT 许可的基础上附加 Commons Clause 条件，未经单独书面授权不得销售本软件或将其用于商业用途。详见 LICENSE。

🙏 致谢

• Sea-ORM - 优秀的 ORM 框架，DBNexus 建立在其上
• SQLx - 异步 SQL 工具包
• sqlparser - SQL 方言解析，支撑权限检查与注入防护
• ICU4X - Unicode 国际化组件，支撑 locale 感知格式化
• Rust 社区提供的优秀工具和库

📞 联系与支持

安全漏洞请勿通过公开 Issue 提交，参见安全文档的漏洞报告流程。

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部

© 2026 Kirky.X. All rights reserved.