响应映射配置教程
本文档介绍如何在 API 上配置响应映射,将第三方接口的响应数据转换为系统实体格式。
概述
响应映射定义了如何将第三方接口的原始响应数据转换为系统实体格式。通过配置响应映射,您可以:
- 将不同格式的第三方响应统一转换为标准实体
- 自动处理字段名称差异、数据类型转换、格式转换等
- 让上层业务只需要关心统一的实体结构
前置条件
在配置响应映射前,请确保:
访问响应映射配置
响应映射通常在 API 编辑页面中配置：
- 打开 系统集成（参考 接口集成文档）
- 找到要配置映射的 API,点击进入编辑页
- 在页面中找到「响应映射」区域
基础配置
在开始配置字段映射前,需要先完成以下基础配置:
1. 选择目标实体
从下拉列表中选择要映射到的实体,例如「用户实体」「订单实体」等。
提示: 如果下拉列表中没有需要的实体,请先到 实体管理 中创建。
2. 设置数据类型
根据接口返回的数据结构选择:
- single (单条数据): 接口返回单个对象,如「用户详情」「订单详情」
- list (列表数据): 接口返回数组,如「用户列表」「订单列表」
3. 设置合并模式
选择映射后的数据如何与原始响应合并:
- 替换: 映射后的数据直接作为接口最终返回
- 合并: 在原始响应的基础上追加/覆盖部分字段
4. 设置根路径 (root_path)
指定实际业务数据在原始响应中的位置。
示例:
如果第三方返回:
{
"code": 0,
"msg": "success",
"data": {
"userId": "10001",
"userName": "张三"
}
}- 如果业务数据在
data中,则根路径填写:data - 如果整个响应就是业务数据,则根路径留空
列表数据示例:
如果第三方返回:
{
"code": 0,
"data": {
"list": [
{ "orderId": "001", "amount": 100 },
{ "orderId": "002", "amount": 200 }
]
}
}- 根路径应填写:
data.list
配置字段映射
完成基础配置后,开始配置具体的字段映射规则。
添加映射规则
- 点击「添加映射」或「添加字段」按钮
- 配置映射规则(见下文)
- 点击「保存」
选择目标字段
方法 1: 从字段树选择(推荐)
- 点击「选择字段」按钮
- 在弹出的实体字段树中,点选要映射的字段
- 系统会自动填充目标字段路径
方法 2: 手动输入
直接在目标字段输入框中输入字段路径,如 user.id
建议: 优先使用字段树选择,避免手动输入错误。
填写来源字段路径
指定第三方响应中对应字段的路径。
路径规则:
- 使用
.分隔层级,如data.user.name - 如果已设置根路径,这里只需填写相对路径
示例:
假设根路径为 data,第三方响应为:
{
"data": {
"user_id": "10001",
"user_name": "张三",
"dept": {
"dept_id": "D001",
"dept_name": "技术部"
}
}
}映射配置:
- 目标字段
id← 来源字段user_id - 目标字段
name← 来源字段user_name - 目标字段
departmentId← 来源字段dept.dept_id - 目标字段
departmentName← 来源字段dept.dept_name
映射方式 (转换类型)
系统支持多种映射方式,适用于不同的转换场景。
1. 直接取值 (direct)
适用场景: 字段一一对应,不需要转换
配置方法:
- 转换类型: 选择「直接取值」
- 来源字段: 填写源字段路径
示例:
- 目标
id← 来源userId(直接取值) - 目标
name← 来源userName(直接取值)
2. 模板拼接 (template)
适用场景: 将多个字段拼接成一个字符串
配置方法:
- 转换类型: 选择「模板拼接」
- 模板内容: 使用
${字段名}引用字段值
示例:
模板: ${userName}(${phone})
如果源数据为:
{
"userName": "张三",
"phone": "13800138000"
}结果: 张三(13800138000)
3. 脚本转换 (script)
适用场景: 复杂的转换逻辑,如条件判断、格式转换、计算等
配置方法:
- 转换类型: 选择「脚本转换」
- 脚本类型: 选择「预置脚本」或「自定义脚本」
预置脚本
系统提供了常用的预置脚本,可以直接选择使用 
自定义脚本
当预置脚本无法满足需求时,可以编写自定义脚本。返回值即为转换后的结果。
脚本上下文:
{
value: any, // 来源字段的值
sourceData: object, // 完整的源数据对象
sourcePath: object, // 来源字段路径信息
}
示例
if (ctx.value === 1) {
return "启用";
} else if (ctx.value === 0) {
return "停用";
} else {
return "未知";
}4. 对象映射 (object)
适用场景: 将多个源字段组合成一个目标对象
配置方法:
- 转换类型: 选择「对象映射」
- 为对象的每个子字段配置映射规则
5. 数组映射 (array)
适用场景: 从源数组中提取、转换数据
配置方法:
- 转换类型: 选择「数组映射」
- 为数组元素的每个字段配置映射规则
配置示例
示例 1: 用户详情接口
第三方响应:
{
"code": 0,
"data": {
"userId": "10001",
"userName": "张三",
"phone": "13800138000",
"enableFlag": 1,
"dept": {
"deptId": "D001",
"deptName": "技术部"
}
}
}目标实体: UserEntity
├─ id (字符串)
├─ name (字符串)
├─ mobile (字符串)
├─ status (字符串)
└─ departmentName (字符串)映射配置:
| 目标字段 | 来源字段 | 转换类型 | 说明 |
|---|---|---|---|
| id | userId | 直接取值 | - |
| name | userName | 直接取值 | - |
| mobile | phone | 直接取值 | - |
| status | enableFlag | 脚本转换 | 1→"启用", 0→"停用" |
| departmentName | dept.deptName | 直接取值 | - |
基础配置:
- 数据类型: single
- 根路径: data
- 合并模式: 替换
示例 2: 订单列表接口
第三方响应:
{
"code": 0,
"data": {
"list": [
{
"order_id": "O001",
"amount_fen": 10000,
"create_time": 1609459200000,
"status": 1
}
]
}
}目标实体: OrderEntity
├─ orderNo (字符串)
├─ amount (数字)
├─ createdAt (字符串)
└─ status (字符串)映射配置:
| 目标字段 | 来源字段 | 转换类型 | 说明 |
|---|---|---|---|
| orderNo | order_id | 直接取值 | - |
| amount | amount_fen | 预置脚本 | 金额分转元 |
| createdAt | create_time | 预置脚本 | 时间戳转日期 |
| status | status | 脚本转换 | 1→"已支付", 2→"已发货" |
基础配置:
- 数据类型: list
- 根路径: data.list
- 合并模式: 替换
下一步
响应映射配置完成后,您可以: