结果集查看、下载和导出接口优化需求文档

文档信息

项目信息
文档版本v1.1 (已实现)
创建日期2025-10-27
更新日期2025-10-30
当前版本Linkis 1.17.0
负责模块linkis-pes-publicservice + pipeline + linkis-storage
开发分支feature/1.17.0-resultset-field-masking
状态✅ 开发完成，已测试

实施总结

代码修改统计

本次开发包含敏感字段屏蔽和字段截取两个功能：

15 files changed, 4166 insertions(+), 386 deletions(-)

新增文件

文件行数说明
ResultUtils.java514行核心工具类，包含字段屏蔽和截取逻辑
FieldTruncationResult.java73行字段截取结果封装实体类
OversizedFieldInfo.java68行超长字段信息实体类

修改文件

文件修改类型说明
LinkisStorageConf.scala配置扩展 (+11行)新增字段截取相关配置项
WorkSpaceConfiguration.java配置扩展 (+4行)新增功能开关配置
FsRestfulApi.java功能增强 (218改动)下载接口支持字段屏蔽和截取
PipelineEngineConnExecutor.scala语法扩展 (+16改动)支持without和truncate子句
CSVExecutor.scala功能增强 (70改动)CSV导出支持屏蔽和截取
ExcelExecutor.scala功能增强 (140改动)Excel导出支持屏蔽和截取
文档新增4份需求和设计文档

核心改进点

  1. 统一工具类: 将字段屏蔽和截取逻辑提取到ResultUtils工具类，实现代码复用
  2. 组合功能: 支持字段屏蔽和字段截取同时使用（applyFieldMaskingAndTruncation方法）
  3. 可配置化: 所有阈值和开关都通过CommonVars配置管理
  4. 向后兼容: 功能可选，不影响现有功能
  5. 标记机制: 截取后的字段会在列名添加(truncated to N chars)后缀标记

实现的核心方法

ResultUtils工具类方法:

  • detectAndHandle(): 检测并处理超长字段（主入口方法）
  • detectOversizedFields(): 检测超长字段，返回超长字段列表
  • truncateFields(): 截取超长字段值
  • applyFieldMaskingAndTruncation(): 同时应用字段屏蔽和截取

1. 需求概述

1.1 需求主题

结果集查看、下载和导出接口优化 - 超长字段截取功能

1.2 需求背景

当前结果集查看功能存在以下问题：

  • 当某一列字段内容超过10000字符时，会导致结果集无法正常查看
  • 缺少对超长字段的检测和处理机制
  • 用户无法获知哪些字段超长，也无法选择处理方式

1.3 需求目标

为结果集查看、下载、导出功能增加超长字段检测和截取能力，提升系统稳定性和用户体验。

2. 功能需求

2.1 核心功能点

2.1.1 结果集查看功能优化

  • 触发条件：结果集中存在字段值长度超过10000字符
  • 处理逻辑：
    1. 检测所有字段值长度
    2. 收集超过10000字符的字段信息（字段名、行号、实际长度）
    3. 最多收集20个超长字段
    4. 返回超长字段列表给前端，由用户确认是否截取
    5. 若用户确认截取，则截取前10000个字符后返回结果集
    6. 若用户取消，则返回原始数据（可能导致查看失败）

2.1.2 结果集下载功能优化

  • 触发条件：结果集中存在字段值长度超过10000字符
  • 处理逻辑：与查看功能相同
    1. 检测所有字段值长度
    2. 收集超过10000字符的字段信息
    3. 最多收集20个超长字段
    4. 返回超长字段列表给前端确认
    5. 若用户确认截取，则截取前10000个字符后下载
    6. 若用户取消，则下载原始数据

2.1.3 结果集导出功能优化

  • 触发条件：结果集中存在字段值长度超过32767字符
  • 处理逻辑：
    1. 检测所有字段值长度
    2. 收集超过32767字符的字段信息（字段名、行号、实际长度）
    3. 最多收集20个超长字段
    4. 返回超长字段列表给前端确认
    5. 若用户确认截取，则截取前32767个字符后导出
    6. 若用户取消，则导出原始数据（可能导致导出失败）

2.2 功能约束

2.2.1 超长字段收集上限

  • 最多收集20个超长字段信息
  • 超过20个时，只返回前20个

2.2.2 截取长度配置

  • 查看和下载：默认10000字符，可配置
  • 导出：默认32767字符，可配置

2.2.3 功能开关

  • 必须提供功能总开关，关闭时相当于回退到原版本功能
  • 开关关闭时，不进行任何检测和截取

3. 非功能需求

3.1 性能要求

  • 字段长度检测不应显著增加接口响应时间
  • 对于大结果集，检测逻辑应高效执行

3.2 兼容性要求

  • 遵循最小改动原则，不影响现有功能
  • 功能开关关闭时，行为与原版本完全一致

3.3 可配置性要求

  • 所有阈值参数必须可配置
  • 配置必须使用 CommonVars 统一管理
  • 参考 JobhistoryConfiguration 的配置方式

4. 接口设计要求

4.1 返回数据结构

需要在结果集相关接口的响应中增加以下信息：

{
  "hasOversizedFields": true,
  "oversizedFields": [
    {
      "fieldName": "column1",
      "rowIndex": 0,
      "actualLength": 15000,
      "maxLength": 10000
    }
  ],
  "maxOversizedFieldCount": 20,
  "data": "结果集数据"
}

4.2 前端交互流程

  1. 后端检测到超长字段，返回超长字段列表
  2. 前端展示提示弹窗，显示超长字段信息
  3. 用户选择是否截取
  4. 前端带着用户选择结果重新请求接口
  5. 后端根据用户选择返回截取或原始数据

5. 配置项清单

配置项名称默认值说明
linkis.resultset.field.truncation.enabledfalse功能总开关
linkis.resultset.field.view.max.length10000查看功能字段最大长度
linkis.resultset.field.download.max.length10000下载功能字段最大长度
linkis.resultset.field.export.max.length32767导出功能字段最大长度
linkis.resultset.field.oversized.max.count20最多收集超长字段数量

6. 实施范围

6.1 开发范围

  • 仅实现后端接口功能
  • 不涉及前端页面开发

6.2 代码边界

  • 不修改现有表结构
  • 不引入新的第三方依赖
  • 不修改现有公共接口签名（只扩展返回数据）

7. 验收标准

7.1 功能验收

  • [x] ✅ 功能开关关闭时，行为与原版本一致
  • [x] ✅ 功能开关开启时，能正确检测超长字段
  • [x] ✅ 能返回正确的超长字段信息列表（通过FieldTruncationResult封装）
  • [x] ✅ 用户选择截取时，能正确截取指定长度
  • [x] ✅ 超长字段超过20个时，只返回前20个
  • [x] ✅ 截取后的字段会在列名添加标记(truncated to N chars)

7.2 配置验收

  • [x] ✅ 所有配置项使用 CommonVars 管理
  • [x] ✅ 配置项放在对应模块的 Configuration 类中（LinkisStorageConf和WorkSpaceConfiguration）
  • [x] ✅ 配置项可以正确读取和生效

7.3 兼容性验收

  • [x] ✅ 不影响现有结果集查看功能
  • [x] ✅ 不影响现有结果集下载功能
  • [x] ✅ 不影响现有结果集导出功能

7.4 扩展功能验收 (新增)

  • [x] ✅ 支持字段屏蔽和字段截取同时使用
  • [x] ✅ Pipeline语法支持truncate参数
  • [x] ✅ CSV和Excel导出都支持字段截取

8. 风险评估

8.1 技术风险

  • 性能影响：字段长度检测可能影响性能，需要优化检测逻辑
  • 内存占用：大结果集检测可能增加内存占用

8.2 兼容性风险

  • 前端兼容：老版本前端不识别新增的返回字段，需要保证向下兼容

9. 参考资料

9.1 相关代码模块

  • 结果集查看相关代码
  • 结果集下载相关代码
  • 结果集导出相关代码

9.2 配置参考

  • org.apache.linkis.jobhistory.conf.JobhistoryConfiguration
  • org.apache.linkis.common.conf.CommonVars