# Like API 开发指引

> 本文面向 **开发 / 实施** 同学：下游传输层与映射体、占位符、脚本与网关转发细节。  
> 运营向配置步骤见同页「运营」Tab。下文单号、密钥为**示例**。

---

## 1. Like API 做什么？

Like API 是 **API 转发与参数映射中台**：

| 能力 | 说明 |
|------|------|
| 统一入口 | 业务只调 **上游标准接口**（`standardCode`） |
| 真实转发 | 网关按 **下游接口**（`supplierCode`）组装 HTTP |
| 结构转换 | **入参 / 出参映射** 在标准 JSON 与服务商结构之间转换 |
| 脚本扩展 | **前置 / 后置脚本**（签名、鉴权等） |
| 可观测 | 请求日志、调用统计、重试 |

---

## 2. 核心名词

| 名词 | 含义 |
|------|------|
| **上游接口** | 对业务暴露的 API，`standardCode` |
| **下游接口** | 服务商真实 API，`supplierCode` |
| **服务商** | 外部系统提供方（运输、轨迹、关务等） |
| **映射** | 一条「上游 ↔ 下游」绑定，含字段对应关系与脚本 |
| **应用** | 调用方：`appKey`、接口权限、IP 白名单 |
| **发布** | 保存后发布，网关才按新版本转发 |

网关调用：`appKey` + Query 中 `standardCode` / `supplierCode` + Body 标准 JSON。

---

## 3. 一次转发怎么走？

```text
业务 JSON
  ▼
鉴权 → 入参映射（标准 → 下游映射树）→ 占位符替换 → 前置脚本
  ▼
组装 Query / Header / Body → HTTP 请求服务商
  ▼
后置脚本 → 出参映射（下游响应 → 标准）→ 返回业务
```

---

## 4. 两层配置：传输 vs 映射

| 层次 | 含义 | 配置位置 |
|------|------|----------|
| **传输层** | 真实 HTTP 上出现的 Query、Header、Body 字段名与占位符 | 下游接口：Query / Header / Body（KV 或树） |
| **映射体** | 业务 JSON 要落到服务商的**字段树** | Json/Xml：**Body 树**；Form：**Mapping Body 树** |

```text
任意下游接口：基本信息 + Query + Header + Response + 示例

Body 区：
  Json/Xml        → Body 参数树（一棵树 = 映射体 + 序列化来源）
  FormUrlEncoded  → Body 表单 KV（传输）+ Mapping Body 树（仅映射体）
```

**Mapping Body 仅 FormUrlEncoded 需要。** Json/Xml 不显示 Mapping Body Tab。

---

## 5. 下游接口详解

**菜单**：`下游接口` → 左侧选 **服务商** → 右侧 **接口列表** → 点接口进入明细（弹窗/页）。

### 5.1 基本信息

| 字段 | 说明 |
|------|------|
| 接口名称 / code | 展示名与 `supplierCode` |
| 请求地址 | 路径部分（不含 Query），如 `/openapi/.../notifyEvent/10001` |
| 请求协议 / 方法 | Http/Https、GET/POST 等 |
| **ContentType** | 决定下方显示哪些 Tab（见 5.2） |
| 返回类型 | 响应 Json/Xml 等 |
| QPS、备注 | 限流与说明 |

ContentType 选错会导致 Tab 与保存字段不匹配，保存时前端会校验。

### 5.2 按 ContentType 显示的 Tab

#### Json / Xml（contentType = 3 / 4）

| Tab | 填什么 | 对应保存字段 | 转发时作用 |
|-----|--------|--------------|------------|
| **Query** | 键值对 | `queryFormParameterList` | 拼到 URL `?` 后 |
| **Header** | 键值对 | `headerFormParameterList` | 请求头 |
| **Body** | **参数树**（可父子级） | `requestBodyParameterList` | **映射目标 + JSON/XML Body 来源** |
| **Response** | 出参树 | `outParameterList` | 出参映射目标 |
| **示例** | 原始 cURL | `inParams` | 文档/对照，不参与转发 |

保存时传：`queryFormParameterList`、`headerFormParameterList`、`requestBodyParameterList`、`outParameterList`。  
不传：`bodyFormParameterList`、`mappingBodyParameterList`。

#### FormUrlEncoded（contentType = 1）

| Tab | 填什么 | 对应保存字段 | 转发时作用 |
|-----|--------|--------------|------------|
| **Query** | 键值对 | `queryFormParameterList` | URL 参数 |
| **Header** | 键值对 | `headerFormParameterList` | 请求头 |
| **Body** | **表单 KV**（无父子树） | `bodyFormParameterList` | **HTTP Body**（`application/x-www-form-urlencoded`） |
| **Mapping Body** | **参数树** | `mappingBodyParameterList` | **仅入参映射目标**（`paraKind = MappingBody`） |
| **Response** | 出参树 | `outParameterList` | 出参映射 |
| **示例** | cURL | `inParams` | 对照 |

保存时传：`queryFormParameterList`、`headerFormParameterList`、`bodyFormParameterList`、`mappingBodyParameterList`、`outParameterList`。  
不传：`requestBodyParameterList`。

### 5.3 Query / Header / Body KV 怎么填

每一行 KV 结构：

| 列 | 说明 |
|----|------|
| 参数名 | 与服务商文档一致，如 `_aop_signature`、`notifyBizEventDTO` |
| 值 | **占位符**或留空，不要填生产签名 |
| 描述 | 可写 curl 示例原文，便于对照 |

`fieldPosition`（保存时自动带上）：

| 值 | 含义 |
|----|------|
| 3 | Query |
| 1 | Header |
| 2 | Body（仅 Form 的 Body 表单 Tab） |

**常用占位符**

| 场景 | 值示例 |
|------|--------|
| 签名 | 留空，前置脚本写入 |
| 时间戳 | `$TimeStamp` |
| 账户字段 | `$FromAccount` |
| Token | `$token` |
| Form 上要带「整段映射后的 JSON」 | `$FromMappingBody` |

**Query 上的业务 DTO（常见开放平台）**

若 cURL 是 `POST 'https://host/path?sign=xxx&bizEventDto={...}'` 且 **没有** `--data`：

- `bizEventDto` 留在 **Query**，值为 `$FromMappingBody`；
- JSON 结构进 **Mapping Body** 参数树；
- **不要**把该 DTO 填进 Body 表单（Body 表单在无 POST body 时可为空）。

### 5.4 Body 参数树（Json/Xml）

列：**排序、参数名、必填、参数类型、参数描述、操作**。

| 要点 | 说明 |
|------|------|
| 树形 | `id` / `pId` 表示父子；对象、数组可展开子节点 |
| `alias` | 映射连线用，通常与 `name` 一致 |
| `paraKind` | Json/Xml Body 为 **Normal（0）** |
| 类型 | String / Integer / Object / Array 等与 `ParameterType` 枚举一致 |
| 内嵌 JSON 字符串 | 如 `extInfo` 整段作 String，不展开内部 JSON（智能填充已按此规则） |

这棵树在 **入参映射** 时作为下游目标树（见第 6 节）。

### 5.5 Mapping Body 参数树（仅 Form）

列与 Json Body 树相同，但语义不同：

| 要点 | 说明 |
|------|------|
| 只描述业务 JSON | 不直接等于 HTTP Body 字节 |
| `paraKind` | **MappingBody（1）** |
| 入参映射 | 映射页右侧 **只读这棵树** |
| 与 Body 表单配合 | 表单里某字段 `$FromMappingBody` ← 映射结果序列化 |

### 5.6 Body 表单（仅 Form 传输层）

| 要点 | 说明 |
|------|------|
| 扁平 KV | 一行一个表单字段 |
| 典型行 | `notifyBizEventDTO` = `$FromMappingBody`；`_aop_signature` = 空（脚本填） |
| 序列化 | 转发时把各行拼成 `key=value&...` 作为 HTTP Body |

### 5.7 Response 与返回配置

- **Response**：服务商返回 JSON/XML 的字段树，供 **出参映射** 使用。  
- **返回配置**（若有）：按业务规则判断成功/失败码等。

### 5.8 智能填充

路径：接口明细 → **智能填充** → 粘贴 cURL → **填充到表单**。

| 识别为 | 自动写入 |
|--------|----------|
| Json / Xml | Query、Header、**Body 参数树** |
| FormUrlEncoded | Query、Header、**Mapping Body 树**；有 `--data` 表单时再加 **Body KV** |

| 规则 | 行为 |
|------|------|
| 签名字段 | 值留空 |
| Query 上 *DTO / JSON 形态 | 值 `$FromMappingBody` |
| curl 示例原文 | 写入对应行 **描述** |
| 弹窗内容 | **不预置** cURL，请粘贴自有导出 |

填充后务必打开 **Mapping Body** 或 **Body** Tab 展开树，确认子级完整后再保存。

### 5.9 保存与发布

1. **保存**：按 ContentType 校验必填列表（如 Form 必须有 `mappingBodyParameterList` 与 `bodyFormParameterList`）。  
2. **发布**：下游接口列表或发布流程中发布；未发布则映射/转发可能仍用旧版。  
3. **服务商账户**：`$FromAccount` 等依赖账户配置，在服务商下维护。

### 5.10 配置自检清单（下游）

| 检查项 | Json | Form |
|--------|------|------|
| ContentType 与 cURL 一致 | ✓ | ✓ |
| 签名未写死在 KV | ✓ | ✓ |
| 映射树 Tab 有业务字段 | Body 树 | Mapping Body 树 |
| DTO 位置与真实 HTTP 一致 | Body 即 JSON | Query/Body KV + Mapping Body |
| 已发布 | ✓ | ✓ |

---

## 6. 映射详解

**菜单位置**：`上游接口` → 选中标准接口 → **映射明细** Tab。

一条映射 = **一个上游接口** + **一个服务商** + **一个下游接口** + 入参/出参对应 + 可选脚本。

### 6.1 映射解决什么问题？

业务只认识标准字段：

```json
{ "orderNo": "ORDER001", "eventCode": "DEMO" }
```

服务商可能要：

- Json：`{ "order": { "orderId": "ORDER001" }, "event": "DEMO" }`  
- Form：Query 上 `bizDto=整段JSON` + Mapping Body 里 `order.orderId` 等结构  

**入参映射**把标准树 **Restructure** 到下游映射树节点；**出参映射**把下游响应树还原为标准树。

### 6.2 创建映射

1. 上游接口页 → **添加映射**（或映射列表中新增）。  
2. 选择 **服务商**、**下游接口**（需已保存并最好已发布）。  
3. 进入该映射的 **映射明细** 编辑入参/出参/脚本。  
4. **保存映射** → **发布**（映射也有发布态，未发布不生效）。

### 6.3 映射明细页结构

| 区域 | 作用 |
|------|------|
| 映射列表 | 一个上游可绑多条下游（1:N 顺序调用） |
| **入参映射** | 标准字段 → 下游字段 |
| **出参映射** | 下游响应 → 标准字段 |
| **前置脚本** | 转发前：签名、改 Header/Form 字段等 |
| **后置脚本** | 转发后：改响应、补充字段 |
| **API 调试** | 带 `standardCode` / `supplierCode` 的联调 |
| **接口明细** | 跳转/view 上游 In Parameters |

### 6.4 入参映射：下游目标树从哪来？

网关 Restructure 时用的 **InParamTreeList** 来源：

| 下游 ContentType | 映射页右侧「下游参数树」来源 |
|------------------|------------------------------|
| **Json / Xml** | 下游接口的 **`requestBodyParameterList`**（Body Tab 那棵树） |
| **FormUrlEncoded** | 下游接口的 **`mappingBodyParameterList`**（Mapping Body Tab） |

| 左侧 | 右侧 |
|------|------|
| 上游 **In Parameters** 树 | 上述下游目标树 |

操作方式（界面为可视化连线/选目标节点）：

- 把上游节点映射到下游节点（按 `alias` / 节点 id 建立关系）；  
- 支持对象、数组层级；数组通常映射到数组下唯一子元素规则（与参数校验一致）；  
- 未映射的上游字段不会出现在下游映射结果中（除非脚本补充）。

**不要**在 Form 场景下去连 Body 表单 KV 行——表单行是传输层；业务字段应对 Mapping Body 树。

### 6.5 FormUrlEncoded 入参 + 转发数据流

```text
业务标准 JSON
  ▼ 入参映射（对 mappingBodyParameterList）
下游映射结果对象（内存）
  ▼ 占位符替换
Query/Header/Body KV 中的 $FromMappingBody 被替换为序列化后的 JSON 字符串
  ▼ 前置脚本（如写 _aop_signature）
  ▼ 拼 Query + Header + application/x-www-form-urlencoded Body
  ▼ HTTP POST 服务商
```

要点：

| 步骤 | 配置位置 |
|------|----------|
| 结构定义 | 下游 **Mapping Body** |
| 谁带 JSON 字符串 | Query 或 Body 表单里值为 `$FromMappingBody` 的字段 |
| 签名 | **前置脚本** 写 Query/FormFieldList |

### 6.6 Json 入参 + 转发数据流

```text
业务标准 JSON
  ▼ 入参映射（对 requestBodyParameterList）
下游映射结果对象
  ▼ 占位符替换（Query/Header KV）
  ▼ 前置脚本
  ▼ SerializationBody → JSON HTTP Body
  ▼ HTTP 请求
```

要点：

| 步骤 | 配置位置 |
|------|----------|
| 结构与映射 | 下游 **Body 参数树**（同一棵） |
| Query/Header | 独立 KV，一般不用 `$FromMappingBody` 塞整段 Body |

### 6.7 出参映射

| 左侧 | 右侧 |
|------|------|
| 下游 **Response** 树 | 上游 **Response** 树 |

用于把服务商返回字段映射成业务标准响应。保存、发布规则与入参映射相同。

### 6.8 前置 / 后置脚本

| 类型 | 时机 | 常见用途 |
|------|------|----------|
| **前置** | HTTP 发出前 | HMAC/MD5 签名、刷新 token、改 Query |
| **后置** | 收到响应后 | 统一包装、字段修正 |

Form 场景脚本常操作 **`FormFieldList`**（含 Query/Body 位置的表单字段）；  
Json 场景常操作 **`OriginalInterfaceMappedInput`**（映射后的对象）。

签名算法需与下游 Query/Header/Body **字段名**一致（在下游接口里配好的名）。

### 6.9 1:N 映射（一个上游多个下游）

| 场景 | 说明 |
|------|------|
| 顺序调用 | 映射列表多条，按顺序执行 |
| 入参分包 | 业务在标准 JSON 里按包名区分给不同下游的数据 |
| 每条映射 | 各自选服务商 + 下游接口 + 独立入参/出参/脚本 |

### 6.10 映射配置自检

| 检查项 | 说明 |
|--------|------|
| 下游接口已发布 | 目标树与线上一致 |
| Form 映射连的是 **Mapping Body** | 不是 Body 表单行 |
| Json 映射连的是 **Body 树** | |
| 需要签名的字段在下游已留空 | 脚本字段名一致 |
| `$FromMappingBody` 字段名与传输层一致 | 如 Query 的 `bizEventDto` |
| 映射已发布 | |
| 应用已分配上游接口且上线 | |

### 6.11 上游接口（映射左侧）

| Tab | 作用 |
|-----|------|
| **In Parameters** | 业务标准入参树 → 入参映射左侧 |
| **Response** | 标准出参树 → 出参映射左侧 |
| 保存字段 | `inParameterList`、`outParameterList` |

上游无 Query/Header/Body 分离；无 Mapping Body。

---

## 7. 推荐上手顺序

1. **下游接口**：智能填充 cURL → 核对 Tab → 保存发布。  
2. **上游接口**：In Parameters / Response → 保存发布。  
3. **映射**：添映射 → 入参/出参 → 前置脚本 → 保存发布映射。  
4. **应用**：授权上游接口 → 上线。  
5. **验证**：网关调用或内嵌 ApiTest → **请求日志** 对报文。

```http
POST /InterfaceForward/ForwardWithSubscribe?standardCode=YOUR_STD&supplierCode=YOUR_SUP
Content-Type: application/json
appKey: YOUR_APP_KEY

{ "orderNo": "ORDER001" }
```

---

## 8. 指引页与调试入口（当前前端）

| 入口 | 路径 / 位置 | 说明 |
|------|-------------|------|
| 本页指引 | `/api/apiDebugger` | 「运营 / 开发」双 Tab Markdown；**不再内嵌**自由调试面板 |
| 独立调试页 | `/api/apiTest` | 通用 `ApiTest`：任意 URL，不绑 standardCode |
| 上游 / 下游内嵌 | 接口详情 → API 调试 Tab | 带当前接口 code，可对照 **示例** cURL |

导入 cURL 只进调试面板，**不会**写回下游接口配置；改配置请走智能填充 + 保存发布。

---

## 9. ContentType 与占位符速查

| ContentType | 值 | 入参映射目标树 |
|-------------|-----|----------------|
| FormUrlEncoded | 1 | `mappingBodyParameterList` |
| Json | 3 | `requestBodyParameterList` |
| Xml | 4 | `requestBodyParameterList` |

| 占位符 | 用途 |
|--------|------|
| `$FromAccount` | 服务商账户 |
| `$FromMappingBody` | Form KV：填入 Mapping Body 映射结果 |
| `$TimeStamp` / `$DateTime` | 时间 |
| `$token` | Token |

详见 `docs/itfx枚举说明.md`、`docs/前端调整.md`。

---

## 10. 网关 API

| 接口 | 说明 |
|------|------|
| `POST InterfaceForward/ForwardWithSubscribe` | 同步转发 |
| `POST InterfaceForward/BatchRequest` | 批量异步 |
| `POST InterfaceForward/ReForward` | 失败重试 |

Query：`standardCode`、`supplierCode`。

---

## 11. 常见问题

**下游保存提示 Body / Mapping Body 不能为空？**  
核对 ContentType：Form 必须同时有 Body 表单与 Mapping Body 树；Json 必须 Body 树有节点。

**映射页右侧树是空的？**  
下游接口未保存、未发布，或 ContentType 与打开的 Tab 不对应（Form 要看 Mapping Body 是否配置）。

**映射对了但服务商报文不对？**  
用 **请求日志** 看最终 Query/Body；重点查 `$FromMappingBody` 是否替换、签名脚本是否写到正确字段名。

**Query 上有 DTO，Mapping Body 也有树，但 Body 表单多了 DTO 一行？**  
POST 参数仅在 URL 时应只在 Query 配 `$FromMappingBody`，Body 表单可为空。

**Json 接口能否配 Mapping Body？**  
界面隐藏；只配 Body 参数树即可。

**配置改了不生效？**  
下游接口、映射、应用均需 **发布**。

---

## 12. 延伸阅读

| 文档 | 说明 |
|------|------|
| `docs/前端调整.md` | 保存字段、Tab、校验 |
| `docs/方案B-重构清单-前后对比.md` | 数据模型与转发流程 |
| `docs/itfx枚举说明.md` | 枚举与占位符 |
| `docs/中后台前端页面设计规范.md` | 页面规范 |

---

**建议**：先读 **第 5 节下游** + **第 6 节映射**，再按第 7 节实操一条完整链路。