dbnexus 0.6.0-rc.2

中文 | English

企业级 Rust 数据库抽象层

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

📋 目录

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

✨ 功能特性

基于 Sea-ORM 构建的高性能、高安全性、功能丰富的数据库访问层。DBNexus 提供一种声明式的数据库访问方法：

🎯 核心功能（始终可用）

⚡ 企业级功能（按需启用）

📦 特性预设

🚀 快速开始

📦 安装

在你的 Cargo.toml 中添加：

[dependencies]
dbnexus = { version = "0.6.0-rc.2", default-features = false, features = ["runtime-tokio-rustls", "sqlite", "permission", "sql-parser", "macros", "config-env"] }
tokio = { version = "1.53", features = ["rt-multi-thread", "macros"] }
sea-orm = { version = "2.0.0-rc.42", features = ["macros"] }

💡 基本用法

步骤 1：定义实体

use dbnexus::{DbPool, db_entity};
use 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 {}

impl ActiveModelBehavior for ActiveModel {}

步骤 2：创建连接池

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = DbPool::new("sqlite::memory:").await?;
    let session = pool.get_session("admin").await?;
    Ok(())
}

步骤 3：插入数据

let user = Model {
    id: 1,
    name: "Alice".to_string(),
    email: "alice@example.com".to_string(),
};
Model::insert(&session, user).await?;

步骤 4：查询数据

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

use dbnexus::{DbPool, db_entity};
use 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 {}

impl ActiveModelBehavior for ActiveModel {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = DbPool::new("sqlite::memory:").await?;
    let session = pool.get_session("admin").await?;
    let user = Model { id: 1, name: "Alice".to_string(), email: "alice@example.com".to_string() };
    Model::insert(&session, user).await?;
    Ok(())
}

🔒 权限控制

use dbnexus::{DbPool, db_entity};
use 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,
}

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

impl ActiveModelBehavior for ActiveModel {}

// 管理员可以访问
let session = pool.get_session("admin").await?;
Model::find_all(&session).await?;

// 普通用户会被拒绝
let session = pool.get_session("guest").await?;
Model::find_all(&session).await?; // 错误：权限被拒绝

🎨 特性标志

数据库驱动（选择一个）

# SQLite（嵌入式）
dbnexus = { version = "0.6.0-rc.2", default-features = false, features = ["runtime-tokio-rustls", "sqlite"] }

# PostgreSQL
dbnexus = { version = "0.6.0-rc.2", features = ["postgres"] }

# MySQL
dbnexus = { version = "0.6.0-rc.2", features = ["mysql"] }

# DuckDB（嵌入式分析型数据库，0.3.0 新增）
dbnexus = { version = "0.6.0-rc.2", features = ["duckdb"] }

# Ladybug（嵌入式图数据库，0.4.0 新增）
dbnexus = { version = "0.6.0-rc.2", features = ["ladybug"] }

# Neo4j（图数据库服务器，0.4.0 新增）
dbnexus = { version = "0.6.0-rc.2", features = ["neo4j"] }

协议兼容数据库

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

运行时

# Tokio with RustLS（默认）
dbnexus = { version = "0.6.0-rc.2", features = ["runtime-tokio-rustls"] }

# Tokio with Native TLS
dbnexus = { version = "0.6.0-rc.2", features = ["runtime-tokio-native-tls"] }

# AsyncStd
dbnexus = { version = "0.6.0-rc.2", features = ["runtime-async-std"] }

核心功能

# 权限控制（自动启用 sql-parser + yaml + cache 特性，强制依赖 sql-parser 防 SQL 注入）
dbnexus = { version = "0.6.0-rc.2", features = ["permission"] }

# SQL 解析（自动启用 cache 特性）
dbnexus = { version = "0.6.0-rc.2", features = ["sql-parser"] }

# 过程宏
dbnexus = { version = "0.6.0-rc.2", features = ["macros"] }

使用预设（推荐）

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

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

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

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

可选功能

# 可观测性（metrics + health-check）
dbnexus = { version = "0.6.0-rc.2", features = ["observability"] }

# 数据管理（migration + sharding + global-index）
dbnexus = { version = "0.6.0-rc.2", features = ["data-management"] }

# 安全（audit + permission-engine）
dbnexus = { version = "0.6.0-rc.2", features = ["security"] }

# 独立特性
dbnexus = { version = "0.6.0-rc.2", features = [
    "metrics",          # Prometheus 指标
    "audit",            # 审计日志
    "migration",        # 数据库迁移
    "sharding",         # 数据分片
    "global-index",     # 跨分片全局索引
    "permission-engine", # 高级权限引擎
    "authentication",   # JWT 认证 + 密码强度验证
    "distributed-capabilities" # 分布式能力聚合（retry/failover/replica-routing/scatter-gather/shard-migration/saga/distributed-id）
    # i18n 已为核心特性，始终可用，无需显式启用
] }

配置

dbnexus = { version = "0.6.0-rc.2", features = [
    "yaml",            # YAML 配置支持
    "config-toml",     # TOML 配置支持
    "config-env",      # 环境变量（默认）
] }

📚 文档

💻 示例

全部示例位于 examples/（独立 crate dbnexus-examples，随 workspace 管理）：

cd examples

# 运行单个示例（每个示例是一个 bin 目标）
cargo run --bin basic_connection

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

完整说明见 examples/README.md。

注意：dbnexus-examples 已设为 publish = false 并纳入 workspace 管理。

📝 代码片段

高级配置

use dbnexus::{DbPool, DbConfig, PoolConfig};

let config = DbConfig {
    url: "postgresql://user:pass@localhost/db".to_string(),
    pool_config: PoolConfig {
        max_connections: 20,
        min_connections: 5,
        idle_timeout: 300,
        acquire_timeout: 5000,
    },
    ..Default::default()
};

let pool = DbPool::with_config(config).await?;

环境变量

export DATABASE_URL="postgresql://user:pass@localhost/db"
export DB_MAX_CONNECTIONS=20
export DB_MIN_CONNECTIONS=5
export DB_ADMIN_ROLE=admin

let config = dbnexus::DbConfig::from_env()?;
let pool = dbnexus::DbPool::with_config(config).await?;

事务处理

let session = pool.get_session("admin").await?;

// 开始事务
session.begin_transaction().await?;

// 多个操作
Model::insert(&session, user1).await?;
Model::insert(&session, user2).await?;

// 提交
session.commit().await?;

监控

use dbnexus::{DbPool, MetricsCollector};

let pool = DbPool::new("postgresql://localhost/db").await?;

// 获取连接池状态
let status = pool.status();
println!("活跃: {}, 空闲: {}", status.active, status.idle);

// 导出 Prometheus 指标
let metrics = MetricsCollector::new();
println!("{}", metrics.export_prometheus());

🏗️ 架构

graph TD
    A[应用层<br/>使用 DbPool 和 Session 的代码] --> B[DBNexus API 层<br/>DbPool, Session<br/>权限检查<br/>事务管理]
    B --> C[功能模块<br/>Config, Permission, Metrics<br/>Migration, Sharding, Audit]
    C --> D[连接池层<br/>连接生命周期管理<br/>健康检查<br/>RAII 保证]
    D --> E[Sea-ORM / SQLx<br/>数据库驱动<br/>查询构建器]

详细的设计理念、模块划分、数据流与安全/性能设计见 架构文档。

🧪 测试

# 全量测试（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

# 切换数据库后端运行集成测试（PostgreSQL/MySQL 需要 Docker 环境）
cargo test --no-default-features --features postgres,default-no-db,all-optional --workspace --exclude dbnexus-examples --exclude dbnexus-macros

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

📊 性能

DBNexus 遵循零成本抽象原则，性能相关能力均为设计层面保证：

• 零成本特性门控：metrics 等可选功能通过 #[cfg(feature = ...)] 编译期裁剪，未启用时为零开销空实现
• 无锁计数：连接池状态（PoolStatus）使用原子类型维护，热路径无锁
• 异步优先：全部 I/O 使用 async/await；读多写少状态使用 RwLock；原子操作采用 AcqRel 内存序，减少不必要的全局同步
• 连接池策略：池 + LRU 复用连接（避免握手开销）、限制最大连接、预热最小连接、健康检查剔除死连接
• 热路径优化（0.5.1）：SQL 注入检测模式表静态化、Saga 补偿查找预索引、Session 并发读优化、DbConfig Arc 共享等

基准测试

仓库内置 4 个 criterion 基准：permission_bench、permission_engine_bench、sharding_bench、metrics_bench（位于 benches/）：

cargo bench

以下为 2026-08-14 在 Linux x86_64（release profile，lto=thin）上两轮平台优化的累计结果（完整报告见 benches/baseline-after.md）：

6 项基准全部正向提升、无回退，平均累计提升约 5.5%。

🔒 安全

DBNexus 从设计之初就以内建安全为目标：

• 无 unsafe 代码 — 所有库代码使用 #![forbid(unsafe_code)]
• 权限强制执行 — 基于角色的表级访问控制（RBAC），覆盖 JOIN/子查询跨表路径
• SQL 注入防护 — 默认参数化查询，SqlParser 表名提取与注入检测，DdlGuard AST 校验
• 配置路径校验 — 防止路径遍历攻击；连接 URL 解析错误不回显凭据
• 速率限制 — 权限检查令牌桶限流，防止滥用

完整的纵深防御设计、漏洞报告流程与安全最佳实践见 安全文档。

🗺️ 开发路线图

短期（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 工作流、代码规范与提交/PR 流程。

开发设置

# 克隆仓库
git clone https://github.com/Kirky-X/dbnexus.git
cd dbnexus

# 安装 pre-commit 钩子
./scripts/install-pre-commit.sh

# 运行测试（CI 特性组合）
cargo test --no-default-features --features sqlite,default-no-db,all-optional

# 运行 linter
cargo clippy --no-default-features --features sqlite,default-no-db,all-optional --all-targets -- -D warnings

📋 更新日志

完整版本历史见 CHANGELOG.md。

📄 许可证

本项目基于 MIT + Commons Clause 许可证发布，商业使用需单独授权。详见 LICENSE。

🙏 致谢

• Sea-ORM - 优秀的 ORM 框架，DBNexus 建立在其上
• SQLx - 异步 SQL 工具包
• Rust 社区提供的优秀工具和库

📞 联系与支持

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

⭐ Star 历史

💝 支持本项目

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

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部

© 2026 Kirky.X. All rights reserved.