欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在进行 OpenHarmony 应用开发时，后端服务的搭建往往是让前端开发者头疼的问题。如果你不想折腾复杂的服务器环境，又希望拥有实时数据库、身份验证和文件存储功能，PocketBase 是你的不二之选。

PocketBase 是一个用 Go 编写的单文件后端，而 pocketbase Dart 库则是它的官方 SDK。它不仅支持标准的 CRUD 操作，还内置了极强的实时订阅（Real-time Subscription）能力。

对于 OpenHarmony 开发者，该库纯 Dart 实现，无平台依赖，是构建中小型移动应用或原型系统的最佳拍档。

一、核心原理解析

PocketBase 的 SDK 采用了基于 HTTP 的异步通信机制，并利用 Server-Sent Events (SSE) 实现了低延迟的实时更新。

二、核心 API 详解

2.1 初始化客户端

在使用前，你需要配置后端地址以便建立连接。

import 'package:pocketbase/pocketbase.dart';

// 💡 核心 API：创建全局客户端实例
final pb = PocketBase('http://你的服务器地址:8090');

// 检查当前认证状态
print('AuthStore 是否有效: ${pb.authStore.isValid}');
print('服务器基地址: ${pb.baseURL}');

2.2 用户身份验证

PocketBase 提供了极其简便的邮箱/密码登录流程，并自动管理令牌。

// 示例：用户登录逻辑
Future<void> login() async {
  // 💡 核心 API：执行登录，结果会自动存储在 pb.authStore 中
  final authData = await pb.collection('users').authWithPassword(
    'test@example.com',
    '1234567890',
  );
  
  print('✅ 登录成功，Token: ${pb.authStore.token}');
  print('用户 ID: ${pb.authStore.model.id}');
}

2.3 实时订阅数据 (SSE)

利用服务器发送事件实现无需轮询的即时更新。

// 示例：监听 messages 集合中所有文档的变化
void subscribeToMessages() {
  // 💡 核心 API：通配符订阅
  pb.collection('messages').subscribe('*', (e) {
    print('收到事件类型: ${e.action}'); // "create", "update", "delete"
    print('变更的数据内容: ${e.record?.data}');
  });
}

// 💡 适配提示：组件销毁时记得取消订阅
// pb.collection('messages').unsubscribe();

三、OpenHarmony 平台适配

3.1 网络请求白名单

在 OpenHarmony 环境中运行前，必须确保你的鸿蒙项目已在 module.json5 中配置了 ohos.permission.INTERNET 权限。

3.2 离线存储适配

pocketbase 默认将令牌保存在内存中。对于持久化登录，可以通过自定义 AuthStore 结合鸿蒙的 Preferences (首选项) 或 Database 模块来实现。

// 💡 技巧：自定义 AuthStore 以支持鸿蒙持久化
class OhosAuthStore extends AuthStore {
  // 这里可以重写 save 和 clear 方法，调用鸿蒙原生的 Preferences 接口
}

四、完整实战示例：鸿蒙实时动态墙

本示例演示了如何通过订阅逻辑实现一个简单但高效的消息动态流动模块。

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

class PBRealtimeDemo extends StatefulWidget {
  const PBRealtimeDemo({super.key});

  @override
  _PBRealtimeDemoState createState() => _PBRealtimeDemoState();
}

class _PBRealtimeDemoState extends State<PBRealtimeDemo> {
  final pb = PocketBase('https://your-pb-instance.com');
  List<RecordModel> posts = [];

  @override
  void initState() {
    super.initState();
    _loadInitialData();
    _setupSubscription();
  }

  // 1. 💡 加载首屏数据
  Future<void> _loadInitialData() async {
    final result = await pb.collection('posts').getList(
      page: 1,
      perPage: 20,
      sort: '-created',
    );
    setState(() => posts = result.items);
  }

  // 2. 💡 建立 SSE 实时监听
  void _setupSubscription() {
    pb.collection('posts').subscribe('*', (e) {
      if (e.action == 'create') {
        setState(() => posts.insert(0, e.record!)); // 将新消息置顶
      }
    });
  }

  @override
  void dispose() {
    pb.collection('posts').unsubscribe(); // 💡 鸿蒙适配要求：显式断开 SSE 连接以节省能耗
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('鸿蒙实时动态 (PocketBase)')),
      body: ListView.builder(
        itemCount: posts.length,
        itemBuilder: (context, index) {
          final post = posts[index];
          return ListTile(
            leading: const Icon(Icons.message, color: Colors.blue),
            title: Text(post.getStringValue('content')),
            subtitle: Text('发布于: ${post.created}'),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        child: const Icon(Icons.add),
        onPressed: () async {
          // 3. 💡 发起数据创建请求
          await pb.collection('posts').create(body: {
            'content': '来自鸿蒙设备的消息@${DateTime.now().second}',
          });
        },
      ),
    );
  }
}

五、总结

pocketbase 软件包为 OpenHarmony 开发者提供了一条通往全栈开发的捷径。其极简的接口设计和强大的实时同步能力，能够显著缩短鸿蒙应用从构思到上线的时间。在开发中，请务必注意实时订阅的资源清理，以确保应用在鸿蒙系统上运行的流畅性和稳定性。