yida-data-source-connectors · diff
git:20260717.d0ccc71 to git:20260728.ca83c23
106 added, 64 removed. Audit A to A.
---
name: yida-data-source-connectors
- description: 宜搭普通自定义页面接入连接器或远程 API 的设计器数据源规范。通过设计器“数据源”面板创建数据源，在页面代码中使用 this.dataSourceMap.<name>.load() 调用。适用于普通自定义页面、Dashboard、大屏需要读取外部接口数据时。
+ description: 宜搭普通自定义页面（native）设计器 dataSourceMap 专用技能。仅用于把连接器/远程 API 注册到 Page dataSource.online 并通过 this.dataSourceMap.<name>.load() 调用。Code Canvas 没有 dataSourceMap，Canvas 数据接入必须转 yida-canvas-data-binding / Canvas HTTP 数据桥。
---
- # 宜搭连接器数据源接入规范
+ # 宜搭普通自定义页面连接器数据源规范
- ## 核心规则
+ ## 核心定位
- 在宜搭普通自定义页面里调用连接器操作或远程 API 时，必须先在设计器“数据源”面板创建对应的数据源，再在页面代码里通过 `this.dataSourceMap.<数据源名>.load()` 调用。
+ 本技能只服务 **普通自定义页面 native 链路**：
- 禁止在普通自定义页面里直接用 `fetch`、`XMLHttpRequest`、`/query/newconnector/testConnector.json`、`ConnectorFactory.testConnector` 或手写远程 URL 绕过设计器数据源。
+ ```text
+ 设计器 Page dataSource.online
+ → this.dataSourceMap.<name>.load()
+ → 连接器 / REMOTE 数据源
+ ```
- 官方示例中心的 schema 回读规律见 [官方示例中心 Schema 范式](../../references/official-example-schema-patterns.md)。其中连接器调用有时会被平台归一为 `REMOTE + /query/publicService/invokeService.json + serviceInfo.connectorInfo`，因此验收时既看设计器数据源是否存在，也要识别这种归一形态。
+ 它不是 Canvas 通用数据接入技能。Code Canvas 组件没有普通页面 `this` 实例，也没有 `dataSourceMap`；遇到 `.canvas.jsx`、`YidaCodeCanvas`、`YidaComp`、React hooks 或 Canvas 看板时，立即转：
- ## 适用场景
+ ```text
+ use_skill("yida-canvas-data-binding", "为 Code Canvas 页面接入连接器或同源 API 数据")
+ ```
- - 普通自定义页面、Dashboard、数据大屏读取外部系统接口。
- - 页面需要调用宜搭 HTTP 连接器动作，例如获取 token、查询设备列表、查询状态、提交指令。
- - 用户要求“把连接器操作添加到页面数据源”“左侧数据源里要能看到连接器”“远程 API 不要写死在 JSX 里”。
- - 修复页面一直卡在“加载中”，且原因是代码绕过数据源直接请求连接器或外部域名。
+ 需要 Canvas 页面容器与运行时规范时同时使用 `yida-canvas-custom-page`。
- > ⚠️ 子表内嵌明细只返回 50 行，应使用 `openyida data query subform` 按 `formInstId + tableFieldId` 分页查询，不要为此新建连接器数据源。
+ ## 路由边界
- ## 实施流程
+ | 信号 | 路由 |
+ | --- | --- |
+ | 普通自定义页、`.oyd.jsx`、`renderJsx`、已有 `this.dataSourceMap` | 本技能 |
+ | 用户明确要求“设计器左侧数据源可见” | 本技能 |
+ | 维护已有 `dataSource.online` / YIDACONNECTOR Schema | 本技能 |
+ | Code Canvas、`.canvas.jsx`、`YidaComp`、hooks | `yida-canvas-data-binding` |
+ | 新建看板/工作台/列表/详情需要连接器数据 | 默认 Canvas 数据桥，不使用本技能 |
+ | 需要创建/管理连接器或 Action 本身 | `yida-connector` |
- 1. 确认连接器动作存在。
+ 不要为了使用本技能而把 Canvas 页面降级成普通自定义页面。
+ ## Native 核心规则
+
+ 普通自定义页面调用连接器或远程 API 时，先在设计器 Page 根节点 `dataSource.online` 注册数据源，再通过：
+
+ ```javascript
+ this.dataSourceMap.<数据源名>.load()
+ ```
+
+ 禁止在 native 页面用 `fetch`、`XMLHttpRequest`、`/query/newconnector/testConnector.json`、`ConnectorFactory.testConnector` 或手写外部 URL 绕过设计器数据源。
+
+ 官方示例回读时可能把数据源归一为：
+
+ ```text
+ REMOTE
+ + /query/publicService/invokeService.json
+ + serviceInfo.connectorInfo
+ ```
+
+ 这是平台可接受的只读形态；源码仍以可审计的连接器配置为准，不写死 `_csrf_token`。
+
+ ## Native 实施流程
+
+ ### 1. 确认连接器与 Action
+
```bash
openyida connector detail <connector-id>
openyida connector list-actions <connector-id>
```
- 2. 为页面规划数据源名称。
-
- 命名使用业务语义，建议小驼峰，例如：
+ ### 2. 规划数据源名称
- - `tricolorGetToken`
- - `tricolorGetUserDtuSns`
- - `tricolorGetDtuSnStateList`
+ 使用业务语义小驼峰，例如：
- 官方示例里高频数据源类别包括表单查询、任务列表、流程发起、保存/更新/删除、连接器动作。OpenYida 生成时应把每个远程能力设计为独立数据源，并为页面状态保留明确字段：
+ - `getDeviceList`
+ - `getDeviceState`
+ - `submitDeviceCommand`
- | 能力 | 数据源命名建议 | 状态字段建议 |
- | --- | --- | --- |
- | 查询列表 | `get<Biz>List` | `loading`、`tableData/list`、`currentPage`、`pageSize`、`totalCount`、`filters/searchFieldJson` |
- | 查询详情 | `get<Biz>ById` | `detailLoading`、`currentRecord` |
- | 保存/更新 | `save<Biz>` / `update<Biz>` | `submitting`、`dialogVisible` |
- | 删除/批量删除 | `delete<Biz>` / `batchDelete<Biz>` | `selectedRowKeys`、`deleting` |
- | 连接器动作 | `<service><Action>` | 与动作结果同名的 `result` / `rawResult` |
+ 每个远程能力使用独立数据源；查询、详情、保存、删除不要混成一个万能 Action。
- 3. 在页面 Schema 的 Page 根节点 `dataSource.online` 中登记连接器数据源。
+ ### 3. 注册 `dataSource.online`
- 数据源必须满足：
+ 连接器数据源需要：
- `dpType: "YIDACONNECTOR"`
- `protocal: "REMOTE"`
- `requestHandler.value: "this.utils.legaoBuiltin.dataSourceHandler"`
- - `options.connector` 指向连接器名，例如 `Http_xxx`
- - `options.connectorAction.value` 使用动作 `operationId`
+ - `options.connector` 指向连接器名
+ - `options.connectorAction.value` 使用 Action `operationId`
- `options.params.inputs` 包含 `Headers`、`Query`、`Body`
- - `options.shouldFetch: false`，由页面代码按需触发
- - `options.didFetch` 必须返回处理后的 content；返回结构不稳定时做归一化
- - `options.onError` 必须 toast 具体数据源/动作名，并让页面加载态恢复
-
- 发布后回读 schema 时，平台可能把连接器数据源归一成以下只读形态；这是可接受的，但不要在源码里写死 `_csrf_token`：
-
- - `dpType: "REMOTE"` / `protocal: "REMOTE"`
- - `options.url` 为 `/query/publicService/invokeService.json?...`
- - `options.params.serviceInfo` 内含 `connectorInfo.connectorId`、`actionId`、`type`、`connection`
- - `requestHandler.value` 仍是 `this.utils.legaoBuiltin.dataSourceHandler`
+ - `options.shouldFetch: false`，页面按需触发
+ - `options.didFetch` 归一返回 content
+ - `options.onError` 暴露数据源/Action 名并恢复 loading
- 4. 页面代码只调用数据源。
+ ### 4. 页面只调用已注册数据源
```javascript
export function loadConnectorDataSource(dataSourceName, headers, query, body) {
var dataSource = this.dataSourceMap && this.dataSourceMap[dataSourceName];
- if (!dataSource || !dataSource.load) {
+ if (!dataSource || typeof dataSource.load !== 'function') {
return Promise.reject(new Error('页面数据源不存在：' + dataSourceName));
}
return dataSource.load({
inputs: JSON.stringify({
Headers: headers || {},
Query: query || {},
Body: body || {}
})
});
}
```
- 5. 所有调用必须有可恢复的加载态。
+ ### 5. 恢复状态
- - 请求失败或超时后必须 `loading: false`。
- - 错误必须显示到页面或 toast，不能只写 `console.log`。
- - 对连接器调用包一层超时控制，避免页面永久停在“加载中”。
+ - 请求失败、取消或超时后必须 `loading: false`。
+ - 页面显示具体错误或 toast，不能只写 console。
+ - 超时和重试必须有限，不能永久停在“加载中”。
+ - mutation 操作避免重复提交；按钮有 submitting/disabled 状态。
- ## 发布和回读验证
+ ## Canvas 转交说明
- 发布后必须回读 Schema，确认数据源仍在 Page 根节点：
+ Canvas 中不得复制上面的 `this.dataSourceMap` 代码。Canvas 数据接入使用：
+ - `dataBinding.mode=connector` + 同源代理 `endpoint`。
+ - 或 `dataBinding.mode=url/form/report` + Canvas `DataBridge`。
+ - `fetch(..., { credentials: 'include' })`。
+ - CSRF、AbortController、返回体解包、`totalCount` 保护、silent refresh。
+ - Cookie、密钥、签名留在平台连接器或后端服务侧。
+
+ 详细规则由 `yida-canvas-data-binding` 决定。本技能只负责判断“当前需求不是 native dataSourceMap”并完成转交，不为 Canvas 发明伪 `dataSourceMap`。
+
+ ## Native 发布与回读验证
+
```bash
+ openyida check-page <src>
+ openyida compile <src>
openyida publish <src> <appType> <formUuid> --health-check
openyida get-schema <appType> <formUuid>
```
- 如需保存回读 Schema，使用 create_file / Write / file edit tool 创建 `<projectRoot>/.cache/openyida/<项目名或任务名>/<page>-schema.json`；从 workspace 根执行后续命令时路径加 `project/` 前缀。不要使用 shell 重定向。
+ 这些是普通自定义页面验证步骤。Canvas 验证必须按 `yida-canvas-custom-page` 使用 `compileCanvasLocal`、Canvas publish 和 `YidaCodeCanvas/runtimeCode` 回读，不要复用这里的 `check-page` 默认。
- 检查点：
+ Native 回读检查：
- - 设计器左侧“数据源”能看到新增连接器数据源。
- - `dataSource.online` 中能看到显式连接器数据源，或回读为 `REMOTE + publicService/invokeService + serviceInfo.connectorInfo` 的平台归一形态。
- - `actions.module.source` 中没有 `ConnectorFactory.testConnector`、`newconnector/testConnector`、外部 API 域名直连代码。
- - 页面运行时使用 `this.dataSourceMap.<name>.load()`。
+ - 设计器左侧“数据源”能看到连接器数据源。
+ - `dataSource.online` 存在显式连接器数据源，或被平台归一为 `REMOTE + publicService/invokeService + serviceInfo.connectorInfo`。
+ - `actions.module.source` 没有 `ConnectorFactory.testConnector`、`newconnector/testConnector` 或外部 API 直连。
+ - 运行时代码使用 `this.dataSourceMap.<name>.load()`。
## 反模式
- 不要发布以下写法：
+ ### Native 反模式
```javascript
fetch('https://api.example.com/data');
new XMLHttpRequest();
postYidaForm('/query/newconnector/testConnector.json?_api=ConnectorFactory.testConnector', payload);
```
- 这些写法会导致设计器数据源不可见、权限和参数不可审计，也容易出现跨域、CSRF、预览态卡死或“加载中”无法恢复的问题。
+ ### Canvas 反模式
- ## PR/验收清单
+ ```javascript
+ // Canvas 中不存在 this 页面实例
+ this.dataSourceMap.getDeviceList.load();
+ ```
- - 页面 Schema 已包含连接器数据源。
- - 页面代码通过 `this.dataSourceMap` 调用。
- - 本地执行 `openyida check-page` 和 `openyida compile` 通过。
- - 发布后执行 `openyida get-schema` 回读验证数据源存在。
- - 若页面仍报错，错误文案应暴露具体数据源名称或连接器动作名。
+ 也禁止看到连接器需求就自动选择本技能；先判断页面运行时。
+
+ ## 验收清单
+
+ - 已确认目标是普通自定义页面，而不是 Canvas。
+ - Page Schema 包含可审计的数据源配置。
+ - native 代码只通过 `this.dataSourceMap` 调用。
+ - loading / error / timeout / retry 可恢复。
+ - `check-page`、compile、发布回读属于 native 链路且通过。
+ - 如果目标是 Canvas，已转 `yida-canvas-data-binding`，本技能没有生成 native 代码。
+
+ > 子表内嵌明细只返回 50 行时，应使用 `openyida data query subform` 按 `formInstId + tableFieldId` 分页查询，不为此新建连接器数据源。