实体与实体映射

功能概述

什么是实体映射

实体映射是 BPMAX 平台提供的数据标准化能力，是一个独立的功能模块。它帮助您定义统一的数据结构标准，并将来自不同数据源的数据自动转换为这些标准格式。

通过实体映射，您可以：

定义数据标准：为业务对象（用户、订单、商品等）建立统一的数据结构定义
数据格式统一：将不同第三方系统、不同接口返回的数据转换为统一格式
简化业务逻辑：上层业务只需适配一套标准结构，无需关心数据来源
降低维护成本：当数据源变更时，只需调整映射配置，业务代码无需修改

为什么需要实体映射

在企业应用中，经常会遇到以下场景：

多系统集成：对接多个第三方系统（ERP、CRM、OA等），每个系统的数据格式都不同
接口差异：即使是同一个系统，不同版本的接口返回格式也可能不一致
字段不统一：不同系统对同一概念使用不同的字段名（userId vs user_id vs uid）
格式不一致：时间格式、金额单位、状态码等表示方式各不相同

实体映射通过建立"标准层"，将这些差异屏蔽在映射配置中，让业务代码保持简洁和稳定。

核心概念

系统实体 (Entity)

系统实体是一份「标准数据结构」定义,用来描述系统内部统一使用的数据格式。例如:

用户实体: 定义用户的标准字段(id、姓名、手机号、部门等)
订单实体: 定义订单的标准字段(订单号、金额、状态、下单时间等)
商品实体: 定义商品的标准字段(商品编码、名称、价格、库存等)

实体映射 (Entity Mapping)

实体映射定义了如何将第三方接口的原始响应数据转换为系统实体格式。包括:

字段映射规则: 指定源字段到目标字段的对应关系
数据转换: 支持直接取值、模板拼接、脚本转换等多种方式
结构转换: 支持单条数据和列表数据的转换

引用实体

当不同实体之间有相同的结构时,可以通过引用实体功能实现结构复用,例如:

多个接口都返回用户信息,可以定义一个「用户实体」供其他实体引用
订单实体中包含商品列表,可以引用「商品实体」

典型应用场景

场景 1：多系统用户数据统一

问题：公司使用多个系统（飞书、企业微信、内部OA），每个系统的用户数据格式不同：

解决方案：定义统一的「用户实体」，为每个系统配置映射规则，业务代码只使用标准实体。

场景 2：接口版本升级

问题：第三方系统升级接口，字段名称和结构发生变化，导致业务代码需要大量修改。

解决方案：只需调整实体映射配置，将新接口的字段映射到原有的标准实体，业务代码无需改动。

场景 3：数据格式标准化

问题：不同接口返回的时间格式、金额单位、状态码表示方式不一致。

解决方案：通过映射脚本统一转换为标准格式（如统一时间格式、金额单位、状态文本）。

与其他功能的关系

与接口集成的关系

实体映射最常用的场景是配合接口集成使用：

接口集成：负责调用第三方 API，获取原始数据
实体映射：负责将原始数据转换为标准格式

使用流程

1. 定义系统实体（本模块）
   ↓
2. 配置数据源（如接口集成）
   ↓
3. 配置实体映射（本模块）
   ↓
4. 业务代码使用标准实体

文档导航

本文档分为以下几个部分，您可以根据需要查阅：

📚 核心文档

实体定义详细教程 - 如何创建和管理系统实体
响应映射配置教程 - 如何配置 API 响应映射规则

🚀 快速开始

第一次使用实体映射

如果您是第一次使用实体映射功能，建议按以下步骤操作：

阅读本文档的「功能概述」和「核心概念」部分，了解基本原理
查看「典型示例」，理解实际应用场景
参考实体定义详细教程创建第一个实体
参考响应映射配置教程配置映射规则
通过调试验证映射效果

配合接口集成使用

实体映射最常与接口集成配合使用，完整流程如下：

在接口集成中配置第三方 API
在本模块中定义标准实体（参考实体定义教程）
在 API 编辑页配置响应映射（参考响应映射教程）
在流程或脚本中调用接口，使用映射后的标准数据

使用实体映射

步骤 1：定义系统实体

系统实体是数据标准化的基础，需要先定义好标准结构。

进入系统管理后台
导航至 实体管理 页面（路径：/entity_mapping）
点击「新建」按钮创建实体
设计实体字段结构：
- 添加字段，设置字段名、类型、是否必填等
- 对于复杂结构，可以使用对象类型或数组类型
- 可以引用其他实体实现结构复用
保存实体定义

详细步骤请参考：实体定义详细教程

步骤 2：配置响应映射

在 API 上配置如何将原始响应转换为标准实体。

进入接口集成的 API 编辑页
找到「响应映射」配置区域
选择目标实体
设置基础参数（数据类型、根路径等）
添加字段映射规则：
- 选择目标字段
- 指定来源字段路径
- 选择转换方式（直接取值、模板拼接、脚本转换等）
保存配置

详细步骤请参考：响应映射配置教程

步骤 3：调试验证

配置完成后，务必进行调试验证。

在 API 编辑页的调试面板中发起测试调用
查看原始响应和映射后的数据
确认字段是否正确填充、格式是否符合预期
如有问题，返回调整映射规则并重新测试

详细方法请参考：响应映射配置教程 - 调试验证

典型示例

示例 1: 用户详情接口

场景: 将第三方用户详情接口的响应转换为统一的用户实体

第三方响应结构:

{
  "code": 0,
  "data": {
    "userId": "10001",
    "userName": "张三",
    "phone": "13800138000",
    "enableFlag": 1
  }
}

目标实体结构:

{
  "id": "10001",
  "name": "张三",
  "mobile": "13800138000",
  "status": "启用"
}

配置要点:

数据类型: single (单条数据)
根路径: data
字段映射:
- id ← userId (直接映射)
- name ← userName (直接映射)
- mobile ← phone (直接映射)
- status ← enableFlag (脚本转换: 1→"启用", 0→"停用")

示例 2: 订单列表接口

场景: 将第三方订单列表接口的响应转换为统一的订单实体列表

配置要点:

数据类型: list (列表数据)
根路径: data.list
字段映射:
- orderNo ← order_id (直接映射)
- amount ← amount_fen (脚本转换: 分→元)
- createdAt ← create_time (预置函数: 时间戳→日期字符串)

完整示例请参考: 响应映射配置教程 - 配置示例