Archived
105 lines
2.7 KiB
Markdown
105 lines
2.7 KiB
Markdown
# Docx Export API
|
|
|
|
导出 Word 文档（.docx）接口。支持通过模板 ID 选择模板，将占位符替换为业务数据后，以流式方式返回文件。
|
|
|
|
---
|
|
|
|
## `POST /api/docx/export`
|
|
|
|
### Request
|
|
|
|
**Content-Type:** `application/json`
|
|
|
|
```json
|
|
{
|
|
"exportId": "string (必填) - 模板标识",
|
|
"businessData": "object (必填) - 业务数据键值对"
|
|
}
|
|
```
|
|
|
|
#### 字段说明
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `exportId` | `String` | 是 | 模板标识，例如 `"annualReport"` |
|
|
| `businessData` | `Map<String, Object>` | 是 | 用于填充模板的变量数据，目前由模板自行定义默认值 |
|
|
|
|
#### 示例
|
|
|
|
```bash
|
|
curl -OJ -X POST http://localhost:6666/api/docx/export \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"exportId": "annualReport",
|
|
"businessData": {}
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
### Response
|
|
|
|
#### 成功 (HTTP 200)
|
|
|
|
直接流式下载 `.docx` 文件。
|
|
|
|
| Header | 值 |
|
|
|--------|----|
|
|
| `Content-Type` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
|
|
| `Content-Disposition` | `attachment; filename="<模板文件名>.docx"` |
|
|
|
|
客户端收到文件流，可保存到本地或直接打开。
|
|
|
|
**curl 示例输出:**
|
|
```
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
|
|
Content-Disposition: attachment; filename="annualReport.docx"
|
|
|
|
<binary docx data streamed>
|
|
```
|
|
|
|
#### 参数校验失败 (HTTP 400)
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"msg": "exportId 不能为空; businessData 不能为空"
|
|
}
|
|
```
|
|
|
|
可能的原因:
|
|
- `exportId` 为空或空白字符串
|
|
- `businessData` 为 `null`（注意：传 `"businessData": ""` 或 `"businessData": 123` 属于类型错误，Spring 会直接返回默认 400 错误）
|
|
|
|
#### 模板不存在 (HTTP 404)
|
|
|
|
```json
|
|
{
|
|
"code": 404,
|
|
"msg": "模板不存在: <exportId>"
|
|
}
|
|
```
|
|
|
|
#### 服务器内部错误 (HTTP 500)
|
|
|
|
文档生成过程中发生异常时返回。
|
|
|
|
---
|
|
|
|
### 可用模板
|
|
|
|
| exportId | 文件名 | 说明 |
|
|
|----------|--------|------|
|
|
| `annualReport` | `annualReport.docx` | 年度工作报告，包含标题、公司信息、数据表格 |
|
|
|
|
模板存储在 `src/main/resources/templates/` 目录下，为标准的 `.docx` 文件。模板中使用 `${variableName}` 语法标记占位符，服务端在生成时替换为实际数据。
|
|
|
|
---
|
|
|
|
### 设计要点
|
|
|
|
1. **流式输出**: 使用 Spring `StreamingResponseBody`，文档生成过程直接写入 HTTP 响应流，不经过内存缓冲，适合大文件。
|
|
2. **前置校验**: 所有参数校验（`@Valid`、模板存在性检查）在流开始前完成，出错时返回 JSON 错误响应，与正常文件流互不干扰。
|
|
3. **Git LFS**: 模板文件（`.docx`）通过 Git LFS 管理，仓库只存指针。
|