flutter_backend_sdk 1.0.0

Flutter SDK for Backend Go API - 用户管理、文件存储、好友系统和实时聊天功能的完整SDK

Flutter Backend SDK

为Backend Go项目提供的Flutter SDK，支持用户认证、文件管理、好友系统和实时聊天功能。

功能特性

• 🔐 用户认证: 注册、登录、激活、密码重置
• 📁 文件管理: 文件上传、下载、分类管理
• 👥 好友系统: 好友请求、好友管理、黑名单
• 💬 实时聊天: WebSocket聊天、在线状态、输入状态
• 🔒 JWT认证: 自动令牌管理和刷新
• 📱 类型安全: 完整的Dart类型定义

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_backend_sdk:
    path: ../path/to/flutter_backend_sdk

快速开始

1. 初始化SDK

import 'package:flutter_backend_sdk/flutter_backend_sdk.dart';

final sdk = BackendSdkClient(
  baseUrl: 'https://your-api.com/api/v1',
  wsUrl: 'wss://your-api.com/ws',  // 可选，默认从baseUrl推导
  enableLogging: true,  // 开发环境建议开启
);

2. 用户认证

// 用户注册
try {
  await sdk.auth.register(RegisterRequest(
    username: 'testuser',
    email: '[e-mail]',
    password: 'password123',
  ));
  print('注册成功，请检查邮箱激活账户');
} catch (e) {
  print('注册失败: $e');
}

// 用户登录
try {
  final response = await sdk.auth.login('testuser', 'password123');
  sdk.setAccessToken(response.accessToken);
  print('登录成功: ${response.user.username}');
} catch (e) {
  print('登录失败: $e');
}

// 获取当前用户信息
final user = await sdk.user.getCurrentUser();
print('当前用户: ${user.username}');

3. 文件管理

// 上传文件
final file = await sdk.file.uploadFile(
  '/path/to/file.jpg',
  request: FileUploadRequest(
    category: 'images',
    isPublic: false,
  ),
);
print('文件上传成功: ${file.filename}');

// 获取我的文件列表
final files = await sdk.file.getMyFiles(
  category: 'images',
  page: 1,
  pageSize: 20,
);
print('文件数量: ${files.data.length}');

4. 好友系统

// 发送好友请求
await sdk.friend.createFriendRequest(
  CreateFriendRequestRequest(
    receiverId: 'user_id',
    note: '你好，我想加你为好友',
  ),
);

// 获取好友请求列表
final requests = await sdk.friend.getIncomingRequests();
for (final request in requests.data) {
  print('好友请求来自: ${request.requester?.username}');
}

// 接受好友请求
await sdk.friend.acceptFriendRequest('request_id');

// 获取好友列表
final friends = await sdk.friend.getFriends();
print('好友数量: ${friends.data.length}');

5. 实时聊天

// 连接聊天WebSocket
await sdk.connectChat(accessToken);

// 监听消息
sdk.chat.messageStream.listen((message) {
  print('收到消息: ${message.content}');
});

// 监听在线状态
sdk.chat.presenceStream.listen((status) {
  print('用户 ${status.userId} 状态: ${status.status}');
});

// 监听输入状态
sdk.chat.typingStream.listen((typing) {
  if (typing.isTyping) {
    print('用户 ${typing.userId} 正在输入...');
  }
});

// 发送消息
await sdk.chat.sendTextMessage('room_id', '你好！');

// 发送输入状态
await sdk.chat.sendTypingStatus('room_id', true);

// 发送在线状态
await sdk.chat.sendPresenceStatus(OnlineStatus.online);

6. 聊天房间管理

// 获取或创建聊天房间
final room = await sdk.chatRoom.getOrCreateRoom('friend_id');
print('聊天房间ID: ${room.id}');

// 获取我的聊天房间列表
final rooms = await sdk.chatRoom.getMyRooms();
for (final room in rooms.data) {
  final otherUserId = room.getOtherUserId(currentUserId);
  print('与用户 $otherUserId 的聊天房间');
}

错误处理

SDK使用统一的异常处理机制：

try {
  await sdk.auth.login('username', 'password');
} on ApiException catch (e) {
  print('API错误: ${e.message} (代码: ${e.code})');
} on NetworkException catch (e) {
  print('网络错误: ${e.message}');
} on AuthException catch (e) {
  print('认证错误: ${e.message}');
} on WebSocketException catch (e) {
  print('WebSocket错误: ${e.message}');
} catch (e) {
  print('未知错误: $e');
}

配置选项

开发环境配置

final sdk = BackendSdkClient(
  baseUrl: 'http://localhost:8080/api/v1',
  wsUrl: 'ws://localhost:8080/ws',
  enableLogging: true,
);

生产环境配置

final sdk = BackendSdkClient(
  baseUrl: 'https://api.yourapp.com/api/v1',
  wsUrl: 'wss://api.yourapp.com/ws',
  timeout: const Duration(seconds: 30),
  enableLogging: false,
);

完整示例

import 'package:flutter/material.dart';
import 'package:flutter_backend_sdk/flutter_backend_sdk.dart';

class ChatApp extends StatefulWidget {
  @override
  _ChatAppState createState() => _ChatAppState();
}

class _ChatAppState extends State<ChatApp> {
  late BackendSdkClient sdk;
  final List<ChatMessage> messages = [];

  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() async {
    sdk = BackendSdkClient(
      baseUrl: 'https://your-api.com/api/v1',
      enableLogging: true,
    );

    // 登录
    try {
      final response = await sdk.auth.login('username', 'password');
      sdk.setAccessToken(response.accessToken);
      
      // 连接聊天
      await sdk.connectChat(response.accessToken);
      
      // 监听消息
      sdk.chat.messageStream.listen((message) {
        setState(() {
          messages.add(message);
        });
      });
    } catch (e) {
      print('初始化失败: $e');
    }
  }

  @override
  void dispose() {
    sdk.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('聊天')),
      body: ListView.builder(
        itemCount: messages.length,
        itemBuilder: (context, index) {
          final message = messages[index];
          return ListTile(
            title: Text(message.content),
            subtitle: Text(message.senderId),
          );
        },
      ),
    );
  }
}

API文档

认证服务 (AuthService)

• register(RegisterRequest) - 用户注册
• login(String, String) - 用户登录
• activate(String, String) - 账户激活
• refreshToken() - 刷新令牌
• logout() - 用户登出
• sendResetPasswordCode(String) - 发送重置密码验证码
• resetPassword(ResetPasswordRequest) - 重置密码

用户服务 (UserService)

• getCurrentUser() - 获取当前用户信息
• updateCurrentUser(UpdateUserRequest) - 更新用户信息
• getUserById(String) - 根据ID获取用户
• getUserByUsername(String) - 根据用户名获取用户
• searchUsers(String) - 搜索用户

文件服务 (FileService)

• uploadFile(String, FileUploadRequest?) - 上传文件
• uploadMultipleFiles(List<String>, FileUploadRequest?) - 批量上传
• getFileById(String) - 获取文件详情
• getMyFiles() - 获取我的文件列表
• getPublicFiles() - 获取公开文件列表
• updateFile(String, FileUpdateRequest) - 更新文件信息
• deleteFile(String) - 删除文件
• getStorageInfo() - 获取存储信息

好友服务 (FriendService)

• createFriendRequest(CreateFriendRequestRequest) - 发送好友请求
• getIncomingRequests() - 获取收到的好友请求
• getOutgoingRequests() - 获取发送的好友请求
• acceptFriendRequest(String) - 接受好友请求
• rejectFriendRequest(String) - 拒绝好友请求
• cancelFriendRequest(String) - 取消好友请求
• getFriends() - 获取好友列表
• deleteFriend(String) - 删除好友
• updateFriendRemark(String, String) - 更新好友备注
• blockUser(BlockUserRequest) - 拉黑用户
• unblockUser(String) - 取消拉黑
• getBlockList() - 获取黑名单

聊天服务 (ChatService)

• connect(String) - 连接WebSocket
• disconnect() - 断开连接
• sendTextMessage(String, String) - 发送文本消息
• sendTypingStatus(String, bool) - 发送输入状态
• sendPresenceStatus(OnlineStatus) - 发送在线状态
• sendReaction(String, String, String) - 发送消息反应

聊天房间服务 (ChatRoomService)

• getOrCreateRoom(String) - 获取或创建聊天房间
• getMyRooms() - 获取我的聊天房间列表
• getRoomById(String) - 根据ID获取聊天房间
• deactivateRoom(String) - 停用聊天房间

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 支持用户认证、文件管理、好友系统和实时聊天
• 完整的类型定义和错误处理