springbootAI 1.8.0__py3-none-any.whl

spring/excel/easy_excel.py

@@ -0,0 +1,94 @@
+"""SpringBootAI ``EasyExcel`` —— 流式构建入口（对齐 alibaba EasyExcel API）。
+
+用法::
+
+    # 读
+    rows = (EasyExcel.read("/tmp/users.xlsx", head=DemoData)
+            .head_row_number(1)
+            .sheet(sheet_no=0)
+            .doRead())
+
+    # 写
+    EasyExcel.write("/tmp/users.xlsx", head=DemoData).sheet("用户列表").doWrite(data_list)
+
+    # 多 sheet
+    EasyExcel.write("/tmp/multi.xlsx", head=DemoData).doWriteAll({"S1": list1, "S2": list2})
+
+    # 读所有 sheet
+    sheets = EasyExcel.read("/tmp/multi.xlsx", head=DemoData).doReadAll()
+
+注解声明不依赖 openpyxl；仅在 ``doRead`` / ``doWrite`` 时检测并提示安装 ``springbootAI[excel]``。
+"""
+from __future__ import annotations
+
+from typing import Any, Optional, Type, Union
+
+from .reader import ExcelReader
+from .writer import ExcelWriter
+
+
+class EasyExcel:
+    """EasyExcel 流式入口（静态工厂方法风格，对齐 alibaba EasyExcel）。"""
+
+    @staticmethod
+    def read(
+        source: Any,
+        head: Optional[Type] = None,
+        head_row_number: Optional[int] = None,
+        sheet_no: Optional[int] = None,
+        sheet_name: Optional[str] = None,
+    ) -> ExcelReader:
+        """构建读取器。
+
+        Args:
+            source:          文件路径或类文件对象。
+            head:            实体类（带 ``@ExcelProperty`` 注解）。
+            head_row_number: 表头所在行号（从 1 起）。默认取类 ``@excel_sheet`` 配置或 1。
+            sheet_no:        工作表索引（0 起）。
+            sheet_name:      工作表名称（优先于 sheet_no）。
+        """
+        return ExcelReader(
+            source=source, head=head, head_row_number=head_row_number,
+            sheet_no=sheet_no, sheet_name=sheet_name,
+        )
+
+    @staticmethod
+    def write(
+        target: Any,
+        head: Optional[Type] = None,
+        sheet_name: Optional[str] = None,
+    ) -> ExcelWriter:
+        """构建写入器。
+
+        Args:
+            target:     文件路径或类文件对象。
+            head:       实体类（带 ``@ExcelProperty`` 注解）。
+            sheet_name: 工作表名称。默认取类 ``@excel_sheet`` 配置或 "Sheet1"。
+        """
+        return ExcelWriter(target=target, head=head, sheet_name=sheet_name)
+
+
+# 便捷函数（非流式，一步到位）
+def read_excel(
+    source: Any,
+    head: Type,
+    sheet_no: Optional[int] = None,
+    sheet_name: Optional[str] = None,
+    head_row_number: Optional[int] = None,
+) -> list:
+    """一步读取：``read_excel(path, DemoData)``。"""
+    return EasyExcel.read(source, head=head, head_row_number=head_row_number,
+                          sheet_no=sheet_no, sheet_name=sheet_name).doRead()
+
+
+def write_excel(
+    target: Any,
+    head: Type,
+    data: list,
+    sheet_name: Optional[str] = None,
+) -> Any:
+    """一步写入：``write_excel(path, DemoData, rows)``。"""
+    return EasyExcel.write(target, head=head, sheet_name=sheet_name).doWrite(data)
+
+
+__all__ = ["EasyExcel", "read_excel", "write_excel"]

spring/excel/exceptions.py

@@ -0,0 +1,31 @@
+"""SpringBootAI Excel 模块异常定义。
+
+设计对齐 EasyExcel 的错误语义：注解配置错误、读写过程错误、可选依赖缺失均通过
+本模块的异常抛出，便于上层统一捕获。
+"""
+
+
+class ExcelError(Exception):
+    """Excel 模块所有异常的基类。"""
+
+
+class ExcelPropertyError(ExcelError):
+    """实体类字段上的 @ExcelProperty / @ExcelIgnore 配置不合法时抛出。"""
+
+
+class ExcelReadError(ExcelError):
+    """读取 Excel 过程中发生的错误（表头缺失、行数据无法转换等）。"""
+
+
+class ExcelWriteError(ExcelError):
+    """写入 Excel 过程中发生的错误。"""
+
+
+class ExcelDependencyError(ExcelError):
+    """缺少可选依赖 openpyxl 时抛出。
+
+    Excel 读写引擎底层依赖 openpyxl。注解声明（@ExcelProperty 等）不依赖任何第三方库，
+    仅在实际 read/write 时检测。未安装时给出明确的安装提示::
+
+        pip install springbootAI[excel]
+    """

spring/excel/reader.py

@@ -0,0 +1,254 @@
+"""SpringBootAI Excel 读取引擎。
+
+按 ``@ExcelProperty`` / ``@ExcelIgnore`` / ``@excel_sheet`` 注解把 Excel 工作表读为实体对象列表。
+底层依赖 openpyxl（仅 ``doRead`` 时检测，注解声明无需安装）。
+
+读取流程对齐 alibaba EasyExcel：
+    1. 读取表头行（``head_row_number``，默认 1）。
+    2. 表头文案 -> ``ExcelColumnModel`` 映射（按 ``value`` 匹配；无注解时按列位置匹配）。
+    3. 数据行逐行按 ``converter.from_excel`` 转换，构造实体实例。
+"""
+from __future__ import annotations
+
+import inspect
+from typing import Any, List, Optional, Type, Union
+
+from .annotations import (
+    ExcelColumnModel, ExcelSheet, _get_class_sheet_meta, parse_excel_columns,
+)
+from .converters import resolve_converter
+from .exceptions import ExcelDependencyError, ExcelReadError
+
+
+def _require_openpyxl():
+    try:
+        import openpyxl
+        return openpyxl
+    except ImportError as e:
+        raise ExcelDependencyError(
+            "Excel 读取依赖 openpyxl，请先安装：pip install springbootAI[excel]"
+        ) from e
+
+
+def _build_instance(cls: Type, kwargs: dict) -> Any:
+    """构造实体实例：优先 ``cls(**kwargs)``，失败则逐字段 setattr（兼容纯 ``__init__`` 模型）。"""
+    # 只保留 __init__ 能接收的参数
+    try:
+        sig = inspect.signature(cls.__init__)
+        params = list(sig.parameters.values())[1:]  # 跳过 self
+        accept_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params)
+        if accept_kwargs:
+            return cls(**kwargs)
+        allowed = {p.name for p in params if p.kind in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY,
+        )}
+        filtered = {k: v for k, v in kwargs.items() if k in allowed}
+        return cls(**filtered)
+    except TypeError:
+        pass
+    # 回退：无参构造 + setattr
+    try:
+        obj = cls()
+    except Exception:
+        obj = object.__new__(cls)
+    for k, v in kwargs.items():
+        try:
+            setattr(obj, k, v)
+        except Exception:
+            pass
+    return obj
+
+
+class ExcelReader:
+    """Excel 读取器。由 ``EasyExcel.read(...)`` 构建，调用 ``doRead`` 执行。"""
+
+    def __init__(
+        self,
+        source: Any,
+        head: Optional[Type] = None,
+        head_row_number: Optional[int] = None,
+        sheet_no: Optional[int] = None,
+        sheet_name: Optional[str] = None,
+    ):
+        self.source = source
+        self.head = head
+        self._head_row_number = head_row_number
+        self._sheet_no = sheet_no
+        self._sheet_name = sheet_name
+
+    # ---- 流式配置 ----
+
+    def head_row_number(self, n: int) -> "ExcelReader":
+        self._head_row_number = n
+        return self
+
+    def sheet(self, sheet_no: Optional[int] = None, sheet_name: Optional[str] = None) -> "ExcelReader":
+        self._sheet_no = sheet_no
+        self._sheet_name = sheet_name
+        return self
+
+    # ---- 执行 ----
+
+    def _resolve_sheet(self, wb) -> List:
+        """返回要读取的工作表列表。"""
+        if self._sheet_name is not None:
+            if self._sheet_name not in wb.sheetnames:
+                raise ExcelReadError(f"工作表不存在: {self._sheet_name}")
+            return [wb[self._sheet_name]]
+        if self._sheet_no is not None:
+            if self._sheet_no >= len(wb.sheetnames):
+                raise ExcelReadError(f"工作表索引越界: {self._sheet_no}")
+            return [wb.worksheets[self._sheet_no]]
+        # 默认读所有 sheet
+        return list(wb.worksheets)
+
+    def _resolve_head_row_number(self, sheet_meta: ExcelSheet) -> int:
+        if self._head_row_number is not None:
+            return self._head_row_number
+        return sheet_meta.head_row_number
+
+    def _read_one_sheet(self, ws) -> List[Any]:
+        head_cls = self.head
+        if head_cls is None:
+            raise ExcelReadError("read 需指定 head 实体类")
+
+        sheet_meta = _get_class_sheet_meta(head_cls)
+        columns: List[ExcelColumnModel] = parse_excel_columns(head_cls)
+        head_row = self._resolve_head_row_number(sheet_meta)
+
+        # 读取表头行
+        max_col = ws.max_column or 0
+        max_row = ws.max_row or 0
+        if max_row < head_row:
+            return []
+        header_cells = [ws.cell(row=head_row, column=c).value for c in range(1, max_col + 1)]
+
+        # 列映射：列序号(1-based) -> ExcelColumnModel
+        col_mapping = self._map_columns(columns, header_cells)
+
+        # 判断是否走"按位置回退"（类无任何 ExcelProperty 注解）
+        used_positional = not _has_explicit_properties(head_cls)
+
+        results: List[Any] = []
+        for row_idx in range(head_row + 1, max_row + 1):
+            # 跳过全空行
+            row_values = [ws.cell(row=row_idx, column=c).value for c in range(1, max_col + 1)]
+            if all(v is None or v == "" for v in row_values):
+                continue
+            kwargs = {}
+            for col_idx, model in col_mapping.items():
+                cell_value = ws.cell(row=row_idx, column=col_idx).value
+                value = self._convert_from_cell(model, cell_value)
+                kwargs[model.attr_name] = value
+            # 位置回退：未映射的列按声明顺序补齐（仅当类无注解且字段数匹配时）
+            if used_positional:
+                # 已按位置映射，无需额外处理
+                pass
+            results.append(_build_instance(head_cls, kwargs))
+        return results
+
+    def _map_columns(self, columns: List[ExcelColumnModel], header_cells: List) -> dict:
+        """表头 -> 列模型映射。返回 {列序号(1-based): ExcelColumnModel}。"""
+        col_mapping: dict = {}
+        explicit = any(c.header for c in columns) and _has_explicit_properties(self.head)
+
+        if explicit:
+            # 按表头文案匹配
+            header_to_col = {}
+            for idx, h in enumerate(header_cells, start=1):
+                if h is None:
+                    continue
+                header_to_col.setdefault(str(h).strip(), idx)
+            for model in columns:
+                col_idx = header_to_col.get(model.header)
+                if col_idx is None:
+                    # 找不到对应表头，按声明顺序回退到下一个空位
+                    continue
+                col_mapping[col_idx] = model
+        else:
+            # 按列位置匹配（无注解或表头为空）
+            for offset, model in enumerate(columns):
+                col_idx = (model.index if model.index is not None else offset) + 1
+                col_mapping[col_idx] = model
+        return col_mapping
+
+    def _convert_from_cell(self, model: ExcelColumnModel, cell_value: Any) -> Any:
+        converter = resolve_converter(model.py_type, model.converter, model.date_format)
+        if converter is None:
+            return cell_value
+        try:
+            return converter.from_excel(cell_value)
+        except Exception as e:
+            raise ExcelReadError(
+                f"字段 '{model.attr_name}' 转换失败 (单元格值={cell_value!r}): {e}"
+            ) from e
+
+    def doRead(self) -> List[Any]:
+        """读取选定的工作表，返回实体列表。"""
+        openpyxl = _require_openpyxl()
+        wb = _load_workbook(self.source, openpyxl, read_only=False)
+        try:
+            sheets = self._resolve_sheet(wb)
+            if not sheets:
+                return []
+            return self._read_one_sheet(sheets[0])
+        finally:
+            try:
+                wb.close()
+            except Exception:
+                pass
+
+    def doReadAll(self) -> dict:
+        """读取所有工作表，返回 {sheet_name: [实体列表]}。"""
+        openpyxl = _require_openpyxl()
+        wb = _load_workbook(self.source, openpyxl, read_only=False)
+        try:
+            result = {}
+            for ws in wb.worksheets:
+                self._sheet_name = ws.title
+                result[ws.title] = self._read_one_sheet(ws)
+            return result
+        finally:
+            try:
+                wb.close()
+            except Exception:
+                pass
+
+
+def _has_explicit_properties(cls: Type) -> bool:
+    """类上是否声明了至少一个 ExcelProperty（用于决定按表头还是按位置匹配）。"""
+    for base in cls.__mro__:
+        for value in vars(base).values():
+            if isinstance(value, ExcelColumnModel):
+                continue
+            if isinstance(value, type):  # 跳过类属性中的类型
+                continue
+            if hasattr(value, "__excel_property__"):
+                return True
+            # ExcelProperty 实例作为类属性
+    # 再扫一次 ExcelProperty 实例
+    for base in cls.__mro__:
+        for value in vars(base).values():
+            if _is_excel_property(value):
+                return True
+    return False
+
+
+def _is_excel_property(value: Any) -> bool:
+    from .annotations import ExcelProperty
+    # 避免与 ExcelColumnModel 混淆
+    return isinstance(value, ExcelProperty)
+
+
+def _load_workbook(source: Any, openpyxl_module, read_only: bool = False):
+    """支持文件路径或类文件对象。"""
+    try:
+        if isinstance(source, (str, bytes)) or hasattr(source, "__fspath__"):
+            return openpyxl_module.load_workbook(filename=str(source), data_only=True, read_only=read_only)
+        # 类文件对象
+        return openpyxl_module.load_workbook(source, data_only=True, read_only=read_only)
+    except Exception as e:
+        raise ExcelReadError(f"加载 Excel 文件失败: {e}") from e
+
+
+__all__ = ["ExcelReader"]

spring/excel/style.py

@@ -0,0 +1,95 @@
+"""SpringBootAI Excel 默认样式 —— 轻量表头/内容样式（基于 openpyxl）。
+
+仅在 writer 实际写入时使用，且为可选项。样式名通过 ``@ExcelSheet(head_style=...)`` 或
+``@ExcelProperty(head_style=...)`` 指定；未指定时使用 ``DEFAULT_HEAD``。
+
+设计克制：不提供复杂主题系统，仅给出一个加粗居中、带边框和浅色填充的默认表头样式，
+以及一个带边框的默认内容样式，满足"功能齐全"的同时避免过度设计。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+# 样式缓存：同名样式复用同一 openpyxl 对象（openpyxl 要求相同样式复用以免撑大文件）
+_STYLE_CACHE: Dict[str, Dict[str, Any]] = {}
+
+
+def _require_openpyxl():
+    try:
+        import openpyxl  # noqa: F401
+        from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+        return Font, PatternFill, Alignment, Border, Side
+    except ImportError as e:  # pragma: no cover - 依赖检测由上层统一处理
+        raise e
+
+
+def get_head_style(name: str = "default"):
+    """获取表头样式对象（带缓存）。"""
+    from .exceptions import ExcelDependencyError
+    try:
+        Font, PatternFill, Alignment, Border, Side = _require_openpyxl()
+    except ImportError:
+        raise ExcelDependencyError(
+            "Excel 写入依赖 openpyxl，请先安装：pip install springbootAI[excel]"
+        )
+    key = f"head::{name}"
+    if key in _STYLE_CACHE:
+        return _STYLE_CACHE[key]
+    thin = Side(style="thin", color="BFBFBF")
+    border = Border(left=thin, right=thin, top=thin, bottom=thin)
+    style = {
+        "font": Font(bold=True, color="FFFFFF", size=11),
+        "fill": PatternFill("solid", fgColor="4472C4"),
+        "alignment": Alignment(horizontal="center", vertical="center", wrap_text=True),
+        "border": border,
+    }
+    _STYLE_CACHE[key] = style
+    return style
+
+
+def get_content_style(name: str = "default"):
+    """获取内容样式对象（带缓存）。"""
+    from .exceptions import ExcelDependencyError
+    try:
+        Font, PatternFill, Alignment, Border, Side = _require_openpyxl()
+    except ImportError:
+        raise ExcelDependencyError(
+            "Excel 写入依赖 openpyxl，请先安装：pip install springbootAI[excel]"
+        )
+    key = f"content::{name}"
+    if key in _STYLE_CACHE:
+        return _STYLE_CACHE[key]
+    thin = Side(style="thin", color="D9D9D9")
+    border = Border(left=thin, right=thin, top=thin, bottom=thin)
+    style = {
+        "font": Font(size=11),
+        "alignment": Alignment(vertical="center", wrap_text=False),
+        "border": border,
+    }
+    _STYLE_CACHE[key] = style
+    return style
+
+
+def apply_head_style(cell, name: str = "default") -> None:
+    """把表头样式应用到单元格。"""
+    style = get_head_style(name)
+    cell.font = style["font"]
+    cell.fill = style["fill"]
+    cell.alignment = style["alignment"]
+    cell.border = style["border"]
+
+
+def apply_content_style(cell, name: str = "default") -> None:
+    """把内容样式应用到单元格。"""
+    style = get_content_style(name)
+    cell.font = style["font"]
+    cell.alignment = style["alignment"]
+    cell.border = style["border"]
+
+
+__all__ = [
+    "get_head_style",
+    "get_content_style",
+    "apply_head_style",
+    "apply_content_style",
+]

spring/excel/writer.py

@@ -0,0 +1,197 @@
+"""SpringBootAI Excel 写入引擎。
+
+按 ``@ExcelProperty`` / ``@ExcelIgnore`` / ``@excel_sheet`` 注解把实体对象列表写入 Excel。
+底层依赖 openpyxl（仅 ``doWrite`` 时检测，注解声明无需安装）。
+
+写入流程对齐 alibaba EasyExcel：
+    1. 按列模型排序写表头行（默认带样式）。
+    2. 逐行按 ``converter.to_excel`` 转换并写单元格；应用数字格式、大数字防丢精度。
+    3. 冻结表头、自适应列宽（可配置）。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Type
+
+from .annotations import (
+    ExcelColumnModel, ExcelSheet, _get_class_sheet_meta, parse_excel_columns,
+)
+from .converters import resolve_converter
+from .exceptions import ExcelDependencyError, ExcelWriteError
+
+# Excel 有效数字位数上限为 15 位，超过即丢精度；长 ID/大数字按字符串写入
+_EXCEL_MAX_SIGNIFICANT_DIGITS = 15
+
+
+def _require_openpyxl():
+    try:
+        import openpyxl
+        return openpyxl
+    except ImportError as e:
+        raise ExcelDependencyError(
+            "Excel 写入依赖 openpyxl，请先安装：pip install springbootAI[excel]"
+        ) from e
+
+
+def _get_value(item: Any, attr_name: str) -> Any:
+    """从实体对象或 dict 取字段值。"""
+    if isinstance(item, dict):
+        return item.get(attr_name)
+    return getattr(item, attr_name, None)
+
+
+def _is_large_int(value: Any) -> bool:
+    """是否为会丢精度的长整数（>15 位有效数字）。"""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return len(str(abs(value))) > _EXCEL_MAX_SIGNIFICANT_DIGITS
+    return False
+
+
+class ExcelWriter:
+    """Excel 写入器。由 ``EasyExcel.write(...)`` 构建，调用 ``doWrite`` 执行。"""
+
+    def __init__(
+        self,
+        target: Any,
+        head: Optional[Type] = None,
+        sheet_name: Optional[str] = None,
+    ):
+        self.target = target
+        self.head = head
+        self._sheet_name = sheet_name
+        self._in_memory: bool = False
+
+    # ---- 流式配置 ----
+
+    def sheet(self, sheet_name: str = "Sheet1") -> "ExcelWriter":
+        self._sheet_name = sheet_name
+        return self
+
+    def in_memory(self, flag: bool = True) -> "ExcelWriter":
+        """写入内存 Workbook（用于随后取 workbook 对象，而非落盘）。"""
+        self._in_memory = flag
+        return self
+
+    # ---- 执行 ----
+
+    def doWrite(self, data: Iterable[Any]) -> Any:
+        """写入单个工作表并保存到 ``target``。返回目标路径或内存 workbook。"""
+        openpyxl = _require_openpyxl()
+        if self.head is None:
+            raise ExcelWriteError("write 需指定 head 实体类")
+        wb = openpyxl.Workbook()
+        # 移除默认空 Sheet
+        default_ws = wb.active
+        sheet_name = self._sheet_name or _get_class_sheet_meta(self.head).sheet_name or "Sheet1"
+        ws = wb.create_sheet(title=sheet_name)
+        wb.remove(default_ws)
+        self._write_sheet(ws, self.head, list(data))
+        return self._save(wb)
+
+    def doWriteAll(self, sheets: Dict[str, Iterable[Any]], head: Optional[Type] = None) -> Any:
+        """写入多个工作表。``sheets`` 为 {sheet_name: data_list}，所有 sheet 共用同一 head。"""
+        openpyxl = _require_openpyxl()
+        head_cls = head or self.head
+        if head_cls is None:
+            raise ExcelWriteError("doWriteAll 需指定 head 实体类")
+        wb = openpyxl.Workbook()
+        default_ws = wb.active
+        for sheet_name, data in sheets.items():
+            ws = wb.create_sheet(title=sheet_name)
+            self._write_sheet(ws, head_cls, list(data))
+        wb.remove(default_ws)
+        return self._save(wb)
+
+    # ---- 内部 ----
+
+    def _write_sheet(self, ws, head_cls: Type, data: List[Any]) -> None:
+        from .style import apply_content_style, apply_head_style
+
+        sheet_meta = _get_class_sheet_meta(head_cls)
+        columns: List[ExcelColumnModel] = parse_excel_columns(head_cls)
+        head_row = sheet_meta.head_row_number
+
+        # 1. 表头
+        for offset, model in enumerate(columns):
+            col_idx = offset + 1
+            cell = ws.cell(row=head_row, column=col_idx, value=model.header)
+            apply_head_style(cell, model.head_style or sheet_meta.head_style or "default")
+
+        # 2. 数据行
+        max_lengths = {m.attr_name: len(str(m.header)) for m in columns}
+        for row_offset, item in enumerate(data, start=1):
+            row_idx = head_row + row_offset
+            for offset, model in enumerate(columns):
+                col_idx = offset + 1
+                raw = _get_value(item, model.attr_name)
+                cell_value, as_string = self._convert_to_cell(model, raw)
+                cell = ws.cell(row=row_idx, column=col_idx, value=cell_value)
+                apply_content_style(cell, model.content_style or sheet_meta.content_style or "default")
+                # 数字格式（仅对数值单元格生效）
+                if model.num_format and not as_string and isinstance(cell_value, (int, float)):
+                    cell.number_format = model.num_format
+                # 统计列宽
+                display_len = len(str(cell_value)) if cell_value is not None else 0
+                if display_len > max_lengths[model.attr_name]:
+                    max_lengths[model.attr_name] = display_len
+
+        # 3. 冻结表头
+        if sheet_meta.freeze_head:
+            ws.freeze_panes = ws.cell(row=head_row + 1, column=1)
+
+        # 4. 列宽
+        self._apply_column_width(ws, columns, max_lengths, sheet_meta)
+
+    def _convert_to_cell(self, model: ExcelColumnModel, raw: Any):
+        """Python 值 -> (单元格值, 是否强制字符串)。"""
+        converter = resolve_converter(model.py_type, model.converter, model.date_format)
+        if converter is not None:
+            try:
+                converted = converter.to_excel(raw)
+            except Exception as e:
+                raise ExcelWriteError(
+                    f"字段 '{model.attr_name}' 转换失败 (值={raw!r}): {e}"
+                ) from e
+            as_string = isinstance(converted, str)
+            return converted, as_string
+        # 无转换器：按规则处理
+        if raw is None:
+            return None, False
+        if model.big_number or _is_large_int(raw):
+            return str(raw), True
+        return raw, False
+
+    def _apply_column_width(self, ws, columns: List[ExcelColumnModel],
+                            max_lengths: dict, sheet_meta: ExcelSheet) -> None:
+        for offset, model in enumerate(columns):
+            col_idx = offset + 1
+            col_letter = ws.cell(row=1, column=col_idx).column_letter
+            if model.width and model.width > 0:
+                ws.column_dimensions[col_letter].width = float(model.width)
+            elif sheet_meta.auto_width:
+                # 自适应：max(表头/内容长度) + 2 余量，上限 60
+                ws.column_dimensions[col_letter].width = min(max(max_lengths[model.attr_name] + 2, 10), 60)
+
+    def _save(self, wb) -> Any:
+        target = self.target
+        if self._in_memory:
+            return wb
+        try:
+            if isinstance(target, (str, bytes)) or hasattr(target, "__fspath__"):
+                wb.save(filename=str(target))
+                return target
+            # 类文件对象
+            wb.save(target)
+            return target
+        except Exception as e:
+            raise ExcelWriteError(f"保存 Excel 文件失败: {e}") from e
+        finally:
+            try:
+                if not self._in_memory:
+                    wb.close()
+            except Exception:
+                pass
+
+
+__all__ = ["ExcelWriter"]