126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
# Report Generator 报告生成工具
|
||
|
||
通用的文档模板处理和报告生成工具，支持Word文档的动态内容生成。
|
||
|
||
## 功能特性
|
||
|
||
### 1. 基础功能
|
||
- ✅ 占位符替换 (`${key}` 格式)
|
||
- ✅ Word文档处理 (基于Apache POI)
|
||
- ✅ 模板文件管理
|
||
- ✅ 多种输入输出方式 (文件路径、流、字节数组)
|
||
|
||
### 2. 高级功能
|
||
- ✅ 书签定位插入 (基于docx4j)
|
||
- ✅ 动态表格生成
|
||
- ✅ 文档合并
|
||
- ✅ 样式管理 (字体、颜色、对齐)
|
||
- ✅ 自动分页控制
|
||
- ✅ 深拷贝支持
|
||
|
||
### 3. 扩展功能
|
||
- 🔄 自定义处理器插件化
|
||
- 🔄 复杂表达式支持
|
||
- 🔄 模板验证
|
||
- 🔄 缓存优化
|
||
|
||
## 架构设计
|
||
|
||
```
|
||
report-generator/
|
||
├── controller/ # HTTP接口层
|
||
├── service/ # 业务逻辑层
|
||
├── engine/ # 模板引擎核心
|
||
│ ├── DocumentProcessor # 文档处理器接口
|
||
│ ├── WordEngine # Word处理引擎
|
||
│ ├── PlaceholderEngine # 占位符处理引擎
|
||
│ └── BookmarkEngine # 书签处理引擎
|
||
├── model/ # 数据模型
|
||
│ ├── TemplateRequest # 处理请求模型
|
||
│ ├── TemplateSource # 模板源定义
|
||
│ └── ProcessResult # 处理结果
|
||
├── util/ # 工具类
|
||
└── exception/ # 异常处理
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 1. HTTP接口方式
|
||
|
||
```bash
|
||
# 简单占位符替换
|
||
POST /api/report/process
|
||
Content-Type: multipart/form-data
|
||
|
||
{
|
||
"templateFile": <template.docx>,
|
||
"data": {
|
||
"name": "张三",
|
||
"date": "2024-01-01",
|
||
"amount": "1000.00"
|
||
},
|
||
"outputFileName": "report.docx"
|
||
}
|
||
```
|
||
|
||
### 2. Java API方式
|
||
|
||
```java
|
||
// 注入服务
|
||
@Autowired
|
||
private ReportGeneratorService reportService;
|
||
|
||
// 创建请求
|
||
TemplateRequest request = TemplateRequest.builder()
|
||
.templatePath("template.docx")
|
||
.data(Map.of("name", "张三", "date", "2024-01-01"))
|
||
.outputPath("result.docx")
|
||
.options(ProcessOptions.builder()
|
||
.enablePlaceholder(true)
|
||
.enableBookmark(true)
|
||
.build())
|
||
.build();
|
||
|
||
// 处理模板
|
||
ProcessResult result = reportService.processTemplate(request);
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 处理选项 (ProcessOptions)
|
||
```java
|
||
ProcessOptions options = ProcessOptions.builder()
|
||
.enablePlaceholder(true) // 启用占位符替换
|
||
.enableBookmark(true) // 启用书签处理
|
||
.enableDynamicTable(true) // 启用动态表格
|
||
.enableAutoPage(true) // 启用自动分页
|
||
.placeholderPattern("${}") // 占位符格式
|
||
.build();
|
||
```
|
||
|
||
### 模板源配置 (TemplateSource)
|
||
```java
|
||
// 文件路径方式
|
||
TemplateSource.fromFile("path/to/template.docx")
|
||
|
||
// 输入流方式
|
||
TemplateSource.fromStream(inputStream)
|
||
|
||
// 字节数组方式
|
||
TemplateSource.fromBytes(byteArray)
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **Apache POI**: Word文档基础操作
|
||
- **docx4j**: 高级Word文档处理
|
||
- **Spring Boot**: 框架支持
|
||
- **Hutool**: 工具库
|
||
- **Jackson**: JSON处理
|
||
|
||
## 性能优化
|
||
|
||
1. **模板缓存**: 常用模板缓存减少IO
|
||
2. **流式处理**: 大文件流式处理避免内存溢出
|
||
3. **异步处理**: 支持异步批量处理
|
||
4. **资源管理**: 自动资源清理和释放 |