posix_tutorial_cn

MMKV for POSIX

MMKV 是基于 mmap 内存映射的 key-value 组件，底层序列化/反序列化使用 protobuf 实现，性能高，稳定性强。从 2015 年中至今在微信上使用，其性能和稳定性经过了时间的验证。近期也已移植到 Android / macOS / Win32 / POSIX 平台，一并开源。

使用指南

MMKV 的使用非常简单，所有变更立马生效，无需调用 save、sync。

配置 MMKV 根目录

• 在 App 启动时初始化 MMKV，设定 MMKV 的根目录，例如在 main() 函数里：

  #include “MMKV.h”
  
  int main() {
      std::string rootDir = getYourAppDocumentDir();
      MMKV::initializeMMKV(rootDir);
      //...
  }

CRUD 操作

• MMKV 提供一个全局的实例，可以直接使用：

  auto mmkv = MMKV::defaultMMKV();
  
  mmkv->set(true, "bool");
  std::cout << "bool = " << mmkv->getBool("bool") << std::endl;
  
  mmkv->set(1024, "int32");
  std::cout << "int32 = " << mmkv->getInt32("int32") << std::endl;
  
  mmkv->set(numeric_limits<uint32_t>::max(), "uint32");
  std::cout << "uint32 = " << mmkv->getUInt32("uint32") << std::endl;
  
  mmkv->set(numeric_limits<int64_t>::min(), "int64");
  std::cout << "int64 = " << mmkv->getInt64("int64") << std::endl;
  
  mmkv->set(numeric_limits<uint64_t>::max(), "uint64");
  std::cout << "uint64 = " << mmkv->getUInt64("uint64") << std::endl;
  
  mmkv->set(3.14f, "float");
  std::cout << "float = " << mmkv->getFloat("float") << std::endl;
  
  mmkv->set(numeric_limits<double>::max(), "double");
  std::cout << "double = " << mmkv->getDouble("double") << std::endl;
  
  mmkv->set("Hello, MMKV for Win32", "string");
  std::string result;
  if (mmkv->getString("string", result)) {
     std::cout << "string = " << result << std::endl;
  }

  可以看到，MMKV 在使用上还是比较简单的。

• 删除 & 查询：

  auto kv = MMKV::defaultMMKV();
       
  mmkv->removeValueForKey("bool");
  std::cout << "bool = " << mmkv->getBool("bool") << std::endl;
  
  mmkv->removeValuesForKeys({"int32", "int64"});
  std::cout << "allKeys: ";
  for (auto &key : mmkv->allKeys()) {
      std::cout << key << ", ";
  }
  std::cout << std::endl;
        
  bool hasBool = mmkv->containsKey("bool");

• 如果不同业务需要区别存储，也可以单独创建自己的实例：

  auto mmkv = MMKV::mmkvWithID("MyID");
  mmkv->set(true, "bool");

• 如果业务需要多进程访问，那么在初始化的时候加上标志位 MMKV.MULTI_PROCESS_MODE：

  auto mmkv = MMKV::mmkvWithID("InterProcessKV", MMKV_MULTI_PROCESS);
  mmkv->set(true, "bool");

支持的数据类型

• 支持以下 C/C++ 语言基础类型：

  • bool、int32、int64、uint32、uint64、float、double

• 支持以下类和容器：

  • std::string、std::vector<std::string>、mmkv::MMBuffer

日志

• MMKV 默认将日志打印到 stdout，不便于对线上问题进行定位和解决。你可以在 App 启动时接收转发 MMKV 的日志。实现mmkv::LogHandler()类型的回调函数，添加类似下面的代码：

  void MyLogHandler(MMKVLogLevel level, const char *file, int line, const char *function, const string &message) {
      auto desc = [level] {
          switch (level) {
              case MMKVLogDebug:
                  return "D";
              case MMKVLogInfo:
                  return "I";
              case MMKVLogWarning:
                  return "W";
              case MMKVLogError:
                  return "E";
              default:
                  return "N";
          }
      }();
      printf("[%s] <%s:%d::%s> %s\n", desc, file, line, function, message.c_str());
  }
  int main() {
      std::string rootDir = getYourAppDocumentDir();
      MMKV::initializeMMKV(rootDir);
      MMKV::registerLogHandler(MyLogHandler);
      //...
  }

  至于使用哪个日志组件，我们推荐使用 xlog，同样也是开源自微信团队。

• 如果你不希望 MMKV 打印日志，你可以一劳永逸地关掉它（虽然我们强烈不建议你这么做）。
  注意：除非有非常强烈的证据表明MMKV的日志拖慢了App的速度，你不应该关掉日志。没有日志，日后万一用户有问题，将无法跟进。

  MMKV::setLogLevel(MMKVLogNone);

备份 & 恢复

• MMKV 提供了备份和恢复接口，可用于备份数据到其他目录，并稍后恢复原有数据。

  std::string rootDir = "/tmp/mmkv_backup";
  auto ret = MMKV::backupOneToDirectory(mmapID, rootDir);
  // backup one instance
  var ret = MMKV.backupOneToDirectory(mmapID, backupRootDir);
  // backup all instances
  auto count = MMKV::backupAllToDirectory(rootDir);
  
  // restore one instance
  ret = MMKV::restoreOneFromDirectory(mmapID, rootDir);
  // restore all instances
  count = MMKV::restoreAllFromDirectory(rootDir);

下一步

• MMKV 原理
• MMKV for Python