GitHub - Kirky-X/dbnexus: Enterprise-grade Rust database abstraction layer built on SeaORM — high-performance data access, multi-tenancy, audit logging, and type-safe query builder

企业级 Rust 数据库抽象层

🎯 基于 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.0"
tokio = { version = "1.50", features = ["rt-multi-thread", "macros"] }
sea-orm = { version = "2.0.0-rc.37", 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.0", features = ["sqlite"] }

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

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

# DuckDB（嵌入式分析型数据库，0.3.0 新增）
dbnexus = { version = "0.3.0", 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.0", features = ["runtime-tokio-rustls"] }

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

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

可选功能

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

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

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

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

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

📚 文档

📖 用户指南

完整使用指南

📘 API 参考

完整 API 文档

💻 示例代码

代码示例

📖 补充资源

资源	描述
📖 用户指南	使用 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());

📂 查看所有示例 →

🏗️ 架构

🏗️ 系统架构

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

🤝 贡献

欢迎贡献！请查看仓库获取贡献指南。

开发设置

# 克隆仓库
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

📄 许可证

本项目采用 MIT 许可证：

🙏 致谢

🌟 基于优秀工具构建

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

📞 支持

📋 Issues

报告 Bug 和问题

💬 Discussions

提问和分享想法

🐙 GitHub

查看源代码

⭐ Star 历史

💝 支持本项目

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

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部

Name		Name	Last commit message	Last commit date
Latest commit History 422 Commits
.cargo		.cargo
.github		.github
benches		benches
docs		docs
examples		examples
macros		macros
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
build.rs		build.rs
deny.toml		deny.toml
rustfmt.toml		rustfmt.toml

Folders and files

Latest commit

History

Repository files navigation

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

📋 目录

✨ 功能特性

🎯 核心功能（始终可用）

⚡ 企业级功能

📦 特性预设

🚀 快速开始

📦 安装

💡 基本用法

🎬 5 分钟快速开始

🔒 权限控制

🎨 特性标志

⚠️ v0.2.0 破坏性变更

数据库驱动（选择一个）

协议兼容数据库

运行时

可选功能

📚 文档

📖 补充资源

💻 示例

💡 真实示例

📝 高级配置

🔧 环境变量

🔄 事务处理

📊 监控

🏗️ 架构

🏗️ 系统架构

🔒 安全性

🛡️ 安全特性

🧪 测试

🎯 运行测试

使用 Docker

🤝 贡献

开发设置

📄 许可证

🙏 致谢

🌟 基于优秀工具构建

📞 支持

⭐ Star 历史

💝 支持本项目

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages