16 KiB
16 KiB
统一API接口设计文档
1. 概述
1.1 目标
为iframe中的第三方应用提供一套统一、简洁、类型安全的系统服务访问接口，使应用开发者无需关注底层通信机制，即可直接调用系统功能。
1.2 核心价值
- 简化开发：封装复杂的跨域通信逻辑，提供类似本地函数调用的体验
- 类型安全：完整的TypeScript类型定义，提供编译时检查和IDE智能提示
- 模块化设计：按功能划分子模块，便于按需使用和维护
- 权限控制：内置权限验证机制，确保系统安全
- 事件驱动：支持双向通信，实现系统与应用间的实时交互
1.3 设计原则
- 透明性：隐藏底层postMessage通信细节
- 一致性：统一的API响应格式和错误处理机制
- 可扩展性：模块化架构支持功能扩展
- 安全性：严格的权限控制和数据验证
2. 系统架构
2.1 整体架构图
graph TB
subgraph "主应用(系统)"
A[主应用UI] --> B[沙箱引擎]
B --> C[事件通信服务]
C --> D[系统服务层]
D --> E[窗口管理]
D --> F[存储服务]
D --> G[网络服务]
D --> H[系统服务]
end
subgraph "子应用(沙箱)"
I[子应用UI] --> J[SDK客户端]
K[业务逻辑] --> J
end
J --"postMessage"--> B
B --"postMessage"--> J
style A fill:#e1f5fe
style I fill:#f3e5f5
style J fill:#f3e5f5
style B fill:#fff3e0
style C fill:#fff3e0
style D fill:#f1f8e9
2.2 SDK架构
classDiagram
class SystemDesktopSDK {
+version: string
+appId: string
+initialized: boolean
+window: WindowSDK
+storage: StorageSDK
+network: NetworkSDK
+events: EventSDK
+ui: UISDK
+system: SystemSDK
+init(config: SDKConfig) Promise~APIResponse~boolean~~
+destroy() Promise~APIResponse~boolean~~
+getStatus() Promise~APIResponse~object~~
}
class SDKBase {
#appId: string
#initialized: boolean
#sendToSystem(type: string, data: any) Promise~T~
#wrapResponse(promise: Promise~T~) Promise~APIResponse~T~~
}
class WindowSDK {
<<interface>>
+setTitle(title: string) Promise~APIResponse~boolean~~
+resize(width: number, height: number) Promise~APIResponse~boolean~~
+move(x: number, y: number) Promise~APIResponse~boolean~~
+minimize() Promise~APIResponse~boolean~~
+maximize() Promise~APIResponse~boolean~~
+restore() Promise~APIResponse~boolean~~
+close() Promise~APIResponse~boolean~~
+getState() Promise~APIResponse~WindowState~~
+on(event: string, callback: Function) void
}
class StorageSDK {
<<interface>>
+set(key: string, value: any) Promise~APIResponse~boolean~~
+get(key: string) Promise~APIResponse~any~~
+remove(key: string) Promise~APIResponse~boolean~~
+clear() Promise~APIResponse~boolean~~
}
class NetworkSDK {
<<interface>>
+request(url: string, config: NetworkRequestConfig) Promise~APIResponse~any~~
+get(url: string, config: any) Promise~APIResponse~any~~
+post(url: string, data: any, config: any) Promise~APIResponse~any~~
}
class EventSDK {
<<interface>>
+emit(channel: string, data: any) Promise~APIResponse~string~~
+on(channel: string, callback: Function) Promise~APIResponse~string~~
+off(subscriptionId: string) Promise~APIResponse~boolean~~
}
class UISDK {
<<interface>>
+showDialog(options: DialogOptions) Promise~APIResponse~object~~
+showNotification(options: NotificationOptions) Promise~APIResponse~string~~
+showToast(message: string, type: string) Promise~APIResponse~string~~
}
class SystemSDK {
<<interface>>
+getSystemInfo() Promise~APIResponse~SystemInfo~~
+getAppInfo() Promise~APIResponse~AppInfo~~
+requestPermission(permission: string) Promise~APIResponse~PermissionStatus~~
}
SDKBase <|-- SystemDesktopSDK
SystemDesktopSDK --> WindowSDK
SystemDesktopSDK --> StorageSDK
SystemDesktopSDK --> NetworkSDK
SystemDesktopSDK --> EventSDK
SystemDesktopSDK --> UISDK
SystemDesktopSDK --> SystemSDK
3. 核心模块设计
3.1 窗口管理模块(WindowSDK)
3.1.1 功能概述
提供对应用窗口的控制能力，包括窗口尺寸调整、位置移动、状态切换等。
3.1.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| setTitle(title) | 设置窗口标题 | title: string | Promise<APIResponse> |
| resize(width, height) | 调整窗口尺寸 | width: number, height: number | Promise<APIResponse> |
| move(x, y) | 移动窗口位置 | x: number, y: number | Promise<APIResponse> |
| minimize() | 最小化窗口 | 无 | Promise<APIResponse> |
| maximize() | 最大化窗口 | 无 | Promise<APIResponse> |
| restore() | 还原窗口 | 无 | Promise<APIResponse> |
| close() | 关闭窗口 | 无 | Promise<APIResponse> |
| getState() | 获取窗口状态 | 无 | Promise<APIResponse> |
3.1.3 事件监听
// 监听窗口变化事件
SystemSDK.window.on('resize', (width, height) => {
console.log(`窗口尺寸变化: ${width}x${height}`)
})
// 移除事件监听
SystemSDK.window.off('resize')
3.2 存储模块(StorageSDK)
3.2.1 功能概述
提供应用数据的持久化存储能力，支持键值对存储、数据查询、删除等操作。
3.2.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| set(key, value) | 存储数据 | key: string, value: any | Promise<APIResponse> |
| get(key) | 获取数据 | key: string | Promise<APIResponse> |
| remove(key) | 删除数据 | key: string | Promise<APIResponse> |
| clear() | 清空所有数据 | 无 | Promise<APIResponse> |
| keys() | 获取所有键名 | 无 | Promise<APIResponse<string[]>> |
| has(key) | 检查键是否存在 | key: string | Promise<APIResponse> |
3.2.3 使用示例
// 存储数据
await SystemSDK.storage.set('userSettings', { theme: 'dark', lang: 'zh' })
// 获取数据
const settings = await SystemSDK.storage.get('userSettings')
// 监听存储变化
SystemSDK.storage.on('onChange', (key, newValue, oldValue) => {
console.log(`存储变更: ${key} 从 ${oldValue} 变为 ${newValue}`)
})
3.3 网络模块(NetworkSDK)
3.3.1 功能概述
提供网络请求能力，支持HTTP请求、文件上传下载等操作。
3.3.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| request(url, config) | 发送HTTP请求 | url: string, config: NetworkRequestConfig | Promise<APIResponse> |
| get(url, config) | GET请求 | url: string, config: object | Promise<APIResponse> |
| post(url, data, config) | POST请求 | url: string, data: any, config: object | Promise<APIResponse> |
| upload(url, file) | 上传文件 | url: string, file: File/Blob | Promise<APIResponse> |
| download(url, filename) | 下载文件 | url: string, filename: string | Promise<APIResponse> |
3.3.3 使用示例
// 发送GET请求
const response = await SystemSDK.network.get('https://api.example.com/users')
// 发送POST请求
const result = await SystemSDK.network.post('https://api.example.com/users', {
name: '张三',
email: 'zhangsan@example.com',
})
// 上传文件
const fileInput = document.querySelector('input[type="file"]')
if (fileInput.files.length > 0) {
await SystemSDK.network.upload('https://api.example.com/upload', fileInput.files[0])
}
3.4 事件通信模块(EventSDK)
3.4.1 功能概述
提供应用间以及应用与系统间的事件通信机制，支持广播、点对点通信等模式。
3.4.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| emit(channel, data) | 发送事件消息 | channel: string, data: any | Promise<APIResponse> |
| on(channel, callback) | 订阅事件频道 | channel: string, callback: Function | Promise<APIResponse> |
| off(subscriptionId) | 取消订阅 | subscriptionId: string | Promise<APIResponse> |
| broadcast(channel, data) | 广播消息 | channel: string, data: any | Promise<APIResponse> |
| sendTo(targetAppId, data) | 发送点对点消息 | targetAppId: string, data: any | Promise<APIResponse> |
3.4.3 使用示例
// 订阅事件
const subscriptionId = await SystemSDK.events.on('user-login', (message) => {
console.log('用户登录:', message.data)
})
// 发送事件
await SystemSDK.events.emit('user-action', { action: 'click', target: 'button1' })
// 取消订阅
await SystemSDK.events.off(subscriptionId)
3.5 UI交互模块(UISDK)
3.5.1 功能概述
提供系统级UI交互能力，如对话框、通知、文件选择器等。
3.5.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| showDialog(options) | 显示对话框 | options: DialogOptions | Promise<APIResponse |
| showNotification(options) | 显示通知 | options: NotificationOptions | Promise<APIResponse> |
| showFilePicker(options) | 显示文件选择器 | options: FilePickerOptions | Promise<APIResponse> |
| showToast(message, type) | 显示Toast消息 | message: string, type: string | Promise<APIResponse> |
3.5.3 使用示例
// 显示确认对话框
const result = await SystemSDK.ui.showDialog({
title: '确认操作',
message: '确定要删除这个文件吗？',
type: 'confirm',
buttons: ['取消', '确定'],
})
if (result.data.buttonIndex === 1) {
// 用户点击了确定
console.log('用户确认删除')
}
// 显示通知
await SystemSDK.ui.showNotification({
title: '操作完成',
body: '文件已成功上传',
icon: '/icons/success.png',
})
3.6 系统信息模块(SystemSDK)
3.6.1 功能概述
提供系统信息查询和基础系统操作能力。
3.6.2 接口定义
| 方法 | 描述 | 参数 | 返回值 |
|---|---|---|---|
| getSystemInfo() | 获取系统信息 | 无 | Promise<APIResponse> |
| getAppInfo() | 获取当前应用信息 | 无 | Promise<APIResponse> |
| requestPermission(permission) | 请求权限 | permission: string | Promise<APIResponse> |
| getClipboard() | 获取剪贴板内容 | 无 | Promise<APIResponse> |
| setClipboard(text) | 设置剪贴板内容 | text: string | Promise<APIResponse> |
| openExternal(url) | 打开外部链接 | url: string | Promise<APIResponse> |
4. 通信机制设计
4.1 消息协议
sequenceDiagram
participant A as 子应用SDK
participant B as 主应用沙箱引擎
participant C as 系统服务
A->>B: postMessage(sdk:call, method, data)
B->>C: 调用相应系统服务
C-->>B: 返回处理结果
B-->>A: postMessage(system:response, data)
4.2 消息格式
// SDK调用消息格式
{
type: 'sdk:call',
requestId: string, // 唯一请求ID
method: string, // 调用方法路径，如 "window.setTitle"
data: any, // 传递的数据
appId: string // 应用ID
}
// 系统响应消息格式
{
type: 'system:response',
requestId: string, // 对应的请求ID
success: boolean, // 是否成功
data: any, // 成功时的数据
error: string // 失败时的错误信息
}
4.3 错误处理机制
// 统一响应格式
interface APIResponse<T> {
success: boolean // 是否成功
data?: T // 成功时的数据
error?: string // 错误信息
code?: number // 错误码
}
5. 权限控制设计
5.1 权限模型
系统采用基于功能的权限控制模型，应用需要在初始化时声明所需权限。
5.2 权限类型
| 权限名称 | 描述 | 敏感级别 |
|---|---|---|
| window.control | 窗口控制权限 | 中 |
| storage.read | 存储读取权限 | 低 |
| storage.write | 存储写入权限 | 中 |
| network.request | 网络请求权限 | 中 |
| event.broadcast | 事件广播权限 | 中 |
| system.clipboard | 剪贴板访问权限 | 高 |
| system.notification | 通知权限 | 低 |
5.3 权限申请流程
flowchart TD
A[应用初始化] --> B{权限检查}
B -->|权限已授予| C[正常运行]
B -->|权限未授予| D[请求权限]
D --> E[用户授权]
E -->|允许| C
E -->|拒绝| F[限制功能]
6. 使用指南
6.1 SDK初始化
// 初始化SDK
const result = await SystemSDK.init({
appId: 'com.example.myapp',
appName: '我的应用',
version: '1.0.0',
permissions: ['storage.read', 'storage.write', 'network.request'],
})
if (result.success) {
console.log('SDK初始化成功')
} else {
console.error('SDK初始化失败:', result.error)
}
6.2 功能调用示例
// 设置窗口标题
await SystemSDK.window.setTitle('我的应用 - 主界面')
// 存储用户数据
await SystemSDK.storage.set('userData', { name: '张三', age: 25 })
// 发送网络请求
const response = await SystemSDK.network.get('/api/user/profile')
// 显示通知
await SystemSDK.ui.showNotification({
title: '数据加载完成',
body: '用户信息已更新',
})
6.3 事件监听示例
// 监听窗口关闭事件
SystemSDK.window.on('close', async () => {
// 保存应用状态
await SystemSDK.storage.set('appState', getCurrentState())
console.log('应用状态已保存')
})
// 监听系统主题变化
SystemSDK.system.on('themeChange', (theme) => {
// 更新应用主题
updateAppTheme(theme)
})