# 方案 B 重构清单（前后对比 · 修订版）

> **前提**：全量重构，不做旧字段兼容。  
> **修订要点**：先定义「一次 HTTP 请求」应保存哪些结构，再说明 **Mapping Body 仅在某些 Content-Type 下才存在**；`application/json` 的请求体参数树 **本身就是映射体**，不单独拆 Mapping Body。

---

## 1. 设计顺序（先看这个）

```text
第一步  请求接口应保存什么（与 Content-Type 无关 + 有关部分分开）
           Query / Header / Body 传输层 + 响应 + 基本信息

第二步  映射体放哪（由 Content-Type 决定）
           Json/Xml  → Body 参数树 = 映射体
           Form 类   → 传输用表单 KV + 独立 Mapping Body 树（表单字段可 $FromMappingBody）
```

**Mapping Body 不是每个接口都有**，只有「Body（或 Query）走表单 KV，且业务 JSON 需要单独做上游映射」时才配置。

---

## 2. 改造后：一次请求应保存什么（目标模型）

### 2.1 与 Content-Type **无关**（任何下游接口都有）

| 存储 | 表 | UI（对齐 ApiTest） | 说明 |
|------|-----|-------------------|------|
| **基本信息** | `t_interface` | 地址、Method、Protocol、ContentType、QPS… | 不变 |
| **Query** | `t_parameter_form`（FieldPosition=**Query**） | Query Tab，KV | 真实 URL Query，不仅 FormUrlEncoded 才有 |
| **Header** | `t_parameter_form`（FieldPosition=**Header**） | Header Tab，KV | 请求头；占位符 $TimeStamp、$token 等 |
| **Response** | `t_parameter`（IsInPara=false） | Response 参数树 | 不变 |
| **返回配置** | `t_interface_return_config` | 返回配置 Tab | 不变 |
| **cURL 示例** | `t_interface.InParams` | cURL Tab | 不变 |
| **服务商级 Fixed** | `t_parameter_fixed`（ServiceProviderId） | 不在接口明细维护 | Url 占位、服务商通用 Header、脚本写入 |

### 2.2 与 Content-Type **有关**（Body 区不同）

| ContentType | Body 传输层保存什么 | 映射体保存什么 | 是否需要 Mapping Body |
|-------------|---------------------|----------------|------------------------|
| **Json (3)** | **`requestBodyParameterList`** 参数树 | **同一棵树** | **否** |
| **Xml (4)** | **`requestBodyParameterList`** 参数树 | **同一棵树** | **否** |
| **FormUrlEncoded (1)** | **`bodyFormParameterList`** KV | **`mappingBodyParameterList`** 参数树 | **是** |
| **FormData (2)** | 二期：`bodyForm` 或 multipart 描述 | 若字段内嵌 JSON，同 FormUrlEncoded | 二期 |
| **上游接口** | **`inParameterList`** 树（业务入参） | **同一棵树** | **否** |

### 2.3 结构总图（改造后）

```text
                    ┌─ 基本信息 (t_interface)
                    │
  任意 Content-Type ├─ queryFormParameterList   (t_parameter_form, Query)
                    ├─ headerFormParameterList  (t_parameter_form, Header)
                    │
                    ├─ Body 区 ─────────────────────────────────────┐
                    │                                                │
                    │   Json/Xml          FormUrlEncoded              │
                    │   requestBody       bodyFormParameterList       │
                    │   ParameterList     (KV 传输)                   │
                    │   (树=映射体)       mappingBodyParameterList    │
                    │                     (树=仅映射体)               │
                    └────────────────────────────────────────────────┘
                    │
                    ├─ outParameterList (出参树)
                    └─ inParams (cURL 示例)
```

### 2.4 页面 Tab（下游接口 · 按 Content-Type 显示）

| Tab | Json / Xml | FormUrlEncoded |
|-----|------------|----------------|
| Query | 显示 KV | 显示 KV |
| Header | 显示 KV | 显示 KV |
| **Body** | **参数树**（= 映射体） | **KV 表**（传输） |
| **Mapping Body** | **隐藏** | **显示**（参数树） |
| cURL | 显示 | 显示 |
| Response | 显示 | 显示 |
| ~~固定配置~~ | 删除（接口级） | 删除 |

与 ApiTest 对齐方式：

- ApiTest 的 Request Tab：Json 时常用 Raw；**接口配置**里 Json 仍用 **参数树** 定义结构（itfx 现有能力，且即映射体）。
- ApiTest 的 FormUrlEncoded：URL Encoded KV = 我们的 **bodyForm**；映射结构不在调试页里，在接口配置里用 **Mapping Body** 维护。

---

## 3. Mapping Body 何时存在（规则定稿）

| 条件 | 结论 |
|------|------|
| `ContentType = Json` 或 `Xml` | **没有** `mappingBodyParameterList`；`requestBodyParameterList` 参与 `InParamRestructure` 且被 `SerializationBody` 序列化 |
| `ContentType = FormUrlEncoded` | **有** `bodyFormParameterList` + **有** `mappingBodyParameterList`；映射只对 Mapping Body 树；表单字段值可为 `$FromMappingBody` |
| Query 上也有「值为 JSON」的罕见情况 | 仍用 Mapping Body 树做映射，Query KV 里字段填 `$FromMappingBody`（与 Body 表单同理） |
| 上游 `IsUpStream=true` | 始终只有 **`inParameterList`**，无 Mapping Body、无 bodyForm |

**占位符**

| 占位符 | 用于 | Content-Type |
|--------|------|----------------|
| `$FromMappingBody` | Form 的 Query/Body（及必要时 Header）字段引用映射结果 | **仅 Form 类** |
| `$FromBody` | **删除**下游表单中的用法 | — |
| Json Body 树字段 | 直接映射到 alias，**不需要**占位符塞整段 JSON | Json / Xml |

---

## 4. 数据库（修订）

### 4.1 `t_parameter_form` — 传输层 KV

**新增** `FieldPosition`：Header=1, Body=2, Query=3。

| FieldPosition | 何时有数据 |
|---------------|------------|
| Query | 任意 Content-Type，有 URL 参数就配 |
| Header | 任意 Content-Type |
| Body | **主要 FormUrlEncoded**；Json/Xml 通常 **无 body 行**（Body 在参数树） |

### 4.2 `t_parameter` — 参数树

**新增** `ParaKind`：

| ParaKind | 含义 | 用于 |
|----------|------|------|
| **0 Normal** | 默认 | 出参；**上游入参**；Json/Xml 的 **RequestBody** |
| **1 MappingBody** | 仅映射、不直接当 HTTP Json Body | **仅** FormUrlEncoded（及日后 FormData）且需要独立映射体时 |

| 列表字段 | ParaKind | IsInPara |
|----------|----------|----------|
| `requestBodyParameterList` | Normal（或枚举值 RequestBody=0） | true |
| `mappingBodyParameterList` | **MappingBody** | true |
| `outParameterList` | Normal | false |

**删除的用法**

- 不再用「一棵 in 树」同时表示 Form 映射 + Json Body（改造前混用）。

### 4.3 `t_parameter_fixed`

- **删**：接口明细维护接口级 Header/Query/Body KV。
- **留**：服务商级、Url、脚本动态 Header。

---

## 5. SaveInterface / GetInterfaceById（请求结构）

`POST /api/Interface/SaveInterface` · 响应为接口 `id`（number）。  
`GetInterfaceById` 字段与保存一致。已删除：`formParameterList`、下游 `inParameterList`。

### 5.1 根对象

| 字段 | 说明 |
|------|------|
| `optionType` | `1` 增 / `3` 改 / `2` 删 |
| `isUpStream` | `true` 上游 / `false` 下游 |
| `serviceProviderId` | 上游 `0` |
| `id` | 改、删必填 |
| `name`, `requestAddress`, `requestProtocol`, `requestMethod`, `contentType` | 基本信息 |
| `code`, `category`, `description`, `isBatch`, `limit`, `responseContentType`, `flowCode`, `isDisableAuth`, `qps`, `mappedParamType`, `inParams` | 可选 |
| `queryFormParameterList` | Query KV，`fieldPosition=3` |
| `headerFormParameterList` | Header KV，`fieldPosition=1` |
| `outParameterList` | 出参树 |
| `requestBodyParameterList` | **仅下游 Json/Xml**，Body 树 = 映射体 |
| `bodyFormParameterList` | **仅下游 FormUrlEncoded**，Body KV |
| `mappingBodyParameterList` | **仅下游 FormUrlEncoded**，映射树 |
| `inParameterList` | **仅上游**入参树 |

### 5.2 Body 字段互斥

| 场景 | 传 | 不传 |
|------|-----|------|
| 下游 Json/Xml (`contentType` 3/4) | `requestBodyParameterList` | `bodyForm*`、`mappingBody*`、`inParameterList` |
| 下游 FormUrlEncoded (`1`) | `bodyFormParameterList` + `mappingBodyParameterList` | `requestBody*`、`inParameterList` |
| 上游 | `inParameterList` | `requestBody*`、`bodyForm*`、`mappingBody*` |

### 5.3 子结构

**FormParameterInput**（Query / Header / Body 行）

```json
{ "optionType": 1, "id": 0, "name": "字段名", "value": "$FromMappingBody", "description": "", "fieldPosition": 2 }
```

`fieldPosition`：`1` Header · `2` Body · `3` Query。Form 业务 JSON 字段用 `$FromMappingBody`。

**ParameterInput**（树节点：requestBody / mappingBody / in / out）

```json
{ "optionType": 1, "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3, "isRequired": true, "sort": "1", "paraKind": 0 }
```

`paraKind`：`0` Normal（requestBody、上游 in、出参）· `1` MappingBody（仅 mappingBody 列表）。新增时 `id`/`pId` 需表达父子关系。

---

## 5.4 示例

**下游 · Json**（`contentType: 3`）

```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, "paraKind": 0 }
  ],
  "outParameterList": []
}
```

**下游 · FormUrlEncoded**（`contentType: 1`）

```json
{
  "optionType": 3,
  "isUpStream": false,
  "serviceProviderId": 5,
  "id": 1001,
  "name": "1688回调",
  "requestAddress": "https://gw.open.1688.com/openapi/http",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 1,
  "queryFormParameterList": [
    { "optionType": 3, "id": 11, "name": "_aop_timestamp", "value": "$TimeStamp", "description": "ms", "fieldPosition": 3 }
  ],
  "headerFormParameterList": [],
  "bodyFormParameterList": [
    { "optionType": 3, "id": 10, "name": "notifyBizEventDTO", "value": "$FromMappingBody", "fieldPosition": 2 },
    { "optionType": 3, "id": 13, "name": "_aop_signature", "value": "", "fieldPosition": 2 }
  ],
  "mappingBodyParameterList": [
    { "optionType": 3, "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3, "paraKind": 1 },
    { "optionType": 3, "id": 2, "pId": 1, "name": "orderId", "alias": "orderId", "type": 1, "paraKind": 1 }
  ],
  "outParameterList": []
}
```

**上游**（`isUpStream: true`）

```json
{
  "optionType": 1,
  "isUpStream": true,
  "serviceProviderId": 0,
  "name": "标准创建订单",
  "requestAddress": "/api/order/create",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 3,
  "queryFormParameterList": [],
  "headerFormParameterList": [],
  "inParameterList": [
    { "optionType": 1, "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3, "paraKind": 0 }
  ],
  "outParameterList": []
}
```

---

## 6. 转发逻辑（修订）

### 6.1 映射树来源（InParamTreeList）

| ContentType | InParamTreeList 来源 |
|-------------|----------------------|
| Json / Xml | **`requestBodyParameterList`**（整棵树） |
| FormUrlEncoded | **`mappingBodyParameterList`** |
| 上游 | 系统接口 **inParameterList**（映射配置页不变） |

### 6.2 HTTP 组装

| 部分 | 来源 |
|------|------|
| URL Query | `queryFormParameterList`（+ 服务商 Fixed Query） |
| Header | `headerFormParameterList`（+ 服务商 Fixed Header） |
| Body Json | `Serialize(requestBodyParameterList` 映射结果 `)` |
| Body FormUrlEncoded | 仅 **`bodyFormParameterList`**；其中 `$FromMappingBody` ← 映射结果序列化 |
| Body Xml | 同 Json，Xml 序列化 |

### 6.3 流程对比（两张）

**Json 下游（无 Mapping Body）**

```text
上游 JSON → Restructure(requestBodyParameterList) → OriginalInterfaceMappedInput
         → ReplacePlaceholder(Query/Header form + Fixed)
         → SerializationBody(Json) → HTTP Body
         → 拼 Query / Header
```

**FormUrlEncoded 下游（有 Mapping Body）**

```text
上游 JSON → Restructure(mappingBodyParameterList) → OriginalInterfaceMappedInput
         → ReplacePlaceholder（含 bodyForm 的 $FromMappingBody）
         → bodyForm 字典 → HTTP Body
         → 拼 Query / Header
```

---

## 7. 前后对比总表（增删改）

### 7.1 删除了什么

| 类别 | 内容 |
|------|------|
| API | 下游 `formParameterList`、下游笼统的 `inParameterList`（拆开后互斥） |
| UI | 固定配置 Tab；接口级 Fixed API |
| 语义 | 所有下游共用一棵 in 树；Form 无 position；Json 也搞 Mapping Body Tab |
| 占位 | 下游表单用 `$FromBody` 表示整段 JSON |

### 7.2 新增了什么

| 类别 | 内容 |
|------|------|
| 表 | `t_parameter_form.FieldPosition`；`t_parameter.ParaKind` |
| API | `queryFormParameterList`、`headerFormParameterList`（**全类型共有**） |
| API | `bodyFormParameterList`（**仅 Form 类**） |
| API | `requestBodyParameterList`（**仅 Json/Xml**，=映射体） |
| API | `mappingBodyParameterList`（**仅 Form 类**） |
| UI | Header Tab；Form 时 Mapping Body Tab；Json 时 Body=树 |
| 占位 | `$FromMappingBody`（**仅 Form KV**） |

### 7.3 改了什么

| 项 | 改造前 | 改造后 |
|----|--------|--------|
| Query | 假 Query（实为 form body） | 真 Query KV，**所有 Content-Type** |
| Body Tab | 永远是参数树 | **Json=树**；**Form=KV** |
| 映射体 | 永远 in 树 | **Json=Body 树**；**Form=Mapping Body 树** |
| 保存 | form + in 混传 | 按 ContentType 传 **互斥** 的 Body 相关列表 |
| 映射 SQL | 下游 IsInPara 全量 | Json：RequestBody 树；Form：**ParaKind=MappingBody** |

---

## 8. Content-Type 全量对照（改造后）

| ContentType | queryForm | headerForm | bodyForm | requestBody 树 | mappingBody 树 | 映射目标 | HTTP Body |
|-------------|-----------|------------|----------|----------------|----------------|----------|-----------|
| **Json** | 可选 | 可选 | **不用** | **必填** | **不用** | requestBody 树 | 序列化该树 |
| **Xml** | 可选 | 可选 | **不用** | **必填** | **不用** | requestBody 树 | Xml 序列化 |
| **FormUrlEncoded** | 常用 | 常用 | **必填** | **不用** | **必填** | mappingBody 树 | bodyForm 字典 |
| **FormData** | 二期 | 二期 | 二期 | **不用** | 二期 | 二期 | 二期 |
| **上游 Json** | — | — | — | **inParameterList** | — | in 树 | — |

---

## 9. 一句话

| | 改造前 | 改造后 |
|---|--------|--------|
| 先保存什么 | form + in 混在一起 | **先** Query/Header（通用）+ **再按 Content-Type 存 Body** |
| Json | in 树 = 映射 + Body | **requestBody 树 = 映射体**，不要 Mapping Body |
| Form | in 树 + form 表 | **bodyForm 传输** + **mappingBody 映射** |
| Mapping Body | （之前文档）每个下游都有 | **仅 Form 类需要** |

---

*文档版本：2026-06-02 · 含 SaveInterface 结构与示例（§5）*