模块调用上下文

了解模块方法当前可以读取的 Runtime、调用方、用户和请求上下文字段。

模块调用上下文是平台在解析并校验一次模块方法调用时生成的 JSON 对象。它与页面或调用方提交的业务参数相互独立，用于向方法实现提供当前 Runtime、调用方、访问用户和请求路由信息。

模块不能假定所有字段在所有入口都存在。方法只应读取本页列出的稳定字段，并根据调用入口决定哪些字段必须存在。没有建立对应身份的调用不会伪造默认值，也不会从请求体中的同名字段回退。

稳定字段

字段	当前类型	何时存在	含义
`applicationRuntimeId`	`string`	所有已经解析到 Runtime 的模块后端调用	当前应用 Runtime ID。平台根据实际执行的 Runtime 写入，并覆盖调用入口提供的同名上下文值。
`callerBusinessId`	`string`	已验证出调用方业务身份时	调用当前方法的源模块或服务 `businessId`。模块通过服务引用调用另一模块时使用该字段区分调用方；直接用户调用或没有业务身份的入口可能不存在。
`targetBusinessId`	`string`	按模块或服务 `businessId` 路由方法时	当前被调用模块或服务的 `businessId`。按全局方法名解析时不存在。
`targetMethodName`	`string`	已成功解析方法时	当前目标方法名。
`userId`	`number \| string`	当前入口完成用户身份校验并返回用户时	当前平台用户 ID。未登录、可选认证未建立身份或服务调用未携带用户身份时不存在。
`workspaceId`	`number \| string`	当前入口完成工作区身份校验时	当前可信工作区 ID。它不会仅根据请求参数或请求体中的同名字段生成。
`httpMethod`	`string`	HTTP 入口	进入 Runtime 的 HTTP 方法，例如 `GET` 或 `POST`。
`requestPath`	`string`	HTTP 入口	进入 Runtime 的原始请求路径。

number | string 表示当前不同鉴权入口可能保留数字 ID，也可能保留字符串形式。ID 用作比较、存储键或 HTTP Header 前应先规范化为非空字符串，不要进行算术运算。

Runtime 与模块级隔离

需要按 Runtime 和调用模块隔离数据时，同时把 applicationRuntimeId 和 callerBusinessId 声明为必需上下文。若数据还属于工作区，再同时要求 workspaceId。任一必需字段缺失时应拒绝调用，不能回退到仅工作区、仅 Runtime 或公共目录。

映射到 HTTP 请求

上下文不会自动完整转发给模块后端。HTTP 方法必须在 methodBody 中显式选择字段，并映射到 Header、 Path、Query 或 Body。以下示例把 Runtime、调用模块和工作区映射为模块自己的业务 Header：

{
  "header": {
    "X-Module-Runtime-Id": {
      "position": "context",
      "key": "applicationRuntimeId",
      "required": true
    },
    "X-Module-Caller-Business-Id": {
      "position": "context",
      "key": "callerBusinessId",
      "required": true
    },
    "X-Module-Workspace-Id": {
      "position": "context",
      "key": "workspaceId",
      "required": true
    }
  }
}

position: "context" 按 key 精确读取上下文字段。输出字段名与上下文键不同时必须写 key；省略 key 时使用输出字段名查找。required: true 的字段缺失会终止调用，不应使用固定值或更宽作用域代替。

需要转换字段或组装请求体时可以使用表达式：

{
  "body": {
    "runtimeId": {
      "expression": "context.applicationRuntimeId",
      "required": true
    },
    "callerBusinessId": {
      "expression": "context.callerBusinessId",
      "required": true
    }
  }
}

表达式中的 context 只包含当前调用已经建立的字段。不要在表达式中从业务参数回退身份字段。

信任与缺失规则

params、Query、普通 Header 和请求体都是业务输入；其中的同名字段不会自动成为可信上下文。
applicationRuntimeId 来自当前实际执行的 Runtime，不由页面或模块自行选择。
callerBusinessId 只在平台验证出调用方业务身份后存在；不能由目标模块根据请求内容猜测。
userId、workspaceId 只代表当前入口已经建立的身份。字段缺失表示该身份没有建立，不表示值为 0、空字符串或系统管理员。
方法依赖某个字段时应声明 required: true 并失败关闭。不要设置固定管理员、默认工作区、公共 Runtime 或其他兼容回退。
日志和错误信息可以记录字段是否存在，但不应输出完整身份声明、凭据或敏感模块属性。

稳定字段

映射到 HTTP 请求

信任与缺失规则

本页内容