# API 文档 - 描述和列出元数据

## 元数据
- 需求编号：003-08
- 需求名称：描述和列出元数据
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 状态：已完成

## API 概述

本文档描述了"描述和列出元数据"功能的 REST API 接口。该功能基于 Salesforce Metadata API，提供了以下核心能力：

1. **描述元数据（DescribeMetadata）**：获取当前 Salesforce Org 支持的所有元数据类型信息
2. **列出元数据（ListMetadata）**：获取指定元数据类型下的具体成员列表，支持分批处理
3. **查询历史（History Query）**：查询元数据操作的执行历史，支持审计和追溯

### 基础信息
- **基础路径**：`/salesforce/metadata`
- **Content-Type**：`application/json`
- **认证方式**：基于 Session 的认证（通过 `MetadataConnectionFactory` 管理）

## 接口列表

### 接口 1：描述元数据

**功能描述**：获取当前 Salesforce Org 支持的所有元数据类型信息，包括元数据对象的类型、目录、子类型等详细信息。

**请求方式**：GET

**请求路径**：`/salesforce/metadata/describe`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| apiVersion | Double | 否 | API 版本号，如 59.0。如果不传，使用 Salesforce 默认版本 |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 描述元数据结果（DescribeMetadataResult） |

**DescribeMetadataResult 结构**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| metadataObjects | Array | 元数据对象列表（DescribeMetadataObject[]） |
| metadataObjectsWithMns | Array | 带命名空间的元数据对象列表（DescribeMetadataObject[]） |
| namespacePrefix | String | 命名空间前缀 |
| serverVersion | String | 服务器版本 |

**DescribeMetadataObject 结构**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| childXmlNames | Array | 子 XML 名称列表（String[]） |
| directoryName | String | 目录名称 |
| inFolder | Boolean | 是否在文件夹中 |
| metaFile | Boolean | 是否有元文件 |
| suffix | String | 文件后缀 |
| xmlName | String | XML 名称 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "metadataObjects": [
      {
        "childXmlNames": [],
        "directoryName": "objects",
        "inFolder": false,
        "metaFile": false,
        "suffix": "object",
        "xmlName": "CustomObject"
      },
      {
        "childXmlNames": [],
        "directoryName": "classes",
        "inFolder": false,
        "metaFile": true,
        "suffix": "cls",
        "xmlName": "ApexClass"
      }
    ],
    "metadataObjectsWithMns": [],
    "namespacePrefix": null,
    "serverVersion": "59.0"
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "列出元数据失败: 连接超时",
  "data": null
}
```

**错误码**：
- DESCRIBE_001：获取 Metadata 连接失败
- DESCRIBE_002：描述元数据失败
- DESCRIBE_008：未知错误

---

### 接口 2：列出元数据

**功能描述**：获取指定元数据类型（及文件夹）下的具体元数据成员列表。支持批量查询，Service 层会自动分批处理（每次最多 3 个查询）。

**请求方式**：POST

**请求路径**：`/salesforce/metadata/list`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| queries | Array | 是 | 查询列表（ListMetadataQuery[]），至少包含一个查询 |

**ListMetadataQuery 结构**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | String | 是 | 元数据类型，如 "CustomObject", "ApexClass", "ApexTrigger" 等 |
| folder | String | 否 | 文件夹名称，用于查询文件夹内的元数据（如文档、报表等） |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 列出元数据结果列表（ListMetadataResult[]） |

**ListMetadataResult 结构**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| fullName | String | 完整名称 |
| type | String | 类型 |
| createdById | String | 创建者 ID |
| createdByName | String | 创建者名称 |
| createdDate | String | 创建日期（ISO 8601 格式） |
| lastModifiedById | String | 最后修改者 ID |
| lastModifiedByName | String | 最后修改者名称 |
| lastModifiedDate | String | 最后修改日期（ISO 8601 格式） |
| manageableState | String | 可管理状态 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "fullName": "Account",
      "type": "CustomObject",
      "createdById": "005xx000001X9YZAA0",
      "createdByName": "Admin User",
      "createdDate": "2023-01-15T08:30:00.000Z",
      "lastModifiedById": "005xx000001X9YZAA0",
      "lastModifiedByName": "Admin User",
      "lastModifiedDate": "2023-06-20T14:22:00.000Z",
      "manageableState": "unmanaged"
    },
    {
      "fullName": "Contact",
      "type": "CustomObject",
      "createdById": "005xx000001X9YZAA0",
      "createdByName": "Admin User",
      "createdDate": "2023-01-15T08:35:00.000Z",
      "lastModifiedById": "005xx000001X9YZAA0",
      "lastModifiedByName": "Admin User",
      "lastModifiedDate": "2023-06-20T14:25:00.000Z",
      "manageableState": "unmanaged"
    }
  ]
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询列表不能为空",
  "data": null
}
```

**错误码**：
- DESCRIBE_003：参数校验失败（查询列表为空、元数据类型为空等）
- DESCRIBE_006：列出元数据失败
- DESCRIBE_008：未知错误

---

### 接口 3：获取元数据查询历史

**功能描述**：查询元数据描述和列出操作的执行历史，支持按操作类型筛选和限制返回数量。

**请求方式**：GET

**请求路径**：`/salesforce/metadata/describe/history`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| operationType | String | 是 | 操作类型，可选值："describe"（描述元数据）、"list"（列出元数据） |
| limit | Integer | 否 | 返回数量限制，默认 10，最大 100 |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 查询历史列表（DataiMetadataDescribe[]） |

**DataiMetadataDescribe 结构**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 记录 ID |
| operationType | String | 操作类型（describe/list） |
| queryContent | String | 查询内容（JSON 格式） |
| resultCount | Integer | 结果数量 |
| status | String | 状态（Success/Failed） |
| errorMessage | String | 错误信息 |
| serverVersion | String | 服务器版本 |
| namespacePrefix | String | 命名空间前缀 |
| metadataObjectCount | Integer | 元数据对象数量 |
| queryTime | String | 查询时间（ISO 8601 格式） |
| createTime | String | 创建时间（ISO 8601 格式） |

**成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "operationType": "describe",
      "queryContent": null,
      "resultCount": null,
      "status": "Success",
      "errorMessage": null,
      "serverVersion": "59.0",
      "namespacePrefix": null,
      "metadataObjectCount": 250,
      "queryTime": "2026-02-06T10:30:00.000+08:00",
      "createTime": "2026-02-06T10:30:00.000+08:00"
    },
    {
      "id": 2,
      "operationType": "list",
      "queryContent": "[{\"type\":\"CustomObject\"}]",
      "resultCount": 50,
      "status": "Success",
      "errorMessage": null,
      "serverVersion": null,
      "namespacePrefix": null,
      "metadataObjectCount": null,
      "queryTime": "2026-02-06T10:35:00.000+08:00",
      "createTime": "2026-02-06T10:35:00.000+08:00"
    }
  ]
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "无效的操作类型，必须是 describe 或 list",
  "data": null
}
```

**错误码**：
- DESCRIBE_003：参数校验失败（无效的操作类型）
- DESCRIBE_008：未知错误

---

## 错误码列表

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| DESCRIBE_001 | 获取 Metadata 连接失败 | 无法获取 Salesforce Metadata 连接，可能是认证失败或网络问题 |
| DESCRIBE_002 | 描述元数据失败 | 调用 Salesforce describeMetadata API 失败 |
| DESCRIBE_003 | 参数校验失败 | 请求参数不符合要求（如查询列表为空、元数据类型为空、无效的操作类型等） |
| DESCRIBE_004 | 记录查询历史失败 | 写入数据库失败 |
| DESCRIBE_005 | 获取查询历史失败 | 从数据库查询历史记录失败 |
| DESCRIBE_006 | 列出元数据失败 | 调用 Salesforce listMetadata API 失败 |
| DESCRIBE_007 | 记录列出元数据历史失败 | 写入数据库失败 |
| DESCRIBE_008 | 未知错误 | 其他未预期的错误 |

## 使用示例

### 示例 1：描述元数据

**请求**：
```bash
curl -X GET "http://localhost:8080/salesforce/metadata/describe?apiVersion=59.0"
```

**响应**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "metadataObjects": [
      {
        "xmlName": "CustomObject",
        "directoryName": "objects",
        "suffix": "object",
        "inFolder": false,
        "metaFile": false
      }
    ],
    "serverVersion": "59.0"
  }
}
```

### 示例 2：列出元数据（单个查询）

**请求**：
```bash
curl -X POST "http://localhost:8080/salesforce/metadata/list" \
  -H "Content-Type: application/json" \
  -d '[{"type": "CustomObject"}]'
```

**响应**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "fullName": "Account",
      "type": "CustomObject",
      "createdByName": "Admin User",
      "lastModifiedByName": "Admin User"
    }
  ]
}
```

### 示例 3：列出元数据（多个查询，自动分批）

**请求**：
```bash
curl -X POST "http://localhost:8080/salesforce/metadata/list" \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "CustomObject"},
    {"type": "ApexClass"},
    {"type": "ApexTrigger"},
    {"type": "VisualforcePage"}
  ]'
```

**说明**：虽然请求包含 4 个查询，但 Service 层会自动分批处理（每次最多 3 个），对调用方透明。

### 示例 4：获取查询历史

**请求**：
```bash
curl -X GET "http://localhost:8080/salesforce/metadata/describe/history?operationType=list&limit=5"
```

**响应**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "operationType": "list",
      "queryContent": "[{\"type\":\"CustomObject\"}]",
      "resultCount": 50,
      "status": "Success",
      "queryTime": "2026-02-06T10:30:00.000+08:00"
    }
  ]
}
```

## 注意事项

1. **分批处理**：listMetadata 接口支持批量查询，但 Salesforce API 限制每次调用最多包含 3 个查询。Service 层会自动分批处理，对调用方透明。

2. **查询历史**：每次 describeMetadata 和 listMetadata 操作都会自动记录到数据库，包括操作类型、查询内容、结果数量、状态等信息。

3. **错误处理**：所有接口都遵循统一的错误处理规范，返回包含错误码和错误信息的 JSON 响应。

4. **性能考虑**：
   - describeMetadata 操作会返回大量元数据类型信息，建议在应用启动时缓存结果
   - listMetadata 操作涉及外部 API 调用，响应时间取决于查询的复杂度和数据量
   - 查询历史接口默认返回 10 条记录，最大支持 100 条

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-003-08-描述和列出元数据.md)
- [设计文档](../design/2026-02-03-003-08-描述和列出元数据-设计.md)
- [决策记录](../decisions/2026-02-03-003-08-ADR-描述和列出元数据技术选型.md)
- [变更日志](../changelog/2026-02-06-003-08-changelog.md)
- [复盘文档](../retros/2026-02-06-003-08-retro.md)
- [会话记录](../sessions/2026-02-03-003-08-session.md)