README-CN.md 15.5 KB
Newer Older
Eyad Hasan's avatar
Eyad Hasan committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# ObjectMapper-CN-Guide
> 文档由Swift老司机活动中心负责翻译,欢迎关注[@SwiftOldDriver](http://weibo.com/6062089411)。翻译有问题可以到 [ObjectMapper-CN-Guide](https://github.com/SwiftOldDriver/ObjectMapper-CN-Guide) 提 PR。

[ObjectMapper](https://github.com/Hearst-DD/ObjectMapper) 是一个使用 Swift 编写的用于 model 对象(类和结构体)和 JSON  之间转换的框架。

- [特性](#特性)
- [基础使用方法](#基础使用方法)
- [映射嵌套对象](#映射嵌套对象)
- [自定义转换规则](#自定义转换规则)
- [继承](#继承)
- [泛型对象](#泛型对象)
- [映射时的上下文对象](#映射时的上下文对象)
- [ObjectMapper + Alamofire](#objectmapper--alamofire) 
- [ObjectMapper + Realm](#objectmapper--realm)
- [待完成](#待完成)
- [安装](#安装)

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

# 基础使用方法
为了支持映射,类或者结构体只需要实现```Mappable```协议。这个协议包含以下方法:
```swift
init?(map: Map)
mutating func mapping(map: Map)
```
ObjectMapper使用自定义的```<-``` 运算符来声明成员变量和 JSON 的映射关系。
```swift
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?
    var fahrenheit: Double?

    init?(map: Map) {

    }

    mutating func mapping(map: Map) {
        celsius 	<- map["celsius"]
        fahrenheit 	<- map["fahrenheit"]
    }
}
```

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

把 JSON 字符串转成 model 对象:

```swift
let user = User(JSONString: JSONString)
```

把一个 model 转成 JSON 字符串:

```swift
let JSONString = user.toJSONString(prettyPrint: true)
```

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

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

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

- `Int`
- `Bool`
- `Double`
- `Float`
- `String`
- `RawRepresentable` (枚举)
- `Array<AnyObject>`
- `Dictionary<String, AnyObject>`
- `Object<T: Mappable>`
- `Array<T: Mappable>`
- `Array<Array<T: Mappable>>`
- `Set<T: Mappable>` 
- `Dictionary<String, T: Mappable>`
- `Dictionary<String, Array<T: Mappable>>`
- 以上所有的 Optional 类型
- 以上所有的隐式强制解包类型(Implicitly Unwrapped Optional)

## `Mappable` 协议

#### `mutating func mapping(map: Map)` 
所有的映射最后都会调用到这个函数。当解析 JSON 时,这个函数会在对象创建成功后被执行。当生成 JSON 时就只有这个函数会被对象调用。

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

```swift
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 推断出用于映射的对象 ([看这个例子](https://github.com/Hearst-DD/ObjectMapper/blob/master/ObjectMapperTests/ClassClusterTests.swift#L62))。

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

149
## `ImmutableMappable` Protocol
Eyad Hasan's avatar
Eyad Hasan committed
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500

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

<table>
  <tr>
    <th>ImmutableMappable</th>
    <th>Mappable</th>
  </tr>
  <tr>
    <th colspan="2">Properties</th>
  </tr>
  <tr>
    <td>
<pre>
<strong>let</strong> id: Int
<strong>let</strong> name: String?
</pre>
  </td>
    <td>
<pre>
var id: Int!
var name: String?
</pre>
    </td>
  </tr>
  <tr>
    <th colspan="2">JSON -> Model</th>
  </tr>
  <tr>
    <td>
<pre>
init(map: Map) <strong>throws</strong> {
  id   = <strong>try</strong> map.value("id")
  name = <strong>try?</strong> map.value("name")
}
</pre>
  </td>
    <td>
<pre>
mutating func mapping(map: Map) {
  id   <- map["id"]
  name <- map["name"]
}
</pre>
    </td>
  </tr>
  <tr>
    <th colspan="2">Model -> JSON</th>
  </tr>
  <tr>
    <td>
<pre>
mutating func mapping(map: Map) {
  id   <strong>>>></strong> map["id"]
  name <strong>>>></strong> map["name"]
}
</pre>
    </td>
    <td>
<pre>
mutating func mapping(map: Map) {
  id   <- map["id"]
  name <- map["name"]
}
</pre>
    </td>
  </tr>
  <tr>
    <th colspan="2">Initializing</th>
  </tr>
  <tr>
    <td>
<pre>
<strong>try</strong> User(JSONString: JSONString)
</pre>
    </td>
    <td>
<pre>
User(JSONString: JSONString)
</pre>
    </td>
  </tr>
</table>

#### `init(map: Map) throws`

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

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

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

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

```swift
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 时调用的。因为不可变的属性不能被 `<-` 映射,所以映射回来时需要使用 `>>>`

```swift
mutating func mapping(map: Map) {
    name      >>> map["name"]
    createdAt >>> (map["createdAt"], DateTransform())
    updatedAt >>> (map["updatedAt"], DateTransform())
    posts     >>> map["posts"]
}
```
# 轻松映射嵌套对象

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

```json
"distance" : {
     "text" : "102 ft",
     "value" : 31
}
```
你可以通过这种写法直接访问到嵌套对象:

```swift
func mapping(map: Map) {
    distance <- map["distance.value"]
}
```
嵌套的键名也支持访问数组中的值。如果有一个返回的 JSON 是一个包含 distance 的数组,可以通过这种写法访问:

```
distance <- map["distances.0.value"]
```
如果你的键名刚好含有 `.` 符号,你需要特别声明关闭上面提到的获取嵌套对象功能:

```swift
func mapping(map: Map) {
    identifier <- map["app.identifier", nested: false]
}
```
如果刚好有嵌套的对象的键名还有 `.` ,可以在中间加入一个自定义的分割符([#629](https://github.com/Hearst-DD/ObjectMapper/pull/629)):
```swift
func mapping(map: Map) {
    appName <- map["com.myapp.info->com.myapp.name", delimiter: "->"]
}
```
这种情况的 JSON 是这样的:

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

# 自定义转换规则
ObjectMapper 也支持在映射时自定义转换规则。如果要使用自定义转换,创建一个 tuple(元祖)包含 ```map["field_name"]``` 和你要使用的变换放在 ```<-``` 的右边:

```swift
birthday <- (map["birthday"], DateTransform())
```
当解析 JSON 时上面的转换会把 JSON 里面的 Int 值转成一个 NSDate ,如果是对象转为 JSON 时,则会把 NSDate 对象转成 Int 值。

只要实现```TransformType``` 协议就可以轻松的创建自定义的转换规则:

```swift
public protocol TransformType {
    associatedtype Object
    associatedtype JSON

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

### TransformOf
大多数情况下你都可以使用框架提供的转换类 ```TransformOf``` 来快速的实现一个期望的转换。 ```TransformOf``` 的初始化需要两个类型和两个闭包。两个类型声明了转换的目标类型和源类型,闭包则实现具体转换逻辑。

举个例子,如果你想要把一个 JSON 字符串转成 Int ,你可以像这样使用 ```TransformOf```

```swift
let transform = TransformOf<Int, String>(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)
```
这是一种更省略的写法:

```swift
id <- (map["id"], TransformOf<Int, String>(fromJSON: { Int($0!) }, toJSON: { $0.map { String($0) } }))
```
# 继承

实现了  ```Mappable``` 协议的类可以容易的被继承。当继承一个 mappable 的类时,使用这样的结构:

```swift
class Base: Mappable {
	var base: String?
	
	required init?(map: Map) {

	}

	func mapping(map: Map) {
		base <- map["base"]
	}
}

class Subclass: Base {
	var sub: String?

	required init?(map: Map) {
		super.init(map)
	}

	override func mapping(map: Map) {
		super.mapping(map)
		
		sub <- map["sub"]
	}
}
```

注意确认子类中的实现调用了父类中正确的初始化器和映射函数。

# 泛型对象

ObjectMapper 可以处理泛型只要这个泛型也实现了`Mappable`协议。看这个例子:

```swift
class Result<T: Mappable>: Mappable {
    var result: T?

    required init?(map: Map){

    }

    func mapping(map: Map) {
        result <- map["result"]
    }
}

let result = Mapper<Result<User>>().map(JSON)
```
# 映射时的上下文对象

`Map` 是在映射时传入的对象,带有一个 optional  `MapContext` 对象,开发者可以通过使用这个对象在映射时传入一些信息。

为了使用这个特性,需要先创建一个对象实现了 `MapContext` 协议(这个协议是空的),然后在初始化时传入 `Mapper` 中。

```swift
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<User>(context: context).map(JSONString)
```

# ObjectMapper + Alamofire

如果网络层你使用的是  [Alamofire](https://github.com/Alamofire/Alamofire) ,并且你希望把返回的结果转换成 Swift 对象,你可以使用 [AlamofireObjectMapper](https://github.com/tristanhimmelman/AlamofireObjectMapper) 。这是一个使用 ObjectMapper 实现的把返回的 JSON 自动转成 Swift 对象的 Alamofire 的扩展。 


# ObjectMapper + Realm

ObjectMapper 可以和 Realm 一起配合使用。使用下面的声明结构就可以使用 ObjectMapper 生成 Realm 对象:

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

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

	func mapping(map: Map) {
		name <- map["name"]
	}
}
```

如果你想要序列化相关联的 RealmObject,你可以使用 [ObjectMapper+Realm](https://github.com/jakenberg/ObjectMapper-Realm)。这是一个简单的 Realm 扩展,用于把任意的 JSON 序列化成 Realm 的类(ealm's List class。)

注意:使用 ObjectMappers 的 `toJSON` 函数来生成 JSON 字符串只在 Realm 的写事务中有效(write transaction)。这是因为 ObjectMapper 在解析和生成时在映射函数( `<-` )中使用  `inout` 作为标记( flag )。Realm 会检测到标记并且强制要求 `toJSON` 函数只能在一个写的事务中调用,即使这个对象并没有被修改。

# 待完成
- 改善错误的处理。可能使用 `throws` 来处理。
- 相关类的文档完善

# 安装
### Cocoapods
如果你的项目使用 [CocoaPods 0.36 及以上](http://blog.cocoapods.org/Pod-Authors-Guide-to-CocoaPods-Frameworks/) 的版本,你可以把下面内容添加到在 `Podfile` 中,将 ObjectMapper 添加到你的项目中:

```ruby
pod 'ObjectMapper', '~> 2.2'
```

### Carthage
如果你的项目使用  [Carthage](https://github.com/Carthage/Carthage) ,你可以把下面的内容添加到 `Cartfile` 中,将 ObjectMapper 的依赖到你的项目中:

```
github "Hearst-DD/ObjectMapper" ~> 2.2
```

### Swift Package Manager
如果你的项目使用  [Swift Package Manager](https://swift.org/package-manager/) ,那么你可以把下面内容添加到 `Package.swift` 中的 `dependencies` 数组中,将 ObjectMapper 的依赖到你的项目中:

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


### Submodule
此外,ObjectMapper 也可以作为一个 submodule 添加到项目中:

1. 打开终端,使用 `cd` 命令进入项目文件的根目录下,然后在终端中输入 `git submodule add https://github.com/Hearst-DD/ObjectMapper.git` ,把 ObjectMapper 作为项目的一个 [submodule](http://git-scm.com/docs/git-submodule) 添加进来。
2. 打开 `ObjectMapper` 文件,并将 `ObjectMapper.xcodeproj` 拖进你 app 项目的文件导航中。
3. 在 Xcode 中,文件导航中点击蓝色项目图标进入到 target 配置界面,在侧边栏的 "TARGETS" 下选择主工程对应的target。
4. 确保 `ObjectMapper.framework` 的部署版本( deployment target )和主工程的部署版本保持一致。
5. 在配置界面的顶部选项栏中,打开 "Build Phases" 面板。
6. 展开 "Target Dependencies" 组,并添加 `ObjectMapper.framework`
7. 点击面板左上角的 `+` 按钮,选择 "New Copy Files Phase"。将这个阶段重命名为 "Copy Frameworks",设置  "Destination" 为 "Frameworks",最后添加 `ObjectMapper.framework`