JSONSerialization: какво е, методи на класа Foundation и как работи

Какво е JSONSerialization

JSONSerialization — е клас от рамката Foundation, достъпен на iOS, macOS, tvOS и watchOS. Той предоставя методи за преобразуване на JSON Data в обекти на Foundation (NSDictionary, NSArray, NSString, NSNumber) и обратно. Класът се появи в iOS 5 и до въвеждането на Codable (Swift 4) остана основният начин за работа с JSON на платформите Apple. Въпреки възрастта си, JSONSerialization остава търсен в наследени проекти на Objective-C и в сценарии, където се изисква динамична обработка на JSON без фиксирана схема на модела.

Кога се използва JSONSerialization

Въпреки появата на Codable, JSONSerialization остава актуален в няколко сценария. Динамична структура на JSON — когато форматът на отговора се променя или е предварително неизвестен — изисква достъп до речници чрез ключове, което е по-лесно да се направи чрез JSONSerialization. Класът се използва също в проекти на Objective-C, където Codable не е достъпен, и при работа с потоци за етапно парсиране на големи JSON файлове. В тестове и макети, isValidJSONObject и data(withJSONObject:options:) позволяват бързо генериране на JSON фикстури без свързване на външни библиотеки, което ускорява разработката и прототипирането.

import Foundation

// Основна структура на използване на JSONSerialization
let jsonString = """
{
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
}
"""

guard let jsonData = jsonString.data(using: .utf8) else {
    return
}

do {
    let json = try JSONSerialization
        .jsonObject(with: jsonData,
                       options: .mutableContainers)
    print(json)
} catch {
    print("Грешка при парсиране на JSON: \(error)")
}

Основни методи на класа

JSONSerialization предоставя четири основни метода за работа с JSON. Основният метод — jsonObject(with:options:), който преобразува Data в обекти на Foundation. Методът data(withJSONObject:options:) извършва обратна сериализация. isValidJSONObject(_:) проверява дали обект може да бъде сериализиран. writeJSONObject(_:to:options:error:) записва JSON директно в поток. За четене на JSON от InputStream съществува методът jsonObject(with:options:), който приема поток вместо Data, което е удобно при интеграция с мрежови заявки, връщащи поточни данни.

JSONObject и JSONData

Методът jsonObject приема Data и връща Any — обикновено NSDictionary или NSArray. За безопасна работа резултатът се преобразува в очаквания тип чрез условно преобразуване. Методът data приема обект на Foundation и връща Data с JSON представяне. Опцията .prettyPrinted добавя форматиране с отстъпи за четимост.

let jsonString = """
{
    "products": [
        {"id": 1, "name": "iPhone", "price": 999},
        {"id": 2, "name": "iPad", "price": 799}
    ]
}
"""
let data = Data(jsonString.utf8)

if let json = try? JSONSerialization
    .jsonObject(with: data) as? [String: Any],
    let products = json["products"] as? [[String: Any]] {

    for product in products {
        if let name = product["name"] as? String {
            print("Продукт: \(name)")
        }
    }
}

// Обратна сериализация: обект -> JSON
let outputDict: [String: Any] = ["status": "ok", "count": 42]
if let outputData = try? JSONSerialization
    .data(withJSONObject: outputDict,
                options: .prettyPrinted) {
    String(data: outputData, encoding: .utf8)
}

Примери за парсиране на JSON

Основно парсиране на речник с примитивни типове — най-честата операция с JSONSerialization. След получаване на Data чрез URLSession, разработчикът извиква jsonObject и преобразува резултата в очаквания тип. За масиви от обекти се използва преобразуване в [[String: Any]], след което всеки елемент се обработва в цикъл. Този подход е гъвкав, но изисква ръчно управление на типовете.

Парсиране на вложени структури

Реалните API връщат сложни вложени JSON обекти с масиви, дати и опционални полета. JSONSerialization обработва правилно всяка дълбочина на влагане, но разработчикът трябва самостоятелно да преобразува всяко ниво в необходимия тип. За опростяване на тази задача Apple препоръчва използването на Codable за типизирани данни, а JSONSerialization — само за динамични структури.

// Парсиране на отговор от API
func parseUserResponse(data: Data) {
    do {
        guard let json = try JSONSerialization
            .jsonObject(with: data) as? [String: Any]
        else { return }

        guard let userId = json["id"] as? Int,
              let name = json["name"] as? String
        else {
            throw ParsingError.missingField
        }

        print("Потребител: \(name) (ID: \(userId))")

    } catch let error as ParsingError {
        print("Парсирането неуспешно: \(error)")
    } catch {
        print("Неочаквана грешка: \(error)")
    }
}

enum ParsingError: Error {
    case missingField
    case invalidType
}

Обработка на грешки

JSONSerialization хвърля грешки при невалиден JSON, несъответствие на типове или превишаване на дълбочината на влагане. Грешките принадлежат към типа CocoaError и съдържат код с описание на проблема. Разработчикът е длъжен да ги обработва чрез конструкцията do-catch, в противен случай приложението ще прекрати неочаквано. Най-честите грешки: NSPropertyListReadCorruptError (неправилен JSON) и NSPropertyListReadUnknownError. Всеки тип грешка изисква своя стратегия за обработка: при невалиден формат трябва да се поиска повторно изпращане на данните, а при несъответствие на структурата — актуализиране на модела за парсиране.

Типове грешки при десериализация

Невалиден JSON — най-честата причина за откази: пропусната запетая, излишен символ или неекраниран кавичка разрушават цялото парсиране. Вторият тип грешки — несъответствие с очакваната структура: например сървърът върна масив вместо речник. JSONSerialization.fragmentsAllowed позволява четене на JSON, чийто корен не е речник или масив, а примитивна стойност. Разработчикът може също да се сблъска с грешка за превишаване на дълбочината на влагане, когато JSON съдържа твърде много нива на йерархия.

Опции за четене и запис

JSONSerialization предоставя няколко опции за конфигуриране на парсирането. .mutableContainers връща NSMutableDictionary и NSMutableArray вместо неизменяеми версии, което е полезно при модифициране на данни след парсиране. .mutableLeaves прави текстовите стойности променливи. .fragmentsAllowed позволява JSON, чийто корен не е обект или масив, а текст или число — удобно за прости API отговори. Опциите .withoutEscapingSlashes и .sortedKeys са достъпни за метода data(withJSONObject:options:), управлявайки форматирането на сериализирания JSON. Опциите се предават чрез битова маска, което позволява комбиниране на множество стойности чрез оператора | за гъвкава конфигурация на парсиране.

// Обработка на различни типове грешки
func safeParse(jsonData: Data) {
    do {
        let object = try JSONSerialization
            .jsonObject(with: jsonData,
                           options: .fragmentsAllowed)

        if let dictionary = object as? [String: Any] {
            print("Речник с \(dictionary.count) ключа")
        } else if let array = object as? [Any] {
            print("Масив с \(array.count) елемента")
        }

    } catch CocoaError.propertyListReadCorrupt {
        print("Повредени JSON данни")
    } catch let error as CocoaError {
        print("Cocoa грешка: \(error)")
    } catch {
        print("Непозната грешка: \(error)")
    }
}

// Проверка на валидността на обекта преди сериализация
let testObject: [String: Any] = ["key": "value", "nested": ["a": 1]]
if JSONSerialization.isValidJSONObject(testObject) {
    print("Валиден JSON обект")
}

Производителността на JSONSerialization се влияе от размера на данните и честотата на извикванията. При еднократно парсиране на малък сървърен отговор разликата е незабележима, но при обработка на десетки мегабайта JSON или чести извиквания в цикли трябва да се вземе предвид допълнителното натоварване от преобразуване на типове. JSONSerialization работи синхронно в текущата нишка, поради което за големи документи се препоръчва преместване на парсирането в опашка на заден план чрез DispatchQueue.global(). Алтернативно може да се използва InputStream за поточна обработка без зареждане на целия файл в паметта, което е критично за приложения с ограничени ресурси. За запис на JSON във файл или мрежов поток, методът writeJSONObject(_:to:options:error:) позволява директно насочване на сериализираните данни към OutputStream без създаване на междинен обект Data, което намалява консумацията на памет при работа с големи документи.