Harbor 是一个 Swift 库，它使用 async/await 提供了一种简单的方式来发起 API 请求。
- 特性
- 要求
- 安装
- 用法
- Mocks (模拟)
- Contributing (贡献)
- Author (作者)
- License (许可)
- Rest Requests (Rest 请求)
- JSON RPC Requests (JSON RPC 请求)
- Auth provider handler (授权提供者处理程序)
- Multipart Post Requests (Multipart Post 请求)
- Retry Requests (重试请求)
- Cancel Request (取消请求)
- Debug Requests (调试请求)
- cURL Command Output (cURL 命令输出)
- 默认 Header
- 自定义 URLSession
- mTLS Certificate (mTLS 证书)
- SSL Pinning (SSL 证书绑定)
- Swift 6 Compatible (Swift 6 兼容)
- Mock Requests (模拟请求)
- Swift 5.9+
- iOS 15.0
您可以使用 CocoaPods 或 Swift Package Manager 将 Harbor 添加到您的项目中。
将以下行添加到您的 Podfile
pod 'Harbor'
将以下内容添加到您的 Package.swift 文件
dependencies: [
.package(url: "https://github.com/javiermanzo/Harbor.git")
]
这提供了一种集中管理通用配置的方法。
您可以将默认 header 包含在每个请求中。
要配置默认 header
await Harbor.setDefaultHeaderParameters([
"MY_CUSTOM_HEADER": "VALUE"
])
如果您需要处理身份验证，您可以实现 HAuthProviderProtocol。 使用 Harbor 类的 setAuthProvider 方法来设置身份验证提供程序。
您需要创建一个实现 HAuthProviderProtocol 的类
class MyAuthProvider: HAuthProviderProtocol {
func getAuthorizationHeader() async -> HAuthorizationHeader {
// Return a HAuthorizationHeader instance
}
func authFailed() async {
// This method is called when the request receives a 401 status code
}
}
之后，设置您的 Auth provider
await Harbor.setAuthProvider(MyAuthProvider())
如果请求类将 needsAuth 属性设置为 true，Harbor 将调用身份验证提供程序的 getAuthorizationHeader 方法来获取 HAuthorizationHeader 实例，以便在执行请求之前将其设置在 header 中。
Harbor 允许您为您的请求设置自定义 URLSession，为高级配置提供灵活性，例如自定义缓存、超时设置或其他协议。
要设置自定义 URLSession，请使用 setCustomURLSession 方法
let customSession = URLSession(configuration: .default)
await Harbor.setCustomURLSession(customSession)
Harbor 支持 mutual TLS (mTLS)，以增强 API 请求的安全性。 此功能允许客户端向服务器提供证书，确保客户端和服务器相互验证。
要设置 mTLS，请使用 setMTLS 方法
let mTLS = HmTLS(p12FileUrl: yourP12FileUrl, password: "yourPassword")
await Harbor.setMTLS(mTLS)
Harbor 支持 SSL Pinning 以增强您的 API 请求的安全性。 SSL Pinning 确保客户端根据已知的固定证书检查服务器的证书，从而增加额外的安全层。
要配置 SSL Pinning，请使用 setSSlPinningSHA256 方法
let sslPinningSHA256 = "yourSHA256CertificateHash"
await Harbor.setSSlPinningSHA256(sslPinningSHA256)
要使用 Harbor 发起请求，您需要创建一个实现以下协议之一的类。
如果您想发送 GET 请求，请使用 HGetRequestProtocol 协议。
queryParameters: 将添加到 URL 的查询参数字典。Model: 请求的结果将被解析为此实体。
如果您想发送 POST 请求，请使用 HPostRequestProtocol 协议。
bodyParameters: 将包含在请求正文中的参数字典。bodyType: 指定在请求正文中发送的数据类型。 它可以是 json 或 multipart。
如果您想发送 PATCH 请求，请使用 HPatchRequestProtocol 协议。
bodyParameters: 将包含在请求正文中的参数字典。bodyType: 指定在请求正文中发送的数据类型。 它可以是 json 或 multipart。
如果您想发送 PUT 请求，请使用 HPutRequestProtocol 协议。
bodyParameters: 将包含在请求正文中的参数字典。bodyType: 指定在请求正文中发送的数据类型。 它可以是 json 或 multipart。
如果您想发送 DELETE 请求，请使用 HDeleteRequestProtocol 协议。
如果您想将响应解析为特定模型，请使用 HRequestWithResultProtocol 协议。 此协议要求您定义您期望在响应中出现的模型类型。
Model: 请求的结果将被解析为此实体。
创建请求类后，您可以使用 request 方法执行请求。
Task {
let response = await MyRequestWithResult().request()
}
如果您使用的协议与 HGetRequestProtocol 或 HRequestWithResultProtocol 不同，则调用 request() 的结果将是一个 HResponse 枚举。
switch response {
case .success:
break
case .error(let error):
break
}
如果您使用 HGetRequestProtocol 或 HRequestWithResultProtocol，则调用 request() 的结果将是一个 HResponseWithResult 枚举。
switch response {
case .success(let result):
break
case .error(let error):
break
}
如果请求正在运行，您可以取消该请求的任务。 request() 将返回 cancelled 作为错误情况。
let task = Task {
let response = await MyRequestWithResult().request()
}
task.cancel()
您可以使用 HDebugRequestProtocol 协议打印有关您的请求的调试信息。 在请求类中实现该协议。
class MyRequest: HRequestWithResultProtocol, HDebugRequestProtocol {
var debugType: HDebugRequestType = .requestAndResponse
// ...
}
debugType 定义您要在控制台中打印的内容。 选项为 none、request、response 或 requestAndResponse。
当您的请求被调用时，您将在 Xcode 控制台中看到有关您的请求的信息。
Harbor 还通过 HarborJRPC 包支持 JSON RPC。
要使用 HarborJRPC，请将以下导入添加到您的文件中
import HarborJRPC
使用此方法设置 JSON RPC 请求的 URL
HarborJRPC.setURL("https://api.example.com/")
使用此方法设置 JSON RPC 版本
// It uses 2.0 as default
HarborJRPC.setJRPCVersion("2.0")
如果您想发送 JRPC 请求，请使用 HJRPCRequestProtocol 协议。
Model: 符合Codable协议的模型，表示预期的响应结构。method: 一个字符串，表示要调用的 JRPC 方法。needsAuth: 一个布尔值，指示请求是否需要身份验证。retries: 请求失败时的重试次数。headers: 一个可选字典，包含要包含在请求中的任何其他 header。parameters: 一个可选参数字典，包含在请求中。
要使用 HarborJRPC 配置请求，请创建一个实现 HJRPCRequestProtocol 的结构或类。 调用 request() 的结果将是一个 HJRPCResponse
switch response {
case .success(let result):
break
case .error(let error):
break
}
Harbor 允许您注册和管理 mock 以方便测试您的 API 请求。
使用 HMock 为您的请求声明 mock 响应。
request: 符合HRequestBaseRequestProtocol的请求类型，将为其设置 mock。statusCode: 要返回的 HTTP 状态代码。jsonResponse: 一个String，表示 JSON 响应。 这将被解码为您的请求的预期模型。error: 如果您想模拟错误响应，则为一个可选的HRequestError。delay: 返回 mock 响应之前的可选延迟（以秒为单位），以模拟网络延迟。
要注册 mock，请使用 register(mock:) 方法。 这将允许您模拟响应而不是进行实际的 API 调用。
let mock = HMock(
///
)
await Harbor.register(mock: mock)
let jsonResponse = """
{ "name": "John Doe" }
"""
let mock = HMock(
request: MyGetUsersRequest.self,
statusCode: 200,
jsonResponse: jsonResponse
)
await Harbor.register(mock: mock)
let mock = HMock(
request: MyGetUsersRequest.self,
statusCode: 401,
error: .authNeeded
)
await Harbor.register(mock: mock)
您可以将 mock 配置为仅在 #DEBUG 中使用，从而防止它们影响生产环境。 默认值为true。
await Harbor.setMocksOnlyInDebug(false)
如果您需要删除特定的 mock，请使用 remove(mock:) 方法。
await Harbor.remove(mock: mock)
要清除所有注册的 mock，请使用 removeAllMocks() 方法。
await Harbor.removeAllMocks()
下面是一个完整的示例，演示了如何使用 Harbor 设置和使用 mock
Task {
let jsonResponse = """
{ "users": [{ "id": 1, "name": "Alice" }] }
"""
let userMock = HMock(
request: MyGetUsersRequest.self,
statusCode: 200,
jsonResponse: jsonResponse
)
// Register the mock
await Harbor.register(mock: userMock)
// Perform a request that will use the registered mock
let response = await MyGetUsersRequest().request()
switch response {
case .success(let users):
// You will receive the mocked response here
print("Users:", users)
case .error(let error):
break
}
}
如果您遇到任何问题，请提交 issue。 欢迎提交 Pull request！
Harbor 由 Javier Manzo 创建。
Harbor 在 MIT 许可下可用。 有关更多信息，请参见 LICENSE 文件。