front/docs/前端调整.md

前端调整清单如下，核心是：下游不再用 inParameterList / formParameterList，改为按 ContentType 拆分 Body、Query、Header。

1. 接口详情页字段调整

删除/停用

• 下游接口不要再使用 inParameterList
• 不再使用 formParameterList
• 删除接口级“固定配置”Tab
• 下游表单中不再使用 $FromBody

新增字段

SaveInterface / GetInterfaceById 使用这些字段：

queryFormParameterList: FormParameterInput[]
headerFormParameterList: FormParameterInput[]
bodyFormParameterList: FormParameterInput[]

requestBodyParameterList: ParameterInput[]
mappingBodyParameterList: ParameterInput[]

inParameterList: ParameterInput[]
outParameterList: ParameterInput[]

---

2. 按 ContentType 显示 Tab

Json / Xml 下游

显示：

• Query：KV
• Header：KV
• Body：参数树
• Response：参数树
• cURL：原样保留

隐藏：

• Mapping Body
• Body Form KV
• 上游 inParameterList

保存时传：

queryFormParameterList
headerFormParameterList
requestBodyParameterList
outParameterList

不要传：

inParameterList
bodyFormParameterList
mappingBodyParameterList

---

FormUrlEncoded 下游

显示：

• Query：KV
• Header：KV
• Body：KV 表
• Mapping Body：参数树
• Response：参数树
• cURL：原样保留

保存时传：

queryFormParameterList
headerFormParameterList
bodyFormParameterList
mappingBodyParameterList
outParameterList

不要传：

inParameterList
requestBodyParameterList

---

上游接口

显示：

• In Parameters：参数树
• Response：参数树

保存时传：

inParameterList
outParameterList

不要传：

requestBodyParameterList
mappingBodyParameterList
bodyFormParameterList

queryFormParameterList、headerFormParameterList 可以传空数组。

---

3. FormParameterInput 调整

新增字段：

fieldPosition: 1 | 2 | 3

含义：

1 = Header
2 = Body
3 = Query

结构：

interface FormParameterInput {
  optionType: number
  id: number
  name: string
  value: string
  description?: string
  fieldPosition: 1 | 2 | 3
}

前端保存前要自动补：

• queryFormParameterList[*].fieldPosition = 3
• headerFormParameterList[*].fieldPosition = 1
• bodyFormParameterList[*].fieldPosition = 2

---

4. ParameterInput 调整

新增字段：

paraKind: 0 | 1

含义：

0 = Normal
1 = MappingBody

结构：

interface ParameterInput {
  optionType: number
  id: number
  pId: number
  name: string
  alias?: string
  cnName?: string
  type: number
  isRequired: boolean
  sort?: string
  description?: string
  paraKind: 0 | 1
}

前端保存前要自动补：

• 上游 inParameterList[*].paraKind = 0
• 下游 Json/Xml requestBodyParameterList[*].paraKind = 0
• 下游 FormUrlEncoded mappingBodyParameterList[*].paraKind = 1
• outParameterList[*].paraKind = 0

---

5. 占位符调整

新增：

$FromMappingBody

用于：

• FormUrlEncoded 的 bodyFormParameterList
• 必要时 Query/Header KV 引用映射结果

删除/停用：

$FromBody

FormUrlEncoded 示例：

{
  "name": "notifyBizEventDTO",
  "value": "$FromMappingBody",
  "fieldPosition": 2
}

---

6. SaveInterface 请求组装

Json 下游示例

{
  "optionType": 1,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "创建订单",
  "requestAddress": "https://api.example.com/order",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 3,

  "queryFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "access_token",
      "value": "$FromAccount",
      "fieldPosition": 3
    }
  ],
  "headerFormParameterList": [],
  "requestBodyParameterList": [
    {
      "optionType": 1,
      "id": 1,
      "pId": 0,
      "name": "orderId",
      "alias": "orderId",
      "type": 1,
      "isRequired": true,
      "paraKind": 0
    }
  ],
  "outParameterList": [],

  "inParameterList": [],
  "bodyFormParameterList": [],
  "mappingBodyParameterList": []
}

FormUrlEncoded 下游示例

{
  "optionType": 1,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "1688回调",
  "requestAddress": "https://gw.open.1688.com/openapi/http",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 1,

  "queryFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "_aop_timestamp",
      "value": "$TimeStamp",
      "description": "ms",
      "fieldPosition": 3
    }
  ],
  "headerFormParameterList": [],
  "bodyFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "notifyBizEventDTO",
      "value": "$FromMappingBody",
      "fieldPosition": 2
    }
  ],
  "mappingBodyParameterList": [
    {
      "optionType": 1,
      "id": 1,
      "pId": 0,
      "name": "order",
      "alias": "order",
      "type": 3,
      "isRequired": true,
      "paraKind": 1
    }
  ],
  "outParameterList": [],

  "inParameterList": [],
  "requestBodyParameterList": []
}

---

7. GetInterfaceById 回填规则

后端现在会返回：

queryFormParameterList
headerFormParameterList
bodyFormParameterList
requestBodyParameterList
mappingBodyParameterList
inParameterList
outParameterList

前端回填时：

• Json/Xml：Body Tab 绑定 requestBodyParameterList
• FormUrlEncoded：Body Tab 绑定 bodyFormParameterList
• FormUrlEncoded：Mapping Body Tab 绑定 mappingBodyParameterList
• 上游：入参树绑定 inParameterList
• Response：绑定 outParameterList
• Query：绑定 queryFormParameterList
• Header：绑定 headerFormParameterList

---

8. 映射页面调整

下游映射目标参数来源改为：

if (downstream.contentType === 1) {
  // FormUrlEncoded
  targetTree = mappingBodyParameterList
} else if (downstream.contentType === 3 || downstream.contentType === 4) {
  // Json / Xml
  targetTree = requestBodyParameterList
}

不要再用下游 inParameterList。

---

9. 前端校验规则

保存前校验：

上游

必须：

inParameterList

禁止有值：

requestBodyParameterList
mappingBodyParameterList
bodyFormParameterList

下游 Json / Xml

必须：

requestBodyParameterList

禁止有值：

inParameterList
mappingBodyParameterList
bodyFormParameterList

下游 FormUrlEncoded

必须：

bodyFormParameterList
mappingBodyParameterList

禁止有值：

inParameterList
requestBodyParameterList

---

10. 页面文案建议

• Query：请求 Query 参数
• Header：请求 Header 参数
• Body：
  • Json/Xml：请求体结构
  • FormUrlEncoded：表单字段
• Mapping Body：业务 JSON 映射体
• Response：响应结构

$FromMappingBody 显示文案：

引用 Mapping Body 映射结果

$FromBody 从下拉选项中移除。