代理转发模式
代理转发模式不连接数据库，而是把平台接口作为反向代理：调用方访问平台地址，平台按配置转发到第三方 HTTP/HTTPS 接口，并把响应原样或按规则返回。适合 统一出入参、隐藏真实地址、附加鉴权、收敛错误码等场景。
适用场景
- 第三方系统只提供固定接口，希望统一由平台鉴权、限流、记录日志。
- 需要在调用第三方时附加固定 Token / API Key，避免把密钥下发给调用方。
- 第三方响应错误码不统一，需要转换为平台业务错误码。
- 需要把第三方接口纳入订阅、配额、缓存、监控等治理体系。
创建步骤
- 进入【工作台】，点击「代理转发模式」。
- 配置路由：平台请求路径、第三方域名与路径、协议与方法。
- 按需配置请求体类型、响应类型。
- 配置第三方鉴权（如 Bearer Token）。
- 在右侧「请求参数」「返回参数」中声明对外暴露的参数，并建立上下游参数映射。
- 使用「测试」验证转发结果，确认后保存并发布。
路由配置
| 字段 | 说明 | 示例 |
|---|---|---|
| 接口名称 | 平台内展示名称 | 查询订单 |
| 请求路径 | 平台对外路径，带项目统一前缀 | /order/query |
| 第三方域名/IP | 目标主机，可带 http://、https:// 前缀 | api.partner.com |
| 第三方路径 | 目标接口路径 | /v1/orders/query |
| 协议 | https 或 http；域名已带协议时以域名中的协议为准 | https |
| 请求方式 | GET / POST / PUT / DELETE / PATCH | POST |
| 连接超时 | 与第三方建立连接的超时，单位 ms | 5000 |
| 响应超时 | 等待第三方响应的超时，单位 ms | 10000 |
平台最终访问地址为「协议 + 第三方域名/IP + 第三方路径」，路径拼接会自动处理首尾 /。请求路径与第三方路径都不允许包含 * 通配符。
请求与响应格式
| 配置 | 可选值 | 说明 |
|---|---|---|
| 请求体类型 | JSON / x-www-form-urlencoded | 仅非 GET 请求展示 |
| 响应类型 | JSON / 文本 | JSON 才会参与错误码映射与结构化返回 |
- 请求体类型为 JSON 时，Body 参数会组装为 JSON 对象。
- 为
x-www-form-urlencoded时，Body 参数会组装为表单。 - 请求头只透传
Accept、Accept-Language、Content-Type三个安全头，其余客户端请求头默认丢弃。 - 返回响应会过滤
Content-Length、Connection、Transfer-Encoding等逐跳头。 - 非流式响应体最大读取 10 MB，超出直接报错。
第三方鉴权
在「鉴权配置」中选择平台访问第三方时使用的认证方式：
| 类型 | 配置项 | 实际效果 |
|---|---|---|
| 无鉴权 | — | 不附加认证信息 |
| Bearer Token | Token | 添加 Authorization: Bearer <token> |
| Basic Auth | 用户名、密码 | 添加 Authorization: Basic <base64> |
| API Key(Header) | Key 名、Key 值 | 在指定请求头中附加 Key |
| API Key(Query) | Key 名、Key 值 | 在查询参数中附加 Key |
密钥保管
第三方 Token、密码、Key 保存在接口定义中，调用方不可见。请限制接口编辑权限，避免密钥通过导出或截图外泄。
参数映射
代理模式的请求参数支持「平台参数名 → 下游参数名」映射：
- 位置为 Query 的参数拼接到第三方 URL 查询串。
- 位置为 Header 的参数写入转发请求头。
- 位置为 Path 的参数替换第三方路径中的
{name}占位符；框架会同时尝试columnName与paramName两种写法。 - 位置为 Body 的参数按请求体类型组装。
未配置任何 Query 参数时，平台会把调用方原始查询参数整体透传；一旦配置了 Query 参数，则只转发配置项及未被消费的原始参数。
返回参数侧提供「导入」：粘贴第三方 JSON 响应示例，平台自动解析为树形字段，便于快速建立响应结构。源参数名 用于把第三方字段映射为平台对外字段。
路径参数安全限制
Path 参数值不允许包含 /、\、..、% 及控制字符，防止在允许的第三方主机内穿越到非预期端点。
错误码映射
第三方错误默认保留原始 HTTP 语义。若希望统一转换为平台业务错误，可在「错误映射」中配置：
| 字段 | 说明 |
|---|---|
| 来源类型 | HTTP 状态码 或 业务码（读取响应 JSON 的 code 字段） |
| 来源值 | 要匹配的状态码或业务码 |
| 目标错误码 | 转换后的平台错误码；留空默认 40016 |
| 目标提示 | 转换后的提示文案；留空时尝试提取第三方 msg/message/error |
匹配顺序：先按业务码匹配，HTTP 状态码为 4xx/5xx 时再按状态码匹配。只有响应类型为 JSON 时才生效；文本响应保持第三方原始语义。未配置映射时，第三方 HTTP 错误按原始状态返回。
出网安全
平台内置代理出网闸门（SSRF 防护）：
- 仅允许
http/https协议。 - 硬拒绝
localhost、云厂商元数据地址（如169.254.169.254、100.100.100.200）等主机。 - 默认禁止访问内网地址；启用白名单后，只有白名单内的主机（可带端口）可以出网。
- 域名解析失败按拒绝处理（fail-closed）。
- 相关配置：
apigo.egress.enabled（默认true）、apigo.egress.allowed-hosts（逗号/分号/空格分隔）。
被拦截时返回 40022「目标地址不被允许访问」。生产环境如需访问内网第三方系统，应由管理员显式配置白名单，而不是关闭闸门。
测试与发布
- 点击底部「测试」打开调试面板，按参数位置填写后发起真实转发。
- 测试用例可保存请求快照，后续回归。
- Mock 规则可在第三方不可用时模拟响应。
- 发布后接口进入当前环境，供凭证授权与订阅使用。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 40022 目标地址不被允许访问 | 命中出网闸门或不在白名单 | 检查目标地址，联系管理员配置白名单 |
| 40016 第三方接口调用失败 | 连接失败、超时或第三方异常 | 检查域名、端口、超时与第三方状态 |
| 第三方返回 401/403 | 鉴权配置缺失或错误 | 核对 Bearer / Basic / API Key 配置 |
| 请求体为空 | GET 请求不发送 Body，或未配置 Body 参数 | 改用 POST 或补充 Body 参数 |
| 响应字段缺失 | 未声明返回参数 | 在返回参数中导入或补充映射 |
| 路径参数报非法字符 | Path 值包含 /、..、% 等 | 对路径参数做编码或改用 Query |