حوّل JSON إلى Codable struct بلغة Swift!

أدخل JSON لتوليد كود Codable struct بلغة Swift بما في ذلك الكائنات المتداخلة! يدعم Codable, CodingKeys, JSONDecoder, iOS.
JSON
النتيجة
 

حوّل JSON إلى Codable struct بلغة Swift!

حوّل JSON إلى structs في Swift تتبنى Codable. تُعرَّف الخصائص بـ let ويُعاد تسميتها بصيغة camelCase، ولا يُولَّد enum باسم CodingKeys إلا للـ structs التي يختلف فيها اسم عن مفتاح JSON الخاص به.

استخدمه حين يحتاج تطبيق iOS أو macOS إلى نموذج لفك ترميز استجابة URLSession بـ JSONDecoder، أو حين تريد أنواعًا تطابق JSON الوهمي خلف معاينة SwiftUI.

طريقة الاستخدام

  1. الصق جسم استجابة من الـ API الخاص بك، مثلًا استجابة التقطتها بـ Proxyman أو Charles.
  2. اضبط اسم النوع على اسم الـ struct في المستوى الأعلى (مثلًا EpisodePage).
  3. الصق النتيجة في ملف Swift؛ وimport Foundation مضمَّن.
  4. فك الترميز بـ try JSONDecoder().decode(EpisodePage.self, from: data).

مثال

المدخلات (JSON)
{
  "podcast": "Swift Talk",
  "episodes": [
    { "id": 301, "title": "Async Sequences", "duration": 1840, "explicit": false },
    { "id": 302, "title": "Macros", "duration": 2215.5, "explicit": false, "guest_name": "Chris" }
  ],
  "total_count": 2
}
المخرجات (Swift · Codable)
import Foundation

struct EpisodePage: Codable {
    let podcast: String
    let episodes: [Episode]
    let totalCount: Int

    enum CodingKeys: String, CodingKey {
        case podcast
        case episodes
        case totalCount = "total_count"
    }
}

struct Episode: Codable {
    let id: Int
    let title: String
    let duration: Double
    let explicit: Bool
    let guestName: String?

    enum CodingKeys: String, CodingKey {
        case id
        case title
        case duration
        case explicit
        case guestName = "guest_name"
    }
}

عناصر المصفوفة episodes تصبح struct باسم Episode. يخلط duration بين عدد صحيح (1840) وعشري (2215.5)، فيكون Double؛ وguest_name، الموجود في الحلقة الثانية فقط، يكون guestName: String?. وأي struct فيه حقل معاد تسميته يحصل على enum CodingKeys يسرد كل مفاتيحه.

الميزات المدعومة

  • كل struct يتبنى Codable؛ والخصائص let غير قابلة للتغيير.
  • المفاتيح بصيغة snake_case وkebab-case تصبح خصائص camelCase، وعندها فقط يُضاف enum CodingKeys: String, CodingKey بالمفاتيح الأصلية.
  • الأنواع: String وInt وDouble وBool، و[T] للمصفوفات.
  • الحقول الغائبة في بعض العناصر أو التي تحوي null تكون Optionals (String?)، فتُفك المفاتيح الغائبة دون مشكلة.
  • القيم مختلطة الأنواع تستخدم enum مولَّدًا قابلًا لفك الترميز باسم JSONValue.
  • الكلمات المحجوزة في Swift مثل default أو class أو self تُحاط بعلامات backtick.
  • المصفوفة على المستوى الأعلى تُنتج typealias Root = [RootItem].

حالات الاستخدام

URLSession مع async/await

من استجابة نموذجية واحدة تحصل على نموذج يمكنك فك ترميزه في السطر الذي يلي let (data, _) = try await URLSession.shared.data(from: url) مباشرة.

شاشات القوائم في SwiftUI

أضف Identifiable إلى الـ struct المولَّد (حين يكون فيه حقل id) ومرّره مباشرة إلى List(page.episodes) { ... }.

بيانات وهمية مضمَّنة في التطبيق

ضمّن JSON النموذجي من مرحلة التصميم في حزمة التطبيق وفك ترميزه بالنموذج نفسه، فيمكن بناء الشاشات قبل أن يجهز الـ API الحقيقي.

ملاحظات وقيود

  • تخرج سلاسل التاريخ على شكل String. للحصول على Date، غيّر نوع الخاصية واضبط استراتيجية مثل decoder.dateDecodingStrategy = .iso8601.
  • إذا غاب من استجابةٍ مفتاحُ خاصية غير اختيارية، يرمي فك الترميز DecodingError.keyNotFound. أضف ? إلى الحقول التي قد يحذفها الـ API، حتى لو كانت موجودة دائمًا في عيّنتك.
  • كل الخصائص let؛ بدّلها إلى var في النماذج التي تعدّلها كحالة للعرض.
  • لا تُتبنى بروتوكولات إضافية مثل Identifiable أو Hashable.
  • الـ enum JSONValue كود مساعد للأنواع المختلطة؛ إن كان في مشروعك نوع مكافئ أصلًا، فاحذفه واستخدم نوعك.

الأسئلة الشائعة

مع keyDecodingStrategy = .convertFromSnakeCase، هل يمكنني حذف CodingKeys؟

نعم، فعندها يحوّل الـ decoder guest_name ↔ guestName نيابة عنك. لكن لا تجمع بين الاثنين: يحوّل الـ decoder المفاتيح إلى camelCase أولًا ثم يقارنها بالقيمة الخام "guest_name" في CodingKeys، فتفشل المطابقة.

لماذا structs لا classes؟

معاملة نماذج الاستجابة كأنواع قيمية هي الاصطلاح المعتاد في Swift، والـ structs تحصل على memberwise initializer مجانًا، ما يسهّل بناء بيانات الاختبار. إن احتجت إلى دلالات المرجع، فغيّرها إلى final class وأضف initializer.

حقل توقعت أن يكون عددًا صحيحًا خرج Double.

حين يحمل مفتاح أعدادًا صحيحة وعشرية معًا، يتجنب Double فقدان الدقة. وبالعكس، إن بدت كل قيم العيّنة مثل 4.0، فإن محلّل JSON في المتصفح يقرؤها كعدد صحيح وقد تحصل على Int، لذا تحقق من القيم الحقيقية للـ API.

هل يحتفظ الترميز إلى JSON مجددًا بالمفاتيح الأصلية؟

تُستخدم CodingKeys في الترميز أيضًا، فيكتب JSONEncoder guest_name مجددًا. والخصائص الاختيارية التي قيمتها nil تُحذف من الناتج.