front/src/views/api/apiDebugger/guide-dev.md

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. 一次转发怎么走？

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

---

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

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

任意下游接口：基本信息 + 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 映射解决什么问题？

业务只认识标准字段：

{ "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 入参 + 转发数据流

业务标准 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 入参 + 转发数据流

业务标准 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 → 请求日志 对报文。

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 节实操一条完整链路。