wordval-utils 1.0.3

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! 导出导入工具:CSV / Excel / JSON
//!
//! 使用方式简洁,一行代码完成导入导出。

use serde::{de::DeserializeOwned, Serialize};
use wordval_core::{Error, Result};

/// 导出格式
pub enum ExportFormat {
    Csv,
    Json,
    Xlsx,
}

/// 导出工具
pub struct Export;

impl Export {
    /// 将 KV 数据集导出为 CSV 字符串
    ///
    /// `columns` 指定列顺序,`rows` 为 key→value 映射的集合。
    ///
    /// # 公式注入防护
    ///
    /// 用户可控的字符串(昵称、备注、地址等)若以 `=`、`+`、`-`、`@`、制表符、
    /// 回车开头,会被 Excel/LibreOffice/Sheets 当作公式解析,进而触发
    /// `HYPERLINK` 外泄、DDE 乃至 RCE。本函数对所有单元格做**中性化**处理
    /// (详见 `sanitize_cell`),从而安全地包含用户输入。
    ///
    /// ```ignore
    /// let csv = Export::to_csv(&["id", "name"], &records)?;
    /// ```
    pub fn to_csv(
        columns: &[&str],
        rows: &[std::collections::HashMap<String, String>],
    ) -> Result<String> {
        let mut w = csv::Writer::from_writer(Vec::new());
        // 表头来自程序代码(非用户输入),通常无需中性化;但为统一行为也做处理,
        // 避免表头意外以 = 开头时被误判。表头几乎不可能含危险字符,开销可忽略。
        let headers: Vec<std::borrow::Cow<'_, str>> =
            columns.iter().map(|c| sanitize_cell(c)).collect();
        w.write_record(headers.iter().map(|h| h.as_ref()))
            .map_err(|e| Error::Msg(format!("CSV写入失败: {}", e)))?;
        for row in rows {
            let vals: Vec<std::borrow::Cow<'_, str>> = columns
                .iter()
                .map(|c| {
                    row.get(*c)
                        .map(|s| sanitize_cell(s))
                        .unwrap_or(std::borrow::Cow::Borrowed(""))
                })
                .collect();
            w.write_record(vals.iter().map(|v| v.as_ref()))
                .map_err(|e| Error::Msg(format!("CSV写入失败: {}", e)))?;
        }
        let data = w
            .into_inner()
            .map_err(|e| Error::Msg(format!("CSV输出失败: {}", e)))?;
        String::from_utf8(data).map_err(|e| Error::Msg(format!("UTF8转换失败: {}", e)))
    }

    /// 将结构化数据导出为 JSON
    pub fn to_json<T: Serialize>(items: &[T]) -> Result<String> {
        serde_json::to_string_pretty(items)
            .map_err(|e| Error::Msg(format!("JSON序列化失败: {}", e)))
    }

    /// 导出为 Excel 可识别格式(UTF-8 BOM + CSV)。
    ///
    /// 注意:产出的是带 BOM 的 CSV 字节流(沿用旧 API),并非真正的 OOXML `.xlsx`。
    /// 与 `to_csv` 一样,单元格已做公式注入中性化处理(见 `sanitize_cell`)。
    pub fn to_xlsx(
        columns: &[&str],
        rows: &[std::collections::HashMap<String, String>],
    ) -> Result<Vec<u8>> {
        let csv_content = Self::to_csv(columns, rows)?;
        let bom = vec![0xEFu8, 0xBB, 0xBF];
        let mut data = bom;
        data.extend(csv_content.as_bytes());
        Ok(data)
    }
}

/// 中性化单元格,防止 CSV/Excel **公式注入**。
///
/// 当值以 `=`、`+`、`-`、`@`(公式触发符)或制表符 `\t`、回车 `\r`(CSV 控制符)
/// 开头时,前置一个单引号 `'`。Excel 会把单引号视为"文本前缀"并显示原始内容,
/// 而不解析为公式;纯 CSV 消费者看到的也只是一个无害的额外字符。
///
/// 判定覆盖两处:原始首字节,以及去除前导空格后的首字节(覆盖带空格前缀的变体)。
///
/// 这是 OWASP 推荐的电子表格导出中性化做法,适用于 Excel/LibreOffice/Google Sheets。
fn sanitize_cell(value: &str) -> std::borrow::Cow<'_, str> {
    /// 判定单个首字节是否为危险字符
    fn is_dangerous(byte: Option<&u8>) -> bool {
        matches!(
            byte,
            Some(b'=') | Some(b'+') | Some(b'-') | Some(b'@') | Some(b'\t') | Some(b'\r')
        )
    }
    // 1. 原始首字节(覆盖以 \t / \r 直接开头的情况)
    // 2. 去除前导空格后的首字节(覆盖带空格前缀的变体)
    if is_dangerous(value.as_bytes().first()) || is_dangerous(value.trim_start().as_bytes().first())
    {
        std::borrow::Cow::Owned(format!("'{}", value))
    } else {
        // 安全值零分配,直接借用
        std::borrow::Cow::Borrowed(value)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn sanitize_cell_neutralizes_formula_chars() {
        assert_eq!(
            sanitize_cell("=HYPERLINK(\"https://evil\")"),
            "'=HYPERLINK(\"https://evil\")"
        );
        assert_eq!(sanitize_cell("+1+1"), "'+1+1");
        assert_eq!(sanitize_cell("-1+1"), "'-1+1");
        assert_eq!(sanitize_cell("@SUM(A1)"), "'@SUM(A1)");
        assert_eq!(sanitize_cell("\tcmd"), "'\tcmd");
        assert_eq!(sanitize_cell("\r\n"), "'\r\n");
    }

    #[test]
    fn sanitize_cell_leaves_safe_values() {
        assert_eq!(sanitize_cell("hello"), "hello");
        assert_eq!(sanitize_cell("123"), "123");
        assert_eq!(sanitize_cell("=1=1"), "'=1=1"); // 含等号仍中性化(保守)
        assert_eq!(sanitize_cell(""), "");
    }

    #[test]
    fn sanitize_cell_resists_leading_whitespace() {
        // 带前导空格的命令同样被中性化
        assert_eq!(sanitize_cell("  =cmd"), "'  =cmd");
        assert_eq!(sanitize_cell("  +cmd"), "'  +cmd");
    }
}

/// 导入工具
pub struct Import;

impl Import {
    /// 从 CSV 字符串解析为 Vec<HashMap<String, String>>
    pub fn from_csv(csv_str: &str) -> Result<Vec<std::collections::HashMap<String, String>>> {
        let mut reader = csv::Reader::from_reader(csv_str.as_bytes());
        let headers = reader
            .headers()
            .map_err(|e| Error::Msg(format!("CSV头解析失败: {}", e)))?
            .clone();
        let mut rows = Vec::new();
        for result in reader.records() {
            let record = result.map_err(|e| Error::Msg(format!("CSV行解析失败: {}", e)))?;
            let mut map = std::collections::HashMap::new();
            for (i, val) in record.iter().enumerate() {
                if let Some(h) = headers.get(i) {
                    map.insert(h.to_string(), val.to_string());
                }
            }
            rows.push(map);
        }
        Ok(rows)
    }

    /// 从 JSON 反序列化
    pub fn from_json<T: DeserializeOwned>(json_str: &str) -> Result<Vec<T>> {
        serde_json::from_str(json_str).map_err(|e| Error::Msg(format!("JSON解析失败: {}", e)))
    }
}