CC/ruoyi-java

Fork 0

Files

荒 a3aa8c74e6 1

2025-11-06 02:12:12 +08:00

6.7 KiB

Raw Blame History

腾讯文档 API 修复说明

修复时间

2025-11-05

修复原因

原代码中使用的腾讯文档 API 基础 URL 不正确，导致接口调用失败。

问题详情

错误的 API 基础 URL：使用了 https://docs.qq.com/open/v3
正确的 API 基础 URL：应该是 https://docs.qq.com/openapi/v3（注意是 /openapi/v3 而不是 /open/v3）

修复的文件列表

1. 配置文件（2个）

文件	修改内容
`ruoyi-admin/src/main/resources/application-dev.yml`	第202行：`api-base-url: https://docs.qq.com/open/v3` → `https://docs.qq.com/openapi/v3`
`ruoyi-admin/src/main/resources/application-prod.yml`	第202行：`api-base-url: https://docs.qq.com/open/v3` → `https://docs.qq.com/openapi/v3`

2. Java 配置类（1个）

文件	修改内容
`ruoyi-system/src/main/java/com/ruoyi/jarvis/config/TencentDocConfig.java`	第33行：更新默认 API 基础地址为 `https://docs.qq.com/openapi/v3`，并添加注释说明

3. Java 工具类（1个）

文件	修改内容
`ruoyi-system/src/main/java/com/ruoyi/jarvis/util/TencentDocApiUtil.java`	更新所有方法的注释和文档说明，确保 API 路径格式正确

详细修改说明

TencentDocConfig.java

// 修改前
private String apiBaseUrl = "https://docs.qq.com/open/v3";

// 修改后
/** API基础地址 - V3版本（注意：是 /openapi/v3 不是 /open/v3） */
private String apiBaseUrl = "https://docs.qq.com/openapi/v3";

TencentDocApiUtil.java 修改的方法

1. readSheetData() - 读取表格数据

修改前：注释中标注路径为 /open/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}
修改后：更新为 /openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}
实际生成的完整URL：https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}

2. writeSheetData() - 写入表格数据

修改前：注释中标注路径为 /open/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}
修改后：更新为 /openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}
增强：添加了关于 V3 API 数据格式的详细说明，参考官方文档
实际生成的完整URL：https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}

3. appendSheetData() - 追加表格数据

修改前：注释中标注路径为 /open/v3/spreadsheets/{id}/sheets/{sheetId}
修改后：更新为 /openapi/v3/spreadsheets/{id}/sheets/{sheetId}
增强：添加了关于工作表信息返回格式的详细说明
实际生成的完整URL：https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}

4. getFileInfo() - 获取文件信息

修改前：注释中标注路径为 /open/v3/spreadsheets/{id}
修改后：更新为 /openapi/v3/spreadsheets/{id}
增强：添加了返回格式示例说明
实际生成的完整URL：https://docs.qq.com/openapi/v3/spreadsheets/{id}

5. getSheetList() - 获取工作表列表

修改前：注释中标注路径为 /open/v3/spreadsheets/{id}/sheets
修改后：更新为 /openapi/v3/spreadsheets/{id}/sheets
增强：添加了返回格式示例说明
实际生成的完整URL：https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets

application-dev.yml & application-prod.yml

# 修改前
api-base-url: https://docs.qq.com/open/v3

# 修改后
# 注意：正确的URL是 /openapi/v3 而不是 /open/v3
api-base-url: https://docs.qq.com/openapi/v3

V3 API 接口路径对照表

功能	正确的完整 URL
读取表格数据	`https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}/ranges/{range}`
写入表格数据	`https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}/ranges/{range}`
获取工作表信息	`https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}`
获取文件信息	`https://docs.qq.com/openapi/v3/spreadsheets/{fileId}`
获取工作表列表	`https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets`
获取用户信息	`https://docs.qq.com/oauth/v2/userinfo`

鉴权方式验证 ✅

当前代码中的鉴权实现是正确的，使用标准的 Bearer Token 方式：

conn.setRequestProperty("Authorization", "Bearer " + accessToken);
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");

数据格式说明

写入数据格式

根据腾讯文档 V3 API 规范，支持两种数据格式：

1. 简单文本数组（当前实现）

{
  "values": [
    ["值1", "值2"],
    ["值3", "值4"]
  ]
}

2. 完整 CellData 结构（用于复杂格式）

{
  "data": [{
    "startRow": 0,
    "startColumn": 0,
    "rows": [{
      "values": [{
        "cellValue": {
          "text": "单元格内容"
        },
        "dataType": "DATA_TYPE_UNSPECIFIED",
        "cellFormat": {
          "textFormat": {
            "font": "SimSun",
            "fontSize": 12
          }
        }
      }]
    }]
  }]
}

当前代码使用简单文本数组格式，适用于大多数场景。如需使用复杂格式（带样式、颜色等），可以在调用时传入完整的 CellData 结构。

参考文档

注意事项

重要：所有使用腾讯文档 API 的地方必须使用 /openapi/v3 而不是 /open/v3
配置文件更新后需要重启应用才能生效
OAuth 授权接口路径保持不变：https://docs.qq.com/oauth/v2/
如果 API 调用仍然失败，请检查：
- Access Token 是否有效
- 文件 ID 和工作表 ID 是否正确
- 网络连接是否正常
- 是否有相关权限

测试建议

修复后建议测试以下功能：

✅ 获取授权 URL
✅ OAuth 回调处理
✅ 读取表格数据
✅ 写入表格数据
✅ 追加表格数据
✅ 获取工作表列表
✅ 获取文件信息

验证结果

✅ 所有配置文件已更新
✅ 所有 Java 代码已更新
✅ 所有注释和文档已更新
✅ 无语法错误（Linter 检查通过）
✅ API 路径格式符合 V3 规范

修复完成时间：2025-11-05
修复人员：AI Assistant
验证状态：✅ 已完成

6.7 KiB Raw Blame History Unescape Escape