Skip to main content

yang_db/
capability.rs

1//! 后端能力与安全约束的单一事实源。
2
3/// 后端类型。
4#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
5#[non_exhaustive]
6pub enum BackendKind {
7    /// MySQL 关系数据库。
8    MySql,
9    /// PostgreSQL 关系数据库。
10    PostgreSql,
11    /// Redis 键值数据库。
12    Redis,
13}
14
15/// SQL 占位符风格;非关系后端使用 `NotApplicable`。
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17#[non_exhaustive]
18pub enum PlaceholderStyle {
19    /// MySQL 的 `?` 占位符。
20    QuestionMark,
21    /// PostgreSQL 的 `$1`、`$2` 编号占位符。
22    NumberedDollar,
23    /// 后端不使用 SQL 占位符。
24    NotApplicable,
25}
26
27/// 可被调用方查询的后端能力。
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29#[non_exhaustive]
30pub enum BackendCapability {
31    /// checked identifier QueryBuilder API。
32    CheckedIdentifiers,
33    /// SELECT/find/value 查询。
34    Select,
35    /// count/sum/avg/min/max 聚合。
36    Aggregate,
37    /// INNER/LEFT/RIGHT JOIN。
38    Join,
39    /// 单行插入。
40    Insert,
41    /// 批量插入及显式 batch size。
42    BatchInsert,
43    /// 条件更新。
44    Update,
45    /// 批量更新。
46    BatchUpdate,
47    /// 条件删除。
48    Delete,
49    /// 方言原生 UPSERT。
50    Upsert,
51    /// 批量 UPSERT。MySQL 是 `INSERT ... ON DUPLICATE KEY UPDATE`;
52    /// PostgreSQL 是 `INSERT ... ON CONFLICT (...) DO UPDATE SET ...`(形状不同)。
53    BatchUpsert,
54    /// PostgreSQL `RETURNING`。
55    Returning,
56    /// PostgreSQL 显式冲突列 `ON CONFLICT (...)`。
57    ExplicitConflictTarget,
58    /// 事务保存点(`SAVEPOINT` / `ROLLBACK TO SAVEPOINT`)。
59    Savepoint,
60    /// 行锁跳过已锁定行(`FOR UPDATE SKIP LOCKED`)。
61    SkipLocked,
62    /// 批量 COPY 导入(PostgreSQL `COPY ... FROM STDIN`)。
63    Copy,
64    /// LISTEN / NOTIFY 通知通道。
65    ListenNotify,
66    /// WITH / WITH RECURSIVE 公共表表达式。
67    Cte,
68    /// 窗口函数(`OVER (...)`)。
69    Window,
70    /// PostgreSQL 数组类型与 `= ANY(...)` / `= ALL(...)` 谓词。
71    Arrays,
72    /// PostgreSQL 范围类型(`int4range` 等)。
73    Range,
74    /// PostgreSQL 多范围类型(`int4multirange` 等)。
75    Multirange,
76    /// jsonpath 查询(`jsonb_path_exists` / `jsonb_path_match`)。
77    JsonPath,
78    /// 全文检索(`to_tsvector` / `to_tsquery`)。
79    FullText,
80    /// MERGE(PostgreSQL 15+,执行前按 `server_version_num` 门控)。
81    Merge,
82    /// 查询计划与锁等待诊断(`EXPLAIN`、`pg_stat_activity` / `pg_locks`)。
83    Diagnostics,
84    /// 两阶段提交(`PREPARE TRANSACTION` / `COMMIT PREPARED` / `ROLLBACK PREPARED`)。
85    TwoPhaseCommit,
86    /// 表级锁(`LOCK TABLE`)。
87    TableLock,
88    /// 事务级会话配置(`SET LOCAL`)。
89    TransactionLocalConfig,
90    /// SQL 事务内的 insert/update/delete 构建器。
91    TransactionCrud,
92    /// Redis Pipeline。
93    RedisPipeline,
94    /// Redis WATCH/MULTI/EXEC 乐观锁事务。
95    RedisOptimisticTransaction,
96    /// Redis Lua 脚本执行。
97    RedisLua,
98}
99
100/// 后端公开 API 必须遵守的安全约束。
101#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
102#[non_exhaustive]
103pub enum SafetyConstraint {
104    /// 数据值使用驱动绑定参数,不拼接为 SQL/命令文本。
105    ParameterizedValues,
106    /// 外部标识符通过 checked identifier API 进入。
107    CheckedIdentifiers,
108    /// 可信 SQL 表达式入口与标识符入口在 API 上显式分离。
109    ExplicitTrustedExpressions,
110    /// UPDATE/DELETE 缺少 WHERE 时 fail-closed。
111    WriteRequiresWhere,
112    /// Redis 命令和值通过结构化参数传给驱动。
113    StructuredCommandArguments,
114}
115
116/// 单个后端的能力快照。
117#[derive(Debug, Clone, Copy, PartialEq, Eq)]
118#[non_exhaustive]
119pub struct BackendCapabilities {
120    /// 后端类型。
121    pub backend: BackendKind,
122    /// 是否为关系数据库。
123    pub relational: bool,
124    /// SQL 占位符风格。
125    pub placeholder_style: PlaceholderStyle,
126    /// QueryBuilder 或原生命令层能力。
127    pub operations: &'static [BackendCapability],
128    /// 事务层能力。
129    pub transaction: &'static [BackendCapability],
130    /// 强制安全约束。
131    pub safety: &'static [SafetyConstraint],
132}
133
134impl BackendCapabilities {
135    /// 判断后端是否声明指定能力。
136    pub fn supports(&self, capability: BackendCapability) -> bool {
137        self.operations.contains(&capability) || self.transaction.contains(&capability)
138    }
139
140    /// 判断后端是否声明指定安全约束。
141    pub fn enforces(&self, constraint: SafetyConstraint) -> bool {
142        self.safety.contains(&constraint)
143    }
144}
145
146const MYSQL_OPERATIONS: &[BackendCapability] = &[
147    BackendCapability::CheckedIdentifiers,
148    BackendCapability::Select,
149    BackendCapability::Aggregate,
150    BackendCapability::Join,
151    BackendCapability::Insert,
152    BackendCapability::BatchInsert,
153    BackendCapability::Update,
154    BackendCapability::BatchUpdate,
155    BackendCapability::Delete,
156    BackendCapability::Upsert,
157    BackendCapability::BatchUpsert,
158];
159
160// PostgreSQL 已实现的全部能力。事务专属能力(保存点、两阶段提交、表级锁、
161// SET LOCAL)声明在 [`POSTGRES_CAPABILITIES`] 的 `transaction` 切片中,
162// [`BackendCapabilities::supports`] 对两个切片一视同仁。
163//
164// MySQL 与 Redis 不得声明 PG 专属能力:能力矩阵是调用方机读契约,
165// 虚报会让下游在错误 SQL 处才暴露问题。
166const POSTGRES_OPERATIONS: &[BackendCapability] = &[
167    BackendCapability::CheckedIdentifiers,
168    BackendCapability::Select,
169    BackendCapability::Aggregate,
170    BackendCapability::Join,
171    BackendCapability::Insert,
172    BackendCapability::BatchInsert,
173    BackendCapability::Update,
174    BackendCapability::BatchUpdate,
175    BackendCapability::Delete,
176    BackendCapability::Upsert,
177    BackendCapability::BatchUpsert,
178    BackendCapability::Returning,
179    BackendCapability::ExplicitConflictTarget,
180    BackendCapability::SkipLocked,
181    BackendCapability::Copy,
182    BackendCapability::ListenNotify,
183    BackendCapability::Cte,
184    BackendCapability::Window,
185    BackendCapability::Arrays,
186    BackendCapability::Range,
187    BackendCapability::Multirange,
188    BackendCapability::JsonPath,
189    BackendCapability::FullText,
190    BackendCapability::Merge,
191    BackendCapability::Diagnostics,
192];
193
194const SQL_SAFETY: &[SafetyConstraint] = &[
195    SafetyConstraint::ParameterizedValues,
196    SafetyConstraint::CheckedIdentifiers,
197    SafetyConstraint::ExplicitTrustedExpressions,
198    SafetyConstraint::WriteRequiresWhere,
199];
200
201/// MySQL 能力契约。
202pub const MYSQL_CAPABILITIES: BackendCapabilities = BackendCapabilities {
203    backend: BackendKind::MySql,
204    relational: true,
205    placeholder_style: PlaceholderStyle::QuestionMark,
206    operations: MYSQL_OPERATIONS,
207    transaction: &[BackendCapability::TransactionCrud],
208    safety: SQL_SAFETY,
209};
210
211/// PostgreSQL 能力契约。
212pub const POSTGRES_CAPABILITIES: BackendCapabilities = BackendCapabilities {
213    backend: BackendKind::PostgreSql,
214    relational: true,
215    placeholder_style: PlaceholderStyle::NumberedDollar,
216    operations: POSTGRES_OPERATIONS,
217    transaction: &[
218        BackendCapability::TransactionCrud,
219        BackendCapability::Returning,
220        BackendCapability::Savepoint,
221        BackendCapability::TwoPhaseCommit,
222        BackendCapability::TableLock,
223        BackendCapability::TransactionLocalConfig,
224    ],
225    safety: SQL_SAFETY,
226};
227
228/// Redis 能力契约。
229pub const REDIS_CAPABILITIES: BackendCapabilities = BackendCapabilities {
230    backend: BackendKind::Redis,
231    relational: false,
232    placeholder_style: PlaceholderStyle::NotApplicable,
233    operations: &[
234        BackendCapability::RedisPipeline,
235        BackendCapability::RedisLua,
236    ],
237    transaction: &[BackendCapability::RedisOptimisticTransaction],
238    safety: &[SafetyConstraint::StructuredCommandArguments],
239};
240
241#[cfg(test)]
242mod tests {
243    use super::*;
244    #[cfg(any(feature = "mysql", feature = "postgres", feature = "redis"))]
245    use std::future::Future;
246
247    #[cfg(any(feature = "mysql", feature = "postgres", feature = "redis"))]
248    fn assert_future<T>(_future: impl Future<Output = T>) {}
249
250    #[cfg(feature = "mysql")]
251    fn mysql_management_contract(db: &crate::mysql::Database) {
252        let _: &'static BackendCapabilities = crate::mysql::Database::capabilities();
253        let _: crate::PoolStatus = db.pool_status();
254        let _: bool = db.is_closed();
255        assert_future::<Result<bool, crate::DbError>>(db.health_check());
256        assert_future::<()>(db.close());
257    }
258
259    #[cfg(feature = "postgres")]
260    fn postgres_management_contract(db: &crate::postgres::Database) {
261        let _: &'static BackendCapabilities = crate::postgres::Database::capabilities();
262        let _: crate::PoolStatus = db.pool_status();
263        let _: bool = db.is_closed();
264        assert_future::<Result<bool, crate::DbError>>(db.health_check());
265        assert_future::<()>(db.close());
266    }
267
268    #[cfg(feature = "redis")]
269    fn redis_management_contract(client: &crate::redis::RedisClient) {
270        let _: &'static BackendCapabilities = crate::redis::RedisClient::capabilities();
271        let _: crate::PoolStatus = client.pool_status();
272        let _: bool = client.is_closed();
273        assert_future::<Result<bool, crate::DbError>>(client.health_check());
274        assert_future::<()>(client.close());
275    }
276
277    #[test]
278    fn management_contract_signatures_compile() {
279        #[cfg(feature = "mysql")]
280        let _ = mysql_management_contract;
281        #[cfg(feature = "postgres")]
282        let _ = postgres_management_contract;
283        #[cfg(feature = "redis")]
284        let _ = redis_management_contract;
285    }
286
287    #[test]
288    fn sql_backends_share_common_contract_and_expose_dialect_differences() {
289        for capability in [
290            BackendCapability::CheckedIdentifiers,
291            BackendCapability::Select,
292            BackendCapability::Aggregate,
293            BackendCapability::Join,
294            BackendCapability::Insert,
295            BackendCapability::BatchInsert,
296            BackendCapability::Update,
297            BackendCapability::BatchUpdate,
298            BackendCapability::Delete,
299            BackendCapability::Upsert,
300            BackendCapability::TransactionCrud,
301        ] {
302            assert!(MYSQL_CAPABILITIES.supports(capability));
303            assert!(POSTGRES_CAPABILITIES.supports(capability));
304        }
305
306        assert!(!MYSQL_CAPABILITIES.supports(BackendCapability::Returning));
307        assert!(POSTGRES_CAPABILITIES.supports(BackendCapability::Returning));
308        assert!(!MYSQL_CAPABILITIES.supports(BackendCapability::ExplicitConflictTarget));
309        assert!(POSTGRES_CAPABILITIES.supports(BackendCapability::ExplicitConflictTarget));
310    }
311
312    #[test]
313    fn both_backends_declare_batch_upsert() {
314        // 形状不同(MySQL ODKU / PG ON CONFLICT + EXCLUDED),但两家都已实现。
315        assert!(MYSQL_CAPABILITIES.supports(BackendCapability::BatchUpsert));
316        assert!(POSTGRES_CAPABILITIES.supports(BackendCapability::BatchUpsert));
317    }
318
319    #[test]
320    fn postgres_capabilities_match_implemented_features() {
321        // P1-26:Phase C 已实现的能力必须全部声明。
322        for capability in [
323            BackendCapability::Savepoint,
324            BackendCapability::Cte,
325            BackendCapability::Window,
326            BackendCapability::SkipLocked,
327            BackendCapability::Returning,
328            BackendCapability::ExplicitConflictTarget,
329            BackendCapability::Copy,
330            BackendCapability::ListenNotify,
331            BackendCapability::BatchUpsert,
332            BackendCapability::Arrays,
333            BackendCapability::Range,
334            BackendCapability::Multirange,
335            BackendCapability::JsonPath,
336            BackendCapability::FullText,
337            BackendCapability::Merge,
338            BackendCapability::Diagnostics,
339            BackendCapability::TwoPhaseCommit,
340            BackendCapability::TableLock,
341            BackendCapability::TransactionLocalConfig,
342        ] {
343            assert!(
344                POSTGRES_CAPABILITIES.supports(capability),
345                "PostgreSQL 已实现 {capability:?},必须声明"
346            );
347        }
348
349        // 可信表达式入口与标识符入口在 API 上显式分离。
350        assert!(
351            POSTGRES_CAPABILITIES.enforces(SafetyConstraint::ExplicitTrustedExpressions),
352            "PostgreSQL 必须声明 ExplicitTrustedExpressions 安全约束"
353        );
354
355        // 仅 PostgreSQL 实现的差异能力不得被 MySQL/Redis 提前声明。
356        for capability in [
357            BackendCapability::Copy,
358            BackendCapability::ListenNotify,
359            BackendCapability::Arrays,
360            BackendCapability::Range,
361            BackendCapability::Multirange,
362            BackendCapability::JsonPath,
363            BackendCapability::FullText,
364            BackendCapability::Merge,
365            BackendCapability::Diagnostics,
366            BackendCapability::TwoPhaseCommit,
367            BackendCapability::TableLock,
368            BackendCapability::TransactionLocalConfig,
369        ] {
370            assert!(
371                !MYSQL_CAPABILITIES.supports(capability),
372                "MySQL 未实现 {capability:?},不得声明"
373            );
374            assert!(
375                !REDIS_CAPABILITIES.supports(capability),
376                "Redis 未实现 {capability:?},不得声明"
377            );
378        }
379    }
380
381    #[test]
382    fn non_postgres_backends_do_not_claim_postgres_only_capabilities() {
383        // 能力矩阵是机读契约;任一 PG 专属能力被 MySQL/Redis 声明都视为回归。
384        for capability in [
385            BackendCapability::Returning,
386            BackendCapability::ExplicitConflictTarget,
387            BackendCapability::SkipLocked,
388            BackendCapability::Savepoint,
389            BackendCapability::Cte,
390            BackendCapability::Window,
391            BackendCapability::Arrays,
392            BackendCapability::Range,
393            BackendCapability::Multirange,
394            BackendCapability::JsonPath,
395            BackendCapability::FullText,
396            BackendCapability::Merge,
397            BackendCapability::Diagnostics,
398            BackendCapability::TwoPhaseCommit,
399            BackendCapability::TableLock,
400            BackendCapability::TransactionLocalConfig,
401        ] {
402            assert!(!MYSQL_CAPABILITIES.supports(capability), "{capability:?}");
403            assert!(!REDIS_CAPABILITIES.supports(capability), "{capability:?}");
404        }
405    }
406
407    #[test]
408    fn redis_is_explicitly_non_relational() {
409        let redis = std::hint::black_box(REDIS_CAPABILITIES);
410
411        assert!(!redis.relational);
412        assert_eq!(redis.placeholder_style, PlaceholderStyle::NotApplicable);
413        assert!(!redis.supports(BackendCapability::Select));
414        assert!(redis.supports(BackendCapability::RedisPipeline));
415        assert!(redis.supports(BackendCapability::RedisOptimisticTransaction));
416        assert!(redis.supports(BackendCapability::RedisLua));
417    }
418
419    #[test]
420    fn sql_safety_contract_is_symmetric() {
421        for constraint in SQL_SAFETY {
422            assert!(MYSQL_CAPABILITIES.enforces(*constraint));
423            assert!(POSTGRES_CAPABILITIES.enforces(*constraint));
424        }
425        assert!(REDIS_CAPABILITIES.enforces(SafetyConstraint::StructuredCommandArguments));
426        assert!(!REDIS_CAPABILITIES.enforces(SafetyConstraint::WriteRequiresWhere));
427    }
428}