Skip to main content

yang_base/table/
record.rs

1//! 数据库记录类型
2//!
3//! 提供 `Record` 类型,用于在不知道具体 Rust 实体时安全读取 MySQL / PostgreSQL
4//! 查询结果。每一行数据以 `serde_json::Map<String, serde_json::Value>` 的形式存储,
5//! 支持两个后端常见类型到 JSON 类型的映射。
6//!
7//! # MySQL 类型映射规则
8//!
9//! | MySQL 类型 | JSON 类型 |
10//! |-----------|----------|
11//! | INT / BIGINT / MEDIUMINT / SMALLINT | Number (i64) |
12//! | TINYINT | Number (i8) |
13//! | TINYINT UNSIGNED | Number (u8) |
14//! | FLOAT / DOUBLE | Number (f64) |
15//! | DECIMAL / NUMERIC | String(保留精度,NEWDECIMAL 协议本就是字符串编码) |
16//! | VARCHAR / TEXT / CHAR | String |
17//! | BOOLEAN(即 TINYINT(1),sqlx 归一化) | Bool |
18//! | DATE / DATETIME / TIMESTAMP | String (ISO 8601) |
19//! | NULL | Null |
20//! | BLOB / BINARY | String (Base64) |
21//! | JSON | Object / Array |
22//!
23//! # PostgreSQL 类型映射规则
24//!
25//! 按 `PgColumn::type_info()` 的 OID / `PgTypeKind` 分派,而不是按类型名字符串,
26//! 避免同名的用户自定义类型被误判。
27//!
28//! | PostgreSQL 类型 | JSON 类型 |
29//! |-----------------|----------|
30//! | BOOL | Bool |
31//! | INT2 / INT4 / INT8 | Number (i64) |
32//! | FLOAT4 / FLOAT8 | Number (f64)(NaN / Infinity 无法表示,返回解码错误) |
33//! | NUMERIC | String(十进制文本,保留 scale) |
34//! | TEXT / VARCHAR / BPCHAR / NAME / ENUM | String |
35//! | BYTEA | String (Base64) |
36//! | DATE | String(ISO 8601 `YYYY-MM-DD`) |
37//! | TIME | String(ISO 8601 `HH:MM:SS[.fffffffff]`) |
38//! | TIMETZ | String(ISO 8601 `HH:MM:SS[.f]±HH:MM`) |
39//! | TIMESTAMP | String(ISO 8601 `YYYY-MM-DDTHH:MM:SS[.f]`,无时区) |
40//! | TIMESTAMPTZ | String(UTC RFC 3339,如 `2026-11-08T10:00:00Z`) |
41//! | INTERVAL | Object `{"months":i32,"days":i32,"microseconds":i64}` |
42//! | UUID | String(连字符小写形式) |
43//! | JSON / JSONB | 对应 JSON 值 |
44//! | INET / CIDR | String(PostgreSQL 文本表示,含掩码时形如 `192.168.1.1/24`) |
45//! | int4range / int8range / numrange / daterange / tstzrange | Range 对象(见下) |
46//! | 数组(一维) | JSON Array,元素按上表转换,数组内 NULL → JSON Null |
47//! | SQL NULL | Null |
48//!
49//! ## Range 契约
50//!
51//! 非空 range 输出为 `{"lower": ..., "upper": ..., "lower_inclusive": bool, "upper_inclusive": bool}`:
52//! 端点按元素类型的标量规则解码;无界端点用 JSON `null` 表示,对应侧的
53//! `*_inclusive` 固定为 `false`。空 range 显式输出 `{"empty": true}`,与
54//! `(,)`(两端无界但非空)严格区分。按内置 range OID 分派;未知 range 元素类型
55//! (如 `tsrange` 或用户自定义 range)fail-closed。
56//!
57//! ## 自定义类型解码器
58//!
59//! 内置规则无法解码的自定义类型(composite / 扩展类型)可由调用方通过
60//! [`register_pg_type_decoder`] 注册解码器。解码分派顺序为:注册表 → 内置规则
61//! → 结构化错误;重复注册同一 OID 会覆盖旧解码器。
62//!
63//! ## PostgreSQL 解码约定
64//!
65//! - 列名保持数据库返回的原样;重复列名时后者覆盖前者(JSON Object 无法保留重复键)。
66//! - SQL NULL 与 JSONB 字面量 `null` 的序列化值都是 JSON `Null`,但后者额外登记在
67//!   sidecar 集合中,可用 [`Record::is_sql_null`] / [`Record::is_json_null`] 区分。
68//! - 未知 OID / 不支持的类型(如 POINT、未注册的 COMPOSITE、未知 RANGE)返回
69//!   `sqlx::Error::ColumnDecode`,消息包含列名、序号、OID 与类型名,绝不静默置 Null。
70//! - 数组仅支持一维(sqlx 的数组解码限制);多维数组返回解码错误。
71//! - INTERVAL 用无损的三段整数对象表示:PostgreSQL 的 months / days / microseconds
72//!   三者符号可以不一致,ISO 8601 duration 无法精确表达这种组合。
73//! - sqlx 的多数解码实现同时支持二进制(扩展协议)与文本(简单协议)结果格式;
74//!   例外是 INTERVAL 的文本格式 sqlx 尚未实现,此时返回解码错误而非错误值。
75//! - 自定义 ENUM / DOMAIN / 自定义数组依赖扩展协议解析出的类型元数据;简单协议
76//!   (如 `sqlx::raw_sql`)无法解析自定义 OID,会返回带 OID 的结构化错误。
77//!
78//! # 示例
79//!
80//! ```rust,ignore
81//! use yang_base::table::Record;
82//!
83//! // 通过 sqlx::FromRow 自动从查询结果构建
84//! let rows: Vec<Record> = query.all().await?;
85//! for row in rows {
86//!     println!("{:?}", row.as_map());
87//! }
88//! ```
89
90use crate::error::BaseError;
91use serde::de::DeserializeOwned;
92use serde::{Deserialize, Serialize};
93
94/// 动态数据库记录
95///
96/// 以键值对形式存储一行数据库查询结果,支持任意表结构。
97/// 字段名为键,字段值为 JSON 值。
98///
99/// # 字段
100///
101/// - `columns`:列名到 JSON 值的映射
102///
103/// # 示例
104///
105/// ```rust,ignore
106/// use yang_base::table::Record;
107/// use serde_json::json;
108///
109/// let row = Record::new()
110///     .set("id", json!(1))
111///     .set("name", json!("Alice"));
112/// ```
113#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
114#[serde(transparent)]
115#[schemars(transparent)]
116pub struct Record {
117    columns: serde_json::Map<String, serde_json::Value>,
118    /// PostgreSQL 中值为 JSON 字面量 `null` 的 `json`/`jsonb` 列名。
119    ///
120    /// JSON 值与 SQL NULL 在解包后都是 [`serde_json::Value::Null`],无法从值本身
121    /// 区分。该集合只记录「列值确实是 JSON null」的列,用于
122    /// [`Record::is_json_null`] 与 [`Record::is_sql_null`];不参与序列化,
123    /// `get()` 与 JSON 输出行为保持不变。
124    #[serde(skip)]
125    #[schemars(skip)]
126    json_nulls: std::collections::BTreeSet<String>,
127}
128
129impl Record {
130    /// 创建空记录。
131    pub fn new() -> Self {
132        Self {
133            columns: serde_json::Map::new(),
134            json_nulls: std::collections::BTreeSet::new(),
135        }
136    }
137
138    /// 该列是否为 SQL NULL(区别于 JSON 字面量 `null`)。
139    ///
140    /// 列不存在时返回 `false`。
141    pub fn is_sql_null(&self, key: &str) -> bool {
142        self.columns
143            .get(key)
144            .is_some_and(serde_json::Value::is_null)
145            && !self.json_nulls.contains(key)
146    }
147
148    /// 该列是否为 PostgreSQL `json`/`jsonb` 的 JSON 字面量 `null`。
149    pub fn is_json_null(&self, key: &str) -> bool {
150        self.json_nulls.contains(key)
151    }
152
153    /// 链式写入字段值。
154    pub fn set(mut self, key: impl Into<String>, value: impl Into<serde_json::Value>) -> Self {
155        self.columns.insert(key.into(), value.into());
156        self
157    }
158
159    /// 写入字段值并返回被替换的旧值。
160    pub fn insert(
161        &mut self,
162        key: impl Into<String>,
163        value: impl Into<serde_json::Value>,
164    ) -> Option<serde_json::Value> {
165        self.columns.insert(key.into(), value.into())
166    }
167
168    /// 移除指定列并返回其原值。
169    ///
170    /// 同时从 JSON null sidecar 中移除该列,避免列已不存在却仍被
171    /// [`Record::is_json_null`] 判定为 JSON null。
172    ///
173    /// # 返回
174    ///
175    /// - `Some(Value)`:列存在时返回被移除的值
176    /// - `None`:列不存在
177    pub fn remove_column(&mut self, key: &str) -> Option<serde_json::Value> {
178        self.json_nulls.remove(key);
179        self.columns.remove(key)
180    }
181
182    /// 只保留指定列,其余列及其 JSON null 登记一并移除。
183    ///
184    /// 用于多列投影:投影结果必须保留 [`Record::is_json_null`] 的区分能力,
185    /// 不能经 `into_map()` + [`Record::from`] 重建(那会丢失 sidecar)。
186    pub fn retain_columns(&mut self, keys: &[&str]) {
187        self.columns.retain(|name, _| keys.contains(&name.as_str()));
188        self.json_nulls.retain(|name| keys.contains(&name.as_str()));
189    }
190
191    /// 获取指定列的原始 JSON 值。
192    ///
193    /// # 参数
194    ///
195    /// - `key`:列名
196    ///
197    /// # 返回
198    ///
199    /// - `Some(&Value)`:列存在时返回值的引用
200    /// - `None`:列不存在
201    pub fn get(&self, key: &str) -> Option<&serde_json::Value> {
202        if key.trim().is_empty() {
203            return None;
204        }
205
206        self.columns.get(key)
207    }
208
209    /// 读取必需字段并转换为目标类型。
210    pub fn require<T>(&self, key: &str) -> Result<T, BaseError>
211    where
212        T: DeserializeOwned,
213    {
214        let value = self
215            .get(key)
216            .ok_or_else(|| BaseError::FieldNotFound("record".to_string(), key.to_string()))?;
217        serde_json::from_value(value.clone())
218            .map_err(|error| BaseError::InvalidFieldType(key.to_string(), error.to_string()))
219    }
220
221    /// 读取可选字段;字段不存在或为 `null` 时返回 `None`。
222    pub fn optional<T>(&self, key: &str) -> Result<Option<T>, BaseError>
223    where
224        T: DeserializeOwned,
225    {
226        let Some(value) = self.get(key) else {
227            return Ok(None);
228        };
229        if value.is_null() {
230            return Ok(None);
231        }
232        serde_json::from_value(value.clone())
233            .map(Some)
234            .map_err(|error| BaseError::InvalidFieldType(key.to_string(), error.to_string()))
235    }
236
237    /// 返回字段映射的只读引用。
238    pub fn as_map(&self) -> &serde_json::Map<String, serde_json::Value> {
239        &self.columns
240    }
241
242    /// 消费记录并返回字段映射。
243    pub fn into_map(self) -> serde_json::Map<String, serde_json::Value> {
244        self.columns
245    }
246
247    /// 消费记录并返回查询写入层使用的 HashMap。
248    #[cfg(feature = "mysql")]
249    pub(crate) fn into_columns(self) -> std::collections::HashMap<String, serde_json::Value> {
250        self.columns.into_iter().collect()
251    }
252}
253
254impl Default for Record {
255    fn default() -> Self {
256        Self::new()
257    }
258}
259
260impl From<serde_json::Map<String, serde_json::Value>> for Record {
261    fn from(columns: serde_json::Map<String, serde_json::Value>) -> Self {
262        Self {
263            columns,
264            json_nulls: std::collections::BTreeSet::new(),
265        }
266    }
267}
268
269/// 将 Record 转换为 serde_json::Value(Object 类型)。
270impl From<Record> for serde_json::Value {
271    fn from(row: Record) -> Self {
272        serde_json::Value::Object(row.columns)
273    }
274}
275
276/// 实现 sqlx::FromRow,支持从 MySQL 查询结果动态解码
277///
278/// 按 MySQL 列类型将值映射到对应的 JSON 类型:
279/// - INT/BIGINT/MEDIUMINT/SMALLINT → i64
280/// - TINYINT → i8
281/// - TINYINT UNSIGNED → u8
282/// - FLOAT/DOUBLE → f64
283/// - DECIMAL/NUMERIC → String(保留精度)
284/// - VARCHAR/TEXT/CHAR → String
285/// - BOOLEAN(即 TINYINT(1))→ Bool
286/// - DATE/DATETIME/TIMESTAMP → ISO 8601 字符串
287/// - NULL → Null
288/// - BLOB/BINARY → Base64 字符串
289/// - JSON → Object/Array
290#[cfg(feature = "mysql")]
291impl<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> for Record {
292    fn from_row(row: &'r sqlx::mysql::MySqlRow) -> Result<Self, sqlx::Error> {
293        use sqlx::Column;
294        use sqlx::Row;
295        use sqlx::TypeInfo;
296        use sqlx::ValueRef;
297
298        let mut columns = serde_json::Map::new();
299
300        // 遍历所有列,按类型解码
301        for col in row.columns() {
302            let col_name = col.name().to_string();
303            let type_name = col.type_info().name().to_uppercase();
304
305            // 先检查是否为 NULL
306            let is_null: bool = row
307                .try_get_raw(col.ordinal())
308                .map(|v| v.is_null())
309                .unwrap_or(false);
310
311            if is_null {
312                // NULL 值映射为 JSON Null
313                columns.insert(col_name, serde_json::Value::Null);
314                continue;
315            }
316
317            // 按 MySQL 类型名称解码
318            let json_value = decode_mysql_column(row, col.ordinal(), &type_name)?;
319            columns.insert(col_name, json_value);
320        }
321
322        Ok(Record {
323            columns,
324            json_nulls: std::collections::BTreeSet::new(),
325        })
326    }
327}
328
329/// MySQL 整数族列在解码时的语义分类。
330///
331/// sqlx 会把 `tinyint(1)` 归一化为 `BOOLEAN`(列宽 == 1),其余 tinyint 保持数值语义。
332/// 抽出纯函数便于在无 MySQL 环境下单测「列名 → 解码分支」的映射,防止
333/// BOOLEAN / TINYINT / TINYINT UNSIGNED 之间的语义再次漂移(验证需求: M24)。
334#[cfg(feature = "mysql")]
335#[derive(Debug, Clone, Copy, PartialEq, Eq)]
336enum MysqlIntegerKind {
337    /// 常规整数(INT/BIGINT/MEDIUMINT/SMALLINT 及其无符号变体),解码为 i64。
338    Int64,
339    /// tinyint(1)(sqlx 归一化为 BOOLEAN),解码为 bool。
340    Boolean,
341    /// 普通 tinyint,保持数值语义,解码为 i8。
342    TinyInt,
343    /// 无符号 tinyint,解码为 u8。
344    TinyIntUnsigned,
345    /// 非整数族类型,交由后续分支按字符串/浮点/日期等处理。
346    Other,
347}
348
349/// 判定 MySQL 列类型名对应的整数族解码分支。
350#[cfg(feature = "mysql")]
351fn mysql_integer_kind(type_name: &str) -> MysqlIntegerKind {
352    // 整数类型:INT、BIGINT、MEDIUMINT、SMALLINT(含 UNSIGNED 变体)
353    if type_name.contains("INT") && !type_name.contains("TINYINT") {
354        return MysqlIntegerKind::Int64;
355    }
356    match type_name {
357        // tinyint(1) 在 MySQL 协议中被 sqlx 归一化为 BOOLEAN(列宽 == 1)
358        "BOOLEAN" => MysqlIntegerKind::Boolean,
359        "TINYINT" => MysqlIntegerKind::TinyInt,
360        "TINYINT UNSIGNED" => MysqlIntegerKind::TinyIntUnsigned,
361        _ => MysqlIntegerKind::Other,
362    }
363}
364
365/// 根据 MySQL 列类型解码列值为 JSON 值
366///
367/// # 参数
368///
369/// - `row`:MySQL 行
370/// - `ordinal`:列索引
371/// - `type_name`:MySQL 类型名称(大写)
372///
373/// # 返回
374///
375/// - `Ok(Value)`:解码成功
376/// - `Err(sqlx::Error)`:解码失败
377#[cfg(feature = "mysql")]
378fn decode_mysql_column(
379    row: &sqlx::mysql::MySqlRow,
380    ordinal: usize,
381    type_name: &str,
382) -> Result<serde_json::Value, sqlx::Error> {
383    use base64::Engine;
384    use sqlx::Row;
385
386    match mysql_integer_kind(type_name) {
387        // 整数类型:INT、BIGINT、MEDIUMINT、SMALLINT(含 UNSIGNED 变体)
388        MysqlIntegerKind::Int64 => {
389            let val: i64 = row.try_get(ordinal)?;
390            return Ok(serde_json::Value::Number(val.into()));
391        }
392        // tinyint(1) 在 MySQL 协议中被 sqlx 归一化为 BOOLEAN(列宽 == 1);
393        // 仅该形态映射为 bool,其余 tinyint 保持数值语义,避免与 FieldType::Integer 声明冲突。
394        MysqlIntegerKind::Boolean => {
395            let val: i8 = row.try_get(ordinal)?;
396            return Ok(serde_json::Value::Bool(val != 0));
397        }
398        // 普通 tinyint 保持数值语义,不再映射为 bool。
399        MysqlIntegerKind::TinyInt => {
400            let val: i8 = row.try_get(ordinal)?;
401            return Ok(serde_json::Value::Number(i64::from(val).into()));
402        }
403        // 无符号 tinyint 此前落到字符串兜底,try_get::<String> 因类型不兼容必然 Err。
404        MysqlIntegerKind::TinyIntUnsigned => {
405            let val: u8 = row.try_get(ordinal)?;
406            return Ok(serde_json::Value::Number(u64::from(val).into()));
407        }
408        MysqlIntegerKind::Other => {}
409    }
410
411    // 定点类型:DECIMAL、NUMERIC
412    // NEWDECIMAL 协议本就是字符串编码,读字符串以保留精度,避免 f64 舍入误差。
413    if type_name == "DECIMAL" || type_name == "NUMERIC" {
414        let val: String = row.try_get_unchecked(ordinal)?;
415        return Ok(serde_json::Value::String(val));
416    }
417
418    // 浮点类型:FLOAT、DOUBLE
419    if type_name == "FLOAT" || type_name == "DOUBLE" {
420        let val: f64 = row.try_get(ordinal)?;
421        // NaN 或 Infinity 无法编码为 JSON Number,返回结构化解码错误而非静默归零
422        let json_num = serde_json::Number::from_f64(val).ok_or_else(|| {
423            sqlx::Error::Decode("浮点数值为 NaN 或 Infinity 无法编码为 JSON Number".into())
424        })?;
425        return Ok(serde_json::Value::Number(json_num));
426    }
427
428    // 日期时间类型:DATE、DATETIME、TIMESTAMP
429    if type_name == "DATE" {
430        let val: chrono::NaiveDate = row.try_get(ordinal)?;
431        // 转换为 ISO 8601 格式字符串
432        return Ok(serde_json::Value::String(
433            val.format("%Y-%m-%d").to_string(),
434        ));
435    }
436
437    if type_name == "DATETIME" || type_name == "TIMESTAMP" {
438        let val: chrono::NaiveDateTime = row.try_get(ordinal)?;
439        // 转换为 ISO 8601 格式字符串
440        return Ok(serde_json::Value::String(
441            val.format("%Y-%m-%dT%H:%M:%S").to_string(),
442        ));
443    }
444
445    if type_name == "TIME" {
446        let val: chrono::NaiveTime = row.try_get(ordinal)?;
447        return Ok(serde_json::Value::String(
448            val.format("%H:%M:%S").to_string(),
449        ));
450    }
451
452    // 二进制类型:BLOB、BINARY、VARBINARY、LONGBLOB、MEDIUMBLOB、TINYBLOB
453    if type_name.contains("BLOB") || type_name.contains("BINARY") {
454        let val: Vec<u8> = row.try_get(ordinal)?;
455        // 转换为 Base64 字符串
456        let encoded = base64::engine::general_purpose::STANDARD.encode(&val);
457        return Ok(serde_json::Value::String(encoded));
458    }
459
460    // JSON 类型:直接解析为 JSON 值
461    if type_name == "JSON" {
462        let val: serde_json::Value = row.try_get(ordinal)?;
463        return Ok(val);
464    }
465
466    // 字符串类型:VARCHAR、TEXT、CHAR、LONGTEXT、MEDIUMTEXT、TINYTEXT、ENUM、SET
467    // 以及其他未知类型,尝试作为字符串读取
468    let val: String = row.try_get(ordinal)?;
469    Ok(serde_json::Value::String(val))
470}
471
472/// PostgreSQL 内置 range 的元素类别。
473#[cfg(feature = "postgres")]
474#[derive(Debug, Clone, Copy, PartialEq, Eq)]
475enum PgRangeKind {
476    Int4,
477    Int8,
478    Numeric,
479    Date,
480    TimestampTz,
481}
482
483/// PostgreSQL 标量列的解码类别。
484///
485/// 按 OID 归类后再统一走标量与数组两条路径,保证同一个类型在标量和数组中的
486/// JSON 表示完全一致。
487#[cfg(feature = "postgres")]
488#[derive(Debug, Clone, Copy, PartialEq, Eq)]
489enum PgScalarKind {
490    Bool,
491    Int2,
492    Int4,
493    Int8,
494    Float4,
495    Float8,
496    Numeric,
497    /// TEXT / VARCHAR / BPCHAR / NAME。
498    Text,
499    Bytea,
500    Date,
501    Time,
502    TimeTz,
503    Timestamp,
504    TimestampTz,
505    Interval,
506    Uuid,
507    /// JSON / JSONB。
508    Json,
509    Inet,
510    Cidr,
511    /// 用户自定义枚举,按标签文本输出。
512    Enum,
513    /// 内置 range 类型,解码为 JSON 对象。
514    Range(PgRangeKind),
515}
516
517/// 列的解码计划。
518#[cfg(feature = "postgres")]
519#[derive(Debug, Clone, PartialEq, Eq)]
520enum PgDecodePlan {
521    /// 标量类型。
522    Scalar(PgScalarKind),
523    /// 一维数组,元素沿用同一套标量解码。
524    Array(Box<PgDecodePlan>),
525    /// 调用方注册的自定义解码器。
526    Custom(u32),
527    /// 不支持的类型,携带类型名与 OID 供结构化错误使用。
528    Unsupported(String),
529}
530
531/// 注册型 PostgreSQL 解码器收到的原始列值。
532///
533/// 扩展协议(prepared statement)结果为 [`PgValue::Binary`],简单协议
534/// (如 `sqlx::raw_sql`)结果为 [`PgValue::Text`]。
535#[cfg(feature = "postgres")]
536#[derive(Debug, Clone, Copy, PartialEq, Eq)]
537pub enum PgValue<'a> {
538    /// 二进制(扩展协议)结果格式。
539    Binary(&'a [u8]),
540    /// 文本(简单协议)结果格式。
541    Text(&'a str),
542}
543
544#[cfg(feature = "postgres")]
545impl<'a> PgValue<'a> {
546    /// 二进制格式的原始字节;文本格式返回 `None`。
547    pub fn as_bytes(&self) -> Option<&'a [u8]> {
548        match self {
549            Self::Binary(bytes) => Some(bytes),
550            Self::Text(_) => None,
551        }
552    }
553
554    /// 文本格式的字符串;二进制格式返回 `None`。
555    pub fn as_str(&self) -> Option<&'a str> {
556        match self {
557            Self::Binary(_) => None,
558            Self::Text(text) => Some(text),
559        }
560    }
561}
562
563/// 自定义 PostgreSQL 类型解码器。
564#[cfg(feature = "postgres")]
565pub type PgTypeDecoder = for<'a> fn(&PgValue<'a>) -> Result<serde_json::Value, BaseError>;
566
567/// 进程级自定义解码器注册表。
568///
569/// 这是 [`register_pg_type_decoder`] 明确要求的扩展点,不是资源所有权单例;
570/// 读写均经 `RwLock`,中毒时取回内部值继续服务,避免解码路径 panic。
571#[cfg(feature = "postgres")]
572static PG_TYPE_DECODERS: std::sync::OnceLock<
573    std::sync::RwLock<std::collections::HashMap<u32, PgTypeDecoder>>,
574> = std::sync::OnceLock::new();
575
576#[cfg(feature = "postgres")]
577fn pg_type_decoders() -> &'static std::sync::RwLock<std::collections::HashMap<u32, PgTypeDecoder>> {
578    PG_TYPE_DECODERS.get_or_init(|| std::sync::RwLock::new(std::collections::HashMap::new()))
579}
580
581/// 注册自定义 OID 解码器。
582///
583/// 注册后,该 OID 优先于内置规则解码。重复注册同一 OID 会覆盖旧解码器
584/// (幂等;线程安全)。解码器返回的 [`BaseError`] 会被包装为带列上下文的
585/// `sqlx::Error::ColumnDecode`。
586#[cfg(feature = "postgres")]
587pub fn register_pg_type_decoder(oid: u32, decoder: PgTypeDecoder) {
588    let mut decoders = match pg_type_decoders().write() {
589        Ok(decoders) => decoders,
590        Err(poisoned) => poisoned.into_inner(),
591    };
592    decoders.insert(oid, decoder);
593}
594
595#[cfg(feature = "postgres")]
596fn lookup_pg_decoder(oid: u32) -> Option<PgTypeDecoder> {
597    let decoders = match pg_type_decoders().read() {
598        Ok(decoders) => decoders,
599        Err(poisoned) => poisoned.into_inner(),
600    };
601    decoders.get(&oid).copied()
602}
603
604/// 按 PostgreSQL 内置类型的稳定 OID 归类标量类型。
605///
606/// 只在 `PgTypeKind::Simple` 分支使用;未知 OID 返回 `None`,由调用方转成结构化错误。
607#[cfg(feature = "postgres")]
608fn pg_scalar_kind(oid: u32) -> Option<PgScalarKind> {
609    Some(match oid {
610        // pg_type.dat 中的内置 OID 是稳定的。
611        16 => PgScalarKind::Bool,
612        21 => PgScalarKind::Int2,
613        23 => PgScalarKind::Int4,
614        20 => PgScalarKind::Int8,
615        700 => PgScalarKind::Float4,
616        701 => PgScalarKind::Float8,
617        1700 => PgScalarKind::Numeric,
618        25 | 1043 | 1042 | 19 => PgScalarKind::Text,
619        17 => PgScalarKind::Bytea,
620        1082 => PgScalarKind::Date,
621        1083 => PgScalarKind::Time,
622        1266 => PgScalarKind::TimeTz,
623        1114 => PgScalarKind::Timestamp,
624        1184 => PgScalarKind::TimestampTz,
625        1186 => PgScalarKind::Interval,
626        2950 => PgScalarKind::Uuid,
627        114 | 3802 => PgScalarKind::Json,
628        869 => PgScalarKind::Inet,
629        650 => PgScalarKind::Cidr,
630        // 内置 range 类型的 OID 同样是稳定的;只识别本轮承诺的五种。
631        3904 => PgScalarKind::Range(PgRangeKind::Int4),
632        3926 => PgScalarKind::Range(PgRangeKind::Int8),
633        3906 => PgScalarKind::Range(PgRangeKind::Numeric),
634        3912 => PgScalarKind::Range(PgRangeKind::Date),
635        3910 => PgScalarKind::Range(PgRangeKind::TimestampTz),
636        _ => return None,
637    })
638}
639
640/// 按 PostgreSQL 内置数组类型的稳定 OID 归类其元素类型。
641///
642/// 直接识别内置数组 OID 可以绕开 `PgTypeKind::Array`,从而同时适配
643/// 扩展协议(二进制)与简单协议(文本)结果。
644#[cfg(feature = "postgres")]
645fn pg_array_element_kind(oid: u32) -> Option<PgScalarKind> {
646    Some(match oid {
647        1000 => PgScalarKind::Bool,
648        1001 => PgScalarKind::Bytea,
649        1003 => PgScalarKind::Text,
650        1005 => PgScalarKind::Int2,
651        1007 => PgScalarKind::Int4,
652        1009 => PgScalarKind::Text,
653        1014 => PgScalarKind::Text,
654        1015 => PgScalarKind::Text,
655        1016 => PgScalarKind::Int8,
656        1021 => PgScalarKind::Float4,
657        1022 => PgScalarKind::Float8,
658        1041 => PgScalarKind::Inet,
659        651 => PgScalarKind::Cidr,
660        1115 => PgScalarKind::Timestamp,
661        1182 => PgScalarKind::Date,
662        1183 => PgScalarKind::Time,
663        1185 => PgScalarKind::TimestampTz,
664        1187 => PgScalarKind::Interval,
665        1231 => PgScalarKind::Numeric,
666        1270 => PgScalarKind::TimeTz,
667        199 => PgScalarKind::Json,
668        2951 => PgScalarKind::Uuid,
669        3807 => PgScalarKind::Json,
670        _ => return None,
671    })
672}
673
674/// 生成不支持类型的描述(类型名 + OID),用于结构化解码错误。
675#[cfg(feature = "postgres")]
676fn pg_unsupported_description(oid: Option<u32>, type_name: &str) -> String {
677    match oid {
678        Some(oid) => format!("{type_name}(OID {oid})"),
679        None => format!("{type_name}(OID 未知)"),
680    }
681}
682
683/// 根据列类型信息生成解码计划。
684///
685/// 先按稳定的内置 OID 直接分派标量与数组;只有自定义类型才依赖 `PgTypeKind`
686/// 递归(`Array` / `Domain` / `Enum`)。
687#[cfg(feature = "postgres")]
688fn pg_decode_plan(type_info: &sqlx::postgres::PgTypeInfo) -> PgDecodePlan {
689    use sqlx::postgres::PgTypeKind;
690    use sqlx::TypeInfo;
691
692    let oid = type_info.oid().map(|oid| oid.0);
693
694    // 注册表优先于内置规则,允许调用方覆盖任意 OID 的解码方式。
695    if let Some(oid) = oid {
696        if lookup_pg_decoder(oid).is_some() {
697            return PgDecodePlan::Custom(oid);
698        }
699    }
700
701    // 内置标量与内置数组的 OID 是稳定的,且不依赖类型名解析。
702    if let Some(kind) = oid.and_then(pg_scalar_kind) {
703        return PgDecodePlan::Scalar(kind);
704    }
705    if let Some(kind) = oid.and_then(pg_array_element_kind) {
706        return PgDecodePlan::Array(Box::new(PgDecodePlan::Scalar(kind)));
707    }
708
709    // 简单协议(如 sqlx::raw_sql)无法解析自定义类型的 OID,sqlx 会留下
710    // `DeclareWithOid`,其 name() 为 "?";此时调用 kind() 会 panic(sqlx 内部
711    // unreachable!),必须提前转成结构化错误。
712    if type_info.name() == "?" {
713        let detail = match oid {
714            Some(oid) => {
715                format!("未解析的自定义类型(OID {oid};文本协议无法解析类型名,请使用扩展协议)")
716            }
717            None => "未解析的自定义类型(OID 未知)".to_string(),
718        };
719        return PgDecodePlan::Unsupported(detail);
720    }
721
722    match type_info.kind() {
723        PgTypeKind::Array(element) => PgDecodePlan::Array(Box::new(pg_decode_plan(element))),
724        PgTypeKind::Domain(inner) => pg_decode_plan(inner),
725        kind => pg_decode_plan_from_kind(oid, type_info.name(), kind),
726    }
727}
728
729/// 类型类别分派(不含 Array / Domain 递归,便于在无数据库环境做单元测试)。
730#[cfg(feature = "postgres")]
731fn pg_decode_plan_from_kind(
732    oid: Option<u32>,
733    type_name: &str,
734    kind: &sqlx::postgres::PgTypeKind,
735) -> PgDecodePlan {
736    use sqlx::postgres::PgTypeKind;
737
738    match kind {
739        PgTypeKind::Enum(_) => PgDecodePlan::Scalar(PgScalarKind::Enum),
740        PgTypeKind::Composite(_) => PgDecodePlan::Unsupported(format!(
741            "复合类型 {} 没有注册解码器;请调用 yang_base::table::register_pg_type_decoder(oid, decoder)",
742            pg_unsupported_description(oid, type_name)
743        )),
744        PgTypeKind::Range(_) => PgDecodePlan::Unsupported(format!(
745            "range 类型 {} 不在内置支持列表(int4range/int8range/numrange/daterange/tstzrange);\
746             请调用 yang_base::table::register_pg_type_decoder(oid, decoder)",
747            pg_unsupported_description(oid, type_name)
748        )),
749        PgTypeKind::Simple => match oid.and_then(pg_scalar_kind) {
750            Some(kind) => PgDecodePlan::Scalar(kind),
751            None => PgDecodePlan::Unsupported(pg_unsupported_description(oid, type_name)),
752        },
753        // Array / Domain 由 pg_decode_plan 递归处理;其余结构(Pseudo)不在本轮能力范围内。
754        _ => PgDecodePlan::Unsupported(pg_unsupported_description(oid, type_name)),
755    }
756}
757
758/// 构造带列上下文的「不支持类型」错误。
759#[cfg(feature = "postgres")]
760fn unsupported_pg_type_error(column_name: &str, ordinal: usize, detail: &str) -> sqlx::Error {
761    sqlx::Error::ColumnDecode {
762        index: format!("{column_name}#{ordinal}"),
763        source: format!("不支持的 PostgreSQL 列类型:{detail}").into(),
764    }
765}
766
767/// `INET` / `CIDR` 的轻量解码包装。
768///
769/// sqlx 默认不启用 `ipnetwork` feature,这里只按 PostgreSQL 二进制/文本格式提取
770/// 地址与掩码,再按 `INET` 或 `CIDR` 的文本表示输出。
771#[cfg(feature = "postgres")]
772#[derive(Debug, Clone)]
773struct PgInetValue {
774    address: String,
775    bits: u8,
776    max_bits: u8,
777}
778
779#[cfg(feature = "postgres")]
780impl PgInetValue {
781    /// 输出 PostgreSQL 文本表示:`INET` 在掩码等于全宽时省略 `/bits`,`CIDR` 始终保留。
782    fn to_json(&self, is_cidr: bool) -> serde_json::Value {
783        if is_cidr || self.bits != self.max_bits {
784            serde_json::Value::String(format!("{}/{}", self.address, self.bits))
785        } else {
786            serde_json::Value::String(self.address.clone())
787        }
788    }
789}
790
791#[cfg(feature = "postgres")]
792impl sqlx::Type<sqlx::Postgres> for PgInetValue {
793    fn type_info() -> sqlx::postgres::PgTypeInfo {
794        sqlx::postgres::PgTypeInfo::with_name("inet")
795    }
796}
797
798#[cfg(feature = "postgres")]
799impl sqlx::postgres::PgHasArrayType for PgInetValue {
800    fn array_type_info() -> sqlx::postgres::PgTypeInfo {
801        sqlx::postgres::PgTypeInfo::with_name("_inet")
802    }
803}
804
805#[cfg(feature = "postgres")]
806impl<'r> sqlx::Decode<'r, sqlx::Postgres> for PgInetValue {
807    fn decode(value: sqlx::postgres::PgValueRef<'r>) -> Result<Self, sqlx::error::BoxDynError> {
808        match value.format() {
809            sqlx::postgres::PgValueFormat::Binary => parse_pg_inet_bytes(value.as_bytes()?),
810            sqlx::postgres::PgValueFormat::Text => parse_pg_inet_text(value.as_str()?),
811        }
812    }
813}
814
815/// 解析 `INET` / `CIDR` 的二进制格式:
816/// family(1) + bits(1) + is_cidr(1) + 地址字节数(1) + 地址字节
817/// (IPv4 4 字节 / IPv6 16 字节)。
818#[cfg(feature = "postgres")]
819fn parse_pg_inet_bytes(bytes: &[u8]) -> Result<PgInetValue, sqlx::error::BoxDynError> {
820    if bytes.len() < 4 {
821        return Err("INET 二进制值长度不足 4 字节".into());
822    }
823
824    let family = bytes[0];
825    let bits = bytes[1];
826    let address_len = usize::from(bytes[3]);
827    let address = &bytes[4..];
828
829    let (address, max_bits) = match (family, address_len, address.len()) {
830        // PGSQL_AF_INET
831        (2, 4, 4) => (
832            std::net::Ipv4Addr::new(address[0], address[1], address[2], address[3]).to_string(),
833            32,
834        ),
835        // PGSQL_AF_INET6
836        (3, 16, 16) => {
837            let octets: [u8; 16] = address.try_into().map_err(|_| "INET 二进制地址长度非法")?;
838            (std::net::Ipv6Addr::from(octets).to_string(), 128)
839        }
840        _ => {
841            return Err(format!(
842                "未知的 INET 地址族或长度:family={family}, address_len={address_len}, len={}",
843                address.len()
844            )
845            .into())
846        }
847    };
848
849    if bits > max_bits {
850        return Err(format!("INET 掩码位数 {bits} 超出 {max_bits}").into());
851    }
852
853    Ok(PgInetValue {
854        address,
855        bits,
856        max_bits,
857    })
858}
859
860/// 解析文本格式的 `INET` / `CIDR`(简单协议结果)。
861#[cfg(feature = "postgres")]
862fn parse_pg_inet_text(text: &str) -> Result<PgInetValue, sqlx::error::BoxDynError> {
863    let (address, bits) = match text.split_once('/') {
864        Some((address, bits)) => (address, Some(bits)),
865        None => (text, None),
866    };
867
868    let max_bits = if address.contains(':') { 128 } else { 32 };
869    let bits = match bits {
870        Some(bits) => bits.parse::<u8>()?,
871        None => max_bits,
872    };
873    if bits > max_bits {
874        return Err(format!("INET 掩码位数 {bits} 超出 {max_bits}").into());
875    }
876
877    // 解析一次地址,顺带统一为 IPv6 压缩表示。
878    let address = if max_bits == 128 {
879        address.parse::<std::net::Ipv6Addr>()?.to_string()
880    } else {
881        address.parse::<std::net::Ipv4Addr>()?.to_string()
882    };
883
884    Ok(PgInetValue {
885        address,
886        bits,
887        max_bits,
888    })
889}
890
891/// 千分位以下的纳秒按 ISO 8601 输出:整秒不带小数点,否则去掉尾部零。
892#[cfg(feature = "postgres")]
893fn format_pg_time(time: chrono::NaiveTime) -> String {
894    use chrono::Timelike;
895    let base = time.format("%H:%M:%S").to_string();
896    let nanos = time.nanosecond();
897    if nanos == 0 {
898        base
899    } else {
900        let fraction = format!("{nanos:09}");
901        format!("{base}.{}", fraction.trim_end_matches('0'))
902    }
903}
904
905/// 输出 `±HH:MM[:SS]` 形式的时区偏移。
906#[cfg(feature = "postgres")]
907fn format_pg_offset(offset: chrono::FixedOffset) -> String {
908    let seconds = offset.local_minus_utc();
909    let sign = if seconds < 0 { '-' } else { '+' };
910    let seconds = seconds.abs();
911    let hours = seconds / 3600;
912    let minutes = (seconds % 3600) / 60;
913    let secs = seconds % 60;
914    if secs == 0 {
915        format!("{sign}{hours:02}:{minutes:02}")
916    } else {
917        format!("{sign}{hours:02}:{minutes:02}:{secs:02}")
918    }
919}
920
921#[cfg(feature = "postgres")]
922fn pg_bool_to_json(value: bool) -> Result<serde_json::Value, sqlx::Error> {
923    Ok(serde_json::Value::Bool(value))
924}
925
926#[cfg(feature = "postgres")]
927fn pg_i64_to_json(value: i64) -> Result<serde_json::Value, sqlx::Error> {
928    Ok(serde_json::Value::Number(value.into()))
929}
930
931#[cfg(feature = "postgres")]
932fn pg_f64_to_json(value: f64) -> Result<serde_json::Value, sqlx::Error> {
933    // NaN / Infinity 无法编码为 JSON Number,返回结构化解码错误而非静默归零。
934    serde_json::Number::from_f64(value)
935        .map(serde_json::Value::Number)
936        .ok_or_else(|| {
937            sqlx::Error::Decode("浮点数值为 NaN 或 Infinity,无法编码为 JSON Number".into())
938        })
939}
940
941#[cfg(feature = "postgres")]
942fn pg_bigdecimal_to_json(value: sqlx::types::BigDecimal) -> Result<serde_json::Value, sqlx::Error> {
943    // 保留 NUMERIC 的十进制 scale,不经过 f64。
944    Ok(serde_json::Value::String(value.to_string()))
945}
946
947#[cfg(feature = "postgres")]
948fn pg_string_to_json(value: String) -> Result<serde_json::Value, sqlx::Error> {
949    Ok(serde_json::Value::String(value))
950}
951
952#[cfg(feature = "postgres")]
953fn pg_bytea_to_json(value: Vec<u8>) -> Result<serde_json::Value, sqlx::Error> {
954    use base64::Engine;
955    Ok(serde_json::Value::String(
956        base64::engine::general_purpose::STANDARD.encode(value),
957    ))
958}
959
960#[cfg(feature = "postgres")]
961fn pg_date_to_json(value: chrono::NaiveDate) -> Result<serde_json::Value, sqlx::Error> {
962    Ok(serde_json::Value::String(
963        value.format("%Y-%m-%d").to_string(),
964    ))
965}
966
967#[cfg(feature = "postgres")]
968fn pg_time_to_json(value: chrono::NaiveTime) -> Result<serde_json::Value, sqlx::Error> {
969    Ok(serde_json::Value::String(format_pg_time(value)))
970}
971
972#[cfg(feature = "postgres")]
973fn pg_timetz_to_json(
974    value: sqlx::postgres::types::PgTimeTz<chrono::NaiveTime, chrono::FixedOffset>,
975) -> Result<serde_json::Value, sqlx::Error> {
976    Ok(serde_json::Value::String(format!(
977        "{}{}",
978        format_pg_time(value.time),
979        format_pg_offset(value.offset)
980    )))
981}
982
983#[cfg(feature = "postgres")]
984fn pg_timestamp_to_json(value: chrono::NaiveDateTime) -> Result<serde_json::Value, sqlx::Error> {
985    Ok(serde_json::Value::String(format!(
986        "{}T{}",
987        value.date().format("%Y-%m-%d"),
988        format_pg_time(value.time())
989    )))
990}
991
992#[cfg(feature = "postgres")]
993fn pg_timestamptz_to_json(
994    value: chrono::DateTime<chrono::Utc>,
995) -> Result<serde_json::Value, sqlx::Error> {
996    // sqlx 已把 TIMESTAMPTZ 归一化为 UTC;RFC 3339 是 ISO 8601 的子集。
997    Ok(serde_json::Value::String(
998        value.to_rfc3339_opts(chrono::SecondsFormat::AutoSi, true),
999    ))
1000}
1001
1002#[cfg(feature = "postgres")]
1003fn pg_interval_to_json(
1004    value: sqlx::postgres::types::PgInterval,
1005) -> Result<serde_json::Value, sqlx::Error> {
1006    // 三段整数无损表达 PostgreSQL interval;各段符号可能独立。
1007    Ok(serde_json::json!({
1008        "months": value.months,
1009        "days": value.days,
1010        "microseconds": value.microseconds,
1011    }))
1012}
1013
1014#[cfg(feature = "postgres")]
1015fn pg_uuid_to_json(value: sqlx::types::Uuid) -> Result<serde_json::Value, sqlx::Error> {
1016    Ok(serde_json::Value::String(value.to_string()))
1017}
1018
1019#[cfg(feature = "postgres")]
1020fn pg_json_to_json(value: serde_json::Value) -> Result<serde_json::Value, sqlx::Error> {
1021    Ok(value)
1022}
1023
1024#[cfg(feature = "postgres")]
1025fn pg_inet_to_json(value: PgInetValue, is_cidr: bool) -> Result<serde_json::Value, sqlx::Error> {
1026    Ok(value.to_json(is_cidr))
1027}
1028
1029/// 判断 range 原始值是否为空 range。
1030///
1031/// sqlx 的 `PgRange` 解码把空 range 的两端都还原为 `Unbounded`,与 `(,)`
1032/// 无法区分;这里在解码前按原始协议判定:二进制首字节的 `EMPTY` 标志位为
1033/// `0x01`,文本格式恰为 `empty`。
1034#[cfg(feature = "postgres")]
1035fn pg_range_is_empty(value: &sqlx::postgres::PgValueRef<'_>) -> Result<bool, sqlx::Error> {
1036    match value.format() {
1037        sqlx::postgres::PgValueFormat::Binary => {
1038            let bytes = value.as_bytes().map_err(sqlx::Error::Decode)?;
1039            Ok(bytes.first().is_some_and(|flags| flags & 0x01 != 0))
1040        }
1041        sqlx::postgres::PgValueFormat::Text => {
1042            let text = value.as_str().map_err(sqlx::Error::Decode)?;
1043            Ok(text == "empty")
1044        }
1045    }
1046}
1047
1048/// 把一个 range 端点转换为 `(JSON 值, 是否闭区间)`;无界端点用 `null` + `false`。
1049#[cfg(feature = "postgres")]
1050fn pg_range_bound_to_json<T>(
1051    bound: std::ops::Bound<T>,
1052    convert: impl Fn(T) -> Result<serde_json::Value, sqlx::Error>,
1053) -> Result<(serde_json::Value, bool), sqlx::Error> {
1054    match bound {
1055        std::ops::Bound::Included(value) => Ok((convert(value)?, true)),
1056        std::ops::Bound::Excluded(value) => Ok((convert(value)?, false)),
1057        std::ops::Bound::Unbounded => Ok((serde_json::Value::Null, false)),
1058    }
1059}
1060
1061/// 按文档契约把 range 转为 JSON 对象;空 range 明确输出 `{"empty": true}`。
1062#[cfg(feature = "postgres")]
1063fn pg_range_to_json<T>(
1064    range: sqlx::postgres::types::PgRange<T>,
1065    empty: bool,
1066    convert: impl Fn(T) -> Result<serde_json::Value, sqlx::Error>,
1067) -> Result<serde_json::Value, sqlx::Error> {
1068    if empty {
1069        return Ok(serde_json::json!({ "empty": true }));
1070    }
1071    let (lower, lower_inclusive) = pg_range_bound_to_json(range.start, &convert)?;
1072    let (upper, upper_inclusive) = pg_range_bound_to_json(range.end, convert)?;
1073    Ok(serde_json::json!({
1074        "lower": lower,
1075        "upper": upper,
1076        "lower_inclusive": lower_inclusive,
1077        "upper_inclusive": upper_inclusive,
1078    }))
1079}
1080
1081/// 解码内置 range 列。
1082#[cfg(feature = "postgres")]
1083fn decode_pg_range(
1084    row: &sqlx::postgres::PgRow,
1085    ordinal: usize,
1086    kind: PgRangeKind,
1087) -> Result<serde_json::Value, sqlx::Error> {
1088    use sqlx::Row;
1089
1090    let raw = row.try_get_raw(ordinal)?;
1091    let empty = pg_range_is_empty(&raw)?;
1092    // 空 range 在文本协议下的原始值是字面量 `empty`,交给 `PgRange<T>` 解码
1093    // 会先撞上元素类型解析错误(ParseIntError 等);直接返回契约 JSON。
1094    if empty {
1095        return Ok(serde_json::json!({ "empty": true }));
1096    }
1097
1098    match kind {
1099        PgRangeKind::Int4 => {
1100            let range: sqlx::postgres::types::PgRange<i32> = row.try_get_unchecked(ordinal)?;
1101            pg_range_to_json(range, empty, |value| pg_i64_to_json(i64::from(value)))
1102        }
1103        PgRangeKind::Int8 => {
1104            let range: sqlx::postgres::types::PgRange<i64> = row.try_get_unchecked(ordinal)?;
1105            pg_range_to_json(range, empty, pg_i64_to_json)
1106        }
1107        PgRangeKind::Numeric => {
1108            let range: sqlx::postgres::types::PgRange<sqlx::types::BigDecimal> =
1109                row.try_get_unchecked(ordinal)?;
1110            pg_range_to_json(range, empty, pg_bigdecimal_to_json)
1111        }
1112        PgRangeKind::Date => {
1113            let range: sqlx::postgres::types::PgRange<chrono::NaiveDate> =
1114                row.try_get_unchecked(ordinal)?;
1115            pg_range_to_json(range, empty, pg_date_to_json)
1116        }
1117        PgRangeKind::TimestampTz => {
1118            let range: sqlx::postgres::types::PgRange<chrono::DateTime<chrono::Utc>> =
1119                row.try_get_unchecked(ordinal)?;
1120            pg_range_to_json(range, empty, pg_timestamptz_to_json)
1121        }
1122    }
1123}
1124
1125/// 调用注册表解码未知类型列。
1126#[cfg(feature = "postgres")]
1127fn decode_pg_custom(
1128    row: &sqlx::postgres::PgRow,
1129    ordinal: usize,
1130    column_name: &str,
1131    oid: u32,
1132) -> Result<serde_json::Value, sqlx::Error> {
1133    use sqlx::Row;
1134
1135    let Some(decoder) = lookup_pg_decoder(oid) else {
1136        return Err(unsupported_pg_type_error(
1137            column_name,
1138            ordinal,
1139            &format!("OID {oid} 未注册解码器"),
1140        ));
1141    };
1142
1143    let raw = row.try_get_raw(ordinal)?;
1144    let value = match raw.format() {
1145        sqlx::postgres::PgValueFormat::Binary => {
1146            PgValue::Binary(raw.as_bytes().map_err(sqlx::Error::Decode)?)
1147        }
1148        sqlx::postgres::PgValueFormat::Text => {
1149            PgValue::Text(raw.as_str().map_err(sqlx::Error::Decode)?)
1150        }
1151    };
1152    decoder(&value).map_err(|error| {
1153        unsupported_pg_type_error(
1154            column_name,
1155            ordinal,
1156            &format!("OID {oid} 的注册解码器失败: {error}"),
1157        )
1158    })
1159}
1160
1161/// 解码单个 PostgreSQL 标量列。
1162#[cfg(feature = "postgres")]
1163fn decode_pg_scalar(
1164    row: &sqlx::postgres::PgRow,
1165    ordinal: usize,
1166    kind: PgScalarKind,
1167) -> Result<serde_json::Value, sqlx::Error> {
1168    use sqlx::Row;
1169
1170    // 这里全部使用 `try_get_unchecked`:类型已经由 OID / PgTypeKind 精确匹配,
1171    // 且 Domain / Enum 的类型信息无法通过 `Type::compatible` 的默认规则匹配。
1172    match kind {
1173        PgScalarKind::Bool => pg_bool_to_json(row.try_get_unchecked(ordinal)?),
1174        PgScalarKind::Int2 => {
1175            pg_i64_to_json(i64::from(row.try_get_unchecked::<i16, _>(ordinal)?))
1176        }
1177        PgScalarKind::Int4 => {
1178            pg_i64_to_json(i64::from(row.try_get_unchecked::<i32, _>(ordinal)?))
1179        }
1180        PgScalarKind::Int8 => pg_i64_to_json(row.try_get_unchecked::<i64, _>(ordinal)?),
1181        PgScalarKind::Float4 => {
1182            pg_f64_to_json(f64::from(row.try_get_unchecked::<f32, _>(ordinal)?))
1183        }
1184        PgScalarKind::Float8 => pg_f64_to_json(row.try_get_unchecked::<f64, _>(ordinal)?),
1185        PgScalarKind::Numeric => {
1186            pg_bigdecimal_to_json(row.try_get_unchecked::<sqlx::types::BigDecimal, _>(ordinal)?)
1187        }
1188        PgScalarKind::Text | PgScalarKind::Enum => {
1189            pg_string_to_json(row.try_get_unchecked::<String, _>(ordinal)?)
1190        }
1191        PgScalarKind::Bytea => {
1192            pg_bytea_to_json(row.try_get_unchecked::<Vec<u8>, _>(ordinal)?)
1193        }
1194        PgScalarKind::Date => {
1195            pg_date_to_json(row.try_get_unchecked::<chrono::NaiveDate, _>(ordinal)?)
1196        }
1197        PgScalarKind::Time => {
1198            pg_time_to_json(row.try_get_unchecked::<chrono::NaiveTime, _>(ordinal)?)
1199        }
1200        PgScalarKind::TimeTz => pg_timetz_to_json(row.try_get_unchecked::<
1201            sqlx::postgres::types::PgTimeTz<chrono::NaiveTime, chrono::FixedOffset>,
1202            _,
1203        >(ordinal)?),
1204        PgScalarKind::Timestamp => {
1205            pg_timestamp_to_json(row.try_get_unchecked::<chrono::NaiveDateTime, _>(ordinal)?)
1206        }
1207        PgScalarKind::TimestampTz => {
1208            pg_timestamptz_to_json(row.try_get_unchecked::<chrono::DateTime<chrono::Utc>, _>(
1209                ordinal,
1210            )?)
1211        }
1212        PgScalarKind::Interval => pg_interval_to_json(
1213            row.try_get_unchecked::<sqlx::postgres::types::PgInterval, _>(ordinal)?,
1214        ),
1215        PgScalarKind::Uuid => {
1216            pg_uuid_to_json(row.try_get_unchecked::<sqlx::types::Uuid, _>(ordinal)?)
1217        }
1218        PgScalarKind::Json => {
1219            pg_json_to_json(row.try_get_unchecked::<serde_json::Value, _>(ordinal)?)
1220        }
1221        PgScalarKind::Inet => {
1222            pg_inet_to_json(row.try_get_unchecked::<PgInetValue, _>(ordinal)?, false)
1223        }
1224        PgScalarKind::Cidr => {
1225            pg_inet_to_json(row.try_get_unchecked::<PgInetValue, _>(ordinal)?, true)
1226        }
1227        PgScalarKind::Range(kind) => decode_pg_range(row, ordinal, kind),
1228    }
1229}
1230
1231/// 解码一维 PostgreSQL 数组;元素转换与标量路径共用同一套函数。
1232#[cfg(feature = "postgres")]
1233fn decode_pg_array(
1234    row: &sqlx::postgres::PgRow,
1235    ordinal: usize,
1236    column_name: &str,
1237    element: &PgDecodePlan,
1238) -> Result<serde_json::Value, sqlx::Error> {
1239    use sqlx::Row;
1240
1241    let PgDecodePlan::Scalar(kind) = element else {
1242        return Err(match element {
1243            PgDecodePlan::Unsupported(detail) => {
1244                unsupported_pg_type_error(column_name, ordinal, detail)
1245            }
1246            _ => sqlx::Error::Decode("不支持多维 PostgreSQL 数组".into()),
1247        });
1248    };
1249
1250    // 数组内 NULL 用 `Option<T>` 保留;PostgreSQL 数组允许 NULL 元素。
1251    macro_rules! decode_elements {
1252        ($ty:ty, $convert:expr) => {{
1253            let values: Vec<Option<$ty>> = row.try_get_unchecked(ordinal)?;
1254            let mut elements = Vec::with_capacity(values.len());
1255            for value in values {
1256                elements.push(match value {
1257                    Some(value) => $convert(value)?,
1258                    None => serde_json::Value::Null,
1259                });
1260            }
1261            Ok(serde_json::Value::Array(elements))
1262        }};
1263    }
1264
1265    match kind {
1266        PgScalarKind::Bool => decode_elements!(bool, pg_bool_to_json),
1267        PgScalarKind::Int2 => {
1268            decode_elements!(i16, |value: i16| { pg_i64_to_json(i64::from(value)) })
1269        }
1270        PgScalarKind::Int4 => {
1271            decode_elements!(i32, |value: i32| { pg_i64_to_json(i64::from(value)) })
1272        }
1273        PgScalarKind::Int8 => decode_elements!(i64, pg_i64_to_json),
1274        PgScalarKind::Float4 => {
1275            decode_elements!(f32, |value: f32| { pg_f64_to_json(f64::from(value)) })
1276        }
1277        PgScalarKind::Float8 => decode_elements!(f64, pg_f64_to_json),
1278        PgScalarKind::Numeric => {
1279            decode_elements!(sqlx::types::BigDecimal, pg_bigdecimal_to_json)
1280        }
1281        PgScalarKind::Text | PgScalarKind::Enum => {
1282            decode_elements!(String, pg_string_to_json)
1283        }
1284        PgScalarKind::Bytea => decode_elements!(Vec<u8>, pg_bytea_to_json),
1285        PgScalarKind::Date => decode_elements!(chrono::NaiveDate, pg_date_to_json),
1286        PgScalarKind::Time => decode_elements!(chrono::NaiveTime, pg_time_to_json),
1287        PgScalarKind::TimeTz => decode_elements!(
1288            sqlx::postgres::types::PgTimeTz<chrono::NaiveTime, chrono::FixedOffset>,
1289            pg_timetz_to_json
1290        ),
1291        PgScalarKind::Timestamp => {
1292            decode_elements!(chrono::NaiveDateTime, pg_timestamp_to_json)
1293        }
1294        PgScalarKind::TimestampTz => {
1295            decode_elements!(chrono::DateTime<chrono::Utc>, pg_timestamptz_to_json)
1296        }
1297        PgScalarKind::Interval => {
1298            decode_elements!(sqlx::postgres::types::PgInterval, pg_interval_to_json)
1299        }
1300        PgScalarKind::Uuid => decode_elements!(sqlx::types::Uuid, pg_uuid_to_json),
1301        PgScalarKind::Json => decode_elements!(serde_json::Value, pg_json_to_json),
1302        PgScalarKind::Inet => decode_elements!(PgInetValue, |value: PgInetValue| {
1303            pg_inet_to_json(value, false)
1304        }),
1305        PgScalarKind::Cidr => decode_elements!(PgInetValue, |value: PgInetValue| {
1306            pg_inet_to_json(value, true)
1307        }),
1308        // range 数组的 OID 不在内置分派表中,正常不会走到这里;显式 fail-closed。
1309        PgScalarKind::Range(_) => Err(sqlx::Error::Decode("不支持 PostgreSQL range 数组".into())),
1310    }
1311}
1312
1313/// 解码单个 PostgreSQL 列。
1314#[cfg(feature = "postgres")]
1315fn decode_pg_column(
1316    row: &sqlx::postgres::PgRow,
1317    ordinal: usize,
1318    column_name: &str,
1319    plan: &PgDecodePlan,
1320) -> Result<serde_json::Value, sqlx::Error> {
1321    match plan {
1322        PgDecodePlan::Scalar(kind) => decode_pg_scalar(row, ordinal, *kind),
1323        PgDecodePlan::Array(element) => decode_pg_array(row, ordinal, column_name, element),
1324        PgDecodePlan::Custom(oid) => decode_pg_custom(row, ordinal, column_name, *oid),
1325        PgDecodePlan::Unsupported(detail) => {
1326            Err(unsupported_pg_type_error(column_name, ordinal, detail))
1327        }
1328    }
1329}
1330
1331/// 实现 `sqlx::FromRow`,支持从 PostgreSQL 查询结果动态解码。
1332///
1333/// 与 MySQL 实现并存,按 feature 分别编译。类型分派基于 OID / `PgTypeKind`,
1334/// 不依赖可能被用户自定义类型复用的类型名。
1335#[cfg(feature = "postgres")]
1336impl<'r> sqlx::FromRow<'r, sqlx::postgres::PgRow> for Record {
1337    fn from_row(row: &'r sqlx::postgres::PgRow) -> Result<Self, sqlx::Error> {
1338        use sqlx::Column;
1339        use sqlx::Row;
1340        use sqlx::ValueRef;
1341
1342        let mut columns = serde_json::Map::new();
1343        let mut json_nulls = std::collections::BTreeSet::new();
1344
1345        for col in row.columns() {
1346            let name = col.name().to_string();
1347            let ordinal = col.ordinal();
1348
1349            // SQL NULL 直接映射为 JSON Null,不再推断具体类型。
1350            if row.try_get_raw(ordinal)?.is_null() {
1351                columns.insert(name, serde_json::Value::Null);
1352                continue;
1353            }
1354
1355            let plan = pg_decode_plan(col.type_info());
1356            let value = decode_pg_column(row, ordinal, &name, &plan)?;
1357            // json/jsonb 的 JSON 字面量 null 解码后同样是 Value::Null,这里单独登记,
1358            // 使调用方能与 SQL NULL 区分(序列化输出仍保持 null)。
1359            if value.is_null() && matches!(plan, PgDecodePlan::Scalar(PgScalarKind::Json)) {
1360                json_nulls.insert(name.clone());
1361            }
1362            // 列名保持数据库原样;重复列名时后者覆盖前者。
1363            columns.insert(name, value);
1364        }
1365
1366        Ok(Record {
1367            columns,
1368            json_nulls,
1369        })
1370    }
1371}
1372
1373#[cfg(test)]
1374mod tests {
1375    use super::*;
1376    use serde_json::json;
1377
1378    #[test]
1379    fn json_null_sidecar_distinguishes_sql_null() {
1380        let mut row = Record::new()
1381            .set("sql_null", json!(null))
1382            .set("json_null", json!(null));
1383        row.json_nulls.insert("json_null".to_string());
1384
1385        assert!(row.is_sql_null("sql_null"));
1386        assert!(!row.is_json_null("sql_null"));
1387        assert!(row.is_json_null("json_null"));
1388        assert!(!row.is_sql_null("json_null"));
1389        assert!(!row.is_sql_null("missing"));
1390
1391        // 既有读取与序列化行为不变:两者都仍是 JSON null。
1392        assert_eq!(row.get("json_null"), Some(&json!(null)));
1393        assert_eq!(
1394            serde_json::to_value(&row).expect("记录应可序列化"),
1395            json!({ "sql_null": null, "json_null": null })
1396        );
1397    }
1398
1399    #[test]
1400    fn remove_column_preserves_json_null_sidecar() {
1401        let mut row = Record::new()
1402            .set("json_null", json!(null))
1403            .set("sql_null", json!(null))
1404            .set("extra", json!(null));
1405        row.json_nulls.insert("json_null".to_string());
1406        row.json_nulls.insert("extra".to_string());
1407
1408        assert_eq!(row.remove_column("extra"), Some(json!(null)));
1409        assert!(
1410            !row.is_json_null("extra"),
1411            "被移除列的 JSON null 登记必须清除"
1412        );
1413        assert_eq!(row.get("extra"), None);
1414        assert_eq!(row.remove_column("extra"), None);
1415        assert_eq!(row.remove_column("missing"), None);
1416
1417        // 其余列的 sidecar 不受影响。
1418        assert!(row.is_json_null("json_null"));
1419        assert!(!row.is_sql_null("json_null"));
1420        assert!(row.is_sql_null("sql_null"));
1421    }
1422
1423    #[test]
1424    fn retain_columns_preserves_json_null_sidecar() {
1425        let mut row = Record::new()
1426            .set("keep_json", json!(null))
1427            .set("keep_sql", json!(null))
1428            .set("drop", json!(null));
1429        row.json_nulls.insert("keep_json".to_string());
1430        row.json_nulls.insert("drop".to_string());
1431
1432        row.retain_columns(&["keep_json", "keep_sql"]);
1433
1434        assert_eq!(row.as_map().len(), 2);
1435        assert!(row.is_json_null("keep_json"));
1436        assert!(!row.is_sql_null("keep_json"));
1437        assert!(row.is_sql_null("keep_sql"));
1438        assert_eq!(row.get("drop"), None);
1439        assert!(
1440            !row.is_json_null("drop"),
1441            "被裁掉列的 JSON null 登记必须清除"
1442        );
1443    }
1444
1445    #[test]
1446    fn get_rejects_blank_column_name() {
1447        let mut row = Record::new();
1448        row.insert("", json!(1));
1449        row.insert("   ", json!(2));
1450        row.insert("name", json!("Alice"));
1451
1452        assert_eq!(
1453            row.get("name").and_then(|value| value.as_str()),
1454            Some("Alice")
1455        );
1456        assert_eq!(row.get(""), None);
1457        assert_eq!(row.get("   "), None);
1458    }
1459
1460    #[test]
1461    fn serializes_as_plain_object_and_checks_types() {
1462        let row = Record::new().set("id", 7).set("name", "Alice");
1463
1464        assert_eq!(
1465            serde_json::to_value(&row).expect("记录应可序列化"),
1466            json!({
1467                "id": 7,
1468                "name": "Alice"
1469            })
1470        );
1471        assert_eq!(row.require::<i64>("id").expect("id 应为整数"), 7);
1472        assert!(row.require::<String>("id").is_err());
1473        assert!(row.require::<String>("missing").is_err());
1474    }
1475
1476    #[cfg(feature = "mysql")]
1477    #[test]
1478    fn mysql_integer_kind_distinguishes_boolean_tinyint_and_unsigned() {
1479        // 只有 tinyint(1)(sqlx 归一化为 BOOLEAN)才映射 bool,其余保持数值语义。
1480        assert_eq!(mysql_integer_kind("BOOLEAN"), MysqlIntegerKind::Boolean);
1481        assert_eq!(mysql_integer_kind("TINYINT"), MysqlIntegerKind::TinyInt);
1482        assert_eq!(
1483            mysql_integer_kind("TINYINT UNSIGNED"),
1484            MysqlIntegerKind::TinyIntUnsigned
1485        );
1486        assert_eq!(mysql_integer_kind("INT"), MysqlIntegerKind::Int64);
1487        assert_eq!(mysql_integer_kind("INT UNSIGNED"), MysqlIntegerKind::Int64);
1488        assert_eq!(mysql_integer_kind("BIGINT"), MysqlIntegerKind::Int64);
1489        assert_eq!(mysql_integer_kind("MEDIUMINT"), MysqlIntegerKind::Int64);
1490        assert_eq!(mysql_integer_kind("SMALLINT"), MysqlIntegerKind::Int64);
1491        assert_eq!(mysql_integer_kind("VARCHAR"), MysqlIntegerKind::Other);
1492    }
1493
1494    #[cfg(feature = "postgres")]
1495    #[test]
1496    fn pg_scalar_kind_covers_required_oids() {
1497        // 覆盖需求列出的全部标量族,未知 OID 必须返回 None 而不是默认字符串。
1498        for (oid, expected) in [
1499            (16, PgScalarKind::Bool),
1500            (21, PgScalarKind::Int2),
1501            (23, PgScalarKind::Int4),
1502            (20, PgScalarKind::Int8),
1503            (700, PgScalarKind::Float4),
1504            (701, PgScalarKind::Float8),
1505            (1700, PgScalarKind::Numeric),
1506            (25, PgScalarKind::Text),
1507            (1043, PgScalarKind::Text),
1508            (1042, PgScalarKind::Text),
1509            (19, PgScalarKind::Text),
1510            (17, PgScalarKind::Bytea),
1511            (1082, PgScalarKind::Date),
1512            (1083, PgScalarKind::Time),
1513            (1266, PgScalarKind::TimeTz),
1514            (1114, PgScalarKind::Timestamp),
1515            (1184, PgScalarKind::TimestampTz),
1516            (1186, PgScalarKind::Interval),
1517            (2950, PgScalarKind::Uuid),
1518            (114, PgScalarKind::Json),
1519            (3802, PgScalarKind::Json),
1520            (869, PgScalarKind::Inet),
1521            (650, PgScalarKind::Cidr),
1522            (3904, PgScalarKind::Range(PgRangeKind::Int4)),
1523            (3926, PgScalarKind::Range(PgRangeKind::Int8)),
1524            (3906, PgScalarKind::Range(PgRangeKind::Numeric)),
1525            (3912, PgScalarKind::Range(PgRangeKind::Date)),
1526            (3910, PgScalarKind::Range(PgRangeKind::TimestampTz)),
1527        ] {
1528            assert_eq!(pg_scalar_kind(oid), Some(expected), "OID {oid} 映射漂移");
1529        }
1530
1531        // POINT / 未列入内置清单的 range / 自定义类型等不得被静默归类。
1532        assert_eq!(pg_scalar_kind(600), None);
1533        assert_eq!(pg_scalar_kind(50_000), None);
1534        // tsrange 不在本轮承诺的五种内置 range 内,必须 fail-closed。
1535        assert_eq!(pg_scalar_kind(3908), None);
1536        assert_eq!(pg_scalar_kind(3905), None);
1537    }
1538
1539    #[cfg(feature = "postgres")]
1540    #[test]
1541    fn pg_array_element_kind_covers_required_arrays() {
1542        assert_eq!(pg_array_element_kind(1000), Some(PgScalarKind::Bool));
1543        assert_eq!(pg_array_element_kind(1005), Some(PgScalarKind::Int2));
1544        assert_eq!(pg_array_element_kind(1007), Some(PgScalarKind::Int4));
1545        assert_eq!(pg_array_element_kind(1016), Some(PgScalarKind::Int8));
1546        assert_eq!(pg_array_element_kind(1021), Some(PgScalarKind::Float4));
1547        assert_eq!(pg_array_element_kind(1022), Some(PgScalarKind::Float8));
1548        assert_eq!(pg_array_element_kind(1231), Some(PgScalarKind::Numeric));
1549        assert_eq!(pg_array_element_kind(1009), Some(PgScalarKind::Text));
1550        assert_eq!(pg_array_element_kind(1003), Some(PgScalarKind::Text));
1551        assert_eq!(pg_array_element_kind(1014), Some(PgScalarKind::Text));
1552        assert_eq!(pg_array_element_kind(1015), Some(PgScalarKind::Text));
1553        assert_eq!(pg_array_element_kind(1001), Some(PgScalarKind::Bytea));
1554        assert_eq!(pg_array_element_kind(1182), Some(PgScalarKind::Date));
1555        assert_eq!(pg_array_element_kind(1183), Some(PgScalarKind::Time));
1556        assert_eq!(pg_array_element_kind(1270), Some(PgScalarKind::TimeTz));
1557        assert_eq!(pg_array_element_kind(1115), Some(PgScalarKind::Timestamp));
1558        assert_eq!(pg_array_element_kind(1185), Some(PgScalarKind::TimestampTz));
1559        assert_eq!(pg_array_element_kind(1187), Some(PgScalarKind::Interval));
1560        assert_eq!(pg_array_element_kind(2951), Some(PgScalarKind::Uuid));
1561        assert_eq!(pg_array_element_kind(199), Some(PgScalarKind::Json));
1562        assert_eq!(pg_array_element_kind(3807), Some(PgScalarKind::Json));
1563        assert_eq!(pg_array_element_kind(1041), Some(PgScalarKind::Inet));
1564        assert_eq!(pg_array_element_kind(651), Some(PgScalarKind::Cidr));
1565
1566        // 内置标量 OID 不应当被误判为数组。
1567        assert_eq!(pg_array_element_kind(23), None);
1568        assert_eq!(pg_array_element_kind(600), None);
1569    }
1570
1571    #[cfg(feature = "postgres")]
1572    #[test]
1573    fn pg_decode_plan_classifies_enum_simple_and_unsupported() {
1574        use sqlx::postgres::PgTypeKind;
1575        use std::sync::Arc;
1576
1577        let simple = PgTypeKind::Simple;
1578        assert_eq!(
1579            pg_decode_plan_from_kind(Some(23), "INT4", &simple),
1580            PgDecodePlan::Scalar(PgScalarKind::Int4)
1581        );
1582
1583        // 用户自定义枚举按标签文本解码。
1584        let enum_kind = PgTypeKind::Enum(Arc::from(vec!["happy".to_string()]));
1585        assert_eq!(
1586            pg_decode_plan_from_kind(Some(50_000), "mood", &enum_kind),
1587            PgDecodePlan::Scalar(PgScalarKind::Enum)
1588        );
1589
1590        // 未知 OID 的描述必须带类型名与 OID,供结构化错误使用。
1591        match pg_decode_plan_from_kind(Some(600), "POINT", &simple) {
1592            PgDecodePlan::Unsupported(detail) => {
1593                assert!(detail.contains("POINT"), "{detail}");
1594                assert!(detail.contains("600"), "{detail}");
1595            }
1596            other => panic!("POINT 应判定为不支持,实得 {other:?}"),
1597        }
1598
1599        // COMPOSITE / RANGE 等结构类型同样判为不支持。
1600        let composite =
1601            PgTypeKind::Composite(Arc::from(Vec::<(String, sqlx::postgres::PgTypeInfo)>::new()));
1602        assert!(matches!(
1603            pg_decode_plan_from_kind(Some(50_001), "pair", &composite),
1604            PgDecodePlan::Unsupported(ref detail) if detail.contains("pair")
1605        ));
1606    }
1607
1608    #[cfg(feature = "postgres")]
1609    #[test]
1610    fn pg_time_formatting_is_iso8601() {
1611        use chrono::NaiveTime;
1612
1613        let whole = NaiveTime::from_hms_opt(1, 2, 3).expect("合法时间");
1614        assert_eq!(format_pg_time(whole), "01:02:03");
1615
1616        let fraction = NaiveTime::from_hms_nano_opt(12, 34, 56, 789_000_000).expect("合法时间");
1617        assert_eq!(format_pg_time(fraction), "12:34:56.789");
1618
1619        // 纳秒级精度去尾零。
1620        let nanos = NaiveTime::from_hms_nano_opt(0, 0, 0, 123_400_000).expect("合法时间");
1621        assert_eq!(format_pg_time(nanos), "00:00:00.1234");
1622
1623        let date = chrono::NaiveDate::from_ymd_opt(2026, 11, 8).expect("合法日期");
1624        let timestamp = date
1625            .and_hms_nano_opt(10, 30, 0, 500_000_000)
1626            .expect("合法时间");
1627        assert_eq!(
1628            pg_timestamp_to_json(timestamp).expect("日期时间应可编码"),
1629            json!("2026-11-08T10:30:00.5")
1630        );
1631    }
1632
1633    #[cfg(feature = "postgres")]
1634    #[test]
1635    fn pg_timetz_formatting_includes_offset() {
1636        use chrono::{FixedOffset, NaiveTime};
1637        use sqlx::postgres::types::PgTimeTz;
1638
1639        let time = NaiveTime::from_hms_opt(10, 30, 0).expect("合法时间");
1640        let east = FixedOffset::east_opt(8 * 3600).expect("合法偏移");
1641        assert_eq!(format_pg_offset(east), "+08:00");
1642        assert_eq!(
1643            pg_timetz_to_json(PgTimeTz { time, offset: east }).expect("timetz 应可编码"),
1644            json!("10:30:00+08:00")
1645        );
1646
1647        let west = FixedOffset::east_opt(-(5 * 3600 + 30 * 60)).expect("合法偏移");
1648        assert_eq!(format_pg_offset(west), "-05:30");
1649    }
1650
1651    #[cfg(feature = "postgres")]
1652    #[test]
1653    fn pg_interval_maps_to_lossless_object() {
1654        use sqlx::postgres::types::PgInterval;
1655
1656        let value = pg_interval_to_json(PgInterval {
1657            months: 14,
1658            days: 3,
1659            microseconds: 14_706_789_000,
1660        })
1661        .expect("interval 应可编码");
1662
1663        assert_eq!(
1664            value,
1665            json!({"months": 14, "days": 3, "microseconds": 14_706_789_000_i64})
1666        );
1667    }
1668
1669    #[cfg(feature = "postgres")]
1670    #[test]
1671    fn pg_inet_binary_and_text_formats() {
1672        // AF_INET + 24 位掩码 + 4 字节地址长度 + 192.168.1.1
1673        let masked = [2_u8, 24, 0, 4, 192, 168, 1, 1];
1674        assert_eq!(
1675            parse_pg_inet_bytes(&masked)
1676                .expect("IPv4 应可解析")
1677                .to_json(false),
1678            json!("192.168.1.1/24")
1679        );
1680
1681        // 掩码等于全宽时 INET 省略 /bits,CIDR 始终保留。
1682        let host = [2_u8, 32, 0, 4, 10, 0, 0, 1];
1683        assert_eq!(
1684            parse_pg_inet_bytes(&host)
1685                .expect("IPv4 应可解析")
1686                .to_json(false),
1687            json!("10.0.0.1")
1688        );
1689        assert_eq!(
1690            parse_pg_inet_bytes(&host)
1691                .expect("IPv4 应可解析")
1692                .to_json(true),
1693            json!("10.0.0.1/32")
1694        );
1695
1696        // AF_INET6 + ::1
1697        let mut v6 = [0_u8; 20];
1698        v6[0] = 3;
1699        v6[1] = 128;
1700        v6[3] = 16;
1701        v6[19] = 1;
1702        assert_eq!(
1703            parse_pg_inet_bytes(&v6)
1704                .expect("IPv6 应可解析")
1705                .to_json(false),
1706            json!("::1")
1707        );
1708
1709        assert_eq!(
1710            parse_pg_inet_text("192.168.1.1/24")
1711                .expect("文本 INET 应可解析")
1712                .to_json(false),
1713            json!("192.168.1.1/24")
1714        );
1715        assert_eq!(
1716            parse_pg_inet_text("::1")
1717                .expect("文本 INET 应可解析")
1718                .to_json(false),
1719            json!("::1")
1720        );
1721    }
1722
1723    #[cfg(feature = "postgres")]
1724    #[test]
1725    fn pg_float_rejects_non_finite_values() {
1726        assert_eq!(pg_f64_to_json(2.25).expect("有限浮点应可编码"), json!(2.25));
1727        assert!(pg_f64_to_json(f64::NAN).is_err());
1728        assert!(pg_f64_to_json(f64::INFINITY).is_err());
1729    }
1730
1731    #[cfg(feature = "postgres")]
1732    #[test]
1733    fn pg_range_bounds_follow_documented_json_contract() {
1734        use sqlx::postgres::types::PgRange;
1735        use std::ops::Bound;
1736
1737        let bounded = PgRange {
1738            start: Bound::Included(1_i32),
1739            end: Bound::Excluded(5_i32),
1740        };
1741        assert_eq!(
1742            pg_range_to_json(bounded, false, |value: i32| pg_i64_to_json(i64::from(
1743                value
1744            )))
1745            .expect("range 应可编码"),
1746            json!({
1747                "lower": 1,
1748                "upper": 5,
1749                "lower_inclusive": true,
1750                "upper_inclusive": false,
1751            })
1752        );
1753
1754        let unbounded = PgRange::<i64> {
1755            start: Bound::Unbounded,
1756            end: Bound::Included(10),
1757        };
1758        assert_eq!(
1759            pg_range_to_json(unbounded, false, pg_i64_to_json).expect("无界 range 应可编码"),
1760            json!({
1761                "lower": null,
1762                "upper": 10,
1763                "lower_inclusive": false,
1764                "upper_inclusive": true,
1765            })
1766        );
1767
1768        // 空 range 与 `(,)` 必须明确区分。
1769        let empty = PgRange::<i64> {
1770            start: Bound::Unbounded,
1771            end: Bound::Unbounded,
1772        };
1773        assert_eq!(
1774            pg_range_to_json(empty, true, pg_i64_to_json).expect("空 range 应可编码"),
1775            json!({"empty": true})
1776        );
1777    }
1778
1779    #[cfg(feature = "postgres")]
1780    #[test]
1781    fn pg_decoder_registry_prefers_and_overwrites() {
1782        fn first(_: &PgValue<'_>) -> Result<serde_json::Value, BaseError> {
1783            Ok(json!("first"))
1784        }
1785        fn second(_: &PgValue<'_>) -> Result<serde_json::Value, BaseError> {
1786            Ok(json!("second"))
1787        }
1788
1789        let oid = 4_000_000_001_u32;
1790        register_pg_type_decoder(oid, first);
1791        let decoder = lookup_pg_decoder(oid).expect("注册后应能查回解码器");
1792        assert_eq!(
1793            decoder(&PgValue::Text("x")).expect("解码器应成功"),
1794            json!("first")
1795        );
1796
1797        // 重复注册同一 OID 覆盖旧解码器。
1798        register_pg_type_decoder(oid, second);
1799        let decoder = lookup_pg_decoder(oid).expect("重复注册后应能查回解码器");
1800        assert_eq!(
1801            decoder(&PgValue::Text("x")).expect("解码器应成功"),
1802            json!("second")
1803        );
1804    }
1805}