JSON 与对象处理

脚本需要解析第三方响应、构造请求体，或把外部字段映射成 Soln 字段 API 名时，可以使用 JSON 和对象处理方法。

常用方法

方法	说明
JSON.stringify(value)	把对象转换成 JSON 文本；接口签名需要原始 body 文本时使用
JSON.parse(text)	把 JSON 文本解析成对象；只有拿到文本响应并需要手动解析时使用
Object.entries(object)	把对象转换成 [key, value] 列表，便于过滤或映射
Object.fromEntries(entries)	把 [key, value] 列表转换回对象，常用于移除空值后重新组装对象
record[key]	按动态字段名读取对象值；使用前需要检查值类型
typeof value	检查运行时类型，例如 string、number、boolean
Array.isArray(value)	遍历第三方响应字段前，先确认它是否是数组
Number(value)	把外部数字文本转换成数字，再写入数字字段
`String(value

构造 JSON 请求体

const body = {
  orderNo: 'SO-1001',
  amount: 1200,
  status: 'paid',
};

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'POST',
  json: body,
});

把文本响应解析成 JSON

当接口返回的是 JSON 文本，但不能直接用 requestJson 处理时，可以手动解析。

const response = await context.http.request({
  url: 'https://example.com/api/orders',
  expect: 'text',
});

const data = JSON.parse(response.bodyText) as {
  orders: Array<{ id: string; amount: number }>;
};

安全读取对象字段

function readText(record: Record<string, unknown>, key: string) {
  const value = record[key];
  return typeof value === 'string' ? value : '';
}

const orderNo = readText(externalOrder, 'order_no');

移除空值

function omitEmptyValues(input: Record<string, unknown>) {
  return Object.fromEntries(
    Object.entries(input).filter(([, value]) => (
      value !== undefined &&
      value !== null &&
      value !== ''
    ))
  );
}

const data = omitEmptyValues({
  orderNo: externalOrder.order_no,
  amount: externalOrder.amount,
  remark: externalOrder.remark,
});

映射外部字段到 Soln 字段

const data = {
  orderNo: externalOrder.order_no,
  amount: Number(externalOrder.amount || 0),
  customerName: externalOrder.customer_name,
};

await context.form.create({
  formApiName: 'orders',
  title: String(data.orderNo || ''),
  data,
});

说明

请求体是普通对象时，优先使用 context.http 的 json 参数。只有脚本拿到文本响应且需要手动解析时，才使用 JSON.parse。写入 Soln 记录前，需要先确认第三方响应结构符合预期。