APIResource

基于 URL 发起请求的通用 API 资源，适用于任意 HTTP 接口。继承自 FlowResource 基类，并扩展了请求配置与 refresh()。与 MultiRecordResource、SingleRecordResource 不同，APIResource 不依赖资源名，直接按 URL 请求，适合自定义接口、第三方 API 等场景。

创建方式：ctx.makeResource('APIResource') 或 ctx.initResource('APIResource')。使用前需设置 setURL()；RunJS 上下文中会自动注入 ctx.api（APIClient），无需手动 setAPIClient。

适用场景

场景	说明
自定义接口	调用非标准资源 API（如 `/api/custom/stats`、`/api/reports/summary`）
第三方 API	通过完整 URL 请求外部服务（需目标支持 CORS）
一次性查询	临时拉取数据，用完即弃，无需绑定到 `ctx.resource`
与 ctx.request 的取舍	需要响应式数据、事件、错误状态时用 APIResource；简单一次性请求可用 `ctx.request()`

基类能力（FlowResource）

所有 Resource 均具备：

方法	说明
`getData()`	获取当前数据
`setData(value)`	设置数据（仅本地）
`hasData()`	是否有数据
`getMeta(key?)` / `setMeta(meta)`	读写元数据
`getError()` / `setError(err)` / `clearError()`	错误状态
`on(event, callback)` / `once` / `off` / `emit`	事件订阅与触发

请求配置

方法	说明
`setAPIClient(api)`	设置 APIClient 实例（RunJS 中通常由上下文自动注入）
`getURL()` / `setURL(url)`	请求 URL
`loading`	读写加载状态（get/set）
`clearRequestParameters()`	清空请求参数
`setRequestParameters(params)`	合并设置请求参数
`setRequestMethod(method)`	设置请求方法（如 `'get'`、`'post'`，默认 `'get'`）
`addRequestHeader(key, value)` / `removeRequestHeader(key)`	请求头
`addRequestParameter(key, value)` / `getRequestParameter(key)` / `removeRequestParameter(key)`	单参数增删查
`setRequestBody(data)`	请求体（POST/PUT/PATCH 时使用）
`setRequestOptions(key, value)` / `getRequestOptions()`	通用请求选项

URL 格式

资源风格：支持 NocoBase 资源简写，如 users:list、posts:get，会与 baseURL 拼接
相对路径：如 /api/custom/endpoint，与应用的 baseURL 拼接
完整 URL：跨域时使用完整地址，目标需配置 CORS

数据拉取

方法	说明
`refresh()`	按当前 URL、method、params、headers、data 发起请求，将响应 `data` 写入 `setData(data)` 并触发 `'refresh'` 事件。失败时设置 `setError(err)` 并抛出 `ResourceError`，不触发 `refresh` 事件。需已设置 `api` 与 URL。

示例

基础 GET 请求

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/endpoint');
res.setRequestParameters({ page: 1, pageSize: 10 });
await res.refresh();
const data = res.getData();

资源风格 URL

const res = ctx.makeResource('APIResource');
res.setURL('users:list');
res.setRequestParameters({ pageSize: 20, sort: ['-createdAt'] });
await res.refresh();
const rows = res.getData()?.data ?? [];

POST 请求（带请求体）

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/submit');
res.setRequestMethod('post');
res.setRequestBody({ name: '测试', type: 'report' });
await res.refresh();
const result = res.getData();

监听 refresh 事件

const res = ctx.makeResource('APIResource');
res.setURL('/api/stats');
res.on('refresh', () => {
  const data = res.getData();
  ctx.render(<div>统计: {JSON.stringify(data)}</div>);
});
await res.refresh();

错误处理

const res = ctx.makeResource('APIResource');
res.setURL('/api/may-fail');
try {
  await res.refresh();
  const data = res.getData();
} catch (e) {
  const err = res.getError();
  ctx.message.error(err?.message ?? '请求失败');
}

自定义请求头

const res = ctx.makeResource('APIResource');
res.setURL('https://api.example.com/data');
res.addRequestHeader('X-Custom-Header', 'value');
res.addRequestParameter('key', 'xxx');
await res.refresh();

注意事项

ctx.api 依赖：RunJS 中 ctx.api 由运行环境注入，通常无需手动 setAPIClient；若在无上下文的场景使用，需自行设置。
refresh 即请求：refresh() 会按当前配置发起一次请求，method、params、data 等需在调用前配置好。
错误不更新 data：请求失败时 getData() 保持原值，可通过 getError() 获取错误信息。
与 ctx.request：简单一次性请求可用 ctx.request()；需要响应式数据、事件、错误状态管理时用 APIResource。

#APIResource

#适用场景

#基类能力（FlowResource）

#请求配置

#URL 格式

#数据拉取

#示例

#基础 GET 请求

#资源风格 URL

#POST 请求（带请求体）

#监听 refresh 事件

#错误处理

#自定义请求头

#注意事项

#相关