数据插件
数据插件在接口执行完成后、响应返回前，对结果数据做二次加工。它不改变 SQL 与接口逻辑，只改变「返回什么」。常见用途：敏感字段脱敏、字段重命名、编码转文本、列表转树、多条结果取单条。
入口
在任意开发模式的工作台右侧点击「数据插件」。插件按三类组织：
| 分类 | 插件 |
|---|---|
| 数据处理 | 过滤清洗、数值格式化、数值替换、字段合并 |
| 数据映射 | 字段重命名、字典转换 |
| 结果转换 | Tree 形结构、多级嵌套、单对象 |
每个插件有独立开关，启用后配置内容才会生效。点击「保存配置」写入接口定义，随后仍需保存并发布接口。
Tree 形结构、多级嵌套、单对象三者只能启用一个。切换时会提示关闭当前启用的插件。
执行顺序
多个插件同时启用时，按固定顺序执行：
| 顺序 | 插件 |
|---|---|
| 1 | 字段重命名（fieldMapping） |
| 2 | 过滤清洗（dataProcess） |
| 3 | 字典转换（dictTransform） |
| 4 | 数值格式化（fieldFormat） |
| 5 | 数值替换（fieldReplace） |
| 6 | 字段合并（dataMerge） |
| 7 | Tree 形结构（treeTransform） |
| 8 | 单对象（singleObject） |
| 9 | 多级嵌套（nestedStructure） |
这意味着后执行的插件看到的是前一个插件处理后的字段名与值，配置时需按实际顺序设计。
过滤清洗
对结果列表执行规则，规则可多条、按添加顺序执行：
| 规则类型 | 配置 | 说明 |
|---|---|---|
| 数据过滤 | 字段、操作符、值 | 仅保留满足条件的记录 |
| 数据排序 | 字段、升序/降序 | 按字段排序 |
| 数据脱敏 | 字段 （可多选）、脱敏类型 | 对字段值做掩码 |
| 字段计算 | 源字段、运算符、操作数、新字段名 | 计算或拼接后写入新字段 |
操作符：等于、不等于、大于、小于、大于等于、小于等于、包含、不包含、为空、不为空。计算运算符：+、-、*、/、concat。
脱敏类型：
| 类型 | 适用 |
|---|---|
| 通用脱敏 | 任意字符串 |
| 手机号 | 手机号码 |
| 身份证号 | 身份证 |
| 邮箱 | 邮箱地址 |
| 银行卡 | 卡号 |
| 姓名 | 人名 |
| 地址 | 地址文本 |
计算规则的「新字段名」可以与旧字段同名，用于覆盖原值。
字段重命名
把源字段映射为新字段名：
| 配置 | 说明 |
|---|---|
| 源字段 | 从当前返回参数树中选择 |
| 目标字段 | 新字段名 |
| 默认值 | 源字段为空时的回退值 |
| 删除源字段 | 勾选后映射完成即移除原字段 |
多条映射按列表顺序执行。目标字段名重复时，后执行的映射会覆盖先前的值。
字典转换
把编码值转换为可读文本：
- 选择源字段与目标字段（目 标留空则覆盖源字段）。
- 逐条维护「原值 → 显示值」映射。
- 未命中映射时使用默认值。
- 「保留原始字段」勾选后保留源字段，否则用转换结果替换。
适合状态码、类型编码、地区编码等场景。
数值格式化
| 格式 | 说明 | 示例模板 |
|---|---|---|
| 日期时间 | 按模板格式化日期 | yyyy-MM-dd HH:mm:ss |
| 金额 | 千分位金额 | #,##0.00 |
| 百分比 | 百分比展示 | 按页面提示 |
| 数字 | 数字格式 | #,##0.00 |
| 转大写 | 字符串大写 | — |
| 转小写 | 字符串小写 | — |
| 去除空格 | 去除首尾空格 | — |
日期、金额、数字需要填写格式模板。
数值替换
按条件替换字段值：
| 匹配方式 | 说明 |
|---|---|
| 等于 | 值完全相等 |
| 包含 | 包含目标文本 |
| 开头匹配 | 以目标文本开头 |
| 结尾匹配 | 以目标文本结尾 |
| 正则匹配 | 满足正则 |
| 为空时替换 | 字段为 null |
| 为空字符串时替换 | 字段为空串 |
命中后写入替换值。适合把 null 统一转为 -、把异常值转为固定文案等。
字段合并
把多个字段拼接为一个新字段：
- 选择多个源字段。
- 设置目标字段名。
- 可设置分隔符（如
-、空格）。 - 可选择合并后删除源字段。
源字段按选择顺序拼接，空值按空字符串处理。
Tree 形结构
把平铺的父子列表转换为树：
| 配置 | 说明 |
|---|---|
| 节点 ID 字段 | 唯一标识字段 |
| 父节点 ID 字段 | 指向父节点 ID |
| 子节点字段名 | 生成 children 的字段名，默认 children |
| 根节点 ID | 作为根起点的值；留空时按父 ID 缺失或自引用识别 |
适合菜单、部门、地区等层级数据。数据中存在环时可能导致节点丢失，配置前应确保父子关系合法。
多级嵌套
按一个或多个分组字段把列表折叠为多层 children：
- 每个层级配置分组字段、children 字段名、标签字段与展示字段。
- 层级按配置顺序嵌套。
- 可选择保留叶子节点的原始字段；不保留时只输出指定的叶子展示字段。
与 Tree 形结构的区别：Tree 依据父子 ID 还原层级，多级嵌套依据分组字段重新聚合。
单对象
把结果集转换为单个对象：
| 模式 | 说明 |
|---|---|
| 取第一条 | 直接返回列表第一条 |
| 条件匹配 | 按字段、操作符、目标值筛选后返回第一条 |
结果集为空时返回 null。适合「详情查询」这类只应该返回一条记录的接口。
字段路径与嵌套结果
插件字段来自「返回参数」树，支持 data.user.phone 这样的完整路径。平台会定位到实际列表或对象，在该层级执行插件，再把结果写回原响应结构。因此对嵌套对象内的字段做脱敏、映射时，直接选择完整路径即可。
失败与排查
- 插件内部异常时，平台记录错误日志并返回未处理的原始数据，不会让接口直接失败。配置后务必用测试或实际调用核对结果。
- 插件只处理执行结果的数据部分；分页、总数等包装字段由平台维护。
- 修改返回参数后，插件里已选字段可能失效， 需要重新选择。
- 插件配置保存在接口定义中，随版本发布与迁移一起生效。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 插件不生效 | 未启用开关或未保存配置 | 打开开关并保存配置，再保存接口 |
| 脱敏后字段消失 | 同时启用了字段重命名/替换 | 检查执行顺序与字段名 |
| 字典转换未命中 | 原值类型或大小写不一致 | 按实际值配置映射或设置默认值 |
| 列表没有变成树 | 父子字段配置错误或存在环 | 核对 ID 与父 ID，清理非法数据 |
| 单对象返回 null | 条件无匹配或结果为空 | 检查筛选条件 |
| 启用第二个结果转换插件被拦截 | 结果转换插件互斥 | 关闭当前插件后再启用 |