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: 'test@example.com',
    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

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

Libraries

flutter_backend_sdk
Flutter SDK for Backend Go API