JSONSerialization: ano ito, mga pamamaraan ng Foundation class at paano ito gumagana

Ano ang JSONSerialization

JSONSerialization — ay isang klase mula sa Foundation framework, available sa iOS, macOS, tvOS at watchOS. Nagbibigay ito ng mga pamamaraan para sa pag-convert ng JSON Data sa Foundation objects (NSDictionary, NSArray, NSString, NSNumber) at vice versa. Ang klase ay lumitaw sa iOS 5 at hanggang sa pagpapakilala ng Codable (Swift 4) ay nanatiling pangunahing paraan ng pagtatrabaho sa JSON sa mga platform ng Apple. Sa kabila ng edad nito, ang JSONSerialization ay nananatiling hinihiling sa mga legacy na proyekto sa Objective-C at sa mga sitwasyon kung saan kinakailangan ang dynamic na pagproseso ng JSON na walang nakapirming schema ng modelo.

Kailan ginagamit ang JSONSerialization

Sa kabila ng pagdating ng Codable, ang JSONSerialization ay nananatiling may kaugnayan sa ilang mga sitwasyon. Dynamic na istraktura ng JSON — kapag ang format ng tugon ay nagbabago o hindi alam nang maaga — ay nangangailangan ng pag-access sa mga diksyunaryo sa pamamagitan ng mga susi, na mas madaling gawin sa pamamagitan ng JSONSerialization. Ginagamit din ang klase sa mga proyekto ng Objective-C kung saan hindi available ang Codable, at kapag nagtatrabaho sa mga stream para sa sunod-sunod na pag-parse ng malalaking JSON file. Sa mga pagsubok at mock-up, ang isValidJSONObject at data(withJSONObject:options:) ay nagbibigay-daan sa mabilis na pagbuo ng JSON fixtures nang hindi kumokonekta sa mga third-party na library, na nagpapabilis sa pag-unlad at prototyping.

import Foundation

// Pangunahing istraktura ng paggamit ng 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("Error sa pag-parse ng JSON: \(error)")
}

Mga pangunahing pamamaraan ng klase

JSONSerialization ay nagbibigay ng apat na pangunahing pamamaraan para sa pagtatrabaho sa JSON. Ang pangunahing pamamaraan — jsonObject(with:options:), na nagko-convert ng Data sa Foundation objects. Ang pamamaraang data(withJSONObject:options:) ay nagsasagawa ng reverse serialization. Sinusuri ng isValidJSONObject(_:) kung ang isang bagay ay maaaring i-serialize. writeJSONObject(_:to:options:error:) ay nagsusulat ng JSON nang direkta sa isang stream. Para sa pagbabasa ng JSON mula sa InputStream, mayroong pamamaraang jsonObject(with:options:), na tumatanggap ng stream sa halip na Data, na maginhawa kapag isinasama sa mga kahilingan sa network na nagbabalik ng stream data.

JSONObject at JSONData

Ang pamamaraang jsonObject ay tumatanggap ng Data at nagbabalik ng Any — kadalasang NSDictionary o NSArray. Para sa ligtas na pagtatrabaho, ang resulta ay kino-convert sa inaasahang uri sa pamamagitan ng kondisyonal na conversion. Ang pamamaraang data ay tumatanggap ng Foundation object at nagbabalik ng Data na may representasyon ng JSON. Ang opsyon na .prettyPrinted ay nagdaragdag ng pag-format na may mga indentation para sa pagiging madaling mabasa.

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("Produkto: \(name)")
        }
    }
}

// Reverse serialization: bagay -> JSON
let outputDict: [String: Any] = ["status": "ok", "count": 42]
if let outputData = try? JSONSerialization
    .data(withJSONObject: outputDict,
                options: .prettyPrinted) {
    String(data: outputData, encoding: .utf8)
}

Mga halimbawa ng pag-parse ng JSON

Pangunahing pag-parse ng isang diksyunaryo na may mga primitive na uri — ang pinakakaraniwang operasyon sa JSONSerialization. Pagkatapos makatanggap ng Data sa pamamagitan ng URLSession, tinatawag ng developer ang jsonObject at kino-convert ang resulta sa inaasahang uri. Para sa mga array ng mga bagay, ginagamit ang conversion sa [[String: Any]], pagkatapos ang bawat elemento ay pinoproseso sa isang loop. Ang diskarteng ito ay nababaluktot ngunit nangangailangan ng manual na pamamahala ng uri.

Pag-parse ng mga nested na istraktura

Ang mga tunay na API ay nagbabalik ng mga kumplikadong nested JSON object na may mga array, petsa, at opsyonal na field. JSONSerialization ay wastong nagpoproseso ng anumang lalim ng pagiging nested, ngunit ang developer ay dapat na independiyenteng i-convert ang bawat antas sa kinakailangang uri. Upang pasimplehin ang gawaing ito, inirerekomenda ng Apple ang paggamit ng Codable para sa naka-type na data, at JSONSerialization — para lamang sa mga dynamic na istraktura.

// Pag-parse ng tugon mula sa 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("User: \(name) (ID: \(userId))")

    } catch let error as ParsingError {
        print("Nag-fail ang pag-parse: \(error)")
    } catch {
        print("Hindi inaasahang error: \(error)")
    }
}

enum ParsingError: Error {
    case missingField
    case invalidType
}

Pangangasiwa ng error

JSONSerialization ay nagtatapon ng mga error sa hindi wastong JSON, hindi tugmang uri, o paglampas sa lalim ng pagiging nested. Ang mga error ay kabilang sa uri ng CocoaError at naglalaman ng code na may paglalarawan ng problema. Ang developer ay obligadong pangasiwaan ang mga ito sa pamamagitan ng do-catch na konstruksyon, kung hindi, ang application ay biglang magtatapos. Ang pinakakaraniwang error: NSPropertyListReadCorruptError (maling JSON) at NSPropertyListReadUnknownError. Ang bawat uri ng error ay nangangailangan ng sarili nitong diskarte sa pangangasiwa: sa hindi wastong format, kailangang humiling ng muling pagpapadala ng data, at sa hindi tugmang istraktura — i-update ang modelo ng pag-parse.

Mga uri ng error sa deserialization

Hindi wastong JSON — ang pinakakaraniwang sanhi ng pagkabigo: nawawalang kuwit, sobrang karakter, o hindi na-escape na panipi ay sumisira sa buong pag-parse. Ang pangalawang uri ng error — hindi pagkakatugma sa inaasahang istraktura: halimbawa, ang server ay nagbalik ng array sa halip na diksyunaryo. JSONSerialization.fragmentsAllowed ay nagpapahintulot sa pagbabasa ng JSON na ang ugat ay hindi diksyunaryo o array, kundi isang primitive na halaga. Ang developer ay maaari ring makatagpo ng error sa paglampas sa lalim ng pagiging nested kapag ang JSON ay naglalaman ng masyadong maraming antas ng hierarchy.

Mga opsyon sa pagbasa at pagsulat

Ang JSONSerialization ay nagbibigay ng ilang mga opsyon para sa pag-configure ng pag-parse. .mutableContainers ay nagbabalik ng NSMutableDictionary at NSMutableArray sa halip na mga hindi nababagong bersyon, na kapaki-pakinabang kapag binabago ang data pagkatapos ng pag-parse. .mutableLeaves ay ginagawang nababago ang mga halaga ng teksto. .fragmentsAllowed ay nagpapahintulot sa JSON na ang ugat ay hindi bagay o array, kundi isang string o numero — maginhawa para sa mga simpleng tugon ng API. Ang mga opsyon na .withoutEscapingSlashes at .sortedKeys ay available para sa pamamaraang data(withJSONObject:options:), na kumokontrol sa pag-format ng na-serialize na JSON. Ang mga opsyon ay ipinapadala sa pamamagitan ng bit mask, na nagpapahintulot sa pagsasama-sama ng maraming halaga sa pamamagitan ng operator | para sa nababaluktot na pag-configure ng pag-parse.

// Pangangasiwa ng iba't ibang uri ng error
func safeParse(jsonData: Data) {
    do {
        let object = try JSONSerialization
            .jsonObject(with: jsonData,
                           options: .fragmentsAllowed)

        if let dictionary = object as? [String: Any] {
            print("Diksyunaryo na may \(dictionary.count) na susi")
        } else if let array = object as? [Any] {
            print("Array na may \(array.count) na item")
        }

    } catch CocoaError.propertyListReadCorrupt {
        print("Sirang data ng JSON")
    } catch let error as CocoaError {
        print("Cocoa error: \(error)")
    } catch {
        print("Hindi kilalang error: \(error)")
    }
}

// Pagsusuri ng validity ng bagay bago ang serialization
let testObject: [String: Any] = ["key": "value", "nested": ["a": 1]]
if JSONSerialization.isValidJSONObject(testObject) {
    print("Wastong JSON object")
}

Ang pagganap ng JSONSerialization ay naiimpluwensyahan ng laki ng data at dalas ng mga tawag. Sa isang beses na pag-parse ng isang maliit na tugon ng server, ang pagkakaiba ay hindi napapansin, ngunit kapag nagpoproseso ng sampu-sampung megabyte ng JSON o madalas na mga tawag sa mga loop, kailangang isaalang-alang ang overhead ng conversion ng uri. Ang JSONSerialization ay gumagana nang synchronously sa kasalukuyang thread, kaya naman para sa malalaking dokumento ay inirerekomenda na ilipat ang pag-parse sa isang background queue sa pamamagitan ng DispatchQueue.global(). Bilang alternatibo, maaaring gamitin ang InputStream para sa stream processing nang hindi nilo-load ang buong file sa memorya, na kritikal para sa mga application na may limitadong mapagkukunan. Para sa pagsulat ng JSON sa isang file o network stream, ang pamamaraang writeJSONObject(_:to:options:error:) ay nagpapahintulot sa direktang pagruruta ng na-serialize na data sa OutputStream nang hindi lumilikha ng intermediate Data object, na nagbabawas ng konsumo ng memorya kapag nagtatrabaho sa malalaking dokumento.