Files
dev-screen-starter/doc/data-integration-guide.md
T

302 lines
7.1 KiB
Markdown

# 外部数据接入设计与使用教程
本文档说明 Dev Screen Starter 的统一数据源设计。目标是让一个大屏页面可以集中声明多个数据源,并同时支持 HTTP、WebSocket、SignalR、MQTT 等不同协议。
## 1. 核心原则
一个大屏页面可以有多个图表和多个数据源。不同数据源可以使用不同协议:
- 指标卡来自 HTTP 轮询。
- 告警列表来自 WebSocket 推送。
- 设备状态来自 MQTT topic。
- .NET 后端事件来自 SignalR hub。
页面不应该在组件里分散写 `fetch`、`new WebSocket`、MQTT 订阅等细节。推荐把数据源集中放在一个文件中:
```txt
apps/demo-screen/src/demo/dataSources.ts
```
业务组件只消费统一的 `DataState<T>`。
## 2. 当前实现状态
已实现:
- `mockSource`
- `httpSource`
- `websocketSource`
- `defineDataSources`
- `useScreenDataSources`
已预留类型和声明函数:
- `signalrSource`
- `mqttSource`
SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。
## 3. 统一状态模型
每个数据源都会返回同一种结构:
```ts
type DataState<T> = {
data: T | null
loading: boolean
error: string | null
status: 'idle' | 'connecting' | 'open' | 'closed' | 'error'
lastUpdated?: number
sourceType?: 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
}
```
组件不需要关心底层协议,只看 `data/loading/error/status`。
## 4. 页面集中声明数据源
示例:
```ts
import {
defineDataSources,
httpSource,
mockSource,
mqttSource,
signalrSource,
websocketSource
} from '@dev-screen-starter/data'
export const screenDataSources = defineDataSources({
overview: httpSource({
url: '/api/overview',
intervalMs: 10000,
transform: (raw) => ({
todayOrders: raw.today_orders,
onlineDevices: raw.online_devices,
alertCount: raw.alert_count
})
}),
orderTrend: httpSource({
url: '/api/order-trend',
intervalMs: 30000,
transform: (raw) => ({
categories: raw.times,
values: raw.items.map((item) => item.count)
})
}),
alerts: websocketSource({
url: 'ws://localhost:3000/ws/alerts',
mode: 'append',
maxItems: 20,
transform: (raw) => ({
time: raw.time,
area: raw.area,
status: raw.message
})
}),
deviceStatus: mqttSource({
url: 'ws://broker.example.com/mqtt',
topic: 'factory/device/status',
mode: 'replace'
}),
dotnetEvents: signalrSource({
url: '/hubs/screen',
method: 'screenEvent',
mode: 'append',
maxItems: 50
}),
localFallback: mockSource({
data: {
title: '本地 mock 数据'
}
})
})
```
## 5. 页面消费数据源
```tsx
import { useScreenDataSources } from '@dev-screen-starter/data'
import { screenDataSources } from './dataSources'
export function ProjectScreen() {
const data = useScreenDataSources(screenDataSources)
const overview = data.overview.data
const alerts = data.alerts.data ?? []
return (
<>
<MetricCard label="今日订单" value={overview?.todayOrders ?? 0} unit="单" />
<AlertList rows={alerts} />
</>
)
}
```
## 6. HTTP 数据源
适合:
- 指标卡
- 趋势图
- 排行图
- 低频刷新数据
- 页面初始化数据
```ts
const sources = defineDataSources({
overview: httpSource({
url: '/api/overview',
intervalMs: 10000,
transform: (raw) => ({
orders: raw.orders,
devices: raw.devices
})
})
})
```
字段说明:
- `url`: 请求地址。
- `baseUrl`: API 基础地址,建议来自 `.env`。
- `query`: 查询参数。
- `headers`: 静态 header 或返回 header 的函数。
- `authToken`: token 字符串或返回 token 的函数,会自动写入 `Authorization: Bearer <token>`。
- `timeoutMs`: 超时时间。
- `init`: `fetch` 的 RequestInit 参数。
- `intervalMs`: 轮询间隔,不传则只请求一次。
- `immediate`: 是否立即请求,默认 `true`。
- `transform`: 数据清洗函数。
## 7. WebSocket 数据源
适合:
- 实时告警
- 订单流水
- 设备状态
- 秒级推送数据
```ts
const sources = defineDataSources({
alerts: websocketSource({
url: 'ws://localhost:3000/ws/alerts',
mode: 'append',
maxItems: 20,
reconnect: { enabled: true, maxRetries: 10, delayMs: 3000 },
heartbeat: { message: 'ping', intervalMs: 30000 },
transform: (raw) => ({
time: raw.time,
message: raw.message
})
})
})
```
字段说明:
- `url`: WebSocket 地址。
- `protocols`: 可选 WebSocket protocols。
- `mode`: `replace` 或 `append`,默认 `replace`。
- `maxItems`: `append` 模式最多保留多少条。
- `reconnect`: 断线重连设置。
- `heartbeat`: 心跳消息设置。
- `transform`: 单条消息的清洗函数。
WebSocket 消息如果是字符串,会优先尝试 `JSON.parse`。如果不是 JSON,会把原始字符串传给 `transform`。
## 8. MQTT 数据源
当前已预留类型:
```ts
deviceStatus: mqttSource({
url: 'ws://broker.example.com/mqtt',
topic: 'factory/device/status',
mode: 'replace'
})
```
建议:
- 浏览器端 MQTT 通常使用 MQTT over WebSocket。
- 如果客户现场已有 MQTT broker,可以按项目接入 MQTT SDK。
- 如果鉴权复杂,优先让后端网关把 MQTT 转成 WebSocket,再给大屏消费。
## 9. SignalR 数据源
当前已预留类型:
```ts
dotnetEvents: signalrSource({
url: '/hubs/screen',
method: 'screenEvent',
mode: 'append',
maxItems: 50
})
```
建议:
- 客户后端是 .NET 时再引入 SignalR SDK。
- SignalR 适配器应只放在 `packages/data` 或客户项目的数据层,不要散落在业务组件里。
## 10. Demo 当前接入方式
当前 demo 使用 `mockSource` 模拟集中数据源:
```ts
export const demoDataSources = defineDataSources({
metrics: mockSource({ data: metrics, intervalMs: 15000 }),
alerts: mockSource({ data: alertRows, intervalMs: 12000 }),
operationEvents: mockSource({ data: operationEvents, intervalMs: 10000 }),
capacityTrend: mockSource({ data: capacityTrend })
})
```
页面中统一消费:
```ts
const data = useScreenDataSources(demoDataSources)
const metrics = data.metrics.data ?? []
const alertRows = data.alerts.data ?? []
```
后续替换成真实接口时,只需要改 `dataSources.ts`,页面渲染结构可以尽量少改。
## 11. 推荐落地顺序
第一步:
- 使用 `mockSource` 完成页面开发。
- 用 `transform` 提前对齐组件需要的数据结构。
第二步:
- 把初始化数据换成 `httpSource`。
- 对接客户 REST API。
第三步:
- 把告警、设备状态、流水数据换成 `websocketSource`。
第四步:
- 项目确实需要时,再引入 MQTT 或 SignalR SDK,实现对应 adapter。
## 12. 注意事项
- `dataSources` 建议定义在组件外部,保证引用稳定。
- 高频数据不要全部刷新整页,只更新对应数据源。
- WebSocket 的 `append` 模式要设置 `maxItems`,避免列表无限增长。
- 数据清洗放在 `transform`,展示组件只消费干净数据。
- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。