Apollo iOS 1.2 迁移指南

本指南描述了将您的代码从版本 1.0 或 1.1 迁移到 Apollo iOS 1.2 版本的过程。Apollo iOS。

尽管 1.2 是一个 minor 版本升级，但在这个版本中解决了一个关键问题，升级过程中需要进行小的重大变更是必需的。虽然我们努力使次要版本的升级路径平滑，但如果没有这次迁移，无法合理地解决这个问题。

缓存键配置 API

本版本中配置自定义缓存键的 API 实现了细微的变化。在您生成的SchemaConfiguration.swift文件中定义的cacheKeyInfo(for:objecthots:)函数已进行了修改。

在先前版本中，objecthots:参数是JSONObject类型，这是一个typealias，表示Dictionary<String, AnyHashable>类型。在 1.2 版本中，objecthots:参数是新建类型ObjectData。

为保留您的实现，SchemaConfiguration.swift文件只会在第一次生成代码时生成。这意味着在升级到 Apollo iOS 1.2 时，您需要修改cacheKeyInfo(for:objecthots:)函数的函数签名。

对于新项目，该函数将在第一次生成代码时正确生成。

理由

因为缓存键解析在原始JSON（来自网络响应）和SelectionSet模型数据（直接写入缓存时）上同时进行，因此底层object数据将具有不同的格式。这种不一致性导致了一些用户难以跟踪的bug。ObjectData包装器struct用于在cacheKeyInfo(for:object:)函数的上下文中规范这种数据以保持一致格式。

迁移步骤

对于大多数用户，更改只是将函数签名从

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: JSONObject) -> CacheKeyInfo? {
3
    /// ...
4
  }
5
}

修改为

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: ObjectData) -> CacheKeyInfo? {
3
    /// ...
4
  }
5
}

对于大多数基本用例，这些用例仅使用object的subscript来访问其值，这将是足够的。ObjectData结构体并没有提供与Dictionary相同的API，并且存在一些语义上的差异，您可能需要解决。我们建议运行充分的测试以确认您的缓存键解析函数仍然返回预期的值。

如果您的缓存键解析函数在新函数签名下无法编译或无法正确解析缓存键，请继续阅读以获取更多信息。

底层值类型更改

The ObjectData struct 允许您以保持值类型一致性的方式访问提供的object中的值。如果您的对cacheKeyInfo(for:object:)函数的实现将值转换为特定预期类型，则可能需要修改您的代码以确保正确执行类型转换。

• 标量类型
  • 原始的标量值（String, Int, Float, Double或Bool）
• 自定义标量类型
  • 自定义标量将被反序列化为从类型jsonValue属性返回的原始值。
  • 有关更多信息，请参阅自定义标量。
• 对象类型s
  • 对于其他嵌套在传入的GraphQL对象，将返回另一个ObjectData结构体。
  • 在之前的版本中，返回值是另一个JSONObject（即。Dictionary）。
• 列表类型
  • 对于列表字段，返回值是新定义的ListData结构体。
  • ListData结构体与ObjectData结构体功能相同，但是包裹了一个元素数组而不是字典。

ObjectData API 限制

The ObjectData结构体公开了一个显著受限的 API。它仅允许对底层数据的键值对进行索引访问。通常，这个 API 应该足以访问解决缓存键所需的值。如果您cacheKeyInfo(for:object:)函数正在使用任何其他功能来使用Dictionary，您需要重构您的代码。

为了避免对缓存键解析机制的复杂性要求，仅在需要时根据用户反馈对ObjectDataAPI进行扩展。如果您的cacheKeyInfo(for:object:)函数需要在ObjectData上公开其他功能，请提交一个功能请求.

示例

让我们考虑一个示例cacheKeyInfo(for:object:)函数，它是从之前版本中需要修改以迁移到1.2版本的。

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: JSONObject) -> CacheKeyInfo? {
3
    switch type {
4
    case Objects.User:
5
        let userInfo = object[info] as? [String: AnyHashable]
6
        let emailList = userInfo["emailAddresses"] as? [String]
7
        return try? CacheKeyInfo(jsonValue: emailList[0])
8

9
    case Objects.Post:
10
        let timestampCustomScalar = object["timestamp"] as? TimeStamp
11
        let timestampRawValue = object["timestamp"] as? String
12
        let timestampString = (timestampCustomScalar?.jsonValue as? String)
13
            ?? timestampRawValue
14
        return try? CacheKeyInfo(jsonValue: timestampString)
15

16
    case Objects.Product:
17
      return try? CacheKeyInfo(id: object["UPC"])
18

19
    default:
20
      return nil
21
    }
22
  }
23
}

要将此函数迁移到1.2版本，我们需要进行一些更改。

1. 必须将object参数更改为类型ObjectData
2. 需要对User对象的info字段进行类型转换，使其成为ObjectData而不是[String: AnyHashable]
3. 对于User对象的info.emailAddresses应期望是ListData类型而不是[String]。
4. 之前，Post对象的自定义标量timestamp的值可能是TimeStamp自定义标量或其原始jsonValue类型，这取决于数据来源。现在，我们应该一直期待反序列化为jsonValue – 在这种情况下，一个String。
5. Product对象的自定义字段UPC一直是标量值。这里不需要进行任何更改。

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: ObjectData) -> CacheKeyInfo? {
3
    switch type {
4
    case Objects.User:
5
        let userInfo = object["info"] as? ObjectData
6
        let emailList = userInfo["emailAddresses"] as? ListData
7
        return try? CacheKeyInfo(jsonValue: emailList[0] as? String)
8

9
    case Objects.Post:
10
        let timestamp = object["timestamp"] as? String
11
        return try? CacheKeyInfo(jsonValue: timestamp)
12

13
    case Objects.Product:
14
        return try? CacheKeyInfo(jsonValue: object["UPC"])
15

16
    default:
17
      return nil
18
    }
19
  }
20
}

ObjectData和ListData索引访问器可以链式使用。这意味着User对象的缓存密钥解决方法可以更简单地实现为：

1
case Objects.User:
2
    return try? CacheKeyInfo(
3
        jsonValue: object["info"]?["emailAddresses"]?[0]
4
    )

Swift访问修饰符

1.2.0引入了新的代码生成配置参数，允许您指定生成的Swift类型的访问控制。1.2.0引入了新的代码生成配置参数，允许您指定生成的Swift类型的访问控制。当使用模块类型为embeddedInTarget或operation输出类型为relative或absolute时，您可以选择让生成的Swift类型可以通过public或internal访问。

您不需要将这些选项添加到您的代码生成配置中，但未指定选项时使用的默认值与先前的Apollo iOS版本不同。

在1.2.0之前，所有的Swift类型都使用public访问权限生成，新的配置选项的默认值是internal。

这意味着您之前可能使用公有的Swift类型的地方，现在可能会出现编译器错误，因为这些类型不再可访问。要解决这个问题，您需要在代码生成配置中添加配置选项，指定public访问修饰符。

您可能需要手动修改模式配置和自定义标量文件，因为如果这些文件已经存在，它们将不会被重新生成。手动更新它们的替代方案是删除这些文件，运行代码生成，然后重新添加任何可能在现有的自定义标量文件中使用的自定义逻辑。

示例

模块类型

1
"output": {
2
    "schemaTypes": {
3
        "moduleType": {
4
            "embeddedInTarget": {
5
                "name": "MyApplicationTarget",
6
                "accessModifier": "public"
7
            }
8
        },
9
        "path": "./generated/schema/"
10
    }
11
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
5
            path: "./generated/schema/",
6
            moduleType: .embeddedInTarget(name: "MyApplicationTarget", accessModifier: .public)
7
        )
8
        ...
9
    )
10
)

操作 - 相对

1
"output": {
2
  "operations" : {
3
    "relative" : {
4
      "subpath": "Generated",
5
      "accessModifier": "public"
6
    }
7
  }
8
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        operations: .relative(
5
      subpath: "generated",
6
      accessModifier: .public
7
    )
8
        ...
9
    )
10
)

操作 - 绝对

1
"output": {
2
  "operations" : {
3
    "absolute" : {
4
      "path": "Generated",
5
      "accessModifier": "public"
6
    }
7
  }
8
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        operations: .absolute(
5
      path: "generated",
6
      accessModifier: .public
7
    )
8
        ...
9
    )
10
)