dbnexus 0.4.0 - Docs.rs

docs.rs failed to build dbnexus-0.4.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Visit the last successful build: dbnexus-0.3.4

English

🎯 基于 Sea-ORM 构建的高性能、高安全性、功能丰富的数据库访问层

DBNexus 提供了一种声明式的数据库访问方法：

✨ 类型安全	🔒 权限控制	🏊 智能连接池	📊 企业级监控
编译时检查	表级 RBAC	RAII 自动管理	Prometheus 指标

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(())
}

✨ 功能特性

🎯 核心功能	⚡ 企业级功能
始终可用	按需启用

🎯 核心功能（始终可用）

状态	功能	描述
✅	连接池管理	RAII 风格的自动连接生命周期管理
✅	权限控制	基于角色的表级访问控制（RBAC）
✅	过程宏	自动生成 CRUD 方法和权限检查
✅	SQL 解析器	提取操作类型和目标表
✅	事务支持	完整的事务管理
✅	多数据库支持	SQLite、PostgreSQL、MySQL、DuckDB

⚡ 企业级功能

状态	功能	描述
🔍	指标监控	Prometheus 指标导出（`metrics` 特性）
📊	分布式追踪	OpenTelemetry 集成（`tracing` 特性）
📝	审计日志	所有操作的自动审计（`audit` 特性）
🗄️	数据库迁移	自动迁移执行（`migration` 特性）
🔀	数据分片	支持分片策略（`sharding` 特性）
🌐	全局索引	跨分片查询（`global-index` 特性）
💾	缓存	oxcache 缓存（内部 moka L1 后端）（`cache` 特性）
🔐	权限引擎	高级权限系统（`permission-engine` 特性）
🛡️	JWT 认证	JWT + 密码强度验证（`authentication` 特性，0.3.0 新增）

📦 特性预设

预设	特性	使用场景
embedded	`runtime-tokio-rustls`, `sqlite`, `config-env`	嵌入式/边缘设备超最小配置
microservice	`runtime-tokio-rustls`, `postgres`, `permission`, `sql-parser`, `config-env`, `observability`	微服务部署
monolith	`runtime-tokio-rustls`, `postgres`, `permission`, `sql-parser`, `yaml`, `data-management`, `security`, `observability`	单体应用
enterprise	`postgres`, `monolith`, `permission-engine`	完整企业功能
all-optional	`cache`, `observability`, `data-management`, `security`, `migration`	5 个聚合 feature（手动添加数据库驱动和其他特性）

🚀 快速开始

📦 安装

在你的 Cargo.toml 中添加：

[dependencies]
dbnexus = "0.3.3"
tokio = { version = "1.52", features = ["rt-multi-thread", "macros"] }
sea-orm = { version = "2.0.0-rc.42", features = ["macros"] }

💡 基本用法

🎬 5 分钟快速开始

步骤 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,
}

#[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?; // 错误：权限被拒绝

🎨 特性标志

⚠️ v0.2.0 破坏性变更

所有用户必须更新 Cargo.toml：

v0.1.x → v0.2.0 是破坏性变更。 cache feature 不再默认启用，多个 feature 现在显式要求 cache 必须启用。

数据库驱动（选择一个）

# SQLite（默认，嵌入式）
dbnexus = { version = "0.3.3", features = ["sqlite"] }

# PostgreSQL
dbnexus = { version = "0.3.3", features = ["postgres"] }

# MySQL
dbnexus = { version = "0.3.3", features = ["mysql"] }

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

协议兼容数据库

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

数据库	兼容协议	说明
CockroachDB	PostgreSQL	分布式 SQL 数据库
YugabyteDB	PostgreSQL	分布式 PostgreSQL
TiDB	MySQL	分布式 HTAP 数据库
MariaDB	MySQL	MySQL 兼容分支
Aurora	PostgreSQL/MySQL	AWS 云原生数据库

运行时

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

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

# AsyncStd
dbnexus = { version = "0.3.3", features = ["runtime-async-std"] }

可选功能

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

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

# 过程宏
dbnexus = { version = "0.3.3", features = ["macros"] }

# 企业级功能
dbnexus = { version = "0.3.3", features = [
    "metrics",          # Prometheus 指标
    "tracing",          # 分布式追踪
    "audit",            # 审计日志
    "migration",        # 数据库迁移
    "sharding",         # 数据分片
    "global-index",     # 跨分片全局索引
    "permission-engine", # 高级权限引擎
    "authentication"   # JWT 认证 + 密码强度验证（0.3.0 新增）
] }

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

📚 文档

📖 补充资源

资源	描述
📖 用户指南	使用 DBNexus 的全面指南
📘 API 参考	完整 API 文档
🏗️ 架构文档	系统架构和设计决策
📦 示例	可运行的代码示例

💻 示例

💡 真实示例

📝 高级配置

use dbnexus::{DbPool, DbConfig};

let config = DbConfig {
    url: "postgresql://user:pass@localhost/db".to_string(),
    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());

📂 查看所有示例 →

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

🏗️ 架构

🏗️ 系统架构

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/>查询构建器]

查看 ARCHITECTURE.md 获取详细的架构文档。

🔒 安全性

🛡️ 安全特性

DBNexus 在设计时就考虑了安全性：

无 unsafe 代码 - 所有库代码都使用 #![forbid(unsafe_code)]
权限强制执行 - 具有编译时验证的表级访问控制
SQL 注入防护 - 默认使用参数化查询
配置路径验证 - 防止路径遍历攻击
速率限制 - 权限检查速率限制以防止滥用

🧪 测试

🎯 运行测试

# SQLite 测试
cargo test --features sqlite

# PostgreSQL 测试
cargo test --features postgres

# MySQL 测试
cargo test --features mysql

# 所有测试（需要 Docker）
make test-all

使用 Docker

# 启动数据库
make docker-up

# 运行所有测试
make test-all

# 停止数据库
make docker-down

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 获取详细的贡献指南。

开发设置

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

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

# 运行测试
cargo test --all-features

# 运行 linter
cargo clippy --all-features

📋 更新日志

详见 CHANGELOG.md。

📄 许可证

本项目采用 MIT 许可证：

🙏 致谢

🌟 基于优秀工具构建

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

📞 支持

⭐ Star 历史

💝 支持本项目

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

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部