Crate sz_orm_core

Expand description

§SZ-ORM — 鲜视达 ORM

Rust 异步 ORM 工作空间（原型阶段），兼容 ThinkORM 风格。

§架构概览

SZ-ORM 工作空间由 43 个成员 组成（41 个 sz-orm-* lib + cli + examples）：

§核心引擎 (sz-orm-core)

模块	功能
`model`	`Model` trait — 定义表名、主键、时间戳、软删除、关联关系
`query`	`QueryBuilder<M>` — 链式 API，支持 SELECT/INSERT/UPDATE/DELETE/聚合/分页/JOIN
`dialect`	多数据库方言 — MySQL (反引号)、PostgreSQL (双引号)、SQLite、Oracle 23ai
`pool`	异步连接池 — 可配置大小、超时、空闲回收、健康检查、最大生命周期
`transaction`	ACID 事务 — 隔离级别、保存点、`TransactionManager` 多事务管理
`migration`	文件迁移系统 — up/down/rollback/reset/refresh，含 `SchemaBuilder`
`cache`	多级缓存 — `MemoryCache`、`MultiLevelCache`，支持 TTL
`value`	统一值类型 — 20 种变体 (整数/浮点/字符串/字节/UUID/日期/JSON/数组)
`db_type`	数据库类型枚举 — MySQL、PostgreSQL、SQLite、Oracle、Redis、MongoDB 等 11 种
`error`	错误类型体系 — `DbError`(20 变体)、`PoolError`、`CacheError`、`TxError`

§数据库适配器

sz-orm-sqlx — sqlx 适配器，连接真实 MySQL/PostgreSQL/SQLite/Oracle
sz-orm-sql-validator — SQL 校验与注入检测

§扩展生态包 (18 个)

包名	功能
sz-orm-crypto	加密原语 (AES-256-GCM, PBKDF2, HMAC-SHA256)
sz-orm-auth	JWT 鉴权 (HS256)
sz-orm-scheduler	Cron 定时任务调度
sz-orm-mqtt	MQTT 客户端 (rumqttc)
sz-orm-websocket	WebSocket 服务端 (tokio-tungstenite)
sz-orm-queue	消息队列 (RabbitMQ/lapin, Kafka, NATS, ActiveMQ, RocketMQ, Pulsar)
sz-orm-storage	对象存储 (S3/阿里云/腾讯云/华为云/七牛/又拍云/本地)
sz-orm-ai	AI 集成 (Embedding, RAG, Vector)
sz-orm-grpc	gRPC 服务/客户端
sz-orm-graphql	GraphQL 查询支持
sz-orm-es	Elasticsearch 集成
sz-orm-tracing	分布式追踪
sz-orm-logger	日志系统
sz-orm-swagger	API 文档生成
sz-orm-masking	数据脱敏
sz-orm-health	健康检查
sz-orm-audit	审计日志
sz-orm-batch	批量操作

§高级特性包 (6 个)

包名	功能
sz-orm-dtx	分布式事务
sz-orm-rw	读写分离
sz-orm-sharding	分库分表
sz-orm-limit	限流控制
sz-orm-config	配置管理
sz-orm-mig	迁移管理增强

§平台支持

sz-orm-wasm — WebAssembly 编译目标
sz-orm-lc — 本地/边缘计算
sz-orm-back — 备份与恢复

§快速入门

use sz_orm_core::*;

// 1. 定义模型
#[derive(Clone)]
struct User {
    id: i64,
    name: String,
    email: String,
}

impl Model for User {
    type PrimaryKey = i64;
    fn table_name() -> &'static str { "users" }
    fn pk(&self) -> Self::PrimaryKey { self.id }
    fn set_pk(&mut self, pk: Self::PrimaryKey) { self.id = pk; }
}

// 2. 构建查询
let dialect = get_dialect(DbType::MySQL).unwrap();
let sql = QueryBuilder::<User>::new(dialect)
    .table("users")
    .select(vec!["id", "name", "email"])
    .where_cond("status = 'active'")
    .order_by("created_at")
    .order_desc("id")
    .limit(10)
    .build_select();

// 3. 执行前校验
QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
    .table("users")
    .select(vec!["id", "name"])
    .validate()?; // 校验 SQL 语法、注入、括号平衡

// 4. 其他操作
let mut data = std::collections::HashMap::new();
data.insert("name".to_string(), Value::String("Alice".to_string()));
data.insert("age".to_string(), Value::I64(25));

let insert_sql = QueryBuilder::<User>::new(dialect)
    .table("users")
    .build_insert(&data);

let update_sql = QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
    .table("users")
    .where_cond("id = 1")
    .build_update(&data);

let delete_sql = QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
    .table("users")
    .where_cond("id = 1")
    .build_delete();

§支持的数据库

数据库	方言实现	真实连接	引用方式
MySQL	`MySqlDialect` (` 反引号)	sz-orm-sqlx	✅
PostgreSQL	`PostgreSqlDialect` (`"` 双引号)	sz-orm-sqlx	✅
SQLite 3.35+	`SqliteDialect` (`"` 双引号)	sz-orm-sqlx	✅
Oracle 23ai	`OracleDialect` (类型自动映射)	sz-orm-sqlx	✅

通过 get_dialect(DbType::MySQL) 获取方言实例。每个方言处理：

标识符引用风格
字符串转义规则
分页语法 (LIMIT/OFFSET vs OFFSET/FETCH)
JSON 提取函数 (JSON_EXTRACT vs #>> vs json_extract vs JSON_VALUE)
全文搜索 (MATCH AGAINST vs to_tsvector vs CONTAINS)
布尔转整数 (IF/CASE)
自增关键字 (AUTO_INCREMENT/GENERATED BY DEFAULT AS IDENTITY)

§核心功能详解

§QueryBuilder API

所有查询方法返回 Self，支持链式调用：

// 基础查询
QueryBuilder::<M>::new(dialect)
    .table("users")
    .select(vec!["id", "name"])
    .where_cond("status = 'active'")    // AND
    .or_where("role = 'admin'")         // OR
    .where_in("id", vec![Value::I64(1), Value::I64(2)])
    .where_between("age", Value::I64(18), Value::I64(30))
    .where_null("deleted_at")
    .order_by("created_at")
    .order_desc("id")
    .group_by("status")
    .having("COUNT(*) > 5")
    .limit(20)
    .offset(40)
    .page(3, 20)                       // page=3, page_size=20
    .join_inner("posts", "users.id", "posts.user_id")
    .join_left("profiles", "users.id", "profiles.user_id")
    .build_select();

// 聚合函数
builder.build_count();    // SELECT COUNT(*)
builder.build_exists();   // SELECT EXISTS(...)
builder.build_max("score");
builder.build_min("price");
builder.build_sum("amount");
builder.build_avg("value");

§SQL 校验

// 编译时 + 运行时双重校验
builder.validate()?;              // 校验 SELECT
builder.validate_insert(&data)?;  // 校验 INSERT（含空数据检测）
builder.validate_update(&data)?;  // 校验 UPDATE（含空数据检测）
builder.validate_delete()?;       // 校验 DELETE

// 校验内容包括：SQL 语法、注入检测、括号平衡、
// 表名/列名合法性、JOIN 列名校验

§Model Trait

pub trait Model: Send + Sync + Sized + 'static {
    type PrimaryKey: Send + Sync + Debug + Display + Clone + Default;

    fn table_name() -> &'static str;          // 表名（必需）
    fn pk_name() -> &'static str { "id" }     // 主键列名
    fn pk(&self) -> Self::PrimaryKey;         // 获取主键值
    fn set_pk(&mut self, pk: Self::PrimaryKey); // 设置主键值
    fn foreign_key(relation: &str) -> String; // 外键命名 "user_id"
    fn timestamp_fields() -> Option<TimestampFields>; // 自动时间戳
    fn soft_delete_field() -> Option<&'static str>;   // 软删除字段
}

// ModelExt 扩展
pub trait ModelExt: Model {
    fn columns() -> Vec<&'static str>;     // 所有列
    fn fillable() -> Vec<&'static str>;    // 可填充列
    fn guarded() -> Vec<&'static str>;     // 保护列（默认含主键）
    fn hidden() -> Vec<&'static str>;      // 隐藏列（不序列化）
    fn relations() -> HashMap<&str, Relation>; // 关联关系
    fn fill(&mut self, data: HashMap<String, Value>); // 批量赋值
    fn to_json(&self) -> serde_json::Value; // 序列化
}

// 四种关联关系
// BelongsTo   — 多对一（Order → User）
// HasMany     — 一对多（User → Orders）
// HasOne      — 一对一（User → Profile）
// BelongsToMany — 多对多（User ↔ Role，通过中间表）

§连接池

// 通过 Builder 配置
let config = PoolConfigBuilder::new()
    .max_size(100)       // 最大连接数
    .min_idle(10)        // 最小空闲连接
    .acquire_timeout(30) // 获取超时（秒）
    .idle_timeout(600)   // 空闲超时（秒）
    .max_lifetime(1800)  // 最大生命周期（秒）
    .build()?;

let pool = Pool::new(config, factory)?;
let conn = pool.acquire().await?;  // 获取连接（带超时）
pool.release(conn).await;         // 归还连接
pool.status().await;               // PoolStatus { idle, active, max, min }
pool.reap_idle().await;           // 回收空闲连接
pool.close_all().await;           // 关闭所有连接

§事务

// 事务选项
let opts = TransactOptions::default()
    .with_isolation(IsolationLevel::Serializable)
    .read_only()
    .with_timeout(Duration::from_secs(30));

let mut tx = Transaction::new(conn, opts);
tx.execute("INSERT INTO users VALUES (1)").await?;
tx.query("SELECT * FROM users").await?;

// 保存点（嵌套事务）
let sp = tx.savepoint().await?;         // SAVEPOINT sp_N
tx.rollback_to_savepoint(&sp).await?;   // ROLLBACK TO SAVEPOINT sp_N
tx.release_savepoint(&sp).await?;       // RELEASE SAVEPOINT sp_N

tx.commit().await?;
// tx.rollback().await?;

// TransactionManager：管理多个命名事务
let mgr = TransactionManager::new();
mgr.begin("tx1", conn, opts).await?;
mgr.commit("tx1").await?;
mgr.list().await;        // ["tx1"]
mgr.state("tx1").await;  // Some(TransactionState::Committed)

§迁移系统

// 文件命名：<version>_<name>_up.sql / <version>_<name>_down.sql
// 示例：001_create_users_up.sql, 001_create_users_down.sql

let resolver = FileMigrationResolver::new(PathBuf::from("./migrations"));
let migrations = resolver.resolve(DbType::MySQL)?;

let mut migrator = Migrator::new(MigrationContext::default())
    .add_migrations(migrations);

migrator.migrate().await?;                     // 执行所有待迁移
migrator.up(Some("003")).await?;               // 执行到指定版本
migrator.down(Some("001")).await?;             // 回滚到指定版本
migrator.rollback("002").await?;               // 回滚单个迁移
migrator.reset().await?;                       // 全部回滚 + 重新执行
migrator.refresh().await?;                     // 同 reset
migrator.progress();                            // MigrationProgress { total, applied, pending }

// SchemaBuilder：程序化建表
let sql = SchemaBuilder::new("users")
    .add_column(ColumnDef::new("id", "INT").not_null().auto_increment())
    .add_column(ColumnDef::new("name", "VARCHAR").length(255).not_null())
    .add_index(IndexDef::new("idx_name", vec!["name"]).unique())
    .add_foreign_key(
        ForeignKeyDef::new("fk_role", "role_id", "roles", "id")
            .on_delete("CASCADE")
    )
    .build(DbType::MySQL);

§值类型 (Value)

// 20 种变体，覆盖所有数据库类型
Value::Null | Bool(bool) | I8..I64 | U8..U64 | F32 | F64
| String(String) | Bytes(Vec<u8>) | Uuid(String) | Date(String)
| DateTime(String) | Time(String) | Json(String) | Array(Vec<Value>)

// 类型转换
value.as_str()    // Option<&str>
value.as_i64()    // Option<i64>（支持 F32/F64/Bool/String→i64 转换）
value.as_f64()    // Option<f64>
value.as_bool()   // Option<bool>（支持 "true"/"1"/"yes"/"on" 等）
value.as_bytes()  // Option<&[u8]>
value.to_param()  // Cow<str> — SQL 参数格式

// From 实现
let v: Value = 42i64.into();
let v: Value = "hello".into();
let v: Value = vec![1u8, 2u8].into();

§错误处理

统一错误类型体系，每种错误携带唯一错误码：

// DbError — 20 种变体，错误码 DB001-DB020
DbError::QueryError("...")
DbError::ConnectionRefused("...")
DbError::ConnectionTimeout("...")
DbError::NotFound("...")
DbError::ConstraintViolation("...")
// ... 等

// PoolError — 6 种变体，错误码 PL001-PL006
PoolError::Exhausted | Timeout | AlreadyAcquired | InvalidConfig | ...

// CacheError — 6 种变体，错误码 CH001-CH006
// TxError — 6 种变体（NotStarted, CommitFailed, SavepointError 等）

// 便捷方法
DbError::query("test failed")        // 创建查询错误
DbError::connection("timeout")       // 创建连接错误
DbError::not_found("user #42")       // 创建未找到错误
err.is_retryable()                   // 是否可重试
err.error_code()                     // "DB001"

§验证方法

SZ-ORM 通过 7 线验证体系 保证质量：

验证方法	描述	测试文件
TDD	核心模块 115+ 单元测试	`core.rs`
集成	真实 MySQL/PG/SQLite/Oracle 端到端	`integration_mysql.rs`, `integration_pg.rs`, `integration_sqlite.rs`
Jepsen	29 并发正确性测试 + 10 真实 DB Jepsen	`jepsen.rs`, `real_db_jepsen.rs`
Fuzz	11 边界/边缘案例发现	`fuzz.rs`
Stress	77 性能基准测试	`stress.rs`, `core_bench.rs`
Chaos	16 故障鲁棒性测试	`chaos.rs`
Formal	14 形式化验证不变量	`formal.rs`

总计：1,723 测试（1,317 #[test] + 406 #[tokio::test]；部分需真实服务）

§类型别名与常量

// 类型别名
pub type Shared<T> = Arc<T>;
pub type Boxed<T> = Box<T>;
pub type DbResult<T> = Result<T, DbError>;
pub type PoolResult<T> = Result<T, PoolError>;
pub type CacheResult<T> = Result<T, CacheError>;
pub type TxResult<T> = Result<T, TxError>;

// 默认常量
pub const DEFAULT_BATCH_SIZE: usize = 1000;
pub const DEFAULT_ACQUIRE_TIMEOUT: u64 = 30;   // 秒
pub const DEFAULT_IDLE_TIMEOUT: u64 = 600;      // 秒
pub const DEFAULT_MAX_LIFETIME: u64 = 1800;     // 秒
pub const DEFAULT_MIN_IDLE: u32 = 5;
pub const DEFAULT_MAX_SIZE: u32 = 100;

§导出清单

use sz_orm_core::*; 将导入以下模块的全部公共符号：

async_trait (重导出)、bytes::Bytes、chrono::{DateTime, Utc}、serde::{Deserialize, Serialize}
cache::* — Cache, MemoryCache, MultiLevelCache, CacheStats
db_type::* — DbType 枚举 (11 种数据库)
dialect::* — Dialect, MySqlDialect, PostgreSqlDialect, SqliteDialect, OracleDialect, get_dialect()
error::* — DbError, PoolError, CacheError, TxError
migration::* — Migration, Migrator, SchemaBuilder, ColumnDef, IndexDef, ForeignKeyDef
model::* — Model, ModelExt, Relation, BelongsTo, HasMany, HasOne, BelongsToMany
pool::* — Pool, PoolConfig, PoolConfigBuilder, Connection, ConnectionFactory, PoolStatus
query::* — QueryBuilder<M> (链式 SQL 构造器)
transaction::* — Transaction, TransactionManager, TransactOptions, IsolationLevel
value::* — Value 枚举 (20 种变体)

Modules§

access_control: 行级和字段级权限控制
accessors: Accessors / Mutators + Attribute Casting
behaviors: 行为系统（Behaviors）— 可插拔代码复用单元
cache: Cache abstraction layer
circuit_breaker: 断路器抽象 trait
data_permission: 数据权限拦截器（Data Permission Interceptor）
db_type: 数据库类型定义
dialect: 不同数据库的方言抽象
dirty_attributes: 脏字段追踪（Dirty Attributes）+ @DynamicInsert / @DynamicUpdate
dynamic_filter: 动态 Filter（Hibernate @Filter / @FilterDef 风格）
dynamic_sql: XML/py_sql 动态 SQL 构造器（rbatis 风格）
entity_graph: Entity Graph + @BatchSize 批量抓取
error: 错误类型与处理
executor: 执行器 trait（模型层与执行层的契约）
find_with_related: find_with_related 关联查询流畅 API
guard: 防全表 UPDATE/DELETE 攻击守卫（Safe SQL Guard）
hooks: 钩子系统（Hooks）— 软删除 + 多租户
hydration_plugin: Hydration Modes + Plugin 拦截器链
i18n: 国际化（i18n）支持
join_dsl: JoinDSL — 类型安全的 JOIN 语法（Diesel 风格）
json_query: JSON 字段查询增强
l2_cache: L2 二级缓存（Level-2 Cache）
lambda: Lambda 类型安全 Wrapper
migration: Migration system
model: 模型抽象层
observer: Observer + Event Subscriber — 模型生命周期观察者模式
optimistic_lock: 乐观锁（Optimistic Locking）
phinx_migration: Phinx 风格 migration 链式 API
pool: Connection Pool
query: 查询构造器
queryable: derive(Queryable) — 从 SELECT 结果自动派生结构体（Diesel 风格）
quick_query: 快捷查询（Db::name 风格）
rate_limiter: 限流器（Rate Limiter）
repository: Repository Pattern 仓储模式
result_map: ResultMap 高级映射 + Native Query + ResultSetMapping
retry: 通用错误重试器
schema_gen: Diesel 风格 schema.rs 自动生成
shadow: 双轨影子流量校验模块
sql_safety: SQL 安全工具：标识符与外键动作校验
transaction: Transaction support
type_handler: TypeHandler SPI — 自定义类型处理器注册
typed: 强类型 AST 支持模块
typed_ast: 强类型 AST 表达式层（Diesel 风格探索）
value: Value 类型定义

Macros§

define_columns: 为 Model 定义一组类型安全的字段标记
schema: Compile-time SQL schema generator.
sql_string: Compile-time SQL validation macro.
typed_query: Diesel 风格强类型 AST 宏（与 sql_string! / query! 并存）。

Structs§

AccessorRegistry: Accessor / Mutator / Cast 注册中心
And: 逻辑 AND 表达式 left AND right
AttributeBehavior: 通用属性 Behavior — 在指定事件触发时通过闭包设置属性
AttributeCaster: 类型转换器
AuditPlugin: 审计插件（记录所有写操作）
AuditRecord: 审计记录
BatchLoader: 批量加载器
BatchSizeConfig: 批量大小配置
BehaviorRegistry: Behavior 注册中心 — 管理多个 Behavior 的注册与分发
BelongsTo: 多对一关系配置
BelongsToMany: 多对多关系配置
BigInt: SQL BigInt 类型（对应 i64 / BIGINT）
Binary: SQL Binary 类型（对应 Vec / BLOB/BYTEA/VARBINARY）
BlameableBehavior: 自动填充操作人 Behavior
BlockPlugin: 阻断插件（演示 Abort 决策）
Bool: SQL Bool 类型（WHERE 条件表达式结果）
Bytes: Re-export common types A cheaply cloneable and sliceable chunk of contiguous memory.
CacheStats
ClickHouseDialect: ClickHouse 方言实现（列式 OLAP 数据库）
ClosureAccessor: 闭包风格 Accessor
ClosureMutator: 闭包风格 Mutator
ColumnExpr: 列引用表达式
ColumnOptions: 列选项构建器（Phinx 风格链式配置）
ColumnSchema: 单列的元数据（足够生成 typed_query! 声明）
CustomCondition: 自定义条件规则 — 通过闭包动态生成 WHERE 子句
DamengDialect: 兼容方言（委派给基础方言实现）
DataPermissionInterceptor: 数据权限拦截器 — 注册多个规则并应用到 SQL
Date: SQL Date 类型（对应日期，不含时间）
DateTime: ISO 8601 combined date and time with time zone.
Db: 快捷查询入口（think-orm Db::name() 风格）
Db2Dialect: IBM DB2 LUW 方言实现
DefaultCircuitBreaker: 默认断路器实现
DepartmentScope: 部门范围规则 — 自动追加 dept_id IN (...) 或 dept_id = ? 条件
DirtyTracker: 脏字段追踪器
Discriminator: 多态鉴别器
DiscriminatorCase: 多态鉴别器 case
Double: SQL Double 类型（对应 f64 / DOUBLE/DOUBLE PRECISION）
DynamicSqlParser: 动态 SQL 解析器
EnabledFilter: 已启用的 Filter 实例（携带运行时参数）
EntityGraph: 实体图
EntityResult: Entity 结果（用于 ResultSetMapping）
Eq: 相等比较表达式 column = value
ErrorContext: #6 修复：错误上下文链节点
FieldResult: 实体字段结果
FileMigrationResolver
FilterDef: Filter 定义
FilterParam: Filter 参数定义
FilterRegistry: Filter 注册表 — 管理 FilterDef + 启用状态 + 运行时参数
FindWithRelated: find_with_related 关联查询构造器（JOIN 模式）
ForeignKeyDef
ForeignKeyOptions: 外键选项构建器（Phinx 风格链式配置）
GBaseDialect: 兼容方言（委派给基础方言实现）
GaussDbDialect: 兼容方言（委派给基础方言实现）
Ge: 大于等于比较表达式 column >= value
GraphEdge: 实体图边（关联关系）
Gt: 大于比较表达式 column > value
HasMany: 一对多关系配置
HasOne: 一对一关系配置
HookContext: 钩子执行上下文
HookDispatcher: 钩子执行辅助工具
HookRegistry: 钩子注册表
IndexDef
IndexOptions: 索引选项构建器（Phinx 风格链式配置）
Integer: SQL Integer 类型（对应 i32 / INT）
JoinBuilder: JOIN 构造器（已指定 JOIN 类型，待指定右表）
JoinBuilt: JOIN 已完整构造，可生成 SQL
JoinOn: JOIN 已指定右表，待指定 ON 条件
Json: SQL JSON 类型
JsonQuery: JSON 字段查询构造器
JsonUpdate: JSON 字段更新构造器
KingbaseDialect: 兼容方言（委派给基础方言实现）
LambdaWrapper: Lambda 类型安全查询构造器
Le: 小于等于比较表达式 column <= value
Literal: 字面量表达式
Lt: 小于比较表达式 column < value
Mapping: 单字段映射规则（property <-> column）
MariaDbDialect: 兼容方言（委派给基础方言实现）
MemoryCache
Migration
MigrationContext
MigrationProgress
Migrator
MorphMany: 多态一对多配置（父模型侧）
MorphTo: 多态反向配置（子模型侧）
MultiLevelCache
MySqlDialect: MySQL 方言实现
N1Alert: N+1 查询告警
N1DetectionConfig: N+1 检测配置
N1QueryDetector: N+1 查询检测器
NativeQuery: NativeQuery — 原生 SQL + ResultSetMapping
Ne: 不相等比较表达式 column != value
NegativeCache: 带负缓存的缓存包装器
NestedAssociation: 一对一嵌套映射（association）
NestedCollection: 一对多嵌套映射（collection）
Nullable: 可空类型包装器（对应 Option / NULLABLE）
Or: 逻辑 OR 表达式 left OR right
OracleDialect: Oracle 方言实现（Oracle 23ai）
OrderBy: 排序子句
OwnerOnly: 仅所有者可访问规则 — 自动追加 user_id = ? 条件
PermissionContext: 权限上下文 — 当前请求的用户/租户/部门信息
PhinxTable: Phinx 风格表构建器
PluginChain: 插件链（按注册顺序执行）
PluginContext: 插件上下文（携带操作信息）
PolarDbDialect: 兼容方言（委派给基础方言实现）
Pool: 连接池核心实现
PoolConfig
PoolConfigBuilder
PoolStatus
PooledConnection: 连接池中的连接条目，记录创建时间和最后使用时间
PostgreSqlDialect: PostgreSQL 方言实现
QueryBuilder: 用于构造 SQL 查询的查询构造器
QueryBuilderWrapper: 查询构造器包装类型，用于挂载作用域
RateLimitResult: 限流判定结果
Real: SQL Real 类型（对应 f32 / FLOAT/REAL）
ResultMap: 完整结果映射规则
ResultMapRegistry: ResultMap 注册中心（线程安全）
ResultSetMapping: Hibernate @SqlResultSetMapping 风格的结果集映射
ResultSetMappingRegistry: ResultSetMapping 注册中心
RowData: 行数据（列名 -> Value）
RowDesc: 行描述：列名 + 列数
SafeSqlGuard: 防全表 UPDATE/DELETE 攻击守卫
ScalarResult: 标量结果列
SchemaBuilder
SchemaGenerator: 生成器：把表元数据列表转换成 schema.rs 文件内容
ScopeRegistry: 全局作用域注册表
SlowQueryPlugin: 慢查询检测插件
SlowQueryRecord: 慢查询记录
SmallInt: SQL SmallInt 类型（对应 i8/i16 / TINYINT/SMALLINT）
SoftDeleteConfig: 软删除配置
SoftDeleteScope: 软删除全局作用域
SqlLogPlugin: SQL 日志插件
SqlParams: SQL 参数容器
SqlRewritePlugin: SQL 改写插件（演示 Modified 决策）
SqlServerDialect: SQL Server 方言实现（SQL Server 2012+ / T-SQL）
SqliteDialect: SQLite 方言实现
SybaseDialect: 兼容方言（委派给基础方言实现）
TableSchema: 单表的元数据
TenantBehavior: 自动填充 tenant_id Behavior
TenantConfig: 多租户配置
TenantIsolation: 租户隔离规则 — 自动追加 tenant_id = ? 条件
TenantScope: 多租户全局作用域
Text: SQL Text 类型（对应 String / VARCHAR/TEXT）
TiDbDialect: 兼容方言（委派给基础方言实现）
TimestampBehavior: 自动填充时间戳 Behavior
TimestampFields: 时间戳字段配置
TlsConfig: TLS 配置
TransactOptions
Transaction: 事务对象，封装一个数据库事务
TransactionManager: 事务管理器，管理多个事务
TypedSelectQuery: 类型安全的 SELECT 查询构造器
Untyped: 未指定的 SQL 类型
Utc: The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).
Uuid: SQL UUID 类型
ValidationError: SQL 校验错误集合。
XmlNode

Enums§

AutoCommit
BatchStrategy: 批量抓取策略
CacheError: 缓存特有错误
CacheLookup: 缓存查找结果
CastType: 字段类型转换枚举
CircuitState: 断路器状态
ColType: 列类型枚举（v1.1.0 新增）
ColumnType: Phinx 风格列类型枚举
DbError: 数据库错误类型
DbType: 支持的数据库类型
DynamicSqlError: 动态 SQL 错误
ExecutionStage: 执行阶段
FilterError: Filter 错误类型
GuardError: 守卫错误类型
GuardPolicy: 守卫策略
HookEvent: 钩子事件类型
HydrationError: Hydration 错误
HydrationMode: Hydration 填充模式
IsolationLevel
JoinKind: JOIN 类型
MigrationDirection
OrderDirection: 排序方向
ParamValue: 参数值
PermissionError: 数据权限错误类型
PluginDecision: 插件决策
PoolError: 连接池特有错误
PoolEvent: 连接池事件
PropagationBehavior: 事务传播行为
QueryError: 反序列化错误
RateLimitError: 限流器错误
Relation: 模型间的关系描述
RelationError: 关系操作错误类型
ResultMapError: ResultMap 错误
TableChange: ALTER TABLE 的变更操作
TenantUpdatePolicy: 租户隔离行为配置：是否在 update 时强制 tenant_id 不可变更
TlsVersion: TLS 版本
TransactionState: 事务状态
TxError: 事务特有错误
Value: 数据库值类型
WhereClause: WHERE 条件子句（内部表示）
XmlNodeType

Constants§

DEFAULT_ACQUIRE_TIMEOUT: Default connection timeout in seconds
DEFAULT_BATCH_SIZE: 批量操作的默认分片大小。
DEFAULT_IDLE_TIMEOUT: Default idle timeout in seconds
DEFAULT_MAX_LIFETIME: Default max lifetime in seconds
DEFAULT_MAX_NESTING_DEPTH: H-8 默认最大嵌套深度
DEFAULT_MAX_SIZE: Default maximum pool size
DEFAULT_MIN_IDLE: Default minimum idle connections
MAX_IDENTIFIER_LEN: L-4 修复：SQL 标识符最大长度（取所有主流数据库最严格值）

Traits§

Accessor: 自定义字段读取器（Accessor / Getter）
ActiveRecord: 支持关系加载的模型 trait（ActiveRecord 模式）
Behavior: 行为 trait — 可插拔代码复用单元
Cache
CircuitBreaker: 断路器抽象 trait
Column: 字段标记 trait
Connection: 数据库连接 trait
ConnectionFactory: 连接工厂 trait，用于创建新连接
Deserialize: A data structure that can be deserialized from any data format supported by Serde.
Dialect: 数据库方言 trait
Executor: 最小执行器 trait
ExprTable: 表达式所属的表（用于跨表列引用检查）
FromRow: 从 HashMap<String, Value> 按列名反序列化（更鲁棒）
GlobalScope: 全局查询作用域
Hookable: 可钩选 Model trait
InferSqlType: Rust 类型 → SQL 类型标记推断 trait
MigrationResolver
Model: 所有 ORM 模型必须实现的核心 trait
ModelExt: 模型扩展 trait，提供额外功能
Mutator: 自定义字段设置器（Mutator / Setter）
PermissionRule: 数据权限规则 trait
Plugin: Plugin 拦截器 trait
QueryBuilderExt
Queryable: 从 Vec<Value> 按列顺序反序列化（Diesel 风格）
RateLimiter: 限流器抽象 trait
RelationAccess: ModelExt 的关系访问扩展方法
RelationLoader: 可存储已加载关系数据的模型 trait
Scope: 查询结果过滤作用域
Serialize: A data structure that can be serialized into any data format supported by Serde.
SoftDelete: 软删除 trait
SqlType: SQL 类型标记 trait
TenantModel: 多租户 Model trait
TypedColumn: 类型安全的列标记 trait
TypedColumnExt: 列扩展 trait：为 TypedColumn 提供 .eq() / .lt() / .gt() 等便捷方法
TypedExpression: 强类型表达式 trait
TypedTable: 类型安全的表标记 trait

Functions§

_schema_lookup: 在编译期查找表 schema 常量
append_where_clauses: 将权限子句追加到 SQL 的 WHERE 部分
apply_result_map: 应用 ResultMap 规则到单行，返回属性 HashMap
apply_result_map_many: 应用 ResultMap 到多行，处理 collection 聚合
apply_result_set_mapping: 应用 ResultSetMapping 到单行，返回 (entity_attrs_vec, scalar_values_vec)
apply_result_set_mapping_many: 应用 ResultSetMapping 到多行
build_dynamic_insert: 生成仅含非 null 字段的 INSERT SQL（对应 Hibernate @DynamicInsert）
build_dynamic_update: 生成仅含脏字段的 UPDATE SQL（对应 Hibernate @DynamicUpdate）
cross_join: 便捷函数：构造 CROSS JOIN
find_with_related_eager_sql: 生成 eager load 的两条 SQL（适合 1:N 关联）
find_with_related_join: 生成 JOIN 模式 SQL（便捷函数）
find_with_related_subquery: 生成子查询模式 SQL（适合 1:N 关联，避免主表行膨胀）
full_join: 便捷函数：构造 FULL OUTER JOIN
get_dialect: 根据数据库类型获取对应的方言实例
hydrate: 通用 hydrate 函数：根据 mode 自动选择
hydrate_array: Array 模式：每行 → Vec<Value>（按列名排序后顺序）
hydrate_column: Column 模式：每行的指定列 → Vec<Value>
hydrate_object: Object 模式：每行 → HashMap<String, Value>
hydrate_scalar: Scalar 模式：每行 → Value（取第一列，按列名排序）
hydrate_single_scalar: SingleScalar 模式：唯一行 + 唯一列 → Value
inner_join: 便捷函数：构造 INNER JOIN
inspect_relation: 高级辅助：从 relations map 中提取关联表的元数据
is_deadlock_error: M-8 修复：检测错误字符串是否表示死锁
left_join: 便捷函数：构造 LEFT JOIN
read_through: Read-through（同步版）：缓存未命中时通过 loader 回源加载，写入缓存后返回
read_through_async: Read-through（异步版）：缓存未命中时通过异步 loader 回源加载，写入缓存后返回
render_condition: 渲染 WHERE 子句模板，将 :param_name 替换为实际值
render_condition_with_dialect: v0.2.2 修复 H-1：方言感知的 WHERE 子句模板渲染
retry_on_deadlock: M-8 修复：在死锁时自动重试事务
right_join: 便捷函数：构造 RIGHT JOIN
rows_to_values: 将查询结果行转换为 Vec<HashMap<String, Value>> 以便存入关系字段
set_error_hook: 设置全局错误上报 hook
sql_type_to_rust: 把 SQL 类型字符串映射到 Rust 类型字符串
trigger_error_hook: 触发错误 hook（在 DbError 创建/返回时调用）
validate_fk_action: 校验外键 ON DELETE / ON UPDATE 动作
validate_id_value: 校验 IN 子句中的 id 值
validate_identifier: 校验 SQL 标识符（表名/列名/约束名/索引名）
value_as_bool: 提取 bool
value_as_f64: 提取 f64
value_as_i64: 提取 i64（支持 I8/I16/I32/I64/U8/U16/U32/U64/F32/F64/Bool/String 转换）
value_as_nullable_i64: 提取 Option<i64>（Null 返回 None）
value_as_nullable_string: 提取 Option<String>（Null 返回 None）
value_as_string: 提取 String
value_to_json: 将 Value 转换为 serde_json::Value（递归处理 Array）
write_around: Write-around（写旁路）：仅写后端存储，同时失效缓存中的旧值
write_through: Write-through（同步版）：同时写入缓存和后端存储（通过 writer 回调）
write_through_async: Write-through（异步版）：同时写入缓存和异步后端存储

Type Aliases§

BatchLoaderFn: 批量加载函数类型
BehaviorResult: Behavior 处理结果
Boxed: Alias for Box<T>
CacheResult: Result type for cache operations
ConditionGenerator: 条件生成闭包类型
DbResult: Alias for Result<T, DbError>
FilterResult: Filter 结果
GuardResult: 守卫结果
HookFn: 运行时钩子函数类型
HookResult: 钩子执行结果
HydrationResult: Hydration 结果类型
PermissionResult: 权限结果
PoolEventCallback: 连接池事件回调
PoolResult: Result type for pool operations
QueryRows: 查询结果行：Vec<HashMap<列名, 值>>
QueryStreamItem: 流式查询结果项类型别名：避免 Connection::query_stream 签名触发 clippy::type_complexity。
QueryValues: 位置式查询结果类型
ResultSetMappingResult: ResultSetMapping 应用结果类型（entities + scalars）
Shared: Alias for Arc<T>
TxResult: Result type for transaction operations

Attribute Macros§

async_trait: Re-export async traits

Derive Macros§

Deserialize
Serialize

Crate sz_orm_core

Crate sz_orm_core Copy item path

§SZ-ORM — 鲜视达 ORM

§架构概览

§核心引擎 (sz-orm-core)

§数据库适配器

§扩展生态包 (18 个)

§高级特性包 (6 个)

§平台支持

§快速入门

§支持的数据库

§核心功能详解

§QueryBuilder API

§SQL 校验

§Model Trait

§连接池

§事务

§迁移系统

§值类型 (Value)

§错误处理

§验证方法

§类型别名与常量

§导出清单

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate sz_orm_core