APIリクエストのコード化可能およびコードの整理方法

こんにちは、Habr！

Swift 4以降、新しいCodableプロトコルにアクセスできるようになり、モデルのエンコード/デコードが容易になりました。 私のプロジェクトにはAPI呼び出し用のコードがたくさんありますが、過去1年間、繰り返しコードを削除し、マルチパートリクエストやURLクエリパラメーターに対してもCodableを使用することで、この膨大なコードを非常に軽量で簡潔でシンプルなものに最適化するために多くの作業を行ってきました。 私の意見では、サーバーからリクエストを送信し、レスポンスを解析するためのいくつかの優れたクラスであることが判明しました。 また、便利なファイル構造もあります。これは、リクエストの各グループのコントローラーであり、バックエンドでVapor 3を使用するときに慣れました。 数日前、私はすべての開発を別のライブラリで選択し、CodyFireという名前を付けました。 この記事で彼女についてお話ししたいと思います。

免責事項

CodyFireはAlamofireに基づいていますが、Alamofireの単なるラッパーではなく、iOSのREST APIを操作するためのシステム全体のアプローチです。 だから、AlamofireがCodableサポートがある5番目のバージョンを見ているのではないかと心配しません。 私の創造物を殺すことはありません。

初期化

遠くから少し始めましょう。つまり、3台のサーバーがあることが多いという事実です。

dev-開発用、Xcodeから始めるもの
ステージ -リリース前のテスト用、通常はTestFlightまたはInHouseで
prod-生産、AppStore向け

もちろん、多くのiOS開発者は、 環境変数の存在とXcodeのスタートアップスキームについて知っていますが、私の（8年以上の）プラクティスでは、開発者の90％がテスト中またはビルド前に適切なサーバーを一定の時間で記述しています。私はそれを正しく行う方法の良い例を示すことによって修正したいもの。

CodyFireはデフォルトで、アプリケーションが現在どの環境で実行されているかを自動的に判断し、非常に単純にします。

#if DEBUG //DEV environment #else if Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt" { //TESTFLIGHT environment } else { //APPSTORE environment } #endif 

これはもちろん内部であり、AppDelegateのプロジェクトでは3つのURLを登録するだけで済みます。

 import CodyFire @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { let dev = CodyFireEnvironment(baseURL: "http://localhost:8080") let testFlight = CodyFireEnvironment(baseURL: "https://stage.myapi.com") let appStore = CodyFireEnvironment(baseURL: "https://api.myapi.com") CodyFire.shared.configureEnvironments(dev: dev, testFlight: testFlight, appStore: appStore) return true } } 

そして、これを喜んで、他に何もすることはできません。

しかし、実際には、Xcodeでdev、stage、prodサーバーをテストする必要がある場合が多いため、スタートアップスキームを使用することをお勧めします。

ヒント： [スキームの管理]セクションで、プロジェクトのすべての開発者が使用できるように、各スキームの[共有]チェックボックスをオンにすることを忘れないでください。

各スキームでは、dev、testFlight、appStoreの3つの値を取ることができる環境変数「env」を記述する必要があります。



また、これらのスキームをCodyFireで使用するには、 CodyFireを初期化した後にAppDelegate.didFinishLaunchingWithOptionsに次のコードを追加する必要があります

 CodyFire.shared.setupEnvByProjectScheme() 

さらに、多くの場合、プロジェクトのボスまたはテスターがLoginScreenのどこかでサーバーをオンザフライで切り替えるように要求する場合があります。 CodyFireを使用すると、環境を変更してサーバーを1行で切り替えることで、これを簡単に実装できます。

 CodyFire.shared.environmentMode = .appStore 

これは、アプリケーションが再起動されるまで機能します。起動後に保存する場合は、値をUserDefaultsに保存し、 AppDelegateでアプリケーションが起動するときにチェックを行い、必要な環境に切り替えます。

この重要な点を話しました。環境の切り替えが美しく行われるプロジェクトがさらに増えることを願っています。 同時に、ライブラリはすでに初期化されています。

ファイル構造とコントローラー

これで、すべてのAPI呼び出しのファイル構造に対する私のビジョンについて話すことができます。これはCodyFireのイデオロギーと呼ばれます。

プロジェクトで最終的にどのように見えるか見てみましょう



ファイルのリストを見てみましょう、 API.swiftから始めましょう。

 class API { typealias auth = AuthController typealias post = PostController } 

すべてのコントローラーへのリンクはここにリストされているため、 `API.controller.method`を介して簡単に呼び出すことができます。

 class AuthController {} 

API + Login.swift

 extension AuthController { struct LoginResponse: Codable { var token: String } static func login(email: String, password: String) -> APIRequest<LoginResponse> { return APIRequest("login").method(.post) .basicAuth(email: email, password: password) .addCustomError(.notFound, "User not found") } } 

このデコレータでは、APIを呼び出す関数を宣言します。

-エンドポイントを指定
-HTTP POSTメソッド
-基本認証にラッパーを使用
-サーバーからの特定の応答に必要なテキストを宣言します（これは便利です）
-そして、データがデコードされるモデルを示します

何が隠されたままですか？

-完全なサーバーURLを指定する必要はありません。 すでにグローバルに設定されています
-すべてが正常であれば、 200 OKを受け取ることを示す必要はありませんでした

200 OKは、すべてのリクエストに対してCodyFireが期待するデフォルトのステータスコードです。この場合、データがデコードされ、コールバックが呼び出されます。

さらに、 LoginScreenのコードのどこかで、単に呼び出すことができます

 API.auth.login(email: "test@mail.com", password: "qwerty").onError { error in switch error.code { case .notFound: print(error.description) //: User not found default: print(error.description) } }.onSuccess { token in //TODO:  auth token    print("Received auth token: "+ token) } 

onErrorとonSuccessは、APIRequestが返すことができるコールバックのほんの一部に過ぎません。これらについては後で説明します。

入力例では、返されたデータが自動的にデコードされる場合のオプションのみを考慮しましたが、自分でそれを実装できたと言うことができ、あなたは正しいでしょう。 そのため、例として登録フォームを使用してモデルでデータを送信する可能性を考えてみましょう。

API + Signup.swift

 extension AuthController { struct SignupRequest: JSONPayload { let email, password: String let firstName, lastName, mobileNumber: String init(email: String, password: String, firstName: String, lastName: String, mobileNumber: String) { self.email = email self.password = password self.firstName = firstName self.lastName = lastName self.mobileNumber = mobileNumber } } struct SignupResponse: Codable { let token: String } static func signup(_ request: SignupRequest) -> APIRequest<SignupResponse> { return APIRequest("signup", payload: request).method(.post) .addError(.conflict, "Account already exists") } } 

ログインとは異なり、登録中に大量のデータを送信します。

この例では、 JSONPayloadプロトコルに準拠するSignupRequestモデルがあります（したがって、CodyFireはペイロードタイプを理解します）。そのため、リクエストの本文はJSONの形式になります。 x-www-form-urlencodedが必要な場合は、 FormURLEncodedPayloadを使用します 。

その結果、ペイロードモデルを受け入れる単純な関数が得られます

 API.auth.signup(request) 

成功すると、特定の応答モデルが返されます。

クールだと思いますよね？

しかし、マルチパートの場合はどうでしょうか？

Postを作成できる例を見てみましょう。

投稿+ Create.swift

 extension PostController { struct CreateRequest: MultipartPayload { var text: String var tags: [String] var images: [Attachment] var video: Data init (text: String, tags: [String], images: [Attachment], video: Data) { self.text = text self.tags = tags self.images = images self.video = video } } struct Post: Codable { let text: String let tags: [String] let linksToImages: [String] let linkToVideo: String } static func create(_ request: CreateRequest) -> APIRequest<CreateRequest> { return APIRequest("post", payload: request).method(.post) } } 

このコードは、画像ファイルの配列と1つのビデオを含むマルチパートフォームを送信できます。
ディスパッチを呼び出す方法を見てみましょう。 Attachmentについての最も興味深い瞬間です。

 let videoData = FileManager.default.contents(atPath: "/path/to/video.mp4")! let imageAttachment = Attachment(data: UIImage(named: "cat")!.jpeg(.high)!, fileName: "cat.jpg", mimeType: .jpg) let payload = PostController.CreateRequest(text: "CodyFire is awesome", tags: ["codyfire", "awesome"], images: [imageAttachment], video: videoData) API.post.create(payload).onProgress { progress in print(" : \(progress)") }.onError { error in print(error.description) }.onSuccess { createdPost in print("  : \(createdPost)") } 

添付ファイルは、 データに加えて、ファイル名とそのMimeTypeも送信されるモデルです。

Alamofireまたはむき出しのURLRequestを使用してSwiftからマルチパートフォームを送信したことがある場合は、 CodyFireのシンプルさを高く評価するでしょう。

これで、GET呼び出しのよりシンプルでクールな例ができました。

投稿+ Get.swift

 extension PostController { struct ListQuery: Codable { let offset, limit: Int init (offset: Int, limit: Int) { self.offset = offset self.limit = limit } } static func get(_ query: ListQuery? = nil) -> APIRequest<[Post]> { return APIRequest("post").query(query) } static func get(id: UUID) -> APIRequest<Post> { return APIRequest("post/" + id.uuidString) } } 

最も簡単な例は

 API.post.get(id:) 

onSuccessでは 、 Postモデルが返されます。

より興味深い例を次に示します。

 API.post.get(PostController.ListQuery(offset: 0, limit: 100)) 

ListQueryモデルを入力として受け取り、
どのAPIRequestが最終的にフォームのURLパスに変換されるか

 post?limit=0&offset=100 

[Post]配列をonSuccessに返します。

もちろん、古い方法でURLパスを記述できますが、今では完全にコード化できることがわかっています。

最後のリクエスト例はDELETEになります

投稿+ Delete.swift

 extension PostController { static func delete(id: UUID) -> APIRequest<Nothing> { return APIRequest("post/" + id.uuidString) .method(.delete) .desiredStatusCode(.noContent) } } 

2つの興味深い点があります。

-戻り値の型はAPIRequestであり、空のCodableモデルであるジェネリック型Nothingを指定します。
-204 NO CONTENTを受け取ることを明示的に示し、この場合はCodyFireはonSuccessのみを呼び出します。

ViewControllerからこのエンドポイントを呼び出す方法はすでに知っています。

ただし、2つのオプションがあります。1つ目はonSuccessで、2つ目はなしです。 彼を見ます

 API.post.delete(id:).execute() 

つまり、リクエストが満たされているかどうかが重要でない場合は、それに対して.execute（）を呼び出すだけです。そうでない場合は、ハンドラーのonSuccess宣言の後に開始されます。

利用可能な機能

各リクエストの承認

http-headersで各リクエストAPIに署名するには、グローバルハンドラーが使用されます。これはAppDelegateのどこかに設定できます。 さらに、クラシック[String：String]またはCodableモデルを使用して選択できます。

認証ベアラーの例。

1.コーディング可能（推奨）

 CodyFire.shared.fillCodableHeaders = { struct Headers: Codable { //NOTE:  nil,     headers var Authorization: String? var anythingElse: String } return Headers(Authorization: nil, anythingElse: "hello") } 

2.クラシック[文字列：文字列]

 CodyFire.shared.fillHeaders = { guard let apiToken = LocalAuthStorage.savedToken else { return [:] } return ["Authorization": "Bearer \(apiToken)"] } 

リクエストにいくつかのhttp-headerを選択的に追加します

これは、APIRequestの作成時に実行できます。たとえば、次のとおりです。

 APIRequest("some/endpoint").headers(["someKey": "someValue"]) 

不正なリクエストの処理

AppDelegateなどでグローバルに処理できます

 CodyFire.shared.unauthorizedHandler = { //   WelcomeScreen } 

または各リクエストでローカルに

 API.post.create(request).onNotAuthorized { //   } 

ネットワークが利用できない場合

 API.post.create(request). onNetworkUnavailable { //   ,  ,     } 

それ以外の場合、 onErrorでエラー._notConnectedToInternetが発生します

リクエストが始まる前に何かを始める

.onRequestStartedを設定して、ローダーなどの表示を開始できます。
これは便利な場所です。インターネットがない場合は呼び出されず、たとえばローダーを表示するために無駄に表示される必要がないためです。

ログ出力をグローバルに無効/有効にする方法

 CodyFire.shared.logLevel = .debug CodyFire.shared.logLevel = .error CodyFire.shared.logLevel = .info CodyFire.shared.logLevel = .off 

単一のリクエストのログ出力を無効にする方法

 .avoidLogError() 

独自の方法でログを処理する

 CodyFire.shared.logHandler = { level, text in print("  CodyFire: " + text) } 

サーバーの期待されるhttp応答コードを設定する方法

上記で述べたように、デフォルトでは、CodyFireは200 OKを受信することを想定しており、受信した場合、データの解析を開始してonSuccessを呼び出します 。

しかし、予想されるコードは、たとえば201 CREATEDのように、便利な列挙の形式で設定できます。

 .desiredStatusCode(.created) 

または、カスタムの予想コードを設定することもできます

 .desiredStatusCode(.custom(777)) 

リクエストをキャンセル

 .cancel() 

.onCancellationハンドラーを宣言することで、リクエストがキャンセルされていることがわかります

 .onCancellation { //   } 

そうでない場合、 onErrorが発生します

リクエストのタイムアウトを設定する

 .responseTimeout(30) //   30  

ハンドラーはタイムアウトイベントでハングすることもあります

 . onTimeout { //    } 

そうでない場合、 onErrorが発生します

インタラクティブな追加タイムアウトの設定

これは私のお気に入りの機能です。 米国のある顧客が彼女について尋ねてきました。 彼は、ログインフォームがあまりにも早く機能することを好まなかった。彼の意見では、それは認証ではなく偽物であるかのように自然に見えなかった。

アイデアは、彼が電子メール/パスワードのチェックを2秒以上続けることです。 そして、0.5秒しか続かない場合は、さらに1.5秒スローしてからonSuccessを呼び出す必要があります。 正確に2秒または2.5秒かかる場合は、すぐにonSuccessを呼び出します。

 .additionalTimeout(2) // 2     

カスタム日付エンコーダー/デコーダー

CodyFireには独自のDateCodingStrategy列挙型があり、3つの値があります

-secondsSince1970
-ミリ秒
-フォーマット済み（_ customDateFormatter：DateFormatter）

DateCodingStrategyは、デコードとエンコードのために3つの方法で別々に設定できます。
-AppDelegateでグローバルに

 CodyFire.shared.dateEncodingStrategy = .secondsSince1970 let customDateFormatter = DateFormatter() CodyFire.shared.dateDecodingStrategy = .formatted(customDateFormatter) 

-1つのリクエスト

 APIRequest("some/endpoint") .dateDecodingStrategy(.millisecondsSince1970) .dateEncodingStrategy(.secondsSince1970) 

-または、モデルごとに個別に、モデルがCustomDateEncodingStrategyおよび/またはCustomDateDecodingStrategyと一致する必要があります。

 struct SomePayload: JSONPayload, CustomDateEncodingStrategy, CustomDateDecodingStrategy { var dateEncodingStrategy: DateCodingStrategy var dateDecodingStrategy: DateCodingStrategy } 

プロジェクトに追加する方法

ライブラリは、MITライセンスの下でGitHubで入手できます。

現在、インストールはCocoaPodsからのみ利用可能です

 pod 'CodyFire' 

CodyFireが他のiOS開発者にとって有用であり、開発を簡素化し、一般的に世界を少し良くし、人々をやさしくすることを願っています。

お時間をいただきありがとうございます。

UPD：ReactiveCocoaおよびRxSwiftサポートが追加されました

 pod 'ReactiveCodyFire' # ReactiveCocoa pod 'RxCodyFire' # RxSwift #      'CodyFire',     

ReactiveCocaのAPIRequestには.signalProducerがあり、RxSwiftの場合は.observableがあります

UPD2：複数のリクエストを実行できるようになりました
各クエリの結果を取得することが重要な場合は、 .and（）を使用します
このモードでは、可能な限り最大10個のリクエストを実行でき、それらは厳密に次々に実行されます。

 API.employee.all() .and(API.office.all()) .and(API.car.all()) .and(API.event.all()) .and(API.post.all()) .onError { error in print(error.description) }.onSuccess { employees, offices, cars, events, posts in //    !!! } 

onRequestStarted、onNetworkUnavailable、onCancellation、onNotAuthorized、onTimeoutも使用できます。
onProgress-まだ開発中

クエリの結果を気にしない場合は、 .flatten（）を使用できます

 [API.employee.all(), API.office.all(), API.car.all()].flatten().onError { print(error.description) }.onSuccess { print("flatten finished!") } 

それらを同時に実行するには、 .concurrentを追加するだけで（by：3）、これにより3つの要求を同時に実行できます。任意の数を指定できます。
失敗したリクエストエラーをスキップするには、 .avoidCancelOnError（）を追加します
進捗を確認するには、 .onProgressを追加します

UPD3：リクエストごとに個別のサーバーを設定できるようになりました
必要なサーバーアドレスをどこかに作成する必要があります。例えば、このような

 let server1 = ServerURL(base: "https://server1.com", path: "v1") let server2 = ServerURL(base: "https://server2.com", path: "v1") let server3 = ServerURL(base: "https://server3.com") 

そして、エンドポイントを指定する前に、リクエストの初期化でそれらを直接使用できます

 APIRequest(server1, "endpoint", payload: payloadObject) APIRequest(server2, "endpoint", payload: payloadObject) APIRequest(server3, "endpoint", payload: payloadObject) 

または、リクエストを初期化した後にサーバーを指定できます

 APIRequest("endpoint", payload: payloadObject).serverURL(server1)