Mockingbird

Mockingbird 是一个用 Swift 编写的 网络抽象层 (NAL)，它利用了 Foundation 的 URLSession 的强大功能和灵活性。它与 iOS 版本 9 及以上和 macOS 版本 10.12 及以上兼容。

它受到 Moya 和 Alamofire 的启发，专注于更轻松地集成为单元测试提供网络层。

安装

目前仅支持 Cocoapods 和 Swift 包管理器 SPM，对 Carthage 的支持即将到来。Mockingbird 提供两个主要版本，一个支持 Swift 4.2，适用于 iOS 9 及以上版本，另一个支持 Swift 5，它本身支持 iOS 10 及以上版本。两个版本均支持 macOS 10.12 及以上版本，请安装适合您应用程序的版本。

Mockingbird 支持 Xcode 11 包管理器

Cocoapods

要使用 Cocoapods 安装 Mockingird，只需将其添加到项目中的 Podfile

Swift 4.2

 pod 'Mockingbird-Swift', '~> 1.0'

如果您想使用 RxSwift 扩展，请添加它们

pod 'Mockingbird-Swift/RxSwift', '~> 1.0'

Swift 5

 pod 'Mockingbird-Swift', '~> 2.0'

如果您想使用 RxSwift 扩展，请添加它们

pod 'Mockingbird-Swift/RxSwift', '~> 2.0'

要将在您的应用程序中使用该库，请按照以下方式导入 Swift 模块

import Mockingbird_Swift

Swift 包管理器

只需在您的 Package.swift 文件中将 Mockingbird 添加为依赖项

Swift 4.2

dependencies: [
    .package(url: "https://github.com/jandro-es/Mockingbird", .upToNextMajor(from: "1.0.0"))
]

Swift 5

dependencies: [
    .package(url: "https://github.com/jandro-es/Mockingbird", .upToNextMajor(from: "2.0.0"))
]

架构

Mockingbird 项目简化了应用程序中网络层的创建。你可以在不同类型中实现 RemoteServiceType 协议，以声明性方式定义整个层。Mockingbird 会自动生成网络端点的简单映射。Mockingbird 使用 URLSession 作为其底层网络系统，并暴露其配置，允许你进行定制，以及其他许多自定义。下面是一个简化的架构图（更多细节请查看代码）。

使用 Mockingbird

定义远程 API

构建网络层的第一步是声明性方式定义你想要交互的服务或 API。为了定义这些远程 API，你可以使用枚举、结构体 或类，但我们发现使用枚举是最清晰的，但这可能与你使用的情况不同。为了声明一个 API，我们需要实现 RemoteService 协议。以下是一个简单的示例：

enum GitHub {
    case zen
    case userProfile(String)
}

extension GitHub: RemoteServiceType {

    var baseURL: URL {
        return URL(string: "https://api.github.com")!
    }
    var path: String {
        switch self {
        case .zen:
            return "/zen"
        case .userProfile(let name):
            return "/users/\(name)"
        }
    }

    var method: HTTPMethod {
        return .get
    }

    var requestType: RequestType {
        switch self {
        case .zen, .userProfile:
            return .plain
        }
    }

    var testData: Data {
        switch self {
        case .zen:
            return "The hardest thing in this world is to live in it".data(using: String.Encoding.utf8)!
        case .userProfile(let name):
            return "{\"login\": \"\(name)\", \"id\": 123456}".data(using: String.Encoding.utf8)!
        }
    }

    var validation: RequestValidation {
        return .successAndRedirectCodes
    }

    var headers: [String: String]? {
        return nil
    }
}

此示例声明了一个 GitHub API 的接口，包含两个端点，.zen 和 userProfile。让我们一步一个脚印地看每个要求。

基本 URL

正如其名所示，这是 API 的基本 URL。我们可能会为每个端点使用不同的基础（使用枚举），但这被认为是一种坏做法，更好的做法是声明基于不同 URL 的不同服务。基本 URL 应包含协议信息。

路径

这是端点的完全合格路径，包含所有必要的 URL 参数（不是查询字符串的那些）。Mockingbird 不会自动转义 这些参数。

方法

此HTTP方法/动词用于请求。Mockingbird提供了一个枚举，包含以下值：

GET
POST
PATCH
PUT
DELETE
HEAD

请求类型

Mockingbird应进行的请求类型，即如何准备请求和如何处理响应。可用的请求类型包括：

plain: 简单 Request
data: 请求体包含 Data
JSONEncodable: 请求体包含 Encodable 对象
customJSONEncodable: 请求体包含使用自定义 JSONEncoder 的 Encodable 对象
parameters: 请求包含使用 ParameterEncodingType 作为编码器的 URL 参数集合
compositeData: 请求包含 URL 参数集合和 Data 类型的请求体
compositeParameters: 请求包含作为 Data 编码的请求体参数和 URL 参数的组合
download: 请求用于下载文件
downloadParameters: 请求用于下载带有 URL 参数的文件

测试数据

这是当使用 stubbing 请求端点时要返回的 Data 对象。这可以在测试或甚至在合同开发下很有用。

验证

Mockingbird根据所需的验证技术自动验证响应。这使得简化错误管理代码成为可能。可用的验证技术包括：

none: 无验证
successCodes: 标准HTTP成功代码（200,...,299）
successAndRedirectCodes: 标准HTTP成功和重定向代码（200,...,399）
customCodes: 自定义有效HTTP代码集合

headers

这是一个可选的字典，包含要添加到请求中的 HTTP 头。

初始化 Mockingbird 实例

如果你使用默认值，初始化会很简单，你只需让 swift 编译器知道类型

let githubAPI = Mockingbird<GithubAPI>()

Mockingbird 实例允许进行很多自定义和/或配置，如果你想了解所有选项，我建议查看测试，因为所有可能的情况在那里都被覆盖了。

初始化 Mockingbird 最常见的场景包括

let githubAPI = Mockingbird<GithubAPI>(middleware: [Middleware.networkActivityIndicator])

创建一个带有指定 Middleware 的 GithubAPI 实例。

let githubAPI = Mockingbird<GithubAPI>(sessionConfiguration: configuration)

使用指定的 URLSessionConfiguration 创建一个 GithubAPI 实例。

let githubAPI = Mockingbird<GithubAPI>(stubLambda: Mockingbird.immediatelyStub)

创建一个在无延迟情况下返回存根的 GithubAPI 实例。这个存根是 GithubAPI 枚举中声明的 testData。

请求数据

使用闭包

当使用作为返回技术时，它返回一个具有 success(value) 和 failure(error) 情况的 Result 类型。

githubAPI.request(.zen) { result in
    switch result {
    case let .success(response):
      print("data: \(response.data)")
    case let .failure(mockingbirdError):
      print("error: \(mockingbirdError)")
    }
}

使用 RxSwift

RxSwift 扩展内置提供。在请求数据时使用它们

githubAPI.rx.request(.zen)
.subscribe { event in
  switch event {
  case .success(let response):
      print("data: \(response.data)")
  case .error:
      print("error: \(mockingbirdError)")
}

使用 RxSwift 可以通过可用的 Rx 操作符进行整洁的验证和操作。

中间件

中间件是一种强大的添加日志、身份验证令牌以及或修改您的请求和响应的清洁且解耦的方式。它由协议 MiddlewareType 定义。包含两种中间件类型

身份验证令牌中间件

此中间件允许您自动将身份验证令牌添加到所有需要它的请求中。它在 AccessTokenMiddleware 中定义。支持的身份验证令牌类型有

无：无AccessToken
基本：Basic AccessToken
Bearer：Bearer AccessToken
自定义：custom AccessToken

要了解如何使用它，请查看测试中的内容 MockingbirdIntegrationTests。

网络活动中间件

此中间件在实际网络请求开始和结束时执行代码块，允许用户更新UI，例如显示和隐藏网络活动指示器。

static var networkActivityIndicator: NetworkActivityMiddleware {
  return NetworkActivityMiddleware { status, _ in
      switch status {
      case .began:
          DispatchQueue.main.async {
              UIApplication.shared.isNetworkActivityIndicatorVisible = true
          }
      case .ended:
          DispatchQueue.main.async {
              UIApplication.shared.isNetworkActivityIndicatorVisible = false
          }
      }
  }
}

日志记录

Mockingbird 使用 Apple的统一日志。

子系统	类别
com.filtercode.mockingbird	request_operation
com.filtercode.mockingbird	request
com.filtercode.mockingbird	response
com.filtercode.mockingbird	middleware

即将推出

多部分上传
下载进度

贡献力量

安装项目

我们使用 Swift 包管理器 开发框架，在克隆项目后运行

swift package generate-xcodeproj

以生成 Xcode 项目。构建请运行

swift build

运行测试 （假设您已安装 xcpretty，如果没有请删除管道符号）。

xcodebuild test -scheme Mockingbird-Package -project Mockingbird.xcodeproj -enableCodeCoverage YES | xcpretty

许可协议

本项目遵循 MIT 许可协议。

Mockingbird-Swift 2.0.0

Mockingbird-Swift 2.0.0

Mockingbird-Swift 2.0.0

Mockingbird

目录

安装

Cocoapods

Swift 4.2

Swift 5

Swift 包管理器

Swift 4.2

Swift 5

架构

使用 Mockingbird

定义远程 API

基本 URL

路径

方法

请求类型

测试数据

验证

headers

初始化 Mockingbird 实例

请求数据

使用闭包

使用 RxSwift

中间件

身份验证令牌中间件

网络活动中间件

日志记录

即将推出

贡献力量

安装项目

许可协议