Flutter嵌入式数据库插件couchbase_lite的使用

Flutter嵌入式数据库插件couchbase_lite的使用

couchbase_lite plugin

一个用于Couchbase Lite社区版的Flutter插件。它是一个轻量级、无服务器的嵌入式数据库，在Android和iOS上支持实时同步和离线功能。

该项目的目标是使此库与Couchbase Lite的Swift SDK API对齐。

注意：此插件仍在开发中，部分API可能尚未可用。欢迎提供反馈和拉取请求！

此项目基于Fluttercouch分叉而来。

开始使用

在你的Flutter项目中添加依赖项：

dependencies:
  couchbase_lite: ^2.7.1
  
  flutter:
      sdk: flutter

有关Flutter入门的更多信息，请查看官方文档。

支持的版本

iOS

Android

API 参考

• Swift SDK API 参考
• Java SDK API 参考

注意：语法遵循Swift SDK，但这些是平台代码所使用的SDK。

本地服务器设置

下载并安装Couchbase Server / Sync Gateway社区版，访问以下链接：

• Sync Gateway 入门指南
• Couchbase 下载

设置beer-sample数据库（本地Couchbase Server）：

1. 添加beer-sample桶：设置 -> 示例桶
2. 在Couchbase Server的安全性下创建sync_gateway用户
3. 授予sync_gateway访问beer-sample的权限

启动Sync Gateway：

~/Downloads/couchbase-sync-gateway/bin/sync_gateway ~/path/to/sync-gateway-config.json

注意：此示例中包含sync-gateway-config.json（登录信息为u: foo, p: bar）。

使用示例

以下是一个使用BLoC模式（View ↔ BLoC ↔ Repository ↔ Database）的数据库示例：

// 初始化数据库
try {
  database = await Database.initWithName("gettingStarted");
} on PlatformException {
  return "Error initializing database";
}

// 创建新文档（即记录）。
var mutableDoc = MutableDocument()
    .setDouble("version", 2.0)
    .setString("type", "SDK");

// 将其保存到数据库中。
try{
  await database.saveDocument(mutableDoc);
} on PlatformException {
  return "Error saving document";
}

// 更新文档。
mutableDoc = (await database.document(mutableDoc.id))?.toMutable()?.setString("language", "Dart");

if (mutableDoc != null) {
  // 将更新后的文档保存到数据库中。
  try {
    await database.saveDocument(mutableDoc);

    var document = await database.document(mutableDoc.id);

    // 打印文档ID（由数据库生成）和属性。
    print("Document ID :: ${document.id}");
    print("Learning ${document.getString("language")}");
  } on PlatformException {
    return "Error saving document";
  }
}

// 创建查询以获取类型为SDK的文档。
var query = QueryBuilder
    .select([SelectResult.all().from("mydocs")])
    .from("gettingStarted", as: "mydocs")
    .where(Expression.property("type").from("mydocs").equalTo(Expression.string("SDK")));

// 执行查询。
try {
  var result = await query.execute();
  print("Number of rows :: ${result.allResults().length}");
} on PlatformException {
  return "Error running the query";
}

// 注意wss://10.0.2.2:4984/my-database 是用于Android模拟器上的本地Couchbase数据库。
// 创建复制器以从云端推送和拉取更改。
ReplicatorConfiguration config =
ReplicatorConfiguration(database, "ws://10.0.2.2:4984/beer-sample");
config.replicatorType = ReplicatorType.pushAndPull;
config.continuous = true;

// 添加身份验证。
config.authenticator = BasicAuthenticator("foo", "bar");

// 创建复制器（确保添加一个名为replicator的实例或静态变量）。
var replicator = Replicator(config);

// 监听复制器更改事件。
_listenerToken = replicator.addChangeListener((ReplicatorChange event) {
  if (event.status.error != null) {
    print("Error: " + event.status.error);
  }

  print(event.status.activity.toString());
});

// 启动复制器。
await replicator.start();

注意：对于此入门指南，您需要允许使用ws协议。

从Android Pie（版本9，API 28）开始，默认禁用了明文流量支持。虽然wss协议不受影响，但在Android 27或更低版本中使用ws协议的应用程序必须配置网络安全性。例如：

<application android:usesCleartextTraffic="true">
</application>

自iOS 9起，默认启用App Transport Security，强制应用程序仅使用HTTPS。为了完成本入门指南，您需要禁用它，但在生产环境中我们建议启用它，并启用Sync Gateway上的HTTPS。在Xcode资源管理器中，右键单击Info.plist文件并以源文件形式打开它。

在</dict>标签内追加以下内容：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key><true/>
</dict>

示例代码

以下是完整的示例代码，您可以将其直接运行：

import 'dart:async';

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

void main() => runApp(BeerSampleApp(AppMode.production));

class BeerSampleApp extends StatelessWidget {
  final AppMode mode;

  const BeerSampleApp(this.mode);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

class HomeScreen extends StatefulWidget {
  [@override](/user/override)
  _HomeScreenState createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  String _status = 'Initializing...';
  Database _database;
  Replicator _replicator;
  ListenerToken _listenerToken;

  [@override](/user/override)
  void initState() {
    super.initState();
    _initialize();
  }

  Future<void> _initialize() async {
    try {
      _database = await Database.initWithName("gettingStarted");
      _status = 'Database initialized.';
    } catch (e) {
      _status = 'Error initializing database: $e';
      return;
    }

    // 创建新文档。
    var doc = MutableDocument()
        ..setDouble("version", 2.0)
        ..setString("type", "SDK");

    try {
      await _database.saveDocument(doc);
      _status += '\nDocument saved.';
    } catch (e) {
      _status += '\nError saving document: $e';
      return;
    }

    // 查询所有文档。
    var query = QueryBuilder.select([SelectResult.property("type")])
        .from("gettingStarted")
        .where(Expression.property("type").equalTo(Expression.string("SDK")));

    try {
      var result = await query.execute();
      _status += '\nQuery results: ${result.allResults().length} rows.';
    } catch (e) {
      _status += '\nError running query: $e';
      return;
    }

    // 设置复制器。
    var replicatorConfig = ReplicatorConfiguration(_database, "ws://10.0.2.2:4984/beer-sample");
    replicatorConfig.replicatorType = ReplicatorType.pushAndPull;
    replicatorConfig.continuous = true;
    replicatorConfig.authenticator = BasicAuthenticator("foo", "bar");

    try {
      _replicator = Replicator(replicatorConfig);
      _listenerToken = _replicator.addChangeListener((event) {
        if (event.status.activity == ReplicatorActivityLevel.stopped) {
          _status += '\nReplication stopped.';
        } else {
          _status += '\nReplication status: ${event.status.activity}';
        }
      });
      await _replicator.start();
      _status += '\nReplication started.';
    } catch (e) {
      _status += '\nError starting replication: $e';
    }
  }

  [@override](/user/override)
  void dispose() {
    _replicator?.removeChangeListener(_listenerToken);
    _replicator?.stop();
    _replicator?.dispose();
    _database?.close();
    super.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Couchbase Lite Example')),
      body: Center(
        child: Text(_status, textAlign: TextAlign.center),
      ),
    );
  }
}