xdz-hm/capability-socketio

capability-socketio 模块

📋 模块说明

SocketIO 能力层模块，提供实时通信能力，可独立打包为 SDK。

🎯 功能特性

• ✅ Socket.IO 实时通信
• ✅ 自动重连机制
• ✅ Token 自动刷新
• ✅ 生命周期管理
• ✅ 事件订阅/发布
• ✅ 独立打包 SDK

📦 依赖

• @xdz/base-core: 基础设施层（ILog、StorageImpl）
• @kit.NetworkKit: HarmonyOS 网络工具包（WebSocket）
• @kit.AbilityKit: HarmonyOS Ability 工具包

🚀 使用方式

1. 初始化（在 AppInitializer 中）

import { SocketIOManager } from '@xdz/capability-socketio';
import { AuthManager } from '@xdz/base-common';

// 1. 初始化 SocketIO 管理器
SocketIOManager.init(context);

// 2. 设置回调函数
SocketIOManager.isLoggedInProvider = () => {
  return AuthManager.getInstance().isLoggedIn();
};

SocketIOManager.refreshTokenProvider = async () => {
  const result = await AuthManager.getInstance().refreshToken();
  if (result.isSuccess) {
    return AuthManager.getInstance().getAccessToken();
  }
  return null;
};

2. 在 EntryAbility 中监听生命周期

import { SocketIOManager } from '@xdz/capability-socketio';

async onForeground(): Promise<void> {
  await SocketIOManager.onForeground();
}

onBackground(): void {
  SocketIOManager.onBackground();
}

3. 业务代码中使用

import { SocketIORepositoryFactory } from '@xdz/capability-socketio';

// 获取 Repository 实例
const repository = SocketIORepositoryFactory.getInstance();

// 连接服务器
await repository.connect(serverUrl, token);

// 观察连接状态
repository.connectionState.observe((isConnected) => {
  console.log('连接状态:', isConnected);
});

// 发送消息
await repository.sendVehicleControl('lock', vehicleId);

// 观察车辆报警
repository.vehicleAlarm.observe((alarm) => {
  if (alarm) {
    console.log('收到报警:', alarm.data);
  }
});

📁 模块结构

capability-socketio/
├── src/main/ets/socketio/
│   ├── api/              # API 接口
│   │   └── SocketIOService.ets
│   ├── factory/          # 工厂类
│   │   ├── SocketIOServiceFactory.ets
│   │   └── SocketIORepositoryFactory.ets
│   ├── impl/             # 实现类
│   │   └── SocketIOServiceImpl.ets
│   ├── manager/          # 管理器
│   │   └── SocketIOManager.ets
│   ├── model/            # 数据模型
│   │   ├── SocketIOEvent.ets
│   │   └── SocketIOResponse.ets
│   └── repository/       # 数据仓库
│       ├── SocketIORepository.ets
│       └── StateFlow.ets
├── oh-package.json5      # 依赖配置
├── module.json5         # 模块配置
└── index.ets            # 导出入口

🔧 独立打包 SDK

1. 配置模块为 HAR（HarmonyOS Archive）

模块已配置为 type: "har"，可以独立打包。

2. 打包步骤

# 在 DevEco Studio 中
# 1. 右键点击 capability-socketio 模块
# 2. 选择 "Build" -> "Make Module 'capability-socketio'"
# 3. 生成的 HAR 文件在 build/default/outputs/default/ 目录下

3. 使用打包的 SDK

// 在其他项目的 oh-package.json5 中
{
  "dependencies": {
    "@xdz/capability-socketio": "file:../path/to/capability-socketio.har"
  }
}

📝 API 文档

SocketIORepository

• connect(serverUrl?: string, token?: string): 连接服务器
• disconnect(): 断开连接
• isConnected(): 检查连接状态
• checkAndReconnect(serverUrl?: string, token?: string): 检查并重连
• sendVehicleControl(command: string, vehicleId: number): 发送车辆控制指令

SocketIOManager

• init(context: Context): 初始化管理器
• onForeground(): App 进入前台时调用
• onBackground(): App 进入后台时调用
• isLoggedInProvider: 登录状态检查回调
• refreshTokenProvider: Token 刷新回调

⚠️ 注意事项

1. WebSocket 实现: 当前使用 HarmonyOS WebSocket API，需要确保服务器支持 Socket.IO 协议
2. Token 传递: Token 通过 URL 参数传递（?token=xxx）
3. 生命周期: 需要在 EntryAbility 中手动调用 onForeground() 和 onBackground()
4. 依赖方向: capability-socketio 只依赖 base-core，不依赖 base-common

📄 许可证

MIT