实体管理

本文档介绍如何定义和管理系统实体。

概述

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

  • 为不同的业务对象(用户、订单、商品等)建立统一的数据标准
  • 在多个接口之间复用相同的数据结构
  • 为上层业务提供清晰、一致的数据格式

访问实体管理

实体管理位于系统菜单的「能力增强」模块下 实体管理入口

创建实体

新建实体

  1. 打开 实体列表页面
  2. 点击页面右上角的「创建实体」按钮
  3. 在弹出的对话框中填写:
    • 实体名称: 建议使用清晰的业务名称,如「用户实体」「订单实体」「商品实体」
    • 描述: 简要说明这个实体的用途、适用场景等
  4. 点击「创建」保存

添加字段

基本操作

  1. 点击「添加属性」按钮
  2. 在弹出框中填写字段信息: 添加字段弹窗
    • 字段名: 字段的标识符,如 userId、orderNo
    • 引用实体: (可选) 如果该字段是引用其他实体,可以在此选择
    • 字段类型: 选择合适的数据类型(见下文)
    • 是否必填: 勾选表示该字段必须有值
    • 描述: 说明字段的用途、格式要求、取值范围等
  3. 点击「确定」保存

字段类型说明

类型说明适用场景
对象 (object)嵌套对象包含多个子字段的复杂结构
数组 (array)列表订单列表、商品列表等
字符串 (string)文本类型姓名、地址、描述等
整数 (integer)整数类型计数、排序号等
数字 (number)数值类型年龄、数量、金额等
布尔 (boolean)真/假是否启用、是否完成等
空值 (null)空值类型明确表示无值的字段
任意 (any)任意类型不确定类型的动态字段

添加嵌套字段

对象类型字段

当字段类型选择为「对象」时,可以为该字段添加子字段: 对象字段示例

  1. 在字段树中点击该对象字段「添加子属性」按钮
  2. 配置子字段信息，同上述添加字段步骤
  3. 保存

示例: 定义用户实体的地址字段 填写示例

用户实体
├─ id (字符串)
├─ name (字符串)
└─ address (引用对象)
   ├─ province (字符串)
   ├─ city (字符串)
   └─ detail (字符串)

引用实体

什么是引用实体

当不同实体之间有相同的结构时,可以使用「引用实体」功能实现结构复用,避免重复定义。

使用场景

  • 公共结构复用: 多个接口都返回用户信息,可以定义一个「用户实体」供其他实体引用
  • 组合复杂结构: 订单实体中包含用户信息和商品列表,可以分别引用「用户实体」和「商品实体」
  • 维护一致性: 当公共结构需要修改时,只需修改被引用的实体,所有引用处自动生效

配置方法

  1. 在字段配置中,将字段类型设置为「对象」或「数组」
  2. 在「引用实体」下拉框中选择要复用的实体
  3. 保存后,该字段会自动展开为被引用实体的结构

注意事项:

  • 引用的实体结构只能查看,不能在当前实体中直接修改
  • 如需修改,请到被引用的实体中进行修改
  • 避免循环引用(A 引用 B,B 又引用 A)

示例: 订单实体引用用户实体

订单引用用户示例步骤 1: 先定义「用户实体」

步骤 2: 在「订单实体」中引用

订单实体
├─ orderNo (字符串)
├─ amount (数字)
├─ buyer (对象) → 引用「用户实体」
│  ├─ id (字符串) [只读]
│  ├─ name (字符串) [只读]
│  └─ mobile (字符串) [只读]
└─ createdAt (字符串)

编辑和删除字段

编辑字段

  1. 在字段树中点击要编辑的字段右侧的「编辑」按钮
  2. 在弹出的对话框中修改字段信息
  3. 点击「确定」保存

删除字段

  1. 在字段树中点击要删除的字段右侧的「删除」按钮
  2. 确认删除

下一步

实体定义完成后,您可以:

  1. 查看 响应映射配置教程 了解如何配置 API 响应映射
  2. 在 API 编辑页面为接口配置实体映射
  3. 通过调试验证映射效果