SwiftyTraverson 1.1.1

SwiftyTraverson 1.1.1

×

测试已测试✓
语言语言 SwiftSwift
许可证 Apache 2
发布最后发布2018年1月
SwiftSwift版本3.0
SPM支持SPM✗

由Victor Mosin、Steve Maahs维护。

 
依赖项
Alamofire~> 4.0
SwiftyJSON~> 3.0
URITemplate~> 2.0
 

SwiftyTraverson 1.1.1

  • 由
  • Victor Mosin和Steve Maahs

SwiftyTraverson - Hypermedia API/HATEOAS客户端的Swift实现

介绍

此框架受Traverson JavaScript库的启发。

Traverson 允许您在HATEOAS基础API的响应中跟踪关系链接，而不是为每个单个URL硬编码。此外，内置功能允许您

  • 管理发送到服务器的额外信息
  • 处理URI模板变量
  • 使用不同的认证方式

安装

Traverson 通过 CocoaPods 提供。要安装它，只需将以下行添加到您的Podfile中

pod 'SwiftyTraverson', :git => 'https://github.com/smoope/SwiftyTraverson.git'

用法

初始化

let traverson = Traverson()

配置属性

使用Traverson.Builder来配置Traverson

let traverson = Traverson.Builder()
  .requestTimeout(2.0)
  .responseTimeout(5.0)
  .disableCache()
  .defaultHeader("Accept-Language", value: "de-CH")
.build()

可用属性列表

属性 描述
requestTimeout 为每个请求设置请求超时时间间隔（以秒为单位）。更多信息。
responseTimeout 为每个请求设置响应超时时间间隔（以秒为单位）。更多信息。
disableCache 禁用缓存。更多信息。
defaultHeader 设置单个默认标题，该标题将随每个请求发送到服务器。
defaultHeaders 设置要随每个请求发送到服务器的默认标题集合。
authenticator 根据服务器的安全策略对每个请求进行认证。更多信息。
dispatchQueue 设置结果处理程序被调用的队列

发起请求

Traverson 支持以下 HTTP 方法动词操作数据：GET、POST、PUT 和 DELETE。下面将提供使用每个动词的示例。

检索数据

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .get { result, error in
    // Do something...
  }

创建数据

let objectToAdd: Dictionary<String, AnyObject> = ["name": "John Doe"]

traverson
  .from("http://www.some.com")
  .follow("users")
  .post(objectToAdd) { result, error in
    // Do something...
  }

更新数据

let objectToUpdate: Dictionary<String, AnyObject> = ["id": 1, "name": "John Doe"]

traverson
  .from("http://www.some.com")
  .follow("users", "first")
  .put(objectToUpdate) { result, error in
    // Do something...
  }

删除数据

traverson
  .from("http://www.some.com")
  .follow("users")
  .delete { result, error in
    // Do something...
  }

如您所注意到的，post 和 put 方法期望额外的参数来表示要创建或更新的对象，而 get 和 delete 则没有这样的参数。

读取响应

每种描述的方法都期望一个回调函数，该函数具有以下参数：

  • result，一个对象，包含有关请求成功结果的信息
  • error，一个本地的 ErrorType 对象，包含错误的描述，如果发生错误

默认情况下，SwiftyTraverson 将响应解析为 SwiftyJSON 的 JSON 对象。如果您喜欢原生方式，可以与 Dictionary 一起工作

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .get { result, _ in
    let json:JSON? = result.data
    let dictionary:[String: AnyObject]? = result.dictionary
    // Do something...
  }

错误处理

一旦请求过程中出现问题，回调的 error 变量将包含一个描述

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .get { _, error in
    if let err = error {
      // Handle error...
    }
  }

请求认证

如果服务器需要认证，您可以使用 TraversonAuthenticator 协议的内置或自定义实现。

以下示例显示了使用 HTTP 基本认证的方法

let traverson = Traverson.Builder()
  .authenticator(TraversonBasicAuthenticator(username: "username", password: "password"))
  .build()

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .get { result, error in
    // Do something...
  }

在某些情况下，请求默认需要认证

let traverson = Traverson.Builder()
  .authenticator(TraversonBasicAuthenticator(username: "username", password: "password"), preemptive: true)
  .build()

发送附加信息

您可以发送额外的请求范围信息，例如 HTTP 标头

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .withHeader("Custom-Header", value: "Custom-Value")
  .get { result, error in
    // Do something...
  }

由于 SwiftyTraverson 支持 URI 模板（RFC 6570），因此可以通过查询参数传递

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .withTemplateParameter("page", value: "1")
  .get { result, error in
    // Do something...
  }

甚至是数组

traverson
  .from("http://www.some.com")
  .follow("users", "next")
  .withTemplateParameters(["user": "john", "page": "1", "sort": "color,desc"])
  .get { result, error in
    // Do something...
  }

假设我们有以下 URI 模板：http://www.some.com/{user}/{?page,sort}，它将被替换为 http://www.some.com/john/?page=1&sort=color,desc。

重用相同的 Traverson 实例

一旦定义 Traverson 实例，就可以通过调用 newRequest 方法多次使用

traverson
  .from("http://www.some.com")
  .follow("users")
  .get { result, error in
    // Do something...
  }

...

traverson
  .newRequest()
  .follow("users")
  .post(objectToAdd) { result, error in
    // Do something...
  }

...

traverson
  .newRequest()
  .follow("users", "1")
  .delete{ result, error in
    // Do something...
  }

支持不同的媒体类型

SwiftyTraverson 预期您的服务器端实现遵循 HATEOAS 原则，无论使用哪种表示技术来渲染响应。默认情况下，它与 JSON 和 JSON HAL 标准一起工作。

如果使用简单的 JSON 表示，则应在其调用期间指定它

traverson
  .from("http://www.some.com")
  .json()
  .follow("users", "next")
  .get { result, error in
    // Do something...
  }

一旦您的响应完全遵循 HAL 标准，您就不必做任何事情，这是默认行为。或者，您可以强制使用它

traverson
  .from("http://www.some.com")
  .jsonHal()
  .follow("users", "next")
  .get { result, error in
    // Do something...
  }

缓存

默认情况下，系统框架会缓存所有调用。更多详情.

许可

SwiftyTraverson 在 Apache License，Version 2.0 下可用。有关更多信息，请参阅 LICENSE 文件。