Skip to main content

wordval_utils/
export.rs

1//! 导出导入工具:CSV / Excel / JSON
2//!
3//! 使用方式简洁,一行代码完成导入导出。
4
5use serde::{de::DeserializeOwned, Serialize};
6use wordval_core::{Error, Result};
7
8/// 导出格式
9pub enum ExportFormat {
10    Csv,
11    Json,
12    Xlsx,
13}
14
15/// 导出工具
16pub struct Export;
17
18impl Export {
19    /// 将 KV 数据集导出为 CSV 字符串
20    ///
21    /// `columns` 指定列顺序,`rows` 为 key→value 映射的集合。
22    ///
23    /// # 公式注入防护
24    ///
25    /// 用户可控的字符串(昵称、备注、地址等)若以 `=`、`+`、`-`、`@`、制表符、
26    /// 回车开头,会被 Excel/LibreOffice/Sheets 当作公式解析,进而触发
27    /// `HYPERLINK` 外泄、DDE 乃至 RCE。本函数对所有单元格做**中性化**处理
28    /// (详见 `sanitize_cell`),从而安全地包含用户输入。
29    ///
30    /// ```ignore
31    /// let csv = Export::to_csv(&["id", "name"], &records)?;
32    /// ```
33    pub fn to_csv(
34        columns: &[&str],
35        rows: &[std::collections::HashMap<String, String>],
36    ) -> Result<String> {
37        let mut w = csv::Writer::from_writer(Vec::new());
38        // 表头来自程序代码(非用户输入),通常无需中性化;但为统一行为也做处理,
39        // 避免表头意外以 = 开头时被误判。表头几乎不可能含危险字符,开销可忽略。
40        let headers: Vec<std::borrow::Cow<'_, str>> =
41            columns.iter().map(|c| sanitize_cell(c)).collect();
42        w.write_record(headers.iter().map(|h| h.as_ref()))
43            .map_err(|e| Error::Msg(format!("CSV写入失败: {}", e)))?;
44        for row in rows {
45            let vals: Vec<std::borrow::Cow<'_, str>> = columns
46                .iter()
47                .map(|c| {
48                    row.get(*c)
49                        .map(|s| sanitize_cell(s))
50                        .unwrap_or(std::borrow::Cow::Borrowed(""))
51                })
52                .collect();
53            w.write_record(vals.iter().map(|v| v.as_ref()))
54                .map_err(|e| Error::Msg(format!("CSV写入失败: {}", e)))?;
55        }
56        let data = w
57            .into_inner()
58            .map_err(|e| Error::Msg(format!("CSV输出失败: {}", e)))?;
59        String::from_utf8(data).map_err(|e| Error::Msg(format!("UTF8转换失败: {}", e)))
60    }
61
62    /// 将结构化数据导出为 JSON
63    pub fn to_json<T: Serialize>(items: &[T]) -> Result<String> {
64        serde_json::to_string_pretty(items)
65            .map_err(|e| Error::Msg(format!("JSON序列化失败: {}", e)))
66    }
67
68    /// 导出为 Excel 可识别格式(UTF-8 BOM + CSV)。
69    ///
70    /// 注意:产出的是带 BOM 的 CSV 字节流(沿用旧 API),并非真正的 OOXML `.xlsx`。
71    /// 与 `to_csv` 一样,单元格已做公式注入中性化处理(见 `sanitize_cell`)。
72    pub fn to_xlsx(
73        columns: &[&str],
74        rows: &[std::collections::HashMap<String, String>],
75    ) -> Result<Vec<u8>> {
76        let csv_content = Self::to_csv(columns, rows)?;
77        let bom = vec![0xEFu8, 0xBB, 0xBF];
78        let mut data = bom;
79        data.extend(csv_content.as_bytes());
80        Ok(data)
81    }
82}
83
84/// 中性化单元格,防止 CSV/Excel **公式注入**。
85///
86/// 当值以 `=`、`+`、`-`、`@`(公式触发符)或制表符 `\t`、回车 `\r`(CSV 控制符)
87/// 开头时,前置一个单引号 `'`。Excel 会把单引号视为"文本前缀"并显示原始内容,
88/// 而不解析为公式;纯 CSV 消费者看到的也只是一个无害的额外字符。
89///
90/// 判定覆盖两处:原始首字节,以及去除前导空格后的首字节(覆盖带空格前缀的变体)。
91///
92/// 这是 OWASP 推荐的电子表格导出中性化做法,适用于 Excel/LibreOffice/Google Sheets。
93fn sanitize_cell(value: &str) -> std::borrow::Cow<'_, str> {
94    /// 判定单个首字节是否为危险字符
95    fn is_dangerous(byte: Option<&u8>) -> bool {
96        matches!(
97            byte,
98            Some(b'=') | Some(b'+') | Some(b'-') | Some(b'@') | Some(b'\t') | Some(b'\r')
99        )
100    }
101    // 1. 原始首字节(覆盖以 \t / \r 直接开头的情况)
102    // 2. 去除前导空格后的首字节(覆盖带空格前缀的变体)
103    if is_dangerous(value.as_bytes().first()) || is_dangerous(value.trim_start().as_bytes().first())
104    {
105        std::borrow::Cow::Owned(format!("'{}", value))
106    } else {
107        // 安全值零分配,直接借用
108        std::borrow::Cow::Borrowed(value)
109    }
110}
111
112/// 导入工具
113pub struct Import;
114
115impl Import {
116    /// 从 CSV 字符串解析为 Vec<HashMap<String, String>>
117    pub fn from_csv(csv_str: &str) -> Result<Vec<std::collections::HashMap<String, String>>> {
118        let mut reader = csv::Reader::from_reader(csv_str.as_bytes());
119        let headers = reader
120            .headers()
121            .map_err(|e| Error::Msg(format!("CSV头解析失败: {}", e)))?
122            .clone();
123        let mut rows = Vec::new();
124        for result in reader.records() {
125            let record = result.map_err(|e| Error::Msg(format!("CSV行解析失败: {}", e)))?;
126            let mut map = std::collections::HashMap::new();
127            for (i, val) in record.iter().enumerate() {
128                if let Some(h) = headers.get(i) {
129                    map.insert(h.to_string(), val.to_string());
130                }
131            }
132            rows.push(map);
133        }
134        Ok(rows)
135    }
136
137    /// 从 JSON 反序列化
138    pub fn from_json<T: DeserializeOwned>(json_str: &str) -> Result<Vec<T>> {
139        serde_json::from_str(json_str).map_err(|e| Error::Msg(format!("JSON解析失败: {}", e)))
140    }
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146
147    #[test]
148    fn sanitize_cell_neutralizes_formula_chars() {
149        assert_eq!(
150            sanitize_cell("=HYPERLINK(\"https://evil\")"),
151            "'=HYPERLINK(\"https://evil\")"
152        );
153        assert_eq!(sanitize_cell("+1+1"), "'+1+1");
154        assert_eq!(sanitize_cell("-1+1"), "'-1+1");
155        assert_eq!(sanitize_cell("@SUM(A1)"), "'@SUM(A1)");
156        assert_eq!(sanitize_cell("\tcmd"), "'\tcmd");
157        assert_eq!(sanitize_cell("\r\n"), "'\r\n");
158    }
159
160    #[test]
161    fn sanitize_cell_leaves_safe_values() {
162        assert_eq!(sanitize_cell("hello"), "hello");
163        assert_eq!(sanitize_cell("123"), "123");
164        assert_eq!(sanitize_cell("=1=1"), "'=1=1"); // 含等号仍中性化(保守)
165        assert_eq!(sanitize_cell(""), "");
166    }
167
168    #[test]
169    fn sanitize_cell_resists_leading_whitespace() {
170        // 带前导空格的命令同样被中性化
171        assert_eq!(sanitize_cell("  =cmd"), "'  =cmd");
172        assert_eq!(sanitize_cell("  +cmd"), "'  +cmd");
173    }
174
175    fn rec(id: &str, name: &str) -> std::collections::HashMap<String, String> {
176        let mut m = std::collections::HashMap::new();
177        m.insert("id".to_string(), id.to_string());
178        m.insert("name".to_string(), name.to_string());
179        m
180    }
181
182    #[test]
183    fn export_csv_json_xlsx_roundtrip() {
184        let rows = vec![rec("1", "=evil"), rec("2", "ok")];
185        let csv = Export::to_csv(&["id", "name", "missing"], &rows).unwrap();
186        // 表头 + 公式中性化 + 缺失列为空
187        assert!(csv.starts_with("id,name,missing\n"), "{}", csv);
188        assert!(csv.contains("'=") || csv.contains("\"'="), "危险值应中性化: {}", csv);
189        // 导入回读(缺失列不会写入 map)
190        let back = Import::from_csv(&csv).unwrap();
191        assert_eq!(back.len(), 2);
192        assert_eq!(back[1].get("id").unwrap(), "2");
193        assert_eq!(back[0].get("name").unwrap(), "'=evil", "中性化前缀随导出落盘");
194        assert_eq!(back[0].get("missing").unwrap(), "", "缺失列导出为空串");
195        // JSON 导出/导入
196        let json = Export::to_json(&back).unwrap();
197        let items: Vec<std::collections::HashMap<String, String>> =
198            Import::from_json(&json).unwrap();
199        assert_eq!(items.len(), 2);
200        // xlsx 实为 BOM + CSV
201        let x = Export::to_xlsx(&["id", "name"], &rows).unwrap();
202        assert_eq!(&x[..3], &[0xEF, 0xBB, 0xBF]);
203        assert!(String::from_utf8_lossy(&x[3..]).starts_with("id,name\n"));
204    }
205
206    #[test]
207    fn import_error_paths() {
208        // 列数不一致(非 flexible)→ 行解析失败
209        assert!(Import::from_csv("a,b\n1,2,3\n").is_err());
210        // 非法 JSON
211        assert!(Import::from_json::<Vec<String>>("not-json").is_err());
212    }
213}