010-YapDatabase 食用指南

YapDatabase 是一个工作在 iOS 和 MAC 上的数据库，有两大主要特性：

• 基于 sqlite 建立的 collection/key/value/metadata 基础存储功能
• 提供类似视图、辅助索引、全文搜索等高级功能的插件

同时还有以下特性

• 并发性：可以同时在多个连接上进行读写操作，不会阻塞主线程
• 内建缓存：相比于 sqlite 的原始字节缓存，YapDatabase 的缓存可以跳过序列化和反序列化阶段
• 集合：支持集合存储
• 元数据 metadata：支持元数据存储，可以存储一些 object 的额外信息，比如时间戳等
• 性能：在主线程获取数千对象不会掉帧
• objectivec API
• 拓展：内置拓展架构，同时支持自定义
• 视图：YapDatabase 内置的 view 使得过滤、组合和排序数据非常便捷
• 辅助索引：通过索引重要属性来加快搜索速度
• 全文搜索：基于 sqlite 的 FTS 模块，可以以最小代价获得极速的搜索

并发行

YapDatabase 中的只读连接会保存数据库的即时快照，即使其他连接改变数据，也不会影响当前的连接。但必须遵循以下规则：

• 可以同时建立多个连接 Connection
• 每一个连接都是线程安全的
• 可以同时拥有多个只读事务而不阻塞
• 可以同时拥有多个只读事务和一个读写事务而不阻塞
• 对于每一个数据库，同一时间只能有一个读写事务，有唯一一个串行duilie执行读写事务
• 对于每一个连接，同一时间只能有一个事务，每一个连接都维护一个串行队列执行事务

存储

YapDatabase 支持任何类型的 object，只要设置好序列化和反序列化流程就可以，YapDatabase 有提供默认的序列化和反序列化流程，当然也支持自定义。对于支持了 NSCoding 协议的类，可以不需要额外的设置，比如 Cocoa 中的大多数内置类

• NSString
• NSNumber
• NSArray
• NSDictionary
• NSSet
• NSData
• UIColor
• UIImage

对于自定义类，只需要实现 NSCoding 的序列化、反序列化方法就可以了。

@interface Person : NSObject<NSCoding>

@property(strong, nonatomic) NSString *name;
@property(strong, nonatomic) NSString *gender;
@property(assign, nonatomic) NSInteger age;

@end

@implementation Person

- (instancetype)initWithCoder:(NSCoder *)aDecoder
{
    if ([super init])
    {
        self.name = [aDecoder decodeObjectForKey:@"name"];
        self.gender = [aDecoder decodeObjectForKey:@"gender"];
        self.age = [aDecoder decodeIntegerForKey:@"age"];
    }
    return self;
}

- (void)encodeWithCoder:(NSCoder *)aCoder
{
    [aCoder encodeObject:self.name forKey:@"name"];
    [aCoder encodeObject:self.gender forKey:@"gender"];
    [aCoder encodeInteger:self.age forKey:@"age"];
}

@end

如果序列化类的某个属性也是支持 NSCoding 的类，则也可以直接存进数据库，同样的，对于一个数组，序列化和反序列化信息也会依次发送给每一个成员。

YapDatabase 包含一些开箱即用的序列化函数

/**
默认的序列化／反序列化函数，实现了 NSCoding 协议，任何支持 NSCoding 协议的对象（包括系统自带的大多数类）都可以被序列化／反序列化。
**/
+ (YapDatabaseSerializer)defaultSerializer;
+ (YapDatabaseDeserializer)defaultDeserializer;

/**
属性列表序列化／反序列化函数，只支持 SData, NSString, NSArray, NSDictionary, NSDate, NSNumber 这些类，采取了一些优化措施
**/
+ (YapDatabaseSerializer)propertyListSerializer;
+ (YapDatabaseDeserializer)propertyListDeserializer;

/**
一个针对 NSDate 对象的快速序列化／反序列化函数
**/
+ (YapDatabaseSerializer)timestampSerializer;
+ (YapDatabaseDeserializer)timestampDeserializer;

自定义序列化／反序列化函数的方法可以用于加密、压缩和性能优化等方面。

typedef NSData* (^YapDatabaseSerializer)(NSString *collection, NSString *key, id object);
typedef id (^YapDatabaseDeserializer)(NSString *collection, NSString *key, NSData *data);

集合

集合为众多拥有同一关键属性的元素提供了更方拜年的存储结构，它为元素提供除了 key 值外另一个层次的标识，所以 YapDatabase 也可以理解为是 “字典的字典”。

YapDatabase 关于集合的 API 有以下几个

/**
 * Returns the total number of collections.
 * Each collection may have 1 or more key/object pairs.
**/
- (NSUInteger)numberOfCollections;

/**
 * Returns the total number of keys in the given collection.
 * Returns zero if the collection doesn't exist (or all key/object pairs from the collection have been removed).
**/
- (NSUInteger)numberOfKeysInCollection:(NSString *)collection;

/**
 * Object access.
 * Objects are automatically deserialized using database's configured deserializer.
**/
- (id)objectForKey:(NSString *)key inCollection:(NSString *)collection;

/**
 * Fast enumeration over all keys in the given collection.
 *
 * This uses a "SELECT key FROM database WHERE collection = ?" operation,
 * and then steps over the results invoking the given block handler.
**/
- (void)enumerateKeysInCollection:(NSString *)collection
                       usingBlock:(void (^)(NSString *key, BOOL *stop))block;

可以看到一个 object 在 YapDatabase 中是依靠 collection 和 key 两个标识共同唯一确定的。

缓存

YapDatabase 的每一个连接都有自己专属的数据库缓存，与 sqlite 的二进制数据缓存层相比，YapDatabase 的缓存层直接缓存 objectivec 对象，减少了序列化和反序列化的开销。

缓存默认打开，大小为 250，以下是 API

// 这一属性可以选择关闭或开启缓存
@property (atomic, assign, readwrite) BOOL objectCacheEnabled;
@property (atomic, assign, readwrite) BOOL metadataCacheEnabled;

// 可以设置缓存大小，如果赋值为 0 则缓存空间无限
@property (atomic, assign, readwrite) NSUInteger objectCacheLimit;
@property (atomic, assign, readwrite) NSUInteger metadataCacheLimit;

支持对象与元数据分开缓存，也支持在运行中进行缓存大小的修改，每一个连接的缓存都会自动与数据库进行同步。

元数据 Metedata

YapDatabase 支持存储的元祖不仅仅包含对象，还有元数据，底层的数据库表也为元数据开辟了独立的存储列。对象是必须有的，但是元数据是可选的，如果对象为 nil 则元组会被移除，但是元数据为 nil 并不会。元数据与对象可以拥有独立的缓存机制和序列化／反序列化函数。

元数据相关的存储与更新 API 有以下这些

/**
 * Invokes setObject:forKey:inCollection:withMetadata:,
 * and passes a nil value for the metadata parameter.
**/
- (void)setObject:(nullable id)object
           forKey:(NSString *)key
     inCollection:(nullable NSString *)collection;

/**
 * If you call this method with a nil object, then it will delete the row.
 * (Equivalent to calling removeObjectForKey:inCollection:)
 * 
 * Otherwise, this method inserts/updates the row,
 * and sets BOTH the object & metadata columns to the given values.
**/
- (void)setObject:(nullable id)object
           forKey:(NSString *)key
     inCollection:(nullable NSString *)collection
     withMetadata:(nullable id)metadata;

/**
 * If a row with the given collection/key already exists,
 * then this method updates ONLY the object value.
 * The metadata value for the row isn't touched. (It remains whatever it was before.)
 * 
 * Again, it's not possible to have a nil object for a row.
 * So if you try to set the object to nil, this is just going to delete the row.
**/
- (void)replaceObject:(nullable id)object
               forKey:(NSString *)key
         inCollection:(nullable NSString *)collection;

/**
 * If a row with the given collection/key already exists,
 * then this method updates ONLY the metadata value.
 * The object value for the row isn't touched. (It remains whatever it was before.)
**/
- (void)replaceMetadata:(nullable id)metadata
                 forKey:(NSString *)key
           inCollection:(nullable NSString *)collection;

最佳实践

• 避免用同一个连接在主线程和其他线程同时执行事务，因为连接只能串行执行事务
• 避免创建太多连接，会带来开销问题，同时会降低缓存命中，因为连接中执行的事务少，缓存性能没有表现出来
• 为主线程使用专用的连接
• 在主线程的专用连接上不执行任何读写事务（ReadWrite transaction），只执行只读事务
• 为读写操作建立单独的连接

相关 API 与操作

1. 删除

• 删除指定集合的所有元素

  - (void)removeAllObjectsInCollection:(NSString *)collection
  

• 删除数据库所有元素

  - (void)removeAllObjectsInAllCollections;
  

• 删除某一个指定元素

  - (void)removeObjectForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

• 删除某一些指定元素

  - (void)removeObjectsForKeys:(NSArray<NSString *> *)keys inCollection:(nullable NSString *)collection;
  

2. 获取总数

• 获取集合总数

  - (NSUInteger)numberOfCollections;
  

• 获取集合中 key 总数

  - (NSUInteger)numberOfKeysInCollection:(nullable NSString *)collection;
  

• 获取数据库中 key 总数

  - (NSUInteger)numberOfKeysInAllCollections;
  

3. 获取列表

• 获取所有集合的列表

  - (NSArray<NSString *> *)allCollections;
  

• 获取某个集合中所有 key 的列表

  - (NSArray<NSString *> *)allKeysInCollection:(nullable NSString *)collection;
  

4. 获取对象与元数据

• 获取指定对象

  - (nullable id)objectForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

• 检测指定对象是否在集合中

  - (BOOL)hasObjectForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

• 获取指定对象和元数据到指定地址，存在该 key 则返回 YES，否则返回 NO

  - (BOOL)getObject:(__nullable id * __nullable)objectPtr
           metadata:(__nullable id * __nullable)metadataPtr
             forKey:(NSString *)key
       inCollection:(nullable NSString *)collection;
  

• 获取指定元数据

  - (nullable id)metadataForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

5. 获取原始数据

下面的方法会跳过 oc 层缓存，直接获取数据库中的原始数据，因此速度不如上面的方法。

• 获取指定对象

  - (nullable NSData *)serializedObjectForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

• 获取指定元数据

  - (nullable NSData *)serializedMetadataForKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

• 读取指定对象和元数据到指定地址

- (BOOL)getSerializedObject:(NSData * __nullable * __nullable)serializedObjectPtr
        serializedMetadata:(NSData * __nullable * __nullable)serializedMetadataPtr
                    forKey:(NSString *)key
              inCollection:(nullable NSString *)collection;

6. 枚举

• 枚举集合

  - (void)enumerateCollectionsUsingBlock:(void (^)(NSString *collection, BOOL *stop))block;
  - (void)enumerateCollectionsForKey:(NSString *)key usingBlock:(void (^)(NSString *collection, BOOL *stop))block;
  

• 枚举key

  - (void)enumerateKeysInCollection:(nullable NSString *)collection
                       usingBlock:(void (^)(NSString *key, BOOL *stop))block;
  - (void)enumerateKeysInAllCollectionsUsingBlock:(void (^)(NSString *collection, NSString *key, BOOL *stop))block;
  - (void)enumerateKeysAndObjectsInCollection:(nullable NSString *)collection
                                 usingBlock:(void (^)(NSString *key, id object, BOOL *stop))block;
  - (void)enumerateKeysAndMetadataInCollection:(nullable NSString *)collection
                                  usingBlock:(void (^)(NSString *key, __nullable id metadata, BOOL *stop))block;
  

7. 存储和更新

• 存储

  - (void)setObject:(nullable id)object forKey:(NSString *)key inCollection:(nullable NSString *)collection;
  - (void)setObject:(nullable id)object
           forKey:(NSString *)key
     inCollection:(nullable NSString *)collection
     withMetadata:(nullable id)metadata;
  

• 更新

  - (void)replaceObject:(nullable id)object forKey:(NSString *)key inCollection:(nullable NSString *)collection;
  - (void)replaceMetadata:(nullable id)metadata forKey:(NSString *)key inCollection:(nullable NSString *)collection;
  

这里要注意如果存储的对象所属 key 是已经存储在数据库的，则会自动更新这个元素，如果传递的对象是 nil，则会移除这个元素。