Skip to main content

fast_excel/read/
source.rs

1//! xlsx 容器(zip)访问层
2//!
3//! 关键点:**同一份文件可以同时打开多个 zip 句柄**。
4//! 大文件流式读取时,工作表 XML 需要长时间持有自己的读取器,而图片 /
5//! 共享字符串等条目又要能"随用随读"。为了避免自引用结构体(`ZipFile` 借用
6//! `ZipArchive`),这里按条目元信息(压缩方式 + 数据起始偏移 + 压缩长度)
7//! 自己拼一个**独占所有权**的读取器:`data_start` 之后接 `Take` + `DeflateDecoder`。
8
9use std::fs::File;
10use std::io::{BufReader, Read, Seek, SeekFrom};
11use std::path::{Path, PathBuf};
12use std::sync::Arc;
13
14use flate2::read::DeflateDecoder;
15use zip::CompressionMethod;
16use zip::read::ZipArchive;
17
18use crate::error::{ExcelError, Result};
19
20/// `Read + Seek` 组合 trait(用于装箱成 trait object)
21pub trait ReadSeek: Read + Seek {}
22impl<T: Read + Seek> ReadSeek for T {}
23
24/// 装箱后的 zip 读取器
25pub type BoxedReader = Box<dyn ReadSeek + Send>;
26
27/// xlsx 数据来源:磁盘文件或内存字节(可克隆,克隆体共享同一份数据)
28#[derive(Clone)]
29pub enum ZipSource {
30    Path(PathBuf),
31    Bytes(Arc<Vec<u8>>),
32}
33
34impl std::fmt::Debug for ZipSource {
35    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
36        match self {
37            ZipSource::Path(p) => write!(f, "ZipSource::Path({})", p.display()),
38            ZipSource::Bytes(b) => write!(f, "ZipSource::Bytes({} bytes)", b.len()),
39        }
40    }
41}
42
43impl ZipSource {
44    /// 以磁盘文件为数据源
45    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
46        let path = path.as_ref().to_path_buf();
47        if !path.exists() {
48            return Err(ExcelError::Io(format!("文件不存在:{}", path.display())));
49        }
50        Ok(ZipSource::Path(path))
51    }
52
53    /// 以内存字节为数据源
54    pub fn from_bytes(bytes: Vec<u8>) -> Self {
55        ZipSource::Bytes(Arc::new(bytes))
56    }
57
58    pub fn from_arc(bytes: Arc<Vec<u8>>) -> Self {
59        ZipSource::Bytes(bytes)
60    }
61
62    pub fn path(&self) -> Option<&Path> {
63        match self {
64            ZipSource::Path(p) => Some(p.as_path()),
65            ZipSource::Bytes(_) => None,
66        }
67    }
68
69    pub fn len(&self) -> u64 {
70        match self {
71            ZipSource::Path(p) => std::fs::metadata(p).map(|m| m.len()).unwrap_or(0),
72            ZipSource::Bytes(b) => b.len() as u64,
73        }
74    }
75
76    pub fn is_empty(&self) -> bool {
77        self.len() == 0
78    }
79
80    fn open_raw(&self) -> Result<BoxedReader> {
81        match self {
82            // 带缓冲,避免 XML 逐字节读时大量系统调用
83            ZipSource::Path(p) => Ok(Box::new(BufReader::with_capacity(
84                128 * 1024,
85                File::open(p)?,
86            ))),
87            ZipSource::Bytes(b) => Ok(Box::new(SharedBytes::new(b.clone()))),
88        }
89    }
90
91    /// 打开一个 zip 归档句柄(互不影响,可同时持有多份用于并发读取)
92    pub fn open_archive(&self) -> Result<ZipArchive<BoxedReader>> {
93        ZipArchive::new(self.open_raw()?).map_err(|e| ExcelError::NotXlsx(e.to_string()))
94    }
95
96    /// 完整读取一个条目到内存
97    pub fn read_entry(&self, name: &str) -> Result<Vec<u8>> {
98        let meta = self.entry_meta(name)?;
99        let mut reader = self.open_entry_reader(&meta)?;
100        let mut buf = Vec::with_capacity(meta.uncompressed_size.min(64 * 1024 * 1024) as usize);
101        reader.read_to_end(&mut buf)?;
102        Ok(buf)
103    }
104
105    /// 条目是否存在
106    pub fn has_entry(&self, name: &str) -> bool {
107        match self.open_archive() {
108            Ok(mut a) => a.by_name(name).is_ok(),
109            Err(_) => false,
110        }
111    }
112
113    /// 条目名列表(兼容性探测 / 调试用)
114    pub fn entry_names(&self) -> Result<Vec<String>> {
115        let archive = self.open_archive()?;
116        Ok(archive.file_names().map(|s| s.to_string()).collect())
117    }
118
119    /// 取条目元信息
120    pub fn entry_meta(&self, name: &str) -> Result<EntryMeta> {
121        let mut archive = self.open_archive()?;
122        let file = archive
123            .by_name(name)
124            .map_err(|_| ExcelError::NotXlsx(format!("缺少内部条目:{name}")))?;
125        if file.encrypted() {
126            return Err(ExcelError::Unsupported(
127                "加密的 xlsx 文件暂不支持".to_string(),
128            ));
129        }
130        Ok(EntryMeta {
131            name: name.to_string(),
132            data_start: file.data_start(),
133            compression: file.compression(),
134            compressed_size: file.compressed_size(),
135            uncompressed_size: file.size(),
136        })
137    }
138
139    /// 按元信息打开一个**独占所有权**的条目读取器(无借用,可长期持有)
140    pub fn open_entry_reader(&self, meta: &EntryMeta) -> Result<EntryReader> {
141        let mut raw = self.open_raw()?;
142        raw.seek(SeekFrom::Start(meta.data_start))?;
143        let limited = raw.take(meta.compressed_size);
144        let inner: Box<dyn Read + Send> = match meta.compression {
145            CompressionMethod::Stored => Box::new(limited),
146            CompressionMethod::Deflated => Box::new(DeflateDecoder::new(limited)),
147            other => {
148                return Err(ExcelError::Unsupported(format!(
149                    "条目不支持的压缩方式 {other:?}({})",
150                    meta.name
151                )));
152            }
153        };
154        Ok(EntryReader {
155            inner,
156            remaining: meta.uncompressed_size,
157        })
158    }
159
160    /// 一步到位:按条目名打开流式读取器
161    pub fn entry_reader(&self, name: &str) -> Result<EntryReader> {
162        let meta = self.entry_meta(name)?;
163        self.open_entry_reader(&meta)
164    }
165}
166
167/// 条目元信息
168#[derive(Debug, Clone)]
169pub struct EntryMeta {
170    pub name: String,
171    pub data_start: u64,
172    pub compression: CompressionMethod,
173    pub compressed_size: u64,
174    pub uncompressed_size: u64,
175}
176
177/// 独占所有权的条目读取器
178pub struct EntryReader {
179    inner: Box<dyn Read + Send>,
180    /// 未压缩长度(预估容量用)
181    remaining: u64,
182}
183
184impl EntryReader {
185    pub fn uncompressed_size(&self) -> u64 {
186        self.remaining
187    }
188}
189
190impl Read for EntryReader {
191    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
192        self.inner.read(buf)
193    }
194}
195
196#[cfg(test)]
197mod tests {
198    use super::*;
199
200    #[test]
201    fn test_missing_file() {
202        let err = ZipSource::open("definitely-not-exists.xlsx").unwrap_err();
203        assert!(matches!(err, ExcelError::Io(_)));
204    }
205}
206/// `Arc<Vec<u8>>` 上的零拷贝游标(`std::io::Cursor<Arc<Vec<u8>>>` 不满足 `Read`)
207pub(crate) struct SharedBytes {
208    data: Arc<Vec<u8>>,
209    pos: u64,
210}
211
212impl SharedBytes {
213    pub(crate) fn new(data: Arc<Vec<u8>>) -> Self {
214        Self { data, pos: 0 }
215    }
216}
217
218impl Read for SharedBytes {
219    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
220        let data: &[u8] = &self.data;
221        let start = self.pos as usize;
222        if start >= data.len() {
223            return Ok(0);
224        }
225        let n = (data.len() - start).min(buf.len());
226        buf[..n].copy_from_slice(&data[start..start + n]);
227        self.pos += n as u64;
228        Ok(n)
229    }
230}
231
232impl Seek for SharedBytes {
233    fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
234        let len = self.data.len() as i64;
235        let next = match pos {
236            SeekFrom::Start(n) => n as i64,
237            SeekFrom::End(n) => len + n,
238            SeekFrom::Current(n) => self.pos as i64 + n,
239        };
240        if next < 0 {
241            return Err(std::io::Error::new(
242                std::io::ErrorKind::InvalidInput,
243                "seek 到负数位置",
244            ));
245        }
246        self.pos = next as u64;
247        Ok(self.pos)
248    }
249}
250
251#[cfg(test)]
252mod shared_bytes_tests {
253    use super::*;
254
255    #[test]
256    fn test_shared_bytes_seek_read() {
257        let data = Arc::new(vec![1u8, 2, 3, 4, 5]);
258        let mut r = SharedBytes::new(data);
259        assert_eq!(r.seek(SeekFrom::Start(2)).unwrap(), 2);
260        let mut buf = [0u8; 2];
261        r.read_exact(&mut buf).unwrap();
262        assert_eq!(buf, [3, 4]);
263        assert_eq!(r.seek(SeekFrom::End(-1)).unwrap(), 4);
264        assert_eq!(r.read(&mut buf).unwrap(), 1);
265        assert_eq!(buf[0], 5);
266    }
267}