自定义接口配置

概述

当平台内置接口无法满足需求时，您可以自定义配置 HTTP 接口，实现与任何支持 HTTP/HTTPS 协议的外部系统集成。

创建接口平台

接口平台是一组相关接口的集合，通常对应一个外部系统（如 CRM 系统、ERP 系统等）。

操作步骤

进入系统管理后台
导航至 能力增强 > 集成管理
点击"添加平台"按钮
填写平台基本信息
保存平台信息

平台标识命名规范

使用小写字母、数字和下划线
以字母开头
具有描述性
示例：crm_system、erp_system、payment_gateway

配置示例

{
  "name": "CRM 系统",
  "platform_key": "crm_system",
  "category": "业务系统",
  "description": "客户关系管理系统，用于管理客户信息和销售流程",
}

创建 API 接口

在接口平台下创建具体的 API 接口定义。

操作步骤

在接口平台详情页，点击"添加API"
填写接口基本信息
配置请求参数
配置响应定义（可选）
保存接口配置

基本信息配置

字段	说明	示例
接口名称	接口的功能描述	查询客户详情
接口标识	英文标识，用于代码中引用	get_customer_detail
请求方式	GET/POST/PUT/DELETE/PATCH	GET
请求路径	接口的 URL 路径	/api/customers/{id}
描述	接口的详细说明	根据客户 ID 查询客户详细信息

请求方式说明

方式	说明	适用场景
GET	获取资源	查询数据、获取信息
POST	创建资源	提交数据、创建记录
PUT	更新资源（完整更新）	更新完整的数据记录
PATCH	更新资源（部分更新）	更新部分字段
DELETE	删除资源	删除数据记录

请求参数配置

请求参数分为以下几种类型：

1. 路径参数（Path Parameters）

在 URL 路径中的参数，使用 {参数名} 表示。配置path

示例：

路径：/api/customers/{id}
参数：id (客户ID)

2. 查询参数（Query Parameters）

在 URL 后面的查询字符串参数。配置query

示例：

URL：/api/customers?page=1&pageSize=20&keyword=张三

3. 请求头（Headers）

HTTP 请求头参数。配置headers

4. 请求体（Body）

POST、PUT、PATCH 请求的请求体。配置body

创建接口实例

接口实例包含了访问外部系统所需的具体配置信息。

操作步骤

进入系统管理后台
导航至 能力增强 > 集成管理 > 选择平台
点击"添加实例"
填写实例配置
保存实例

配置项说明

基本配置

字段	说明	示例
实例名称	实例的名称	CRM系统_生产环境
实例标识	英文标识	crm_prod
环境类型	dev/test/pre/prod	prod
基础 URL	接口的基础地址	https://api.example.com
超时时间	请求超时时间（毫秒）	30000
描述	实例说明	CRM系统生产环境实例

鉴权配置

根据外部系统的要求选择合适的鉴权方式，详细说明请参考鉴权方式详解。

默认请求头

为所有请求添加默认的请求头。

默认查询参数

为所有请求添加默认的查询参数。

示例：

{
  "defaultQuery": [
    {
      "key": "appId",
      "value": "your-app-id"
    }
  ]
}

测试调用

在接口配置完成后，建议先进行测试调用，确保接口配置正确。

操作步骤

接口详情页右侧
选择环境配置
填写测试参数
点击"发送请求"
查看响应结果

测试技巧

从简单到复杂
- 先测试不需要参数的接口
- 逐步增加参数复杂度
- 最后测试完整的业务场景
测试各种情况
- 正常情况：参数正确，返回成功
- 参数缺失：测试必填参数验证
- 参数错误：测试参数格式验证
- 鉴权失败：测试鉴权配置
查看详细信息
- 请求 URL
- 请求方法
- 请求头
- 请求参数
- 响应状态码
- 响应数据
- 响应时间
保存测试用例
- 将常用的测试参数保存为测试用例
- 方便后续快速测试

最佳实践

1. 接口命名规范（参考）

动词 + 名词 + 补充说明

示例：
- get_customer_list      // 获取客户列表
- create_order           // 创建订单
- update_user_info       // 更新用户信息
- delete_product         // 删除产品

2. 参数设计

使用清晰的参数名称
提供详细的参数说明
标注必填和可选参数
提供参数示例

3. 错误处理

定义统一的错误响应格式
提供清晰的错误信息
使用标准的 HTTP 状态码

4. 版本管理

在 URL 中包含版本号（如 /v1/api/...）
保持向后兼容
及时更新文档

5. 文档维护

为每个接口添加详细说明
提供请求和响应示例
记录常见问题和解决方法
及时更新变更记录