pgbatis 0.1.51

/*
 * @Author: venom
 * @Date: 2021-08-02 10:21:41
 * @LastEditors: BuddyCoder
 * @LastEditTime: 2025-11-12 18:50:05
 * @Description:
 * @FilePath: /buddyServer/Users/caixiaocong/workspace/rust/rust_crates/pgbatis/src/wrapper.rs
 * MIT
 */
use crate::{ColumnExt, Parameters};
use std::collections::HashMap;
use std::fmt;
use tokio_postgres::types::ToSql;

use tracing::*;

/// `Wrapper` 方法可能返回的错误。
///
/// 当前仅包含排序字段校验失败的情况。
#[derive(Debug)]
pub enum WrapperError {
    /// 排序字段包含非法字符（`--` 或 `;`），可能为 SQL 注入攻击。
    OrderBy,
}

impl std::error::Error for WrapperError {}

impl WrapperError {
    /// 返回错误的可读描述。
    pub fn to_string(&self) -> String {
        match self {
            WrapperError::OrderBy => "根据不同的元素返回响应的字符串信息 for OrderBy".to_string(),
        }
    }
}

impl fmt::Display for WrapperError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            WrapperError::OrderBy => write!(f, "Error: OrderBy"),
        }
    }
}

/// 链式 SQL 条件构造器。
///
/// 通过链式方法（`eq`、`like`、`gt`、`set_pages` 等）构建 WHERE 条件、排序和分页。
/// 内部使用 `#args` 占位符，调用 [`build`](Wrapper::build) 时转换为 PostgreSQL 的 `$1`、`$2`... 参数化占位符，
/// 避免 SQL 注入。
///
/// # 示例
///
/// ```rust,ignore
/// use pgbatis::Wrapper;
/// let wrapper = Wrapper::new()
///     .eq(&"name", &"Alice")
///     .gt(&"age", &18)
///     .set_pages(1, 10)
///     .set_order_by_column_ext(&"id", false);
/// let (where_clause, args) = wrapper.build(1).unwrap();
/// // where_clause: " \"name\" = $1  AND  \"age\" > $2 "
/// // args: [&"Alice", &18]
/// ```
///
/// # 字段说明
/// - `where_sql`: 条件片段列表，以 ` AND ` 连接
/// - `args`: 参数数组，顺序与 `#args` 占位符严格一致
/// - `page_no` / `page_size`: 分页参数
/// - `order_by`: 排序字段
/// - `desc`: 是否降序
/// - `recoder_field`: 指定返回字段（空则返回全部字段）
#[derive(Clone)]
pub struct Wrapper<'a> {
    /// WHERE 条件片段列表，每个元素为一个条件表达式（含 `#args` 占位符）。
    pub where_sql: Vec<String>,
    /// 参数数组，顺序与 `#args` 占位符一一对应。
    pub args: Vec<&'a (dyn ToSql + Sync)>,
    /// 预留的格式化参数映射。
    pub formats: HashMap<String, String>,
    /// 可选的 LIMIT 值。
    pub limit: Option<u64>,
    /// 每页记录数，默认 20。
    pub page_size: u64,
    /// 当前页码（从 0 开始），默认 0。
    pub page_no: u64,
    /// 排序字段名。
    pub order_by: &'a str,
    /// 指定返回的字段名列表，为空时返回全部字段。
    pub recoder_field: Vec<&'a str>,
    /// 排序方向：`true` 为降序（DESC），`false` 为升序（ASC）。
    pub desc: bool,
}

fn format_where_sql(temp_where: String, args_number: u32) -> (String, u32) {
    match temp_where.find("#args") {
        Some(_r) => {
            let args_number_str = format!("${}", args_number);
            let result = temp_where.replacen("#args", args_number_str.as_str(), 1);
            let args_numbers = args_number + 1;
            let args_number_result = format_where_sql(result, args_numbers);
            args_number_result
        }
        None => (temp_where, args_number),
    }
}

/// 校验排序字段是否安全，防止 SQL 注入。
///
/// 检测 `--`（注释符）和 `;`（语句分隔符），包含任一字符则返回 `false`。
///
/// # 示例
///
/// ```rust
/// use pgbatis::wrapper::check_order_by;
/// assert!(check_order_by("id"));
/// assert!(!check_order_by("id; DROP TABLE users"));
/// assert!(!check_order_by("id--comment"));
/// ```
pub fn check_order_by(order_by: &str) -> bool {
    let temp = order_by.to_string();
    let jh_index = temp.find("--");
    if jh_index.is_some() {
        return false;
    }

    let fh_index = temp.find(";");

    if fh_index.is_some() {
        return false;
    }
    return true;
}

impl<'a> Wrapper<'a> {
    /// 创建空的 `Wrapper` 实例。
    ///
    /// 默认 `page_size = 20`，`page_no = 0`，`desc = false`。
    pub fn new() -> Self {
        Self {
            //  args_number,
            where_sql: Vec::with_capacity(200),
            args: Vec::with_capacity(200),
            formats: Default::default(),
            limit: None,
            page_size: 20,
            page_no: 0,
            order_by: "",
            desc: false,
            recoder_field: Vec::new(),
        }
    }
    /// 添加等值条件：`column = $n`。
    ///
    /// # 参数
    /// - `column`: 列标识（实现 [`ColumnExt`]）
    /// - `obj`: 要匹配的值
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let wrapper = Wrapper::new().eq(&"id", &"user_1");
    /// ```
    pub fn eq<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" = #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 添加不等条件：`column <> $n`。
    pub fn not_eq<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" <> #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 添加空值判断：`column IS NULL`（无需参数）。
    pub fn is_null<T>(mut self, column: &dyn ColumnExt) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" is NULL ", column_name);
        self.where_sql.push(s);
        self
    }

    /// 添加非空判断：`column IS NOT NULL`（无需参数）。
    pub fn is_not_null<T>(mut self, column: &dyn ColumnExt) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" is not NULL ", column_name);
        self.where_sql.push(s);
        self
    }

    /// 添加范围条件：`column BETWEEN $n AND $n+1`。
    pub fn between<T>(mut self, column: &dyn ColumnExt, min: &'a T, max: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" between  #args AND #args ", column_name);
        self.where_sql.push(s);
        self.args.push(min);
        self.args.push(max);
        self
    }

    /// 添加范围外条件：`NOT BETWEEN $n AND $n+1`。
    pub fn not_between<T>(mut self, column: &dyn ColumnExt, min: &'a T, max: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" not between \"{}\" #args AND #args ", column_name);
        self.where_sql.push(s);
        self.args.push(min);
        self.args.push(max);
        self
    }

    /// 添加 LIKE 模糊匹配条件：`column LIKE $n`。
    ///
    /// `%` 通配符需在传入值中自行拼接，可使用 [`format_like`](crate::format_like) 等辅助函数。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let keyword = format!("%{}%", "hello");
    /// let wrapper = Wrapper::new().like(&"name", &keyword);
    /// ```
    pub fn like<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" like #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

     

    /// 添加 IN 条件：`column IN ($n)`。
    ///
    /// 注意：此方法将整个值作为单个参数绑定，若需多个值的 IN 查询请使用 [`in_array_string`](Wrapper::in_array_string)。
    pub fn set_in<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" in (#args) ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    // 字符串拼接的写法 有安全隐患，可以进行SQL注入攻击。
    //    //只支持字符串
    //     pub fn like_left(mut self, column: &str, obj: &str) -> Self
    //     {
    //         let s = format!(" \"{}\" like '%{}' ",column,obj);
    //         self.where_sql.push(s);
    //         self
    //     }

    //     //只支持字符串
    //     pub fn like_right(mut self, column: &str, obj: &str) -> Self
    //     {
    //         let s = format!(" \"{}\" like '{}%' ",column,obj);
    //         self.where_sql.push(s);
    //         self
    //     }

    /// 添加大于条件：`column > $n`。
    pub fn gt<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" > #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 添加大于等于条件：`column >= $n`。
    pub fn ge<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" >= #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 添加小于条件：`column < $n`。
    pub fn lt<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" < #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 添加小于等于条件：`column <= $n`。
    pub fn le<T>(mut self, column: &dyn ColumnExt, obj: &'a T) -> Self
    where
        T: ToSql + Sync,
    {
        let column_name = column.get();
        let s = format!(" \"{}\" <= #args ", column_name);
        self.where_sql.push(s);
        self.args.push(obj);
        self
    }

    /// 设置 LIMIT 值（偏移返回）。
    ///
    /// 用于限制返回行数，通常配合分页 API 使用。
    pub fn limit(mut self, limit: u64) -> Self {
        self.limit = Some(limit);
        self
    }

    /// 设置分页参数。
    ///
    /// # 参数
    /// - `page_no`: 当前页码（从 1 开始，小于 1 时自动修正为 1）
    /// - `page_size`: 每页记录数
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let wrapper = Wrapper::new()
    ///     .eq(&"status", &1)
    ///     .set_pages(2, 20);  // 第2页，每页20条
    /// ```
    pub fn set_pages(mut self, page_no: u64, page_size: u64) -> Self {
        self.page_no = page_no;
        self.page_size = page_size;
        self
    }

    /// 设置排序字段（字符串形式），含 SQL 注入校验。
    ///
    /// 会调用 [`check_order_by`] 检测非法字符，校验失败返回 [`WrapperError::OrderBy`]。
    ///
    /// # 参数
    /// - `order_by`: 排序字段名
    /// - `desc`: `true` 为降序，`false` 为升序
    ///
    /// # 错误
    /// - 字段包含 `--` 或 `;` 时返回 `Err(WrapperError::OrderBy)`
    pub fn set_order_by(mut self, order_by: &'a str, desc: bool) -> Result<Self, WrapperError> {
        if !check_order_by(order_by) {
            return Err(WrapperError::OrderBy);
        }
        self.order_by = order_by;
        self.desc = desc;
        Ok(self)
    }

    /// 设置排序字段（[`ColumnExt`] 类型安全形式）。
    ///
    /// 相比 [`set_order_by`](Wrapper::set_order_by)，通过 `ColumnExt` trait 获取列名，
    /// 无需手动校验。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let wrapper = Wrapper::new()
    ///     .eq(&"status", &1)
    ///     .set_order_by_column_ext(&"created_at", true);  // 按创建时间降序
    /// ```
    pub fn set_order_by_column_ext(mut self, order_by: &dyn ColumnExt, desc: bool) -> Self {
        self.order_by = order_by.get();
        self.desc = desc;
        self
    }

    /// 获取 ORDER BY 子句字符串。
    ///
    /// 若未设置排序字段（`order_by` 为空），返回 `None`。
    ///
    /// # 返回
    /// - `Some(" ORDER BY {field} DESC ")` 或 `Some(" ORDER BY {field} ASC ")`
    /// - `None` — 未设置排序
    pub fn get_order_by(self) -> Option<String> {
        if self.order_by.is_empty() {
            return None;
        } else {
            let order_by = if self.desc {
                format!(" ORDER BY {}  DESC ", self.order_by)
            } else {
                format!(" ORDER BY {}  ASC ", self.order_by)
            };
            return Some(order_by);
        }
    }

    /// 获取分页信息。
    ///
    /// # 返回
    /// `(limit_str, offset, page_no, page_size)`
    /// - `limit_str`: `" LIMIT {page_size} OFFSET {offset}"` 字符串
    /// - `offset`: 偏移量 = `(page_no - 1) * page_size`
    /// - `page_no`: 修正后的页码（最小为 1）
    /// - `page_size`: 每页记录数
    pub fn get_page_info(self) -> (String, u64, u64, u64) {
        debug!(
            "get_page_info: page_no {},page_size {}",
            self.page_no, self.page_size
        );
        let page_no = if self.page_no < 1 { 1 } else { self.page_no };
        let limit = (page_no - 1) * self.page_size;
        let limit_str = format!(" LIMIT {} OFFSET {}", self.page_size, limit);
        (limit_str, limit, page_no, self.page_size)
    }
    /// 构建最终的 WHERE 子句和参数数组。
    ///
    /// 将所有条件片段用 ` AND ` 连接，同时将 `#args` 占位符替换为 `$1`、`$2`... 等
    /// PostgreSQL 位置参数。参数数组顺序与占位符严格一致。
    ///
    /// # 参数
    /// - `args_number`: 参数起始编号（通常为 1）
    ///
    /// # 返回
    /// - `Ok((where_clause, args))` — WHERE 子句字符串和参数数组。
    ///   若无条件，`where_clause` 为空字符串。
    /// - `Err(String)` — 构建失败
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let wrapper = Wrapper::new()
    ///     .eq(&"name", &"Alice")
    ///     .gt(&"age", &18);
    /// let (where_clause, args) = wrapper.build(1).unwrap();
    /// // where_clause: " \"name\" = $1  AND  \"age\" > $2 "
    /// // args: [&"Alice", &18]
    /// ```
    pub fn build(self, args_number: u32) -> Result<(String, Vec<&'a (dyn ToSql + Sync)>), String> {
        let mut args_number = args_number;
        let mut temp_where_sql = Vec::new();
        for mut temp_where in self.where_sql.iter() {
            let (wheresql, temp_args_number) =
                format_where_sql((&mut temp_where).to_string(), args_number);
            args_number = temp_args_number;
            temp_where_sql.push(wheresql);
        }
        let sql = temp_where_sql.join(" AND ");
        let args = self.args;
        return Ok((sql, args));
    }

    /// 添加一个要返回的字段名。可多次调用以指定多个字段。
    ///
    /// 若不调用此方法，默认返回实体的全部字段（由 [`Parameters::get_field_list`] 决定）。
    pub fn set_recoder_field(mut self, column: &dyn ColumnExt) -> Self {
        let column_name = column.get();
        self.recoder_field.push(column_name);
        self
    }

    /// 获取 SELECT 字段列表字符串。
    ///
    /// 若通过 [`set_recoder_field`](Wrapper::set_recoder_field) 指定了字段，返回字段列表；
    /// 否则返回 [`Parameters::get_field_list`] 的全部字段。
    pub fn get_recoder_field<T>(self) -> String
    where
        T: Parameters,
    {
        if self.recoder_field.len() == 0 {
            T::get_field_list()
        } else {
            self.recoder_field.join(",")
        }
    }


    /// 添加 IN 条件（字符串拼接形式）。
    ///
    /// ⚠️ **安全警告**：此方法直接将字符串值拼接到 SQL 中（如 `IN ('a','b')`），
    /// 若输入来自用户且未校验，存在 SQL 注入风险。仅在输入可控时使用。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let wrapper = Wrapper::new()
    ///     .in_array_string(&"status", &vec!["active".into(), "pending".into()]);
    /// // 生成: "status" in ('active', 'pending')
    /// ```
    pub fn in_array_string(mut self, column: &dyn ColumnExt, obj: &Vec<String>) -> Self          
    {
        let column_name = column.get();
        let array_str = obj.iter().map(|s| format!("'{}'", s)).collect::<Vec<String>>().join(", ");
        //let my_text_array = postgres_array::Array::from_vec(obj).to_string();
        let s = format!(" \"{}\" in ({}) ", column_name,array_str);
        self.where_sql.push(s);
        //self.args.push();
        self
    }
}