Идеальный REST-клиент для iOS

Введение

В подавляющем большинстве современных мобильных приложений используется сетевой обмен данными. Обладая обширным опытом сетевого взаимодействия в крупных компаниях (банки, маркетплейсы и т.п.), хотим поделиться опытом построения идеального, с нашей точки зрения, сетевого клиента для iOS.

В нашем представлении идеальный REST-клиент обеспечивает:

• сетевые запросы в одну строчку в большинстве случаев;

• асинхронность (с iOS 13.0);

• гибкость (возможность широкой настройки);

• компактность реализации —это значит, что код клиента легко понять и, в случае обнаружения недостатка, доработать под свои нужды. В нашем случае код клиента умещается в ~300 строк, протокол с расширениями в ~200 строк и два инструментальных файла по 30 строк. Всего 4 файла: суммарно < 600 строк.

Пример нашего типичного сетевого запроса (внутри некоего класса):

struct Warehouse: Decodable {
    let id: Int
    let title: String
}

func fetchWarehouses() async throws -> [Warehouse] {
    try await userSession.httpClient.get(url: userSession.api("warehouses"))
}

Описание сущности userSession будет далее.

Постановка задачи

Дано:

• стандартный класс URLSession.

Требуется:

• построить REST-клиент поверх HTTP c обменом данными в формате JSON;

• обеспечить возможность автоматической реакции на некоторые ошибки, чтобы не реагировать на них вручную в каждом обработчике сетевого запроса. Это свойство называется Request Retrier. Оно полезно в случае, когда с сервера в ответе на любой запрос может прилететь приоритетное прерывание, без которого дальнейшая работа невозможна (например, обновление пользовательского соглашения об оказываемых услугах которое необходимо принять);

• обеспечить возможность извлекать из сетевых ответов общую информацию и в некоторых случаях кидать исключения. Это свойство называется Response Validator. Случается, что сервер, в случае ошибки запроса, присылает не 400-е значения ошибки, а 200 и, вместо ожидаемого ответа, информацию об ошибке запроса. Именно для обработки таких ситуаций и применяется ResponseValidator;

Решение

Предварительные замечания

URLSession, обладая обширными возможностями и универсальностью, по нашему мнению, обладает и некоторыми недостатками. Перечислим их:

• классический способ подразумевает получение данных через параметр-замыкание в то время, как предпочтительным в текущий момент является асинхронный результат. Начиная с iOS 15, в URLSession появилась поддержка асинхронности. Наше решение работает начиная с iOS13;

let task = URLSession.shared.dataTask(with: url) {(data, response, error) in
  guard let data = data else { return }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

• возвращаемый результат представляет собой класс типа Data и URLResponse, которые надо вручную анализировать и разбирать для получения целевых Decodable-структур DTO (Data Transfer Object) — структур обмена данными или получения информации о транспортной ошибке;

• так же в запросе надо указывать параметры заголовка и класть в них всякую техническую информацию вроде токенов аутентификации (к которым, разумеется, должен быть доступ в месте сетевого вызова). Можно (и нужно) эту информацию положить один раз в URLSessionConfiguration перед инициализацией URLSession. Но можно про это и не знать, и каждый раз указывать это в сетевом запросе. Да, URLSession настолько гибкий, что можно один и тот же результат получать несколькими различными способами, и часто разработчики идут самым прямолинейным путем.

Cуществующие open source решения

Ограничимся рассмотрением самого популярного фреймворка — Alamofire.

Плюсы:

• популярный фреймворк, хорошо подходит для простых проектов.

Минусы:

• заявленная универсальность приводит к громоздким конструкциям «в несколько строк»

// Automatic String to URL conversion, Swift concurrency support, and automatic retry.
let response = await AF.request("https://httpbin.org/get", interceptor: .retryPolicy)
                       // Automatic HTTP Basic Auth.
                       .authenticate(username: "user", password: "pass")
                       // Caching customization.
                       .cacheResponse(using: .cache)
                       // Redirect customization.
                       .redirect(using: .follow)
                       // Validate response code and Content-Type.
                       .validate()
                       // Produce a cURL command for the request.
                       .cURLDescription { description in
                         print(description)
                       }
                       // Automatic Decodable support with background parsing.
                       .serializingDecodable(DecodableType.self)
                       // Await the full response with metrics and a parsed body.
                       .response
// Detailed response description for easy debugging.
debugPrint(response)

• большой объём кода самой библиотеки (300 Кб). Хочется иметь представление о всём коде, который мы используем. В случае Alamofire — это довольно затруднительно;

• иногда отсутствует поддержка полезных фич (etag). Её очень долго не было, и рекомендация поддержки была прекрасна — «не используйте etag». В последних версиях исправили.

• миграция — только одна версия Alamofire на проект. Мажорные версии существенно отличаются. Миграция в большом проекте из многих модулей, которые ведут разные команды, представляется затруднительной. Особенно затруднительна миграция при смене парадигм сетевых запросов (синхронная с замыканиями / асинхронная), поскольку эта смена влечет переделку всего сервисного кода приложения;

• проблема «длинной истории» разработки. Alamofire разрабатывается многие годы, за которые в нём накопилось огромное количество разного редко используемого функционала, что привело к существенной громоздкости библиотеки. Новые особенности там появляются в довольно неуклюжем виде. Как в асинхронном примере выше. Сравните с самым первым примером кода.

Наше решение

Сетевой запрос является естественной асинхронной операцией. С появлением в iOS 13 асинхронных вызовов, они идеально подошли для реализации сетевого обмена. Сетевой клиент у нас реализован в два уровня: протокол и реализация.

Протокол

Дизайн протокола отражает желательный характер сетевых запросов. То есть, GET, POST, PUT, DELETE, PATCH — HTTP-запросы. На первый взгляд, тут присутствует некоторая похожесть методов, но при использовании это выглядит максимально естественно и удобно. Помимо этого, протокол позволяет замокать реализацию для написания модульных-тестов.

/// Асинхронный HTTP клиент
public protocol AsyncHttpClient {

  var session: URLSession { get }

  /// GET HTTP method
  func get<Target: Decodable>(
    url: URL,
    parameters: [String: Any],
    tuners: [AsyncHttp.RequestTuners.Keys: AsyncHttp.RequestTuners]
  ) async throws -> Target

  /// POST HTTP method
  func post<Body: Encodable, Target: Decodable>(
    url: URL,
    body: Body,
    tuners: [AsyncHttp.RequestTuners.Keys: AsyncHttp.RequestTuners]
  ) async throws -> Target

  // Полностью аналогичные POST методы PUT, DELETE, PATCH
  // ...
}

Протокол AsyncHttpClient дополняет расширение, которое позволяет:

• не указывать параметры методов кроме URL;

• не возвращать значение для всех методов кроме GET.

В каждом методе протокола AsyncHttpClient присутствует опциональный набор тюнеров, который позволяет в случае необходимости как угодно настроить любой запрос. В этом проявляется максимальная гибкость нашего решения. Если оно поверх URLSession/URLRequest, значит должен быть опциональный доступ и к URLSession и к URLRequest.

/// Тюнеры запросов
public enum AsyncHttpRequestTuners {
  /// Тюнер запроса - позволяет как угодно настроить запрос
  case request((inout URLRequest) -> Void)

  /// Тюнер ответа - позволяет валидировать и извлекать данные из заголовка ответа
  case response((HTTPURLResponse) throws -> Void)

  /// Тюнер кодера. Позволяет настраивать кодер
  case encoder((inout JSONEncoder) -> Void)

  /// Тюнер декодера. Позволяет настраивать декодер
  case decoder((inout JSONDecoder) -> Void)

  public enum Keys {
    case request
    case encoder
    case decoder
  }
}

Пример использования тюнера:

func fetchCounters() async throws -> Counters {
  try await network.get(
    url: api("counters"),
    tuners: [
      .request: .request { (request: inout URLRequest) in
        request.timeoutInterval = 15
      }
    ]
  )
}

Обратим внимание на параметр метода get parameters: [String: Any]. Для удобства кодирования параметров поставляется протокол CompactDictionaryRepresentable, который транслирует swift-структуру в формат [String: Any]. При этом все опциональные отсутствующие поля игнорируются.

Пример:

// Некоторые перечисления опущены

struct TasksExcelRequest: CompactDictionaryRepresentable {
  let type: String
  let order: String
  let timezoneOffset: Int = TimeZone.current.secondsFromGMT() / 3600
  let warehouseID: String?
  let deliveryType: String?
  let filterStatus: String?

  init(
    type: MarketplaceSegment,
    order: MarketplaceSorting,
    warehouseID: String? = nil,
    deliveryType: DeliveryType? = nil,
    filterStatus: TasksStatus? = nil
  ) {
      self.type = type.rawValue
      self.order = order.rawValue
      self.warehouseID = warehouseID
      self.deliveryType = deliveryType?.rawValue
      self.filterStatus = filterStatus?.rawValue
  }
}

struct MarketplaceFile: Decodable {
  let data: Data
  let mimeType: String
  let name: String
}

func fetchExcel(tasks request: TasksExcelRequest) async throws -> MarketplaceFile {
  try await httpClient.get(
    url: userSession.userSession.api("tasks/excel"),
    parameters: request.compactDictionaryRepresentation
  )
}

Метод get поддерживает etag. Для этого кодирование параметров в URL query всегда происходит в одном и том же порядке.

В случае недостаточности функционала, имеется доступ к базовой URLSession чтобы иметь возможность использовать её функционал.

Реализация.

Функционал HTTP-клиента реализует класс

public class AsyncHttpJsonClient: AsyncHttpClient {
  public init(
    configuration: URLSessionConfiguration = URLSessionConfiguration.default,
    requestRetrier: AsyncHttpRequestRetrier? = nil,
    responseValidator: AsyncHttpResponseValidator? = nil,
    dateFormatter: DateFormatter = ISO8601DateFormatterEx()
  )
  // ...
}

Он конфигурируется URLSessionConfiguration где должны быть настроены параметры аутентификации. При смене параметров аутентификации подразумевается пересоздание всего HTTP-клиента.

Дополнительно можно указать обработчик исключений (requestRetrier), проверщик ответов (responseValidator) и формировщик дат.

/// Протокол специальной реакции на некоторые ошибки
public protocol AsyncHttpRequestRetrier {
  func shouldRetry(request: URLRequest, error: Error) async -> Bool
}

/// Протокол проверки ответов и генерации специфических ошибок
public protocol AsyncHttpResponseValidator {
  func validate(response: HTTPURLResponse, data: Data?) throws
}

К сожалению, стандартный формировщик дат ISO8601DateFormatter обладает недостатками, по-этому в пакет включен расширенный формировщик дат, позволяющий работать с временными поясами и дробными секундами.

В случае, если responseValidator кинет исключение, то requestRetrier тоже вызовется.

Подробно описывать код сетевого клиента представляется излишним. Его технологическая часть составляет примерно 100 строк. Ссылка на код находится в ссылках.

Архитектурные замечания.

В дополнение к сетевому клиенту рекомендуется создать класс UserSession, который будет представлять пользовательскую сессию.

Например:

enum ApiVersion: String {
  case v1
  case v2
  case v3
  case v4
}

protocol UserSessionProtocol: AnyObject {
  var httpClient: AsyncHttpClient { get }

  func endpoint(for target: ApiVersion) -> URL
  func logout() async
  // Dependancy Injecting.
  func locate(service: Any.Type) -> Any?
}

extension UserSessionProtocol {

  func baseUrl() -> URL { baseUrl(for: .v1) }

  func api(_ name: String, version: ApiVersion = .v1) -> URL {
    endpoint(for: version).appendingPathComponent(name)
  }

  func api(_ name: String, version: ApiVersion = .v1, appending pathComponents: [String]) -> URL {
    api(name, version: version).appendingPathComponent(pathComponents.joined(separator: "/"))
  }

  func get<T>(service: T.Type) -> T {
    // Разрешаем форскаст потому что предполагается, что искомые сервисы всегда будут зарегистрированы
    // при создании сессии.
    locate(service: service) as! T
  }

}

Реализация опущена, т.к. она незначительна для нашей статьи. Именно такую сессию использует код из примера 1.

Также рекомендуется вместо непосредственного обращения к сессии (и сетевому клиенту) из бизнес-логики приложения использовать промежуточный сервисный слой. Он изолирует сущности бизнес логики от сущностей сетевого транспорта и исправляет транспортные артефакты вроде таких:

struct Model<Model: Decodable>: Decodable {
  let model: Model
}

struct PaymentsResponse: Decodable {
  let payments: [Payment]
}

struct Payment: Decodable {
  let id: Int
  let date: Date
  let amount: Double
}

protocol ReportsWorker {
  //...
  func fetchPayments() async throws -> [Payment]
  //...
}

class ReportsService: ReportsWorker {
  //...
  func fetchPayments() async throws -> [Payment] {
    // С сервера целевая информация приходит обернутая в несколько слоёв
    // Извлекаем данные из обёрток
    // Кроме того, даты с сервера прилетают неудобном формате. Применяем тюнер
    let response: Transport.Model<PaymentsResponse> = try await userSession.asyncHttpClient.get(
      url: userSession.endpoint().appendingPathComponent("getPayments"),
      tuners: [
        .decoder: .decoder { (decoder: inout JSONDecoder) in
          decoder.dateDecodingStrategy = .formatted( {
            DateFormatter(format: "yyyy-MM-dd")
          }())
        }
      ]
    )
    return response.model.payments
  }
  // ...
}

Для наглядности, визуализируем рекомендованную архитектуру сервисного слоя:

Заключение.

В данной статье мы описали реализацию идеального, по нашему мнению, сетевого клиента на iOS (и прочих AppleOS), которая отличается удобством использования, функциональной гибкостью и компактностью реализации. Надеемся, эта статья окажется полезной для читателей. Пишите комментарии, задавайте вопросы.

Полезные ссылки:

Код асинхронного сетевого клиента на GitHub.

Моя статья "Идеальный наблюдатель на Swift".