kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/design/2026-02-02-005-描述功能-设计.md

18 KiB
Raw Permalink Blame History

设计文档 - 描述功能

元数据

  • 需求编号：001-05
  • 创建时间：2026-02-02
  • 创建人：AI Assistant
  • 状态：进行中

设计概述

本设计文档描述 Salesforce Partner API 描述功能的实现方案，包括 DescribeGlobal（描述所有可用对象）、DescribeSObject（描述特定对象）、DescribeSObjects（描述多个对象）、DescribeLayout（描述对象布局）、DescribeTabs（描述标签页）和 DescribeQuickActions（描述快速操作）六个核心功能。

描述功能是 Salesforce 元数据访问的基础，支持获取对象定义、字段信息、布局配置和 UI 元素。本设计遵循 RESTful API 规范，采用分层架构，将复杂的 Salesforce 元数据转换为易于使用的 JSON 格式。

架构设计

系统架构

┌─────────────────────────────────────────────────────────────┐
│                    客户端 (Client)                          │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP 请求
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              PartnerDescribeController                      │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
│  │ describe │ describe │ describe │ describe │ describe │   │
│  │ Global() │ SObject()│ SObjects()│ Layout() │ Tabs()   │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           describeQuickActions()                    │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────┘
                       │ 调用
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              IPartnerDescribeService                        │
│              PartnerDescribeServiceImpl                     │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
│  │ describe │ describe │ describe │ describe │ describe │   │
│  │ Global() │ SObject()│ SObjects()│ Layout() │ Tabs()   │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           describeQuickActions()                    │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────┘
                       │ 获取连接
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              PartnerConnectionFactory                       │
│              (继承 AbstractConnectionFactory)               │
└──────────────────────┬──────────────────────────────────────┘
                       │ SOAP API 调用
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Salesforce Partner API                         │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
│  │ describe │ describe │ describe │ describe │ describe │   │
│  │ Global() │ SObject()│ SObjects()│ Layout() │ Tabs()   │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           describeQuickActions()                    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

模块架构

模块：datai-salesforce-partner

包结构：

com.datai.partner
├── controller
│   └── PartnerDescribeController.java      # 描述功能控制器
├── service
│   ├── IPartnerDescribeService.java        # 描述服务接口
│   └── impl
│       └── PartnerDescribeServiceImpl.java # 描述服务实现
├── model
│   ├── dto
│   │   ├── DescribeSObjectDto.java         # 描述单个对象请求 DTO
│   │   ├── DescribeSObjectsDto.java        # 描述多个对象请求 DTO
│   │   ├── DescribeLayoutDto.java          # 描述布局请求 DTO
│   │   └── DescribeQuickActionsDto.java    # 描述快速操作请求 DTO
│   └── vo
│       ├── DescribeGlobalResultVo.java     # DescribeGlobal 结果 VO
│       ├── DescribeSObjectResultVo.java    # DescribeSObject 结果 VO
│       ├── DescribeLayoutResultVo.java     # DescribeLayout 结果 VO
│       ├── DescribeTabResultVo.java        # DescribeTabs 结果 VO
│       └── DescribeQuickActionResultVo.java # DescribeQuickActions 结果 VO
└── util
    └── DescribeResultConverter.java        # 描述结果转换工具

数据流

1. 客户端发送描述请求
   ↓
2. Controller 接收请求，参数校验
   ↓
3. Controller 调用 Service 层
   ↓
4. Service 通过 PartnerConnectionFactory 获取 PartnerConnection
   ↓
5. Service 调用 Salesforce API 执行描述操作
   ↓
6. Service 处理返回结果 (DescribeSObjectResult、DescribeGlobalResult 等)
   ↓
7. Service 将描述结果转换为 Map<String, Object> 格式
   ↓
8. Service 返回结果给 Controller
   ↓
9. Controller 返回统一响应格式给客户端

技术方案

技术选型

技术组件 版本 用途
Spring Boot 3.x 基础框架
Spring Security 6.x 权限控制
partner.jar 58.x Salesforce Partner API 客户端
datai-salesforce-auth 1.0 认证和会话管理
datai-salesforce-common 1.0 通用异常和工具

核心设计决策

  1. 描述结果转换策略

    • 将 Salesforce 的 DescribeSObjectResult、DescribeGlobalSObjectResult 等复杂对象转换为 Map<String, Object> 格式
    • 保留所有重要属性，过滤内部实现细节
    • 统一字段命名规范（驼峰命名）

  2. 批量描述优化

    • 使用 describeSObjects(String[]) 方法批量描述多个对象
    • 减少 API 调用次数，提高性能
    • 处理部分对象不存在的情况

  3. 缓存策略（可选）

    • 对象元数据不经常变化，可考虑缓存
    • 缓存时间：建议 1 小时
    • 提供缓存刷新机制

  4. 字段信息处理

    • 完整返回字段定义（名称、类型、标签、是否可创建/更新等）
    • 处理 Picklist 字段的选项值
    • 处理关系字段的引用信息

数据模型

DTO 类设计

1. DescribeSObjectDto

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "描述单个对象请求参数")
public class DescribeSObjectDto {
    @NotBlank(message = "对象类型不能为空")
    @Schema(description = "对象类型（如 Account、Contact）", example = "Account", required = true)
    private String objectType;
}

2. DescribeSObjectsDto

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "描述多个对象请求参数")
public class DescribeSObjectsDto {
    @NotEmpty(message = "对象类型列表不能为空")
    @Schema(description = "对象类型列表", example = "[\"Account\", \"Contact\", \"Opportunity\"]", required = true)
    private List<String> objectTypes;
}

3. DescribeLayoutDto

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "描述对象布局请求参数")
public class DescribeLayoutDto {
    @NotBlank(message = "对象类型不能为空")
    @Schema(description = "对象类型（如 Account、Contact）", example = "Account", required = true)
    private String objectType;
    
    @Schema(description = "记录类型 ID（可选，未指定则返回默认布局）", example = "012xx0000000001AAA")
    private String recordTypeId;
}

4. DescribeQuickActionsDto

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "描述快速操作请求参数")
public class DescribeQuickActionsDto {
    @Schema(description = "对象类型（可选，如 Account、Contact）", example = "Account")
    private String objectType;
}

VO 类设计

1. DescribeGlobalResultVo

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "DescribeGlobal 结果")
public class DescribeGlobalResultVo {
    @Schema(description = "对象描述列表")
    private List<Map<String, Object>> sObjects;
    
    @Schema(description = "最大批次大小")
    private Integer maxBatchSize;
    
    @Schema(description = "是否成功")
    private Boolean success;
    
    @Schema(description = "错误信息列表")
    private List<ErrorVo> errors;
}

2. DescribeSObjectResultVo

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "DescribeSObject 结果")
public class DescribeSObjectResultVo {
    @Schema(description = "对象描述")
    private Map<String, Object> sObject;
    
    @Schema(description = "是否成功")
    private Boolean success;
    
    @Schema(description = "错误信息列表")
    private List<ErrorVo> errors;
}

3. DescribeLayoutResultVo

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "DescribeLayout 结果")
public class DescribeLayoutResultVo {
    @Schema(description = "布局描述列表")
    private List<Map<String, Object>> layouts;
    
    @Schema(description = "是否成功")
    private Boolean success;
    
    @Schema(description = "错误信息列表")
    private List<ErrorVo> errors;
}

4. DescribeTabResultVo

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "DescribeTabs 结果")
public class DescribeTabResultVo {
    @Schema(description = "标签页描述列表")
    private List<Map<String, Object>> tabs;
    
    @Schema(description = "是否成功")
    private Boolean success;
    
    @Schema(description = "错误信息列表")
    private List<ErrorVo> errors;
}

5. DescribeQuickActionResultVo

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Schema(description = "DescribeQuickActions 结果")
public class DescribeQuickActionResultVo {
    @Schema(description = "快速操作描述列表")
    private List<Map<String, Object>> quickActions;
    
    @Schema(description = "是否成功")
    private Boolean success;
    
    @Schema(description = "错误信息列表")
    private List<ErrorVo> errors;
}

接口设计

RESTful API 接口列表

接口名称 HTTP 方法 请求路径 功能描述
describeGlobal GET /partner/describe/global 描述所有可用对象
describeSObject POST /partner/describe/sobject 描述特定对象
describeSObjects POST /partner/describe/sobjects 描述多个对象
describeLayout POST /partner/describe/layout 描述对象布局
describeTabs GET /partner/describe/tabs 描述标签页
describeQuickActions POST /partner/describe/quick-actions 描述快速操作

接口详细设计

1. 描述所有可用对象

接口：GET /partner/describe/global

功能：获取 Salesforce 中所有可用的对象列表，包含对象的基本信息（名称、标签、ID 前缀、权限等）

请求参数：无

响应数据：

{
  "sObjects": [
    {
      "name": "Account",
      "label": "客户",
      "keyPrefix": "001",
      "labelPlural": "客户",
      "createable": true,
      "updateable": true,
      "deletable": true,
      "queryable": true
    }
  ],
  "maxBatchSize": 200,
  "success": true,
  "errors": null
}

2. 描述特定对象

接口：POST /partner/describe/sobject

功能：获取特定对象的详细定义，包含字段列表、子关系、权限信息等

请求参数：

{
  "objectType": "Account"
}

响应数据：

{
  "sObject": {
    "name": "Account",
    "label": "客户",
    "fields": [
      {
        "name": "Id",
        "type": "id",
        "label": "客户 ID",
        "createable": false,
        "updateable": false
      },
      {
        "name": "Name",
        "type": "string",
        "label": "客户名称",
        "createable": true,
        "updateable": true
      }
    ],
    "childRelationships": [...]
  },
  "success": true,
  "errors": null
}

3. 描述多个对象

接口：POST /partner/describe/sobjects

功能：批量获取多个对象的详细定义

请求参数：

{
  "objectTypes": ["Account", "Contact", "Opportunity"]
}

4. 描述对象布局

接口：POST /partner/describe/layout

功能：获取对象的页面布局信息

请求参数：

{
  "objectType": "Account",
  "recordTypeId": "012xx0000000001AAA"
}

5. 描述标签页

接口：GET /partner/describe/tabs

功能：获取 Salesforce 中的所有标签页信息

6. 描述快速操作

接口：POST /partner/describe/quick-actions

功能：获取对象的快速操作定义

请求参数：

{
  "objectType": "Account"
}

实现要点

1. 描述结果转换

DescribeSObjectResult 转换：

  • 提取对象基本信息：name、label、keyPrefix、labelPlural
  • 提取字段列表（Field[]）：name、type、label、length、createable、updateable、nillable、unique 等
  • 提取子关系列表（ChildRelationship[]）：childSObject、field、relationshipName、cascadeDelete
  • 提取权限信息：createable、updateable、deletable、queryable 等
  • 提取 RecordType 信息

DescribeGlobalSObjectResult 转换：

  • 提取对象基本信息：name、label、keyPrefix、labelPlural
  • 提取权限信息：createable、updateable、deletable、queryable 等

DescribeLayoutResult 转换：

  • 提取布局基本信息：layoutType、layoutName、layoutId
  • 提取编辑布局（editLayoutSections）
  • 提取详细布局（detailLayoutSections）
  • 提取相关列表（relatedLists）

DescribeTabSetResult 转换：

  • 提取标签页列表：label、name、url、type、iconUrl、sobjectName

DescribeQuickActionResult 转换：

  • 提取快速操作信息：name、label、description、type、iconUrl

2. 异常处理

异常类型：

  • ConnectionException：连接异常，转换为 SalesforceAuthException
  • ApiFault：API 调用异常，转换为 SalesforceOperationException
  • InvalidSObjectFault：无效的对象类型，转换为 SalesforceOperationException，错误码 1001

错误处理策略：

  • 记录详细错误日志
  • 返回友好的错误消息（中文）
  • 包含原始错误信息便于排查

3. 性能优化

批量描述优化：

  • 使用 describeSObjects(String[]) 方法批量描述多个对象
  • 减少 API 调用次数

缓存策略（可选）：

  • 对象元数据缓存时间：1 小时
  • 使用 Redis 或本地缓存
  • 提供缓存刷新接口

4. 安全设计

权限控制：

  • 所有接口需要登录权限：@PreAuthorize("@ss.hasLogin()")
  • 描述结果受 Salesforce 权限控制，用户只能看到其有权限的对象和字段

数据安全：

  • 不返回敏感字段的详细定义
  • 遵循 Salesforce 的字段级安全性

相关文档