如何将Objective-C环境下的Couchbase Lite 1.3.1升级至3.0版本？

一、升级启动步骤 #

• 清理旧依赖：移除项目中所有Couchbase Lite 1.3.1相关的文件、框架或CocoaPods配置，确保无残留（如用CocoaPods，执行pod deintegrate后删除旧的pod行）。
• 引入3.0版本：通过CocoaPods添加依赖，在Podfile中添加pod 'CouchbaseLite-ObjC', '~> 3.0'，执行pod install完成安装；手动导入的话，下载官方3.0的Objective-C框架并添加到项目。
• 重构核心初始化逻辑：
  1. 移除所有CBLManager相关代码，直接初始化CBLDatabase实例：

     // 旧1.3.1代码
     CBLManager *manager = [CBLManager sharedInstance];
     CBLDatabase *db = [manager databaseNamed:@"mydb"];
     
     // 新3.0代码
     CBLDatabaseConfiguration *config = [[CBLDatabaseConfiguration alloc] init];
     config.directory = @"自定义存储路径（可选）";
     NSError *error;
     CBLDatabase *db = [[CBLDatabase alloc] initWithName:@"mydb" config:config error:&error];
     if (error) { /* 处理初始化错误 */ }
     

  2. 处理文档操作逻辑，替换旧的CBLDocument用法。
• 逐步替换其他弃用API：按查询、同步、视图等模块，逐个替换为3.0对应的API，同时测试每个模块的功能是否正常。
• 全面测试：覆盖数据库读写、同步、查询等核心场景，排查API变更导致的逻辑问题。

二、常见弃用类/方法/属性的替代方案 #

• CBLManager：直接使用CBLDatabase实例管理单个数据库，多数据库场景下初始化多个CBLDatabase对象即可；数据库的全局配置（如存储路径）通过CBLDatabaseConfiguration设置。
• CBLDocument.properties：
  • 获取完整属性字典：使用-[CBLDocument toDictionary]
  • 获取单个属性：使用-[CBLDocument valueForKey:]
  • 修改文档：先转为CBLMutableDocument，通过-[CBLMutableDocument setValue:forKey:]或-[CBLMutableDocument setDictionary:]设置属性，再保存到数据库：

    // 旧1.3.1代码
    CBLDocument *doc = [db documentWithID:@"doc1"];
    NSDictionary *props = doc.properties;
    
    // 新3.0代码
    CBLDocument *doc = [db documentWithID:@"doc1"];
    NSDictionary *props = [doc toDictionary];
    NSString *name = [doc valueForKey:@"name"];
    
    // 修改文档
    CBLMutableDocument *mutableDoc = [doc toMutable];
    [mutableDoc setValue:@"newName" forKey:@"name"];
    NSError *saveError;
    [db saveDocument:mutableDoc error:&saveError];
    

• 旧查询API（CBLView/CBLQuery）：替换为CBLQueryBuilder，通过链式语法构建查询：

  // 示例：查询name等于"Alice"的文档
  CBLQuery *query = [CBLQueryBuilder select:@{@"name": [CBLExpression property:@"name"]}
                                     from:[CBLDataSource database:db]
                                    where:[CBLExpression property:@"name"] equalTo:[CBLExpression string:@"Alice"]];
  CBLQueryResultSet *result = [query execute:&error];
  

• 旧同步API（CBLReplication）：替换为CBLReplicator，使用CBLReplicatorConfiguration配置同步参数：

  CBLURLEndpoint *endpoint = [[CBLURLEndpoint alloc] initWithURL:[NSURL URLWithString:@"ws://example.com/db"]];
  CBLReplicatorConfiguration *config = [[CBLReplicatorConfiguration alloc] initWithDatabase:db target:endpoint];
  config.replicatorType = kCBLReplicatorTypePushAndPull;
  config.continuous = YES;
  
  CBLReplicator *replicator = [[CBLReplicator alloc] initWithConfig:config];
  [replicator start];
  

内容的提问来源于stack exchange，提问作者Arjun Singh Baghel