Alamofire — là gì, HTTP client bằng Swift và cách hoạt động

Alamofire là gì?

Alamofire là một HTTP client cho Swift được tạo bởi Alamofire Software Foundation (ban đầu bởi Mattt Thompson vào năm 2014). Thư viện trừu tượng hóa các chi tiết cấp thấp của URLSession, cung cấp một API sạch sẽ và biểu cảm cho giao tiếp mạng.

Triết lý cốt lõi của Alamofire là cú pháp chuỗi, trong đó các tham số yêu cầu (URL, phương thức, tiêu đề, tham số, bộ mã hóa) được truyền qua các lệnh gọi tuần tự. Điều này làm cho mã dễ đọc hơn và giảm khả năng xảy ra lỗi liên quan đến cấu hình URLRequest không chính xác. Cách tiếp cận khai báo cho phép tập trung vào những gì cần làm thay vì chi tiết về cách thiết lập kết nối. Nhà phát triển mô tả kết quả mong muốn và thư viện xử lý công việc mạng cấp thấp.

Thư viện đã được duy trì tích cực từ năm 2014 và đã trải qua bảy phiên bản chính. Alamofire 5, hiện tại tính đến năm 2025–2026, bao gồm hỗ trợ Combine, async/await, bộ chuyển đổi phản hồi, EventMonitor để gỡ lỗi và RequestInterceptor để chặn các yêu cầu. Mỗi phiên bản chính đều mang lại những cải tiến đáng kể: Alamofire 4 bổ sung hỗ trợ Codable, Alamofire 5 bổ sung Combine Publishers và hệ thống chặn yêu cầu được cải thiện.

Hệ sinh thái Alamofire bao gồm các thư viện bổ sung: AlamofireImage để tải và lưu trữ hình ảnh, AlamofireNetworkActivityIndicator cho chỉ báo mạng trên thanh trạng thái iOS và AlamofireObjectMapper để tích hợp với ObjectMapper. Các thành phần này biến Alamofire thành một ngăn xếp mạng hoàn chỉnh, không chỉ là một HTTP client.

Cài đặt và thiết lập

Alamofire được cài đặt qua Swift Package Manager (khuyến nghị), CocoaPods hoặc Carthage. Trong Xcode, chỉ cần mở menu File → Add Packages, dán URL kho lưu trữ và chỉ định phiên bản.

// Swift Package Manager — thêm vào Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Nhập trong tệp
import Alamofire

Sau khi cài đặt, Alamofire có sẵn trên toàn cầu thông qua không gian tên AF(viết tắt của Alamofire) mà không cần cấu hình thêm. Hầu hết các dự án bắt đầu bằng cách thiết lập Session với cấu hình riêng — điều này cho phép đặt URL cơ sở, tiêu đề mặc định, thời gian chờ và trình xử lý chứng chỉ TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

Việc tạo phiên tùy chỉnh thông qua Session(configuration:) là cần thiết khi cần cấu hình riêng cho các phần khác nhau của ứng dụng — ví dụ: một phiên riêng cho tải hình ảnh với bộ nhớ đệm mạnh và một phiên khác cho các yêu cầu API có xác thực. Session của Alamofire chấp nhận không chỉ cấu hình mà còn cả interceptor, serverTrustManager, cachedResponseHandler và redirectHandler, cung cấp toàn quyền kiểm soát hành vi mạng ở tất cả các giai đoạn của yêu cầu.

Tính năng chính

Alamofire cung cấp một loạt các chức năng bao phủ hầu hết các tình huống tương tác mạng trong ứng dụng iOS. Hãy xem các tính năng chính.

Yêu cầu HTTP

Cú pháp yêu cầu cơ bản bao gồm phương thức, URL, tham số và mã hóa. Tất cả các phương thức HTTP tiêu chuẩn đều được hỗ trợ thông qua enum HTTPMethod: get, post, put, patch, delete. Các tham số có thể được mã hóa dưới dạng tham số URL (URLEncoding), nội dung JSON (JSONEncoding) hoặc dữ liệu đa phần (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("Được tạo bởi người dùng: \(user)")
        case .failure(let error):
            print("Lỗi: \(error)")
        }
    }

Phương thức validate() tự động kiểm tra mã trạng thái (200–299) và loại nội dung, trả về lỗi khi phản hồi bất thường, loại bỏ việc kiểm tra statusCode thủ công. responseDecodable sử dụng giao thức Decodable để tự động giải mã JSON thành cấu trúc Swift — điều này loại bỏ JSONSerialization thủ công và giảm mã mẫu khi làm việc với REST API.

Xử lý phản hồi

Alamofire hỗ trợ nhiều loại trình xử lý phản hồi: response (dữ liệu thô), responseJSON (từ điển/mảng), responseString (văn bản), responseData (Data) và responseDecodable (mô hình Decodable). Bộ chuyển đổi phản hồi có thể tùy chỉnh — cho protobuf, định dạng đồ họa hoặc giao thức tùy chỉnh.

Tải tệp lên và xuống

Để tải dữ liệu lên máy chủ, sử dụng upload, hỗ trợ Data, File và MultipartFormData. Tải xuống các tệp lớn được thực hiện qua download với khả năng tiếp tục thông qua resumeData sau khi ngắt kết nối. Cả hai thao tác đều hỗ trợ theo dõi tiến trình thông qua uploadProgress và downloadProgress với giá trị phân số từ 0 đến 1 để hiển thị trong giao diện người dùng.

Tải lên đa phần với Alamofire đặc biệt thuận tiện: phương thức upload(multipartFormData:) chấp nhận một closure nơi các phần biểu mẫu được thêm qua append. Mỗi phần có thể chứa dữ liệu, tệp hoặc luồng, cùng với tên và loại mime riêng. Alamofire tự động tính toán ranh giới đa phần và đặt tiêu đề Content-Type chính xác, giúp nhà phát triển không cần tự tạo nội dung yêu cầu. Đối với các tệp lớn, nên sử dụng nhà cung cấp luồng thay vì tải toàn bộ tệp vào bộ nhớ — điều này ngăn chặn việc vượt quá giới hạn bộ nhớ trên các thiết bị di động có tài nguyên hạn chế. Một tình huống điển hình là gửi ảnh đại diện người dùng cùng với dữ liệu hồ sơ trong một yêu cầu đa phần duy nhất, giảm số lượng cuộc gọi HTTP và đơn giản hóa xử lý phía máy chủ.

Alamofire vs URLSession

So sánh Alamofire với URLSession gốc giúp đưa ra quyết định kiến trúc. Alamofire không thay thế URLSession — nó được xây dựng trên nó và sử dụng cùng cơ chế cấu hình, bộ nhớ đệm và tác vụ nền. Tất cả các tính năng của URLSession đều có thể truy cập qua Alamofire, nhưng với cú pháp khai báo thuận tiện hơn.

Trong các dự án lớn, Alamofire giảm mã yêu cầu mạng xuống 30–50% và đơn giản hóa xử lý lỗi. Trong các dự án nhỏ hoặc khi kích thước tệp nhị phân là ràng buộc nghiêm ngặt, URLSession gốc được ưu tiên hơn do không có phụ thuộc bên ngoài.

Alamofire 5 hiện đại tích hợp với Combine thông qua thuộc tính publishDecodable, trả về một Publisher, cho phép chuỗi yêu cầu phản ứng với xử lý lỗi và chuyển đổi dữ liệu. Đối với async/await, các phương thức có hậu tố value có sẵn — ví dụ: AF.request(url).serializingDecodable(User.self).value, làm cho cú pháp cực kỳ ngắn gọn và gợi nhớ đến việc làm việc với URLSession gốc. Khi sử dụng async/await, không cần closure nữa và xử lý lỗi được thực hiện thông qua các khối do-catch tiêu chuẩn của Swift, đơn giản hóa việc bảo trì mã và khả năng đọc về lâu dài.

Ví dụ mã

Hãy xem xét một ví dụ phức tạp hơn — một yêu cầu với bộ chặn tự động thêm token ủy quyền và thực hiện thử lại khi lỗi 401. Đây là tình huống điển hình cho các ứng dụng có xác thực JWT.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

AuthInterceptor triển khai hai giao thức: adapt (thêm token vào mỗi yêu cầu) và retry (cố gắng làm mới token khi lỗi 401). Phương thức retry kiểm tra mã trạng thái phản hồi và nếu nhận được 401, yêu cầu token mới qua TokenManager. Sau khi làm mới thành công, yêu cầu được tự động thử lại.

Sử dụng bộ chặn với một phiên:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

Tất cả các yêu cầu qua phiên này tự động đi qua AuthInterceptor — token được thêm vào tiêu đề và khi 401, việc làm mới và thử lại được thực hiện. Điều này loại bỏ sự trùng lặp mã xác thực trong mọi yêu cầu và tập trung hóa logic quản lý token.