xim/open-im-sdk-flutter-m

Fork 0

gem a35eba1160 增加群组通知过滤

2025-11-20 14:27:36 +08:00

5.7 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个 Flutter 插件项目,为 OpenIM 即时通讯服务提供 Flutter SDK 封装。该 SDK 支持 Android、iOS 和 Windows 平台。

核心架构:

Flutter 层通过 MethodChannel 与原生层通信
Android 原生层使用 gomobile 编译的 AAR 包与 OpenIM SDK Core (Go) 交互
iOS 原生层使用 gomobile 编译的 XCFramework 与 OpenIM SDK Core 交互
数据传输格式为 JSON,数据存储使用 OpenIM SDK Core 内置的 SQLite

常用命令

开发环境设置

# 安装依赖
flutter pub get

# 运行示例应用
cd example
flutter pub get
flutter run

测试

# 运行单元测试
flutter test

# 运行集成测试
cd example
flutter test integration_test/plugin_integration_test.dart

代码格式化

# 格式化代码
dart format .

# 分析代码
flutter analyze

Android 构建

# 在 example 目录中构建 Android
cd example
flutter build apk

# 构建 Android AAR
cd android
./gradlew assembleRelease

iOS 构建

# 在 example 目录中构建 iOS
cd example
flutter build ios

核心架构设计

1. 管理器层次结构

IMManager 是核心管理器,包含以下子管理器:

ConversationManager: 会话管理(lib/src/manager/im_conversation_manager.dart)
MessageManager: 消息管理(lib/src/manager/im_message_manager.dart)
FriendshipManager: 好友关系管理(lib/src/manager/im_friendship_manager.dart)
GroupManager: 群组管理(lib/src/manager/im_group_manager.dart)
ChannelManager: <20><>道管理(lib/src/manager/im_channel_manager.dart)
UserManager: 用户管理(lib/src/manager/im_user_manager.dart)

2. 双向通信机制

Flutter → Native (方法调用):

Flutter 通过 MethodChannel 调用原生方法
参数统一使用 _buildParam() 封装,添加 ManagerName 和清理空值
每个请求可携带 operationID 用于追踪

Native → Flutter (回调监听):

原生层通过 MethodChannel 回调 Flutter 层
Flutter 在 IMManager._addNativeCallback() 中统一处理所有监听器回调
监听器类型定义在 lib/src/enum/listener_type.dart

3. 数据模型转换

所有数据模型位于 lib/src/models/,使用 JSON 序列化/反序列化:

Utils.toObj(): JSON Map 转对象
Utils.toList(): JSON Array 转对象列表
所有模型类实现 fromJson() 和 toJson() 方法

4. 监听器系统

监听器定义在 lib/src/listener/,主要包括:

OnConnectListener: 连接状态监听
OnAdvancedMsgListener: 高级消息监听
OnConversationListener: 会话变化监听
OnFriendshipListener: 好友关系监听
OnGroupListener: 群组事件监听
OnChannelListener: 频道事件监听
OnUserListener: 用户信息监听

5. 原生层实现

Android (Java):

插件入口: android/src/main/java/io/openim/flutter_openim_sdk/FlutterOpenimSdkPlugin.java
各管理器实现: android/src/main/java/io/openim/flutter_openim_sdk/manager/
依赖的 OpenIM SDK Core AAR 包位于 android/libs/

iOS (Swift/ObjC):

插件入口: ios/Classes/SwiftFlutterOpenimSdkPlugin.swift
模块化管理器: ios/Classes/Module/
工具类: ios/Classes/Util/

开发注意事项

SDK 初始化和登录流程

必须先初始化 SDK (initSDK() 或 init())
设置监听器 (必须在登录前完成)
登录 (login())
SDK 初始化需要提供:
- platformID: 平台 ID (参考 IMPlatform 枚举)
- apiAddr: OpenIM Server API <20><><EFBFBD>址
- wsAddr: OpenIM Server WebSocket 地址
- dataDir: 数据存储目录

消息收发

创建消息使用 MessageManager.create*Message() 系列方法
发送消息使用 MessageManager.sendMessage()
接收消息通过 OnAdvancedMsgListener 监听
支持单聊、群聊、在线消息等多种场景

平台特定功能

Android 独有: setListenerForService() - 用于后台服务监听
通知可见性规则: Android SDK 35+ 支持的通知管理功能
文件上传: 支持自定义上传监听器 (OnUploadFileListener)

版本管理

SDK 版本定义在 lib/src/openim.dart 中的 OpenIM.version
pubspec.yaml 中的版本应与之保持一致
使用格式: major.minor.patch+build (如 3.8.3+2)

日志和调试

使用 Logger.print() 输出日志 (lib/src/logger.dart)
支持上传日志到服务器: uploadLogs()
可自定义日志级别 (1-6,默认 6 为全部输出)

Android 特定配置

ProGuard 规则

项目使用 ProGuard 混淆,规则文件在 example/android/app/proguard-rules.pro:

-keep class io.openim.** { *; }
-keep class open_im_sdk.** { *; }
-keep class open_im_sdk_callback.** { *; }

Gradle 配置

使用阿里云 Maven 镜像加速依赖下载
本地 Maven 仓库: http://192.168.77.132:8081/repository/mvn2-group (需根据实际情况修改)
compileSdkVersion: 34
minSdkVersion: 21

常见任务

添加新的 API 方法

在对应的 Manager 类(Dart)中添加方法
在 Android Manager 类(Java)中实现
在 iOS Module 类(Swift)中实现
确保参数序列化和回调处理正确

添加新的监听器

在 lib/src/listener/ 创建监听器类
在 ListenerType 枚举中添加类型
在 IMManager._addNativeCallback() 中添加处理逻辑
在原生层实现对应的回调触发

调试原生层交互

Flutter → Native: 在 Logger.print() 查看方法调用日志
Native → Flutter: 在 _addNativeCallback() 设置断点查看回调数据
使用 operationID 追踪特定操作的完整流程

5.7 KiB Raw Permalink Blame History Unescape Escape