文档由Swift老司机活动中心负责翻译，欢迎关注@SwiftOldDriver。翻译有问题可以到 ObjectMapper-CN-Guide 提 PR。

ObjectMapper 是一个使用 Swift 编写的用于 model 对象（类和结构体）和 JSON 之间转换的框架。

• 特性
• 基础使用方法
• 映射嵌套对象
• 自定义转换规则
• 继承
• 泛型对象
• 映射时的上下文对象
• ObjectMapper + Alamofire
• ObjectMapper + Realm
• 待完成
• 安装

特性:

• 把 JSON 映射成对象
• 把对象映射 JSON
• 支持嵌套对象 (单独的成员变量、在数组或字典中都可以)
• 在转换过程支持自定义规则
• 支持结构体（ Struct ）
• Immutable support (目前还在 beta )

基础使用方法

为了支持映射，类或者结构体只需要实现Mappable协议。这个协议包含以下方法：

init?(map: Map)
mutating func mapping(map: Map)

ObjectMapper使用自定义的<-< code=""> 运算符来声明成员变量和 JSON 的映射关系。

class User: Mappable {
    var username: String?
    var age: Int?
    var weight: Double!
    var array: [AnyObject]?
    var dictionary: [String : AnyObject] = [:]
    var bestFriend: User?                       // 嵌套的 User 对象
    var friends: [User]?                        // Users 的数组
    var birthday: NSDate?

    required init?(map: Map) {

    }

    // Mappable
    func mapping(map: Map) {
        username    <- map["username"]="" age="" <-="" map["age"]="" weight="" map["weight"]="" array="" map["arr"]="" dictionary="" map["dict"]="" bestfriend="" map["best_friend"]="" friends="" map["friends"]="" birthday="" (map["birthday"],="" datetransform())="" }="" struct="" temperature:="" mappable="" {="" var="" celsius:="" double?="" fahrenheit:="" init?(map:="" map)="" mutating="" func="" mapping(map:="" celsius="" map["celsius"]="" fahrenheit="" map["fahrenheit"]="" }<="" code="">

一旦你的对象实现了 Mappable, ObjectMapper就可以让你轻松的实现和 JSON 之间的转换。

把 JSON 字符串转成 model 对象：

let user = User(JSONString: JSONString)

把一个 model 转成 JSON 字符串：

let JSONString = user.toJSONString(prettyPrint: true)

也可以使用Mapper.swift类来完成转换（这个类还额外提供了一些函数来处理一些特殊的情况：

// 把 JSON 字符串转成 Model
let user = Mapper().map(JSONString: JSONString)
// 根据 Model 生成 JSON 字符串
let JSONString = Mapper().toJSONString(user, prettyPrint: true)

ObjectMapper支持以下的类型映射到对象中：

• Int
• Bool
• Double
• Float
• String
• RawRepresentable (枚举)
• Array
• Dictionary
• Object
• Array
• Array>
• Set
• Dictionary
• Dictionary>
• 以上所有的 Optional 类型
• 以上所有的隐式强制解包类型（Implicitly Unwrapped Optional）

Mappable 协议

mutating func mapping(map: Map)

所有的映射最后都会调用到这个函数。当解析 JSON 时，这个函数会在对象创建成功后被执行。当生成 JSON 时就只有这个函数会被对象调用。

init?(map: Map)

这个可失败的初始化函数是 ObjectMapper 创建对象的时候使用的。开发者可以通过这个函数在映射前校验 JSON 。如果在这个方法里返回 nil 就不会执行 mapping 函数。可以通过传入的保存着 JSON 的 Map 对象进行校验：

required init?(map: Map){
    // 检查 JSON 里是否有一定要有的 "name" 属性
    if map.JSONDictionary["name"] == nil {
        return nil
    }
}

StaticMappable 协议

StaticMappable 是 Mappable 之外的另一种选择。 这个协议可以让开发者通过一个静态函数初始化对象而不是通过 init?(map: Map)。

注意: StaticMappable 和 Mappable 都继承了 BaseMappable 协议。 BaseMappable 协议声明了 mapping(map: Map) 函数。

static func objectForMapping(map: Map) -> BaseMappable?

ObjectMapper 使用这个函数获取对象后进行映射。开发者需要在这个函数里返回一个实现 BaseMappable 对象的实例。这个函数也可以用于：

• 在对象进行映射前校验 JSON
• 提供一个缓存过的对象用于映射
• 返回另外一种类型的对象（当然是必须实现了 BaseMappable）用于映射。比如你可能通过检查 JSON 推断出用于映射的对象 (看这个例子)。

如果你需要在 extension 里实现 ObjectMapper，你需要选择这个协议而不是 Mappable 。

ImmutableMappable Protocol (Beta)

⚠️ 这个特性还处于 Beta 阶段。正式发布时 API 可能会完全不同。

使用 ImmutableMappable 可以映射不可变的属性。下面的表格展示了 ImmutableMappable 和 Mappable 的不同：

let id: Int
let name: String?

var id: Int!
var name: String?

init(map: Map) throws {
  id   = try map.value("id")
  name = try? map.value("name")
}

mutating func mapping(map: Map) {
  id   <- map["id"]="" <-="" map["name"]="" }="" <="" code="">

mutating func mapping(map: Map) {
  id   >>> map["id"]
  name >>> map["name"]
}

mutating func mapping(map: Map) {
  id   <- map["id"]="" <-="" map["name"]="" }="" <="" code="">

try User(JSONString: JSONString)

User(JSONString: JSONString)

init(map: Map) throws

这个可能抛出异常的初始化函数用于在提供的 Map 里映射不可变属性。每个不可变的初始化属性都要在这个初始化函数里初始化。

当发生下列情况时初始化函数会抛出一个错误：

• Map 根据提供的键名获取不到对应值
• Map 使用 Transform 后没有得到值

ImmutableMappable 使用 Map.value(_:using:) 方法从 Map 中获取值。因为可能抛出异常，这个方法在使用时需要使用 try 关键字。 Optional 的属性可以简单的用 try? 处理。

init(map: Map) throws {
    name      = try map.value("name") // throws an error when it fails
    createdAt = try map.value("createdAt", using: DateTransform()) // throws an error when it fails
    updatedAt = try? map.value("updatedAt", using: DateTransform()) // optional
    posts     = (try? map.value("posts")) ?? [] // optional + default value
}

mutating func mapping(map: Map)

这个方法是在 Model 转回 JSON 时调用的。因为不可变的属性不能被 <-< code=""> 映射，所以映射回来时需要使用 >>> 。

mutating func mapping(map: Map) {
    name      >>> map["name"]
    createdAt >>> (map["createdAt"], DateTransform())
    updatedAt >>> (map["updatedAt"], DateTransform())
    posts     >>> map["posts"]
}

轻松映射嵌套对象

ObjectMapper 支持使用点语法来轻松实现嵌套对象的映射。比如有如下的 JSON 字符串：

"distance" : {
     "text" : "102 ft",
     "value" : 31
}

你可以通过这种写法直接访问到嵌套对象：

func mapping(map: Map) {
    distance <- map["distance.value"]="" }<="" code="">

嵌套的键名也支持访问数组中的值。如果有一个返回的 JSON 是一个包含 distance 的数组，可以通过这种写法访问：

distance <- map["distances.0.value"]="" <="" code="">

func mapping(map: Map) {
    identifier <- map["app.identifier",="" nested:="" false]="" }<="" code="">

func mapping(map: Map) {
    appName <- map["com.myapp.info-="">com.myapp.name", delimiter: "->"]
}

"com.myapp.info" : {
     "com.myapp.name" : "SwiftOldDriver"
}

birthday <- (map["birthday"],="" datetransform())<="" code="">

public protocol TransformType {
    associatedtype Object
    associatedtype JSON

    func transformFromJSON(_ value: Any?) -> Object?
    func transformToJSON(_ value: Object?) -> JSON?
}

let transform = TransformOf(fromJSON: { (value: String?) -> Int? in 
    // 把值从 String? 转成 Int?
    return Int(value!)
}, toJSON: { (value: Int?) -> String? in
    // 把值从 Int? 转成 String?
    if let value = value {
        return String(value)
    }
    return nil
})

id <- (map["id"],="" transform)<="" code="">

id <- (map["id"],="" transformof(fromJSON: { Int($0!) }, toJSON: { $0.map { String($0) } }))

class Base: Mappable {
    var base: String?

    required init?(map: Map) {

    }

    func mapping(map: Map) {
        base <- map["base"]="" }="" subclass:="" base="" {="" var="" sub:="" string?="" required init?(map:="" map)="" super.init(map)
    }

    override func mapping(map: Map) {
        super.mapping(map)

        sub 

class Result: Mappable {
    var result: T?

    required init?(map: Map){

    }

    func mapping(map: Map) {
        result >().map(JSON)

struct Context: MapContext {
    var importantMappingInfo = "映射时需要知道的额外信息"
}

class User: Mappable {
    var name: String?

    required init?(map: Map){

    }

    func mapping(map: Map){
        if let context = map.context as? Context {
            // 获取到额外的信息
        }
    }
}

let context = Context()
let user = Mapper(context: context).map(JSONString)

class Model: Object, Mappable {
    dynamic var name = ""

    required convenience init?(map: Map) {
        self.init()
    }

    func mapping(map: Map) {
        name 

pod 'ObjectMapper', '~> 2.2'

github "Hearst-DD/ObjectMapper" ~> 2.2

.Package(url: "https://github.com/Hearst-DD/ObjectMapper.git", majorVersion: 2, minor: 2),