调整Excel导出时使用的方法

docs/excel.md

@@ -15,29 +15,24 @@ Excel导出工具提供了将数据导出到Excel文件的功能，支持结构
 - **表头样式**：自动应用表头样式（加粗、背景色等）
 - **智能工作表管理**：自动处理工作表的创建和删除，避免产生空sheet
 - **ExportData接口**：支持实现ExportData接口进行高级定制
+- **空数据处理**：即使数据为空（nil或空切片），也会正常生成表头
+- **统一接口**：只暴露 `ExportToWriter` 一个核心方法
 
 ## 使用方法
 
-### 1. 创建工厂（推荐）
+### 1. 创建工厂
 
 ```go
 import "git.toowon.com/jimmy/go-common/factory"
 
-// 方式1：从配置文件创建（推荐）
+// 从配置文件创建
 fac, err := factory.NewFactoryFromFile("./config.json")
-if err != nil {
-    log.Fatal(err)
-}
 
-// 方式2：从配置对象创建
-cfg, _ := config.LoadFromFile("./config.json")
-fac := factory.NewFactory(cfg)
-
-// 方式3：Excel导出不需要配置，可以传nil
+// 或Excel导出不需要配置，可以传nil
 fac := factory.NewFactory(nil)
 ```
 
-### 2. 导出结构体切片到文件（黑盒模式，推荐）
+### 2. 导出结构体切片到文件
 
 ```go
 // 定义结构体
@@ -71,7 +66,7 @@ if err != nil {
 }
 ```
 
-### 3. 导出到HTTP响应（黑盒模式，推荐）
+### 3. 导出到HTTP响应
 
 ```go
 import "net/http"
@@ -103,7 +98,7 @@ func exportUsersHandler(w http.ResponseWriter, r *http.Request) {
 }
 ```
 
-### 4. 使用格式化函数（黑盒模式，推荐）
+### 4. 使用格式化函数
 
 ```go
 import "git.toowon.com/jimmy/go-common/excel"
@@ -202,7 +197,7 @@ file.SetCellStyle("Sheet2", "A1", "A1", style)
 
 ## API 参考
 
-### 工厂方法（黑盒模式，推荐使用）
+### 工厂方法
 
 #### ExportToExcel(w io.Writer, sheetName string, columns []ExportColumn, data interface{}) error
 
@@ -216,19 +211,19 @@ file.SetCellStyle("Sheet2", "A1", "A1", style)
 
 **返回：** 错误信息
 
+**数据为空处理：**
+- 支持 `nil`、空切片、指针类型等空数据情况
+- 即使数据为空，表头也会正常生成
+
 **工作表处理逻辑：**
-- 如果 `sheetName` 为空或未指定，默认使用 "Sheet1"
-- 如果指定的工作表已存在，直接使用该工作表
-- 如果指定的工作表不存在，会自动创建新工作表
-- 如果使用自定义名称（非"Sheet1"），会自动删除默认的"Sheet1"工作表，避免产生空sheet
+- 如果 `sheetName` 为空，默认使用 "Sheet1"
+- 如果指定的工作表不存在，会自动创建
+- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet
 
 **示例：**
 ```go
-// 使用默认Sheet1
-fac.ExportToExcel(w, "", columns, users)
-
-// 使用自定义工作表名称
 fac.ExportToExcel(w, "用户列表", columns, users)
+fac.ExportToExcel(w, "空数据", columns, []User{}) // 空数据也会生成表头
 ```
 
 #### ExportToExcelFile(filePath string, sheetName string, columns []ExportColumn, data interface{}) error
@@ -239,23 +234,23 @@ fac.ExportToExcel(w, "用户列表", columns, users)
 - `filePath`: 文件路径
 - `sheetName`: 工作表名称（可选，默认为"Sheet1"）
 - `columns`: 列定义
-- `data`: 数据列表
+- `data`: 数据列表（可以是结构体切片或实现了ExportData接口的对象）
 
 **返回：** 错误信息
 
+**实现说明：**
+- 此方法内部创建文件并调用 `ExportToWriter`
+- 文件相关的封装由工厂方法处理
+
 **工作表处理逻辑：**
-- 如果 `sheetName` 为空或未指定，默认使用 "Sheet1"
-- 如果指定的工作表已存在，直接使用该工作表
-- 如果指定的工作表不存在，会自动创建新工作表
-- 如果使用自定义名称（非"Sheet1"），会自动删除默认的"Sheet1"工作表，避免产生空sheet
+- 如果 `sheetName` 为空，默认使用 "Sheet1"
+- 如果指定的工作表不存在，会自动创建
+- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet
 
 **示例：**
 ```go
-// 使用默认Sheet1
-fac.ExportToExcelFile("users.xlsx", "", columns, users)
-
-// 使用自定义工作表名称
 fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
+fac.ExportToExcelFile("empty.xlsx", "空数据", columns, []User{}) // 空数据也会生成表头
 ```
 
 ### 高级方法
@@ -266,9 +261,7 @@ fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
 
 **返回：** Excel导出器对象和错误信息
 
-**说明：** 
-- 仅在需要使用高级功能时使用
-- 推荐使用黑盒方法：`ExportToExcel()`、`ExportToExcelFile()`
+**说明：** 仅在需要使用高级功能时使用，推荐使用黑盒方法
 
 ### 结构体类型
 
@@ -304,8 +297,6 @@ type ExportColumn struct {
 
 **说明：** 
 - 允许直接使用tools包的任何格式化函数
-- 推荐使用此适配器，避免重复实现格式化逻辑
-- 与factory中的FormatDateTime等方法保持一致
 
 **示例：**
 ```go
@@ -419,39 +410,36 @@ func main() {
 
 ## 设计优势
 
-### 优势总结
-
 1. **降低复杂度**：调用方无需关心Excel文件对象的创建和管理
-2. **延迟初始化**：Excel导出器在首次使用时才创建，提高性能
-3. **统一接口**：所有操作通过工厂方法调用，接口统一
+2. **延迟初始化**：Excel导出器在首次使用时才创建
+3. **统一接口**：所有操作通过工厂方法调用
 4. **灵活扩展**：支持结构体切片、自定义格式化、ExportData接口等多种方式
 5. **自动优化**：自动调整列宽、应用表头样式等
 
 ## 注意事项
 
-1. **配置检查**：Excel导出不需要配置，可以传nil创建工厂
+1. **配置**：Excel导出不需要配置，可以传nil创建工厂
 2. **错误处理**：所有方法都可能返回错误，需要正确处理
 3. **延迟初始化**：Excel导出器在首次使用时才创建，首次调用可能稍慢
 4. **字段名匹配**：Field字段名必须与结构体字段名匹配（区分大小写）
 5. **嵌套字段**：支持嵌套字段访问（如 "User.Name"），但需要确保字段路径正确
 6. **格式化函数**：格式化函数返回的字符串会直接写入Excel单元格
 7. **列宽设置**：Width为0时会自动调整列宽，但可能影响性能（大数据量时建议设置固定宽度）
-8. **工作表处理**：
-   - 使用默认"Sheet1"时，会直接使用默认工作表，不会产生空sheet
-   - 使用自定义工作表名称时，会自动删除默认的"Sheet1"，确保文件只有一个工作表
-   - 如果指定的工作表已存在，会直接使用，不会重复创建
+8. **工作表处理**：工具会自动处理工作表的创建和删除，确保不会产生空sheet
+9. **空数据处理**：即使数据为 `nil` 或空切片，表头也会正常生成
+10. **方法设计**：
+    - `excel` 包只暴露 `ExportToWriter` 一个核心方法
+    - 文件相关的封装由工厂方法 `ExportToExcelFile` 处理
 
 ## 最佳实践
 
-1. **使用黑盒方法**：推荐使用 `ExportToExcel()` 和 `ExportToExcelFile()`，无需获取Excel对象
+1. **使用工厂方法**：推荐使用 `ExportToExcel()` 和 `ExportToExcelFile()`
 2. **设置列宽**：对于大数据量，建议设置固定列宽以提高性能
 3. **使用格式化函数**：对于日期时间、状态等字段，使用格式化函数提高可读性
 4. **错误处理**：始终检查导出方法的返回值
 5. **HTTP响应**：导出到HTTP响应时，记得设置正确的Content-Type和Content-Disposition头
-6. **工作表命名**：
-   - 推荐使用有意义的工作表名称（如"用户列表"、"订单数据"等），提高可读性
-   - 如果不指定工作表名称，会使用默认的"Sheet1"
-   - 工具会自动处理工作表的创建和删除，确保不会产生空sheet
+6. **工作表命名**：推荐使用有意义的工作表名称，工具会自动处理工作表的创建和删除
+7. **空数据场景**：即使查询结果为空，也可以导出包含表头的Excel文件
 
 ## 示例