3 分钟快速上手 Realm+JSON：CocoaPods 安装与第一个 JSON 模型入库教程

3 分钟快速上手 Realm+JSON：CocoaPods 安装与第一个 JSON 模型入库教程

【免费下载链接】Realm-JSONA concise Mantle-like way of working with Realm and JSON.项目地址: https://gitcode.com/gh_mirrors/re/Realm-JSON

Realm+JSON 是一个简洁、Mantle 风格的 Objective-C 库，专门用来打通Realm 数据库与JSON 数据之间的转换。对新手来说，它最大的价值在于：你只需要写一个模型类，再调用一行方法，就能把服务端返回的 JSON 数组或字典一键入库，完全不用手动逐字段赋值。这篇教程将带你完成 Realm+JSON 的 CocoaPods 安装，并写出你的第一个 JSON 模型入库 Demo，全程约 3 分钟。

一、为什么你需要 Realm+JSON？

在日常 iOS 开发中，从接口拉取 JSON 再存入本地数据库是最常见的需求。传统写法往往是这样：

• 手写NSJSONSerialization解析代码；
• 再逐条把字典里的值赋给模型属性；
• 遇到 snake_case 命名还要自己写转换逻辑……

Realm+JSON 把这些繁琐步骤全部封装掉了。它模仿 Mantle 的设计思路，通过映射字典（Mapping Dictionary）自动完成 JSON 与 Realm 对象之间的双向转换，让"JSON 模型入库"变成一行代码的事。

二、快速安装：CocoaPods 安装步骤

Realm+JSON 已发布到 CocoaPods 官方仓库，安装非常简单。

2.1 添加 Pod 依赖

在你的项目 Podfile 中追加一行：

pod 'Realm+JSON', '~> 0.2'

然后执行：

pod install

小提示：如果网络环境访问 CocoaPods 官方源较慢，也可以直接 clone 本仓库（地址：https://gitcode.com/gh_mirrors/re/Realm-JSON），把Realm+JSON文件夹里的源码复制进你的工程，效果相同。

2.2 引入头文件

在需要使用的地方导入：

#import <Realm+JSON/RLMObject+JSON.h>

导入这个头文件后，你的RLMObject子类就自动获得了createOrUpdateInRealm:withJSONArray:、JSONDictionary等一整套 JSON 能力，声明见 RLMObject+JSON.h。

三、3 分钟上手：定义你的第一个 JSON 模型

我们以项目 Demo 中的MCEpisode（剧集）为例，定义一个简单的 Realm 模型，参考 MCEpisode.h：

@interface MCEpisode : RLMObject @property NSInteger episodeID; @property NSInteger episodeNumber; @property NSString *title; @property NSString *subtitle; @property NSDate *publishedDate; @end

就这么简单！不需要任何 JSON 相关的基类继承，模型保持"干净"。

四、配置 JSON 映射：入站与出站

Realm+JSON 的映射思路是：JSON 里的字段名 ↔ 模型里的属性名。你可以在模型类中实现两个方法来自定义映射：

4.1 入站映射（JSON → 模型）

+ (NSDictionary *)JSONInboundMappingDictionary { return @{ @"episode.title" : @"title", @"episode.description" : @"subtitle", @"episode.id" : @"episodeID", @"episode.published_at" : @"publishedDate", }; }

左边是 JSON 的 key path（支持点语法层级），右边是模型属性。这样即使接口返回的字段名与模型不一致，也能准确对应。

4.2 出站映射（模型 → JSON）

+ (NSDictionary *)JSONOutboundMappingDictionary { return @{ @"title" : @"title", @"subtitle" : @"episode.description", @"episodeID" : @"id", @"publishedDate": @"published_at", }; }

用于把模型转回 JSON 字典，方便直接拼装网络请求参数。

如果完全不写映射方法，Realm+JSON 会使用默认规则：模型属性 camelCase 自动对应 JSON 的 snake_case。

五、核心一步：JSON 一键入库

拿到服务端返回的数据后，入库只需要一行代码。Demo 中完整展示了从 AFNetworking 请求到入库的流程，见 MCTableViewController.m：

RLMRealm *realm = [RLMRealm defaultRealm]; [realm beginWriteTransaction]; NSArray *result = [MCEpisode createOrUpdateInRealm:realm withJSONArray:array]; [realm commitWriteTransaction];

• 传入数组：createOrUpdateInRealm:withJSONArray:，批量入库；
• 传入单个字典：createOrUpdateInRealm:withJSONDictionary:。

入库方法内部会调用 Realm 原生的createOrUpdateInRealm:withObject:，性能有保障，同时利用主键自动完成"有则更新、无则插入"。

六、进阶技巧：日期转换与值转换器

JSON 里的时间字符串如何变成NSDate？枚举字符串如何变成整型？Realm+JSON 内置了值转换器机制：

• 日期字段自动使用 MCJSONDateTransformer.m 处理；
• 自定义枚举可用 MCJSONValueTransformer.h 配置：

+ (NSValueTransformer *)episodeTypeJSONTransformer { return [MCJSONValueTransformer valueTransformerWithMappingDictionary:@{ @"free" : @(MCEpisodeTypeFree), @"paid" : @(MCEpisodeTypePaid) }]; }

规则很简单：实现名为属性名 + JSONTransformer的方法即可，框架会自动识别并调用。

七、补充：多线程与对象拷贝

• 多线程：Realm 规定不同线程不能共享同一个对象实例。可以用primaryKeyValue取出主键值，再到目标线程通过objectInRealm:withPrimaryKeyValue:重新查询，参考 RLMObject+JSON.h。
• 临时副本：编辑 UI 时不想立刻写库？RLMObject+Copying提供了shallowCopy、deepCopy和mergePropertiesFromObject:，先改副本、确认后再提交，非常适合表单类页面，声明见 RLMObject+Copying.h。

八、小结

到这里，你已经完成了 Realm+JSON 的 CocoaPods 安装、模型定义、JSON 映射配置和首个 JSON 模型入库 Demo。回顾一下核心 API：

Realm+JSON 用最少的代码解决了 Realm 与 JSON 之间最麻烦的转换问题。如果你正在使用 Realm 做本地缓存，这个轻量级库值得一试。下一步，不妨直接阅读 RLMObject+JSON.m 源码，深入了解它的映射实现细节！

【免费下载链接】Realm-JSONA concise Mantle-like way of working with Realm and JSON.项目地址: https://gitcode.com/gh_mirrors/re/Realm-JSON