iOS/macOS使用教程 - 《WCDB - 腾讯开源的移动数据库框架》

安装
类字段绑定（ORM）
增删改查（CRUD）
事务（Transaction）
WINQ（WCDB语言集成查询）
- 字段映射与运算符
- 字段组合
- AllProperties
- AnyProperty
加密
全局监控
损坏修复

安装

WCDB提供了多种安装方式，请参考 README

类字段绑定（ORM）

在WCDB内，ORM（Object Relational Mapping）是指

将一个ObjC的类，映射到数据库的表和索引；
将类的property，映射到数据库表的字段；
这一过程。通过ORM，可以达到直接通过Object进行数据库操作，省去拼装过程的目的。

WCDB通过内建的宏实现ORM的功能。如下：

//Message.h
@interface Message : NSObject
 
@property int localID;
@property(retain) NSString *content;
@property(retain) NSDate *createTime;
@property(retain) NSDate *modifiedTime;
@property(assign) int unused; //You can only define the properties you need
 
@end

//Message.mm
#import "Message.h"
@implementation Message
 
WCDB_IMPLEMENTATION(Message)
WCDB_SYNTHESIZE(Message, localID)
WCDB_SYNTHESIZE(Message, content)
WCDB_SYNTHESIZE(Message, createTime)
WCDB_SYNTHESIZE(Message, modifiedTime)
 
WCDB_PRIMARY(Message, localID)
 
WCDB_INDEX(Message, "_index", createTime)
 
@end

//Message+WCTTableCoding.h
#import "Message.h"
#import <WCDB/WCDB.h>
 
@interface Message (WCTTableCoding) <WCTTableCoding>
 
WCDB_PROPERTY(localID)
WCDB_PROPERTY(content)
WCDB_PROPERTY(createTime)
WCDB_PROPERTY(modifiedTime)
 
@end

将一个已有的ObjC类进行ORM绑定的过程如下：

定义该类遵循WCTTableCoding协议。可以在类声明上定义，也可以通过文件模版在category内定义。
使用WCDB_PROPERTY宏在头文件声明需要绑定到数据库表的字段。
使用WCDB_IMPLEMENTATIO宏在类文件定义绑定到数据库表的类。
使用WCDB_SYNTHESIZE宏在类文件定义需要绑定到数据库表的字段。
简单几行代码，就完成了将类和需要的字段绑定到数据库表的过程。这三个宏在名称和使用习惯上，也都和定义一个ObjC类相似，以此便于记忆。

除此之外，WCDB还提供了许多可选的宏，用于定义数据库索引、约束等，如：

WCDB_PRIMARY用于定义主键
WCDB_INDEX用于定义索引
WCDB_UNIQUE用于定义唯一约束
WCDB_NOT_NULL用于定义非空约束
…
定义完成后，只需要调用createTableAndIndexesOfName:withClass:接口，即可创建表和索引。

WCTDatabase *database = [[WCTDatabase alloc] initWithPath:path];
/*
 CREATE TABLE messsage (localID INTEGER PRIMARY KEY,
                         content TEXT,
                         createTime BLOB,
                         modifiedTime BLOB)
 */
BOOL result = [database createTableAndIndexesOfName:@"message"
                                          withClass:Message.class];

接口会根据ORM的定义，创建对应表和索引。

更多关于ORM定义，请参考：ORM使用教程

增删改查（CRUD）

得益于ORM的定义，WCDB可以直接进行通过object进行增删改查（CRUD）操作。开发者可以通过WCTDatabase和WCTTable两个类进行一般的增删改查操作。如下：

//插入
Message *message = [[Message alloc] init];
message.localID = 1;
message.content = @"Hello, WCDB!";
message.createTime = [NSDate date];
message.modifiedTime = [NSDate date];
/*
 INSERT INTO message(localID, content, createTime, modifiedTime) 
 VALUES(1, "Hello, WCDB!", 1496396165, 1496396165);
 */
BOOL result = [database insertObject:message
                                into:@"message"];

//删除
//DELETE FROM message WHERE localID>0;
BOOL result = [database deleteObjectsFromTable:@"message"
                                         where:Message.localID > 0];

//修改
//UPDATE message SET content="Hello, Wechat!";
Message *message = [[Message alloc] init];
message.content = @"Hello, Wechat!";
BOOL result = [database updateRowsInTable:@"message"
                             onProperties:Message.content
                               withObject:message];

//查询
//SELECT * FROM message ORDER BY localID
NSArray<Message *> *message = [database getObjectsOfClass:Message.class
                                                fromTable:@"message"
                                                  orderBy:Message.localID.order()];

WCTTable相当于预设了表名和类名的WCTDatabase对象，接口和WCTDatabase基本一致。

WCTTable *table = [database getTableOfName:@"message"
                                 withClass:Message.class];
//查询
//SELECT * FROM message ORDER BY localID
NSArray<Message *> *message = [table getObjectsOrderBy:Message.localID.order()];

更多关于增删改查的接口，请参考：基础类、CRUD与Transaction

事务（Transaction）

WCDB内可通过两种方式执行事务，一是runTransaction:接口，如下：

BOOL commited = [database runTransaction:^BOOL {
    [database insertObject:message into:@"message"];
    return YES; //return YES to commit transaction and return NO to rollback transaction.
}];

这种方式要求数据库操作在一个BLOCK内完成，简单易用。

另一种方式则是获取WCTTransaction对象，如下：

WCTTransaction *transaction = [database getTransaction];
BOOL result = [transaction begin];
[transaction insertObject:message into:@"message"];
result = [transaction commit];
if (!result) {
    [transaction rollback];
    NSLog(@"%@", [transaction error]);
}

WCTTransaction对象可以在类或函数间传递，因此这种方式也更具灵活性。

更多关于事务的注意事项，请参考：基础类、CRUD与Transaction。

WINQ（WCDB语言集成查询）

WINQ（WCDB Integrated Query，音'wink'），是将自然查询的SQL集成到WCDB框架中的技术，基于C++实现。

传统的SQL语句，通常是开发者拼接字符串完成。这种方式不仅繁琐、易错，而且出错后很难定位到问题所在。同时也容易给SQL注入留下可乘之机。

而WINQ将查询语言集成到了C++中，可以通过类似函数调用的方式来写SQL查询。借用IDE的代码提示和编译器的语法检查，达到易用、纠错的效果。

字段映射与运算符

对于一个已绑定ORM的类，可以通过className.propertyName的方式，获得数据库内字段的映射，以此书写SQL的条件、排序、过滤等等所有语句。如下是几个例子：

/*
 SELECT MAX(createTime), MIN(createTime)
 FROM message
 WHERE localID>0 AND content IS NOT NULL
 */
[database getObjectsOnResults:{Message.createTime.max(), Message.createTime.min()}
                    fromTable:@"message"
                        where:Message.localID > 0 && Message.content.isNotNull()];

/*
 SELECT DISTINCT localID
 FROM message
 ORDER BY modifiedTime ASC
 LIMIT 10
 */
[database getObjectsOnResults:Message.localID.distinct()
                    fromTable:@"message"
                      orderBy:Message.modifiedTime.order(WCTOrderedAscending)
                        limit:10];

/*
 DELETE FROM message
 WHERE localID BETWEEN 10 AND 20 OR content LIKE 'Hello%'
 */
[database deleteObjectsFromtable:@"message"
                           where:Message.local.between(10, 20) 
                                  || Message.content.like("Hello%")];

由于WINQ通过接口调用实现SQL查询，因此在书写过程中会有IDE的代码提示和编译器的语法检查，从而提升开发效率，避免写错。

WINQ的接口包括但不限于：

一元操作符：+、-、!等
二元操作符：||、&&、+、-、*、/、|、&、<<、>>、<、<=、==、!=、>、>=等
范围比较：IN、BETWEEN等
字符串匹配：LIKE、GLOB、MATCH、REGEXP等
聚合函数：AVG、COUNT、MAX、MIN、SUM等
…
凡是SQLite支持的语法规则，WINQ基本都有其对应的接口。且接口名称与SQLite的语法规则基本保持一致。

字段组合

多个字段映射可通过大括号{}进行组合，如：

/*
 SELECT localID, content
 FROM message
 */
[database getAllObjectsOnResults:{Message.localID, Message.content}
                        fromTable:@"message"];

/*
 SELECT *
 FROM message
 ORDER BY createTime ASC, localID DESC
 */
[database getObjectsOfClass:Message.class 
                  fromTable:@"message" 
                    orderBy:{Message.createTime.order(WCTOrderedAscending),  Message.localID.order(WCTOrderedDescending)}];

AllProperties

在上述的组合中，大括号{}的语法实质是C++中列表std::list的隐式初始化。而className.AllProperties则用于获取类定义的所有字段映射的列表，如：

/*
 SELECT localID, content, createTime, modifiedTime
 FROM message
*/
[database getAllObjectsOnResults:Message.AllProperties
                        fromTable:@"message"];

AnyProperty

className.AnyProperty用于指代SQL中的*，如：

/*
 SELECT count(*)
 FROM message
 */
 [database getOneValueOnResult:Message.AnyProperty.count()
                         fromTable:@"message"];

WINQ的使用上接近于C函数调用。对于熟悉SQL的开发者，无须特别学习即可立刻上手使用。

更多WINQ的具体实现，请参考：WINQ原理。

加密

WCDB提供基于sqlcipher的数据库加密功能，如下：

WCTDatabase *database = [[WCTDatabase alloc] initWithPath:path];
NSData *password = [@"MyPassword" dataUsingEncoding:NSASCIIStringEncoding];
[database setCipherKey:password];

全局监控

WCDB提供了对错误和性能的全局监控，可用于调试错误和性能。

//Error Monitor
[WCTStatistics SetGlobalErrorReport:^(WCTError *error) {
    NSLog(@"[WCDB]%@", error);
}];

//Performance Monitor
[WCTStatistics SetGlobalPerformanceTrace:^(WCTTag tag, NSDictionary<NSString *, NSNumber *> *sqls, NSInteger cost) {
    NSLog(@"Database with tag:%d", tag);
    NSLog(@"Run :");
    [sqls enumerateKeysAndObjectsUsingBlock:^(NSString *sqls, NSNumber *count, BOOL *) {
        NSLog(@"SQL %@ %@ times", sqls, count);
    }];
    NSLog(@"Total cost %lld nanoseconds", cost);
}];

//SQL Execution Monitor
[WCTStatistics SetGlobalSQLTrace:^(NSString *sql) {
    NSLog(@"SQL: %@", sql);
}];

更多全局监控的细节，请参考：全局监控与错误处理

损坏修复

WCDB内建了修复工具，以应对数据库损坏，无法使用的情况。

开发者需要在数据库未损坏时，对数据库元信息定时进行备份，如下：

NSData *backupPassword = [@"MyBackupPassword" dataUsingEncoding:NSASCIIStringEncoding];
[database backupWithCipher:backupPassword];

当检测到数据库损坏，即WCTError的type为WCTErrorTypeSQLite，code为11或26（SQLITE_CORRUPT或SQLITE_NOTADB）时，可以进行修复。

//Since recovering is a long time operation, you'd better call it in sub-thread.
[view startLoading];
dispatch_async(DISPATCH_QUEUE_PRIORITY_BACKGROUND, ^{
    WCTDatabase *recover = [[WCTDatabase alloc] initWithPath:recoverPath];
    NSData *password = [@"MyPassword" dataUsingEncoding:NSASCIIStringEncoding];
    NSData *backupPassword = [@"MyBackupPassword" dataUsingEncoding:NSASCIIStringEncoding];
      int pageSize = 4096;//Default to 4096 on iOS and 1024 on macOS.
    [database close:^{
        [recover recoverFromPath:path 
                     withPageSize:pageSize 
                     backupCipher:cipher 
                   databaseCipher:password];
    }];
    [view stopLoading];
});

更多关于损坏修复的使用、原理以及修复工具2.0，请参考：TODO