确定性架构图｜对象参数、字符串重载、完整响应与未知副作用

✦ 问题：明明发了请求，为什么拿到 Promise

某个接口引擎调用第三方服务时，代码看起来很普通：传入一个 URL，接着解析返回的 JSON。真正接入后，日志里却出现了 `[object Promise]`，业务错误被当成“第三方返回了奇怪内容”。这个现象与 HTTP 服务是否正常无关，关键在于 .NET 同名重载与 Jint 对实参类型的匹配。

Microi吾码AI 的接口引擎提供了对象参数入口，也保留了历史字符串重载；写调用时应明确自己要哪一条。

✦ ① 问题出在签名，而不是网络

当前接口中同时存在接受对象参数的同步 `Get(dynamic)` 与接受字符串的异步 `Get(string)`。`V8.Http.Get(url)` 给出字符串后，脚本运行时可能匹配到返回 `Task` 的旧重载；把结果直接拼接或 `JSON.parse`，得到的并非响应文本。

相同 URL 换成 `V8.Http.Get({ Url: url })`，意图就明确落在对象参数的同步用法。

解释图｜当前源码签名静态核对；未声称已在租户运行时复现

var text = V8.Http.Get({
  Url: 'https://api.example.com/orders',
  Timeout: 10
});
var orders = JSON.parse(text);

对象参数也是 GET、POST、PATCH 之间更稳定的共同格式：`Url`、`GetParam`、`Headers`、`Timeout` 的含义保持一致，读代码的人能看到请求的每个组成部分。这里的 URL 是示意地址，应用中应替换成受信任的业务配置。

• 对象参数明确 Url、Timeout、Headers 和查询参数。
• 字符串实参需检查实际返回类型，不把 Task 当响应文本。
• 运行时重载选择仍需在目标租户用最小样例确认。

✦ ② 真要异步，就把等待写出来

后端 V8 有明确命名的 `GetAsync` 与 `GetResponseAsync`。它们的返回值必须在本次请求内 `await`。显式方法名比依赖运行时的同名重载选择更易审查。

var response = await V8.Http.GetResponseAsync({
  Url: 'https://api.example.com/orders',
  GetParam: { page: 1 },
  Timeout: 10
});

异步等待解决的是本次请求的 I/O 阻塞。它不会把任务变成“接口响应后可靠地继续执行”的后台作业。需要持久重试、跨进程恢复或人工核对的调用，应交给 Job、消息队列或有状态的业务流程，而不是用未等待的 Promise 或定时器留下不可见的副作用。

✦ ③ 字符串返回值不足以判断一次关键调用

字符串版适合只关心正文的简单读取。但支付、状态同步和身份交换还需要知道 HTTP 状态码与网络错误；即使返回的文字像 JSON，也不代表请求成功。完整响应入口提供 `StatusCode`、`ErrorMessage`、`Headers`、`Content` 和 `RawBytes`。先判定状态，再解析正文。

var response = V8.Http.PostResponse({
  Url: 'https://api.example.com/orders',
  PostParamString: JSON.stringify({ order: { id: V8.Param.OrderId } }),
  ParamType: 'json',
  Timeout: 10
});
if (response.StatusCode < 200 || response.StatusCode >= 300) {
  return { Code: 0, Msg: '上游订单接口暂不可用' };
}
var result = JSON.parse(response.Content);

错误分支不要把上游响应的原文、凭据或内部地址直接回传前端；可以记录脱敏的追踪号，供服务端排查。嵌套 JSON 采用已序列化的 `PostParamString`，避免对象转换时把层级改变。

✦ ④ 三类失败应当分开处理

第一类是调用约定错误：同名重载选错或忘记 `await`，请求还没被当成预期的字符串处理。第二类是HTTP 失败：请求发出，但有 4xx、5xx、超时或连接异常。第三类是业务失败：HTTP 可能是 200，响应体中的业务码仍拒绝操作。

把三类问题都压成“JSON 解析失败”，后续就无法判断是否产生过第三方副作用，也无法安全重试。

解释图｜分别检查调用约定、HTTP 状态和业务码

可以为每次业务调用固定一份最小诊断记录：动作名、脱敏的目标主机、追踪号、HTTP 状态、第三方业务码、开始和结束时间。日志不放 Token、Query 中的秘密、完整请求体和用户隐私。遇到超时而第三方处理状态未知时，先按幂等键查原业务结果；不要立即换一个请求号再次写入。

• 调用约定：实参类型或 await 错误。
• HTTP：状态码、超时或网络异常。
• 业务：HTTP 200 中仍有拒绝码。

✦ ⑤ URL 安全与兼容行为需要单独确认

后端 `V8.Http` 的严格 SSRF 防护由 SaaS 引擎配置决定。当前源码默认保持兼容行为；显式启用后只允许 HTTP(S)，限制 URL 凭据与私网、回环、元数据地址，并停止自动跟随重定向。若一个集成依赖 302 跳转，更新配置后应改用完整响应读取 `Location`，对下一个目标重新作信任判断。

主机白名单按主机精确匹配，不能把 URL 子串当作放行依据。

这与 Promise 问题属于不同层：参数形状决定脚本拿到什么类型的结果，SSRF 与重定向决定请求是否允许发出和如何走完。两者都要在联调样例里明确检验。

✦ ⑥ 一个可复用的验收清单

先用对象参数调用一个能返回明确错误的测试地址，确认脚本真正拿到响应文本或完整响应对象。再用无效业务参数观察 4xx 与第三方错误码，确保失败信息被分层处理。最后把正常、超时和未知副作用分别写入业务流程：正常成功继续，明确失败按规则修正，未知结果只查原请求。

源码证据图｜摘录自本地当前源码；行号与哈希见本地验证记录

当前文章的结论来自官方后端 V8 文档、责任 Skill 与当前源码签名的静态核对；它没有把示意域名当成真实联调，也没有声称已在某个租户的生产接口复现。读者在自己的集成环境中应按相同三层边界完成请求与回读。

文中说明文字由 AI 辅助创作，并依据当前文档与源码核对；示意代码不含真实业务凭据。

本文说明文字与技术图卡由AI辅助创作，关键签名依据当前官方文档和源码静态核对；示意代码未连接真实业务接口。