469 lines
12 KiB
Markdown
469 lines
12 KiB
Markdown
# 腾讯文档 API 数据格式解析说明
|
||
|
||
## 问题发现
|
||
|
||
在实际调用腾讯文档 V3 API 时，发现返回的数据格式与预期完全不同。
|
||
|
||
---
|
||
|
||
## 数据格式对比
|
||
|
||
### ❌ 我们最初预期的格式（简单格式）
|
||
|
||
```json
|
||
{
|
||
"values": [
|
||
["单元格1", "单元格2", "单元格3"],
|
||
["数据1", "数据2", "数据3"]
|
||
]
|
||
}
|
||
```
|
||
|
||
### ✅ 实际返回的格式（gridData 格式）
|
||
|
||
```json
|
||
{
|
||
"gridData": {
|
||
"startRow": 0,
|
||
"startColumn": 0,
|
||
"rows": [
|
||
{
|
||
"values": [
|
||
{
|
||
"cellValue": {
|
||
"text": "JY202506181808"
|
||
},
|
||
"cellFormat": {
|
||
"textFormat": {
|
||
"font": "Microsoft YaHei",
|
||
"fontSize": 11,
|
||
"bold": false,
|
||
"italic": false,
|
||
"strikethrough": false,
|
||
"underline": false,
|
||
"color": {
|
||
"red": 0,
|
||
"green": 0,
|
||
"blue": 0,
|
||
"alpha": 255
|
||
}
|
||
},
|
||
"horizontalAlignment": "HORIZONTAL_ALIGNMENT_UNSPECIFIED",
|
||
"verticalAlignment": "VERTICAL_ALIGNMENT_UNSPECIFIED"
|
||
},
|
||
"dataType": "DATA_TYPE_UNSPECIFIED"
|
||
},
|
||
{
|
||
"cellValue": {
|
||
"text": ""
|
||
},
|
||
...
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"rowMetadata": [],
|
||
"columnMetadata": []
|
||
},
|
||
"version": "0"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 格式差异分析
|
||
|
||
### 数据层级
|
||
|
||
**简单格式**：
|
||
```
|
||
响应
|
||
└── values (数组)
|
||
├── 行1 (数组)
|
||
│ ├── "单元格1"
|
||
│ └── "单元格2"
|
||
└── 行2 (数组)
|
||
├── "数据1"
|
||
└── "数据2"
|
||
```
|
||
|
||
**gridData 格式**：
|
||
```
|
||
响应
|
||
└── gridData (对象)
|
||
├── startRow (数字)
|
||
├── startColumn (数字)
|
||
├── rows (数组)
|
||
│ └── 行对象
|
||
│ └── values (数组)
|
||
│ └── 单元格对象
|
||
│ ├── cellValue (对象)
|
||
│ │ └── text (字符串) ← 实际文本内容在这里
|
||
│ ├── cellFormat (对象)
|
||
│ └── dataType (字符串)
|
||
├── rowMetadata (数组)
|
||
└── columnMetadata (数组)
|
||
```
|
||
|
||
### 关键区别
|
||
|
||
| 项目 | 简单格式 | gridData 格式 |
|
||
|------|---------|--------------|
|
||
| 根字段 | `values` | `gridData` |
|
||
| 行数据 | 直接数组 | 在 `gridData.rows` 中 |
|
||
| 单元格数据 | 直接字符串 | 在 `cellValue.text` 中 |
|
||
| 格式信息 | 无 | 在 `cellFormat` 中 |
|
||
| 元数据 | 无 | 在 `rowMetadata`、`columnMetadata` 中 |
|
||
|
||
---
|
||
|
||
## 解决方案
|
||
|
||
### 1. 创建数据解析器
|
||
|
||
我们创建了 `TencentDocDataParser` 工具类来统一处理两种格式：
|
||
|
||
**位置**：`ruoyi-system/src/main/java/com/ruoyi/jarvis/util/TencentDocDataParser.java`
|
||
|
||
**核心功能**：
|
||
|
||
#### (1) 解析为简单数组格式
|
||
```java
|
||
JSONArray parsedValues = TencentDocDataParser.parseToSimpleArray(apiResponse);
|
||
```
|
||
|
||
**输入**（gridData 格式）：
|
||
```json
|
||
{
|
||
"gridData": {
|
||
"rows": [
|
||
{
|
||
"values": [
|
||
{"cellValue": {"text": "单元格1"}},
|
||
{"cellValue": {"text": "单元格2"}}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**输出**（简单格式）：
|
||
```json
|
||
[
|
||
["单元格1", "单元格2"]
|
||
]
|
||
```
|
||
|
||
#### (2) 获取指定行数据
|
||
```java
|
||
JSONArray row = TencentDocDataParser.getRow(apiResponse, 0); // 获取第1行
|
||
```
|
||
|
||
#### (3) 获取指定单元格文本
|
||
```java
|
||
String cellText = TencentDocDataParser.getCellText(apiResponse, 0, 2); // 第1行第3列
|
||
```
|
||
|
||
#### (4) 打印数据结构（调试用）
|
||
```java
|
||
TencentDocDataParser.printDataStructure(apiResponse, 5); // 打印前5行
|
||
```
|
||
|
||
### 2. 更新 Service 层
|
||
|
||
在 `TencentDocServiceImpl.java` 的 `readSheetData` 方法中：
|
||
|
||
```java
|
||
// API 调用
|
||
JSONObject result = TencentDocApiUtil.readSheetData(...);
|
||
|
||
// 解析数据为统一的简单格式
|
||
JSONArray parsedValues = TencentDocDataParser.parseToSimpleArray(result);
|
||
|
||
// 返回包含简化格式的响应
|
||
JSONObject response = new JSONObject();
|
||
response.put("values", parsedValues); // 统一格式
|
||
response.put("_原始数据", result); // 保留原始数据供调试
|
||
|
||
return response;
|
||
```
|
||
|
||
### 3. 向后兼容性
|
||
|
||
解析器会自动检测数据格式：
|
||
- 如果有 `gridData` 字段 → 解析为 gridData 格式
|
||
- 如果有 `values` 字段 → 直接返回（简单格式）
|
||
- 如果都没有 → 返回空数组
|
||
|
||
```java
|
||
public static JSONArray parseToSimpleArray(JSONObject apiResponse) {
|
||
// 方式1：检查是否有 gridData 字段（V3 API 新格式）
|
||
JSONObject gridData = apiResponse.getJSONObject("gridData");
|
||
if (gridData != null) {
|
||
return parseGridData(gridData);
|
||
}
|
||
|
||
// 方式2：检查是否有 values 字段（简单格式）
|
||
JSONArray values = apiResponse.getJSONArray("values");
|
||
if (values != null) {
|
||
return values;
|
||
}
|
||
|
||
// 如果都没有，返回空数组
|
||
return new JSONArray();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1：读取表头
|
||
|
||
```java
|
||
// 读取第2行（索引为1）作为表头
|
||
String headerRange = "A2:Z2";
|
||
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, headerRange);
|
||
|
||
// 获取简化后的数据
|
||
JSONArray headerValues = headerData.getJSONArray("values");
|
||
if (headerValues != null && !headerValues.isEmpty()) {
|
||
JSONArray headerRow = headerValues.getJSONArray(0); // 第一行数据
|
||
|
||
// 遍历表头列
|
||
for (int i = 0; i < headerRow.size(); i++) {
|
||
String columnName = headerRow.getString(i);
|
||
System.out.println("第 " + (i+1) + " 列: " + columnName);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 示例 2：查找特定列
|
||
|
||
```java
|
||
// 读取表头行
|
||
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A2:Z2");
|
||
JSONArray headerValues = headerData.getJSONArray("values");
|
||
JSONArray headerRow = headerValues.getJSONArray(0);
|
||
|
||
// 查找"物流单号"列的索引
|
||
int logisticsColumn = -1;
|
||
for (int i = 0; i < headerRow.size(); i++) {
|
||
String columnName = headerRow.getString(i);
|
||
if ("物流单号".equals(columnName)) {
|
||
logisticsColumn = i;
|
||
break;
|
||
}
|
||
}
|
||
|
||
System.out.println("物流单号列在第 " + (logisticsColumn + 1) + " 列（索引: " + logisticsColumn + "）");
|
||
```
|
||
|
||
### 示例 3：读取数据行
|
||
|
||
```java
|
||
// 读取数据行（第3行到第100行）
|
||
JSONObject sheetData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A3:Z100");
|
||
JSONArray dataValues = sheetData.getJSONArray("values");
|
||
|
||
// 遍历每一行
|
||
for (int i = 0; i < dataValues.size(); i++) {
|
||
JSONArray row = dataValues.getJSONArray(i);
|
||
|
||
// 获取订单号（假设在第1列，索引0）
|
||
String orderNo = row.getString(0);
|
||
|
||
// 获取物流单号（假设在第13列，索引12）
|
||
String logisticsNo = row.getString(12);
|
||
|
||
System.out.println("订单号: " + orderNo + ", 物流单号: " + logisticsNo);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 真实数据示例
|
||
|
||
根据用户提供的截图，表格结构：
|
||
|
||
```
|
||
第1行：合并单元格，包含链接（这是合并的标题行）
|
||
第2行：表头
|
||
A列：日期
|
||
B列：公司
|
||
C列：草号
|
||
D列：型号
|
||
E列：数量
|
||
F列：姓名
|
||
G列：电话
|
||
H列：地址
|
||
I列：价格
|
||
J列：备注
|
||
K列：打聚戳图
|
||
L列：是否安排
|
||
M列：物流单号
|
||
N列：标记
|
||
|
||
第3行及以后：数据行
|
||
A列：3月10日
|
||
B列：（空）
|
||
C列：JY20251032904
|
||
...
|
||
M列：（物流单号，可能为空）
|
||
```
|
||
|
||
### 处理代码示例
|
||
|
||
```java
|
||
// 1. 读取表头（第2行）
|
||
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A2:Z2");
|
||
JSONArray headerValues = headerData.getJSONArray("values");
|
||
JSONArray headerRow = headerValues.getJSONArray(0);
|
||
|
||
// 2. 查找关键列的索引
|
||
int orderNoColumn = -1; // 订单号列（草号）
|
||
int logisticsColumn = -1; // 物流单号列
|
||
|
||
for (int i = 0; i < headerRow.size(); i++) {
|
||
String columnName = headerRow.getString(i);
|
||
if (columnName != null) {
|
||
if (columnName.contains("草号")) {
|
||
orderNoColumn = i;
|
||
}
|
||
if (columnName.contains("物流单号")) {
|
||
logisticsColumn = i;
|
||
}
|
||
}
|
||
}
|
||
|
||
System.out.println("订单号列索引: " + orderNoColumn); // 预期: 2（C列）
|
||
System.out.println("物流单号列索引: " + logisticsColumn); // 预期: 12（M列）
|
||
|
||
// 3. 读取数据行（从第3行开始）
|
||
JSONObject sheetData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A3:Z100");
|
||
JSONArray dataValues = sheetData.getJSONArray("values");
|
||
|
||
// 4. 处理每一行数据
|
||
for (int i = 0; i < dataValues.size(); i++) {
|
||
JSONArray row = dataValues.getJSONArray(i);
|
||
|
||
// 获取订单号
|
||
String orderNo = orderNoColumn >= 0 && orderNoColumn < row.size()
|
||
? row.getString(orderNoColumn)
|
||
: null;
|
||
|
||
// 获取物流单号
|
||
String logisticsNo = logisticsColumn >= 0 && logisticsColumn < row.size()
|
||
? row.getString(logisticsColumn)
|
||
: null;
|
||
|
||
if (orderNo != null && !orderNo.isEmpty()) {
|
||
System.out.println("第 " + (i+3) + " 行 - 订单号: " + orderNo + ", 物流单号: " + logisticsNo);
|
||
|
||
// 如果物流单号为空，可以填充
|
||
if (logisticsNo == null || logisticsNo.isEmpty()) {
|
||
System.out.println(" → 需要填充物流单号");
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 写入数据注意事项
|
||
|
||
### 写入接口的数据格式
|
||
|
||
根据腾讯文档 API 规范，写入数据时仍然使用简单格式：
|
||
|
||
```java
|
||
// 写入数据（简单格式）
|
||
Object[][] values = {
|
||
{"数据1", "数据2", "数据3"}
|
||
};
|
||
|
||
tencentDocService.writeSheetData(accessToken, fileId, sheetId, "A10", values);
|
||
```
|
||
|
||
**不需要**转换为 gridData 格式，API 会自动处理。
|
||
|
||
---
|
||
|
||
## 调试技巧
|
||
|
||
### 1. 启用详细日志
|
||
|
||
```yaml
|
||
logging:
|
||
level:
|
||
com.ruoyi.jarvis.util.TencentDocDataParser: DEBUG
|
||
com.ruoyi.jarvis.service.impl.TencentDocServiceImpl: DEBUG
|
||
```
|
||
|
||
### 2. 查看数据结构
|
||
|
||
当调用 `readSheetData` 时，会自动打印前3行数据结构：
|
||
|
||
```
|
||
数据结构（共 98 行，显示前 3 行）：
|
||
第 1 行（15列）: ["日期","公司","草号",...,"物流单号","标记"]
|
||
第 2 行（15列）: ["3月10日","","JY20251032904",...,"",""]
|
||
第 3 行（15列）: ["3月10日","","JY20250309184",...,"6649902864",""]
|
||
```
|
||
|
||
### 3. 检查原始响应
|
||
|
||
Service 返回的数据中包含 `_原始数据` 字段，可以查看 API 的原始响应：
|
||
|
||
```java
|
||
JSONObject result = tencentDocService.readSheetData(...);
|
||
JSONObject originalData = result.getJSONObject("_原始数据");
|
||
System.out.println("原始响应: " + originalData.toJSONString());
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1：为什么会有两种数据格式？
|
||
|
||
**A**：腾讯文档 V3 API 使用 gridData 格式以支持更丰富的格式信息（字体、颜色、对齐方式等）。但对于简单的数据读写，我们只需要文本内容，因此解析器会提取纯文本数据。
|
||
|
||
### Q2：读取的数据是否包含格式信息？
|
||
|
||
**A**：gridData 格式包含完整的格式信息（字体、颜色等），但我们的解析器只提取文本内容。如果需要格式信息，可以从 `_原始数据` 字段中获取。
|
||
|
||
### Q3：解析器会影响性能吗？
|
||
|
||
**A**：解析器只是简单的 JSON 遍历和文本提取，性能影响很小。对于大数据量（数千行），建议分批读取。
|
||
|
||
### Q4：是否兼容旧代码？
|
||
|
||
**A**：完全兼容。解析后的数据格式与旧代码期望的格式一致（`{"values": [[]]}`），无需修改现有代码。
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
### 关键要点
|
||
|
||
1. ✅ **腾讯文档 V3 API 使用 gridData 格式**
|
||
2. ✅ **创建了 TencentDocDataParser 统一处理**
|
||
3. ✅ **Service 层自动解析为简单格式**
|
||
4. ✅ **完全向后兼容，无需修改上层代码**
|
||
5. ✅ **保留原始数据供调试使用**
|
||
|
||
### 文件清单
|
||
|
||
- ✅ `TencentDocDataParser.java` - 数据解析器（新增）
|
||
- ✅ `TencentDocServiceImpl.java` - Service 层（已更新）
|
||
- ✅ `腾讯文档API数据格式解析说明.md` - 本文档（新增）
|
||
|
||
---
|
||
|
||
**文档版本**：1.0
|
||
**创建时间**：2025-11-05
|
||
**适用场景**：腾讯文档 V3 API 数据格式解析
|
||
|