110 lines
4.3 KiB
TypeScript
110 lines
4.3 KiB
TypeScript
import type { DynamicExpression } from './dynamic-expression';
|
||
import type { JsonValue } from './json-value';
|
||
|
||
/**
|
||
* RESTful 请求配置
|
||
*
|
||
* 【架构定位】：
|
||
*
|
||
* - 低代码平台底层网络 I/O 的通用描述符。
|
||
* - 广泛被 QueryConfig 和 MutationConfig 复用。
|
||
*
|
||
* 采用“顶层双模设计”，
|
||
* 在提供常规的可视化表单配置（fixed）的同时，保留了极客级别的代码逃生舱（code）。
|
||
*/
|
||
export type RestRequest = RestRequestByFixed | RestRequestByCode;
|
||
|
||
/**
|
||
* 可视化表单请求配置
|
||
*
|
||
* 适用于 90% 的标准 HTTP 请求。
|
||
* 引擎会将这些配置项与全局的 DataSource 配置进行深度合并（Merge）。
|
||
*/
|
||
export interface RestRequestByFixed {
|
||
type: 'fixed';
|
||
/**
|
||
* 关联的全局数据源 ID
|
||
*
|
||
* 引擎实现指引：
|
||
*
|
||
* 如果指定了 DataSource，引擎应提取该数据源的 baseUrl、params、headers，
|
||
* 并与当前请求的配置进行合并（当前请求的优先级更高）。
|
||
*/
|
||
dataSourceId?: string;
|
||
/**
|
||
* 请求路径
|
||
*
|
||
* 可以是完整的绝对路径（若无 dataSourceId 或需要跨域调用第三方 API），
|
||
* 也可以是相对路径（如 `/users`，引擎会自动拼接 DataSource 的 baseUrl）。
|
||
*/
|
||
url: string;
|
||
/**
|
||
* URL 查询参数 (Query String)
|
||
*
|
||
* 引擎防呆设计 (Poka-yoke)：
|
||
*
|
||
* `params` 最终会被序列化拼接在 URL 后面（如 `?name=A&age=18`）。
|
||
* 坚决抵制在此处传入对象或数组！如果传入 `{ a: { b: 1 } }`，
|
||
* 多数底层客户端（如原生 Fetch 或默认配置的 Axios）会将其序列化为 `?a=[object Object]`，
|
||
* 这会导致后端网关解析崩溃且极其难以排查。
|
||
* 因此，类型被严格锁定为基础数据类型（Primitive Types）。
|
||
*
|
||
* 【核心架构：null 的显式抹除语义 (Explicit Erasure)】
|
||
*
|
||
* 引入 `null` 是为了解决局部请求“抹除”全局 DataSource 继承配置的刚需。
|
||
* 如果全局配置了 `params: { tenantId: '123' }`，而当前请求不需要带此参数，
|
||
* 用户必须在当前配置中显式设置 `params: { tenantId: null }`。
|
||
* 引擎在合并配置时，一旦遇到值为 `null` 的键，必须从最终的请求参数中将其物理删除。
|
||
*/
|
||
params?: Record<string, string | number | boolean | null | undefined>;
|
||
/**
|
||
* HTTP 请求头 (Headers)
|
||
*
|
||
* 同上理，HTTP Headers 协议本身只接受字符串。
|
||
* 如果在 Axios 中传了一个对象（如 `headers: { Authorization: { token: '123' } }`），
|
||
* Axios 就会直接把这个对象序列化成 `[object Object]` 发给后端！
|
||
* 必须锁定为基础数据类型。
|
||
*
|
||
* 同样支持 `null` 值的显式抹除语义（常用于抹除全局继承的 Token 以调用第三方开放 API）。
|
||
*/
|
||
headers?: Record<string, string | number | boolean | null | undefined>;
|
||
/**
|
||
* HTTP 请求体 (Payload / Body)
|
||
*
|
||
* 引擎实现指引：
|
||
* 不强制 body 一定是一个对象，用户可以根据需要自定义。
|
||
* 当 method 为 GET 时，此字段通常被底层 HTTP 客户端忽略。
|
||
*
|
||
* 必须使用 JsonValue 以守住存入数据库时的序列化底线，防止混入 Function 等非法对象。
|
||
*/
|
||
body?: JsonValue;
|
||
}
|
||
|
||
/**
|
||
* 纯代码请求配置 (Code Mode 逃生舱)
|
||
*
|
||
* 解决低代码平台“图灵完备性不足”的终极武器。
|
||
*
|
||
* 业务场景：
|
||
*
|
||
* 当实施人员面临极度变态的鉴权或加密需求时
|
||
* （例如：需要提取当前时间戳、加上全局变量 token，混合后进行 MD5 加密，
|
||
* 最后生成动态的 Headers、签名 Params 和变异的 URL）。
|
||
* 这在可视化的 fixed 模式下是根本无法完成的。
|
||
*
|
||
* 引擎实现指引：
|
||
*
|
||
* `code` 是一段纯函数字符串。它接收全局上下文 `context` 作为参数
|
||
* （可解构出 `variables`, `queries` 等运行时状态）。
|
||
* 它必须 `return` 一个符合 `Omit<RestRequestByFixed, 'type'>` 结构的对象。
|
||
* 引擎在执行该函数（JIT 编译）后，拿着返回的对象去发真实的 HTTP 请求。
|
||
*/
|
||
export interface RestRequestByCode extends DynamicExpression {
|
||
/**
|
||
* 关联的全局数据源 ID
|
||
*
|
||
* 即使在使用代码动态生成请求体时，也依然可以继承底层 DataSource 的公共配置（如 baseUrl）。
|
||
*/
|
||
dataSourceId?: string;
|
||
}
|