Как выполнить запрос к API в Swift с помощью URLSession
Я Равиль Зарипов, программный разработчик из Алматы. В портфолио представлена моя работа с приложениями для Android, iOS, Windows, macOS и Linux. Для мобильных и десктопных решений я использую Delphi, FireMonkey, Kotlin и Swift, а также PHP и базы данных. Такой опыт помогает рассматривать сетевой слой не как изолированный пример, а как часть надёжного приложения.
URLSession — стандартный сетевой клиент в Swift, входящий в Foundation и Cocoa. Он поддерживает HTTP и HTTPS, передачу данных, кэширование, хранение куки и фоновые загрузки. API одинаково работает на iPhone, iPad и Mac, поэтому разработчику не приходится вручную управлять сокетами и сетевыми потоками.
Типичный вызов состоит из трёх этапов: формирования URL, настройки URLRequest и выполнения задачи URLSession. Ответ проверяют по HTTP-коду, затем декодируют в типизированную модель. Ошибки сети, сервера и формата данных обрабатывают отдельно. Такой порядок сохраняет код понятным и упрощает тестирование клиента.
Подготовка URL и структуры запроса
Сначала определяют адрес endpoint, HTTP-метод и параметры запроса. Базовый URL удобно хранить в настройках приложения, а путь к ресурсу добавлять через appendingPathComponent. Этот метод корректно обрабатывает пробелы и специальные символы, сохраняя структуру адреса.
Для 查询-параметров используют URLComponents. Значения передаются отдельными элементами URLQueryItem, поэтому кодирование и объединение параметров выполняются автоматически.
func makeRequest() -> URLRequest? {
var components = URLComponents()
components.scheme = "https"
components.host = "api.example.com"
components.path = "/users"
components.queryItems = [
URLQueryItem(name: "page", value: "2"),
URLQueryItem(name: "limit", value: "20")
]
guard let url = components.url else { return nil }
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 15
return request
}
Метод задают свойством httpMethod: обычно это GET, POST, PUT, PATCH или DELETE. Запросы GET и HEAD обычно не содержат тела, а POST, PUT и PATCH могут передавать JSON. Значение timeoutInterval ограничивает ожидание ответа и помогает избежать зависшего интерфейса при проблемах с сетью.
Передача JSON-тела и заголовков
Тело запроса формируют из структуры, соответствующей типу Encodable. JSONEncoder преобразует её в данные, которые можно записать в httpBody. Ручное объединение словарей в строку здесь не требуется.
struct NewUser: Encodable {
let name: String
let email: String
}
func makeRequest(endpoint: URL) throws -> URLRequest {
let payload = NewUser(
name: "Айдана",
email: "a@example.com"
)
let encoder = JSONEncoder()
encoder.keyEncodingStrategy = .convertToSnakeCase
var request = URLRequest(url: endpoint.appendingPathComponent("users"))
request.httpMethod = "POST"
request.httpBody = try encoder.encode(payload)
request.setValue(
"application/json",
forHTTPHeaderField: "Content-Type"
)
return request
}
Заголовок Content-Type сообщает серверу формат тела, а Accept задаёт желаемый тип ответа. Если сервер ожидает даты в определённом формате, настраивают dateEncodingStrategy. Ошибку кодирования лучше пробрасывать вызывающему коду, чтобы он мог показать понятное уведомление или записать диагностику.
Асинхронный вызов и декодирование ответа
Метод data(for:) выполняет запрос с помощью Swift Concurrency. Он возвращает данные и объект ответа, а функцию можно объявить как async throws. Такой подход избавляет от цепочки вложенных замыканий и позволяет использовать привычные конструкции try, catch и await.
struct User: Decodable {
let id: Int
let name: String
let email: String
}
func loadUser(id: Int, endpoint: URL) async throws -> User {
let url = endpoint
.appendingPathComponent("users")
.appendingPathComponent(String(id))
var request = URLRequest(url: url)
request.httpMethod = "GET"
let (data, response) = try await URLSession.shared.data(for: request)
guard let httpResponse = response as? HTTPURLResponse else {
throw URLError(.badServerResponse)
}
guard (200...299).contains(httpResponse.statusCode) else {
throw URLError(.badServerResponse)
}
return try JSONDecoder().decode(User.self, from: data)
}
Перед декодированием проверяют, что ответ принадлежит HTTPURLResponse, а код состояния находится в диапазоне от 200 до 299. JSONDecoder сопоставляет поля JSON со свойствами структуры. Если сервер использует другие имена полей, помогает convertFromSnakeCase, а для сложных дат настраивают отдельную стратегию декодирования.
Обработка ошибок, тайм-аутов и отмены
Сетевые ошибки возникают до получения HTTP-ответа: нет соединения, DNS-адрес не найден, истекло время ожидания или пользователь отменил задачу. Их перехватывают как URLError и анализируют поле code. Ошибки HTTP-статуса и несоответствие JSON-схемы относятся к другим категориям.
do {
let (_, response) = try await URLSession.shared.data(for: request)
print(response)
} catch let error as URLError {
switch error.code {
case .timedOut:
print("Превышено время ожидания")
case .notConnectedToInternet:
print("Нет подключения к сети")
case .cancelled:
print("Запрос отменён")
default:
print("Сетевая ошибка: \(error.localizedDescription)")
}
}
Код 401 или 403 обычно указывает на проблему авторизации, 404 — на отсутствие ресурса, 409 — на конфликт состояния. Ответ 429 и некоторые ошибки сервера иногда допускают повторную попытку с задержкой. Повторять такие запросы стоит только для идемпотентных операций и с учётом заголовка Retry-After. Отмена через Task.cancel() освобождает связанные ресурсы и предотвращает обновление экрана после ухода пользователя со страницы.
Авторизация и безопасное хранение токенов
Для защищённых ресурсов используют протокол OAuth 2.0. Короткоживущий токен доступа передают в заголовке Authorization, а не в параметрах URL: так секрет не попадёт в журналы сервера и историю браузера.
request.setValue(
"Bearer \(accessToken)",
forHTTPHeaderField: "Authorization"
)
request.setValue(
"application/json",
forHTTPHeaderField: "Accept"
)
Токены сохраняют в Keychain с достаточной степенью защиты. Обычное хранилище настроек не подходит для refresh token, а вывод токенов в консоль следует исключить из production-кода. Соединения выполняют по HTTPS без отключения проверки сертификатов. Дополнительные сценарии использования сетевого слоя представлены в материалах по сетевым запросам.
Когда срок действия токена заканчивается, приложение запрашивает новый access token и повторяет исходную операцию. Чтобы несколько параллельных запросов не запустили одновременное обновление, используют actor или иной механизм координации. Повтор выполняют только после успешного обновления и не чаще одного раза для конкретного запроса.
Сравнение способов выполнения запроса
Общая сессия подходит для простых обращений без индивидуальных настроек. Собственную URLSession создают, когда требуется задать кэш, куки, тайм-ауты, разрешение использовать мобильную сеть или включить фоновую передачу. Конфигурацию сессии желательно определить заранее и использовать повторно.
Асинхронный метод удобен в коде с async и await, а замыкание dataTask сохраняет совместимость с существующей архитектурой. JSONDecoder подходит для предсказуемых ответов, тогда как ручной разбор нужен при смешанных форматах или нестандартных полях. Выбор зависит от модели приложения, требований к отмене задач и способа обработки ошибок.
| Способ | Когда подходит | Что учитывать |
|---|---|---|
| Общая сессия URLSession | Простые запросы без отдельных настроек | Минимальный объём кода, общие параметры сессии |
| URLSession с собственной конфигурацией | Кэш, куки, фоновые загрузки и сетевые ограничения | Требуется управлять жизненным циклом сессии |
data(for:) с async и await |
Swift Concurrency и последовательный поток кода | Удобная обработка ошибок и отмена через Task |
dataTask с замыканием |
Существующий код на основе обратных вызовов | Результат обрабатывается в очереди сессии |
| JSONDecoder | Ответ с известной JSON-схемой | Требуется тип Decodable и точные имена полей |
| Ручной разбор данных | Нестандартный или смешанный формат | Больше кода и собственный контроль ошибок |