自定义标量

除了其内置标量类型内建类型 (Int, String, 等.), GraphQL 支持自定义类型。例如，您的模式可能提供用于 Date、UUID 或 GeoLocation

自定义类型最初是在模式中定义的。要使用自定义类型与模式交互，您的客户端必须为每个自定义类型定义一个Swift类型。

例如，Apollo iOS会自动为所有内建类型定义Swift类型：

GraphQL类型	Swift类型
`Int`	`Int`
`Float`	`Double`
`Boolean`	`布尔值`
`字符串`	`字符串`
`标识符`	`字符串`

生成自定义标量类型

MySchema.graphqls

1
scalar UUID

MySchema/CustomScalars/UUID.swift

1
public extension MySchema {
2
  typealias UUID = String
3
}

注意：自定义标量可以由字段在GraphQL类型中引用，或作为输入参数的值，或引用输入对象。因为自定义标量仅在它们被您的操作引用时生成，因此它们可以在代码生成的任何未来执行中添加到项目中，而不仅仅是初始执行。

定义自定义标量类型

您可以通过创建一个新类型，或通过将类型别名指向另一个现有类型来定义自定义标量类型的类型。

您的自定义标量类型必须符合CustomScalarType协议。这需要您实现自定义标量类型的JSON序列化功能。

要实现CustomScalarType协议：

1. 实现属性 `_jsonValue`。

这个属性将标量值转换为可以序列化为JSON字典的JSONValue。属性_jsonValue的值将被存储为自定义标量的缓存中的JSON值。

通常，这应该与表示自定义标量的网络响应值相同。

2. 实现初始化器 `init(_jsonValue:)`。

此初始化器用于从JSONValue构建自定义标量值。当从网络响应构建标量时，_jsonValue参数将是网络响应中的值。当从缓存值构建标量时，这将是在_jsonValue属性中提供的值。

如果提供的值未被识别，您应该从这个函数中抛出一个错误。Apollo iOS在JSONDecodingError库中提供了JSONDecodingError，但您可以抛出任何您希望抛出的自定义错误。

3. 如有需要，实现`Hashable`和`Equatable`协议。

如果你的自定义标量类型尚未符合Hashable和Equatable，你需要实现hash(into:)和==操作符，分别符合这两个协议。

示例：`UUID`

例如，你可以将typealias将UUID指向Foundation.UUID类型：

MySchema/CustomScalars/UUID.swift

1
import Foundation
2

3
public extension MySchema {
4
  typealias UUID = Foundation.UUID
5
}
6

7
extension Foundation.UUID: CustomScalarType {
8
  public init (_jsonValue value: JSONValue) throws {
9
    guard let uuidString = value as? String,
10
    let uuid = UUID(uuidString: uuidString) else {
11
      throw JSONDecodingError.couldNotConvert(value: value, to: Foundation.UUID.self)
12
    }
13

14
    self = uuid
15
  }
16

17
  public var _jsonValue: JSONValue {
18
    uuidString
19
  }
20
}

示例：`GeoPoint`

或者，你可以创建自己的自定义标量类型。在这种情况下，将typealias替换为新类型。

例如，一个自定义标量 namedGeoPoint，其JSON表示为"100.0,10.0"可以实现如下：

MySchema/CustomScalars/GeoPoint.swift

1
import Foundation
2

3
extension MySchema {
4
    public struct GeoPoint: CustomScalarType, Hashable {
5
        let x: Float
6
        let y: Float
7

8
        public init (_jsonValue value: JSONValue) throws {
9
            let coordinates = try (value as? String)?
10
            .components(separatedBy: ",")
11
            .map { try Float(_jsonValue: $0) }
12

13
            guard let coordinates, coordinates.count == 2 else {
14
                throw JSONDecodingError.couldNotConvert(value: value, to: GeoPoint.self)
15
            }
16

17
            self.x = coordinates[0]
18
            self.y = coordinates[1]
19
        }
20

21
        public var _jsonValue: JSONValue {
22
            "\(String(format: "%.1f", x)),\(String(format: "%.1f", y))"
23
        }
24
    }
25
}

该GeoPoint结构体符合CustomScalarType和Hashable。你必须显式声明符合Hashable，它继承了Equatable的符合性。因为Swift可以在这里合成Hashable和Equatable的符合性，所以你不需要实现它们。

该init(_jsonValue:)初始化器将JSONValue转换为String并将其分离为两个坐标。它使用Float(_jsonValue:)将这些坐标转换为浮点数，这是Apollo提供的。每个内建标量类型都支持JSON序列化，你可以在自定义标量实现中使用。

为了确保序列化JSON的一致性，的_jsonValue函数确保使用String(format:,_:)将坐标格式化为使用单个小数点。

具有多个返回类型的JSON和其他自定义标量

一些自定义标量可能在运行时返回多个类型。这并不理想，因为它会失去类型安全性，但如果你使用了一个你无法控制的API，通常没有更好的替代方案。

当发生这种情况时，因为你不知道传入的类型，所以你不能为这个标量设置一个单一的typealias。相反，你需要定义另一种方式来实例化你的自定义标量对象。

这种情况最常见于JSON，它可以返回数组或字典。以下是一个例如何使用枚举来实现有限的动态类型解析（使用CustomJSON作为占位符类型名）：

MySchema/CustomScalars/CustomJSON.swift

1
extension MySchema {
2
    public enum CustomJSON: CustomScalarType, Hashable {
3
        case dictionary([String: AnyHashable])
4
        case array([AnyHashable])
5

6
        public init(_jsonValue value: JSONValue) throws {
7
            if let dict = value as? [String: AnyHashable] {
8
                self = .dictionary(dict)
9
            } else if let array = value as? [AnyHashable] {
10
                self = .array(array)
11
            } else {
12
                throw JSONDecodingError.couldNotConvert(value: value, to: CustomJSON.self)
13
            }
14
        }
15

16
        public var _jsonValue: JSONValue {
17
            switch self {
18
            case let .dictionary(json as AnyHashable),
19
                 let .array(json as AnyHashable):
20
                return json
21
            }
22
        }
23

24
        public static func == (lhs: CustomJSON, rhs: CustomJSON) -> Bool {
25
            lhs._jsonValue == rhs._jsonValue
26
        }
27

28
        public func hash(into hasher: inout Hasher) {
29
            hasher.combine(_jsonValue)
30
        }
31
    }
32
}

类型条件

持久查询