Crate sz_rust_orm_facade 

ORM Facade — 统一访问 sz-orm 全家桶

设计目标

减少 sz-rust-addons-operate、sz-rust-sz300 等业务包对 sz-orm-* 子包的穿透依赖。 业务包应通过 sz_rust_orm_facade::* 访问 ORM 功能，而非直接依赖 sz-orm-core、 sz-orm-auth、sz-orm-mqtt、sz-orm-scheduler、sz-orm-logger。

使用示例

// 业务包统一通过 facade 访问（推荐）
use sz_rust_orm_facade::{Pool, Value, Model, ModelExt, Authorizer, JwtAuthenticator, MqttConfig, QoS};
use sz_rust_orm_facade::repository::{Repository, WhereCondition, WhereOp};
use sz_rust_orm_facade::scheduler::{CronScheduler, JobHandler, ScheduledTask, Scheduler};

Re-exports

pub use pool_config::SqlxPoolConfig;

Modules

auth

认证子模块（Credentials / User / Claims 等数据结构）

find_with_related

关联查询子模块（find_with_related eager/join/subquery 策略）

hooks

Hooks 子模块（生命周期钩子）

jwt

JWT 子模块（JwtEncoder / JwtClaims 等编码工具）

l2_cache

L2 缓存子模块（二级缓存共享层）

logger

日志子模块（Logger / LogEntry / LogLevel 等）

migration

迁移子模块（schema migration）

pool_config

连接池配置调优（L2 方案：sqlx 配置调优，不修改 sz-orm 上游）

repository

仓储子模块（Repository trait + WhereCondition/WhereOp 条件构造）

scheduler

调度器子模块（CronScheduler / JobHandler / ScheduledTask 等）

Macros

query

Compile-time SQL validation with optional real DB verification.

sql_string

Compile-time SQL validation macro.

Structs

ActiveConfig

Alert

告警事件，由 SaturationGauge / SlaMonitor 等组件在检测到异常时产生， 通过 AlertHook 分发到下游（日志、Webhook 等）。

AliyunOssStorage

阿里云 OSS 存储后端（Mock 实现）

BackpressurePolicy

背压策略

BelongsTo

多对一关系配置

BelongsToMany

多对多关系配置

BuiltQuery

参数化查询构造结果

CronExpr

调度器根级 re-export（供 core 内部 dogfood 使用）

CronScheduler

调度器根级 re-export（供 core 内部 dogfood 使用）

DefaultWebSocketHandler

Default WebSocket handler that tracks connections and echoes messages.

DeleteQuery

DELETE 查询构造器

DistributedRateLimiter

分布式限流器

ErrorBudget

错误预算（Error Budget），基于 SLO 目标和滑动时间窗口。

ErrorRateCounter

错误率计数器，基于滑动时间窗口统计错误率。

FixedWindowRateLimiter

固定窗口限流器

HasMany

一对多关系配置

HasOne

一对一关系配置

HuaweiObsStorage

华为云 OBS 存储后端（Mock 实现）

InMemoryBackend

内存后端（模拟 Redis）

InMemoryQueue

InsertQuery

INSERT 查询构造器

JwtAuthenticator

Authenticator that issues and verifies real HS256 JWTs.

KafkaConfig

LatencyHistogram

延迟分位数直方图。

LocalStorage

LogAlertHook

将告警输出到标准错误流的简单实现。

MemoryCache

Message

消息体

MorphMany

多态一对多配置（父模型侧）

MorphTo

多态反向配置（子模型侧）

MqttConfig

MqttMessage

MqttPlugin

MqttTopic

MultiLevelCache

NatsConfig

OtelTracer

A compatibility wrapper that exposes the same Tracer interface as the OpenTelemetry SDK but is implemented internally by delegating every call to a SzTracer.

Pool

连接池核心实现

PoolConfig

PoolConfigBuilder

PulsarConfig

QiniuKodoStorage

七牛云 Kodo 存储后端（Mock 实现）

Query

查询构造器入口

QueueConfig

RateLimitHeaders

限流响应头

RateLimitResult

RbacAuthorizer

Role-based authorizer backed by a role -> permissions map.

RecordingJobHandler

调度器根级 re-export（供 core 内部 dogfood 使用） JobHandler that records the IDs of every task it has handled, in the order they were handled. Useful for tests that need to assert which tasks fired and in what order.

S3Storage

AWS S3 存储后端（Mock 实现）

SaturationGauge

饱和度告警仪表盘。

ScheduledTask

调度器根级 re-export（供 core 内部 dogfood 使用）

SelectQuery

SELECT 查询构造器

SlaMonitor

SLA 监控器，按操作名聚合延迟与错误统计，并生成 SlaReport。

SlaReport

SLA 监控报告快照，由 SlaMonitor::report 生成。

SlidingWindowRateLimiter

Span

SpanLog

SqlComplexityScore

SQL 复杂度评分结果。

StorageBuilder

StorageConfig

SzTracer

TencentCosStorage

腾讯云 COS 存储后端（Mock 实现）

TimestampFields

时间戳字段配置

TokenBucketRateLimiter

UpYunStorage

又拍云存储后端（Mock 实现）

UpdateQuery

UPDATE 查询构造器

WhitelistValidator

白名单校验器，限制 SQL 只能访问允许的表和列。

WsServer

Enums

AlertLevel

告警级别。

CacheError

缓存特有错误

ComplexityLevel

SQL 复杂度等级。

DbError

数据库错误类型

DbType

支持的数据库类型

MqError

MqProvider

MqttError

OverflowStrategy

溢出处理策略

PoolError

连接池特有错误

QoS

RateLimitError

RateLimitResponseStrategy

限流响应策略

Relation

模型间的关系描述

RelationError

关系操作错误类型

SchedulerError

调度器根级 re-export（供 core 内部 dogfood 使用）

SqlStatementType

SQL statement type detected by the parser

SqlToken

SQL 令牌类型（简化 AST 分析用）。

SqlValidationError

SQL validation errors

StorageError

StorageProvider

StorageWrapper

TracingError

Value

数据库值类型

WsError

Traits

AlertHook

告警分发钩子。实现方可以将告警写入日志、发送到 Webhook、推送到 IM 等。

Authorizer

Cache

Connection

数据库连接 trait

ConnectionFactory

连接工厂 trait，用于创建新连接

JobHandler

调度器根级 re-export（供 core 内部 dogfood 使用） Handler invoked by the scheduler when a task’s cron expression matches the current time. Implementations must be Send + Sync because they may be invoked from a background thread.

MessageQueue

消息队列统一抽象

Model

所有 ORM 模型必须实现的核心 trait

ModelExt

模型扩展 trait，提供额外功能

RateLimiter

RateLimiter trait re-export（限流中间件核心 trait）

RelationAccess

ModelExt 的关系访问扩展方法

RelationLoader

可存储已加载关系数据的模型 trait

Scheduler

调度器根级 re-export（供 core 内部 dogfood 使用）

Storage

Tracer

WebSocketHandler

Functions

detect_statement_type

Detect the type of SQL statement

validate

Entry-level validation that runs all checks

validate_column_name

Validate column name is a valid SQL identifier

validate_delete

Validate a SQL DELETE statement

validate_insert

Validate a SQL INSERT statement

validate_parameter_count

Validate parameter count in prepared statements

validate_select

Validate a SQL SELECT statement

validate_sql

Validate any SQL statement by detecting its type and applying appropriate rules

validate_table_name

Validate table name is a valid SQL identifier

validate_update

Validate a SQL UPDATE statement

value_to_json

将 Value 转换为 serde_json::Value（递归处理 Array）

Type Aliases

ValidationResult

Result type for SQL validation