SwiftyJSON لـ Swift: دليل شامل مع أمثلة تطبيقية

1. ما هي SwiftyJSON ولماذا تحتاجها؟

مكتبة SwiftyJSON هي مكتبة خفيفة الوزن للغة Swift، تُبسّط بشكل كبير التعامل مع بيانات JSON. في Swift التقليدي، يتطلب العمل مع JSON عبر JSONSerialization كتابة الكثير من الكود المتكرر: التحقق اليدوي من الأنواع، معالجة القيم الاختيارية (Optional)، وكتابة العديد من جمل if let أو guard let المتداخلة. هذا يجعل الكود ضخمًا، صعب القراءة، وعرضة للأخطاء.

تحل SwiftyJSON هذه المشكلة بتوفير واجهة برمجية أنيقة وآمنة. بدلاً من التعامل مع القواميس الخام [String: Any] والمصفوفات [Any]، تتعامل مع كائن JSON الذي يدعم التسلسل (chaining)، الاستخراج الآمن للقيم باستخدام صيغة الـ subscript، والتحويل التلقائي للأنواع. تتعامل المكتبة تلقائيًا مع القيم nil دون التسبب في تعطل التطبيق، وتوفر رسائل خطأ واضحة.

الهدف الأساسي من SwiftyJSON هو جعل الكود الذي يتعامل مع JSON نقيًا ومختصرًا مثل Swift نفسه. إنها مثالية للمشاريع التي تحتاج باستمرار إلى تحليل استجابات REST API، معالجة ملفات الإعدادات، أو العمل مع أي هياكل JSON أخرى. تدعم المكتبة بنشاط من قبل المجتمع، ولديها أكثر من 22,000 نجمة على GitHub، وتُستخدم في آلاف التطبيقات.

2. التثبيت

يتم توزيع SwiftyJSON عبر Swift Package Manager (SPM)، CocoaPods، و Carthage. الطريقة الموصى بها هي SPM، لأنه مدمج في Xcode.

عبر Swift Package Manager (موصى به)

1. في Xcode، افتح File → Add Packages...
2. أضف رابط المستودع: https://github.com/SwiftyJSON/SwiftyJSON.git
3. اختر الإصدار (يوصى بآخر إصدار مستقر، مثل 5.0.1)
4. اضغط Add Package

أو أضف إلى ملف Package.swift الخاص بمشروعك:

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "YourProject",
    dependencies: [
        .package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", from: "5.0.1")
    ],
    targets: [
        .target(name: "YourTarget", dependencies: ["SwiftyJSON"])
    ]
)

عبر CocoaPods

أضف إلى ملف Podfile:

pod 'SwiftyJSON', '~> 5.0'

ثم نفّذ الأمر pod install.

عبر Carthage

أضف إلى ملف Cartfile:

github "SwiftyJSON/SwiftyJSON" ~> 5.0

ثم نفّذ الأمر carthage update.

3. البداية السريعة — مثال عملي بسيط

بعد التثبيت، قم باستيراد المكتبة وأنشئ كائن JSON من نص أو بيانات:

import SwiftyJSON

// مثال على نص JSON
let jsonString = """
{
    "name": "أحمد",
    "age": 30,
    "isStudent": false,
    "address": {
        "city": "القاهرة",
        "zip": "11511"
    },
    "hobbies": ["القراءة", "السباحة", "البرمجة"]
}
"""

// تحويل النص إلى Data
guard let jsonData = jsonString.data(using: .utf8) else {
    fatalError("فشل تحويل النص إلى Data")
}

// إنشاء كائن JSON
let json = JSON(jsonData)

// استخراج القيم
let name = json["name"].stringValue      // "أحمد"
let age = json["age"].intValue           // 30
let isStudent = json["isStudent"].boolValue // false
let city = json["address"]["city"].stringValue // "القاهرة"
let firstHobby = json["hobbies"][0].stringValue // "القراءة"

print("الاسم: \(name)، العمر: \(age)، المدينة: \(city)")
print("الهواية الأولى: \(firstHobby)")

يوضح هذا المثال الفكرة الأساسية: الوصول إلى البيانات عبر صيغة الـ subscript واستخدام الخصائص مثل .string