Swift Academy · درس

ترميز المحتوى وJSON

فك ترميز أجسام الطلبات والاستجابات ورمّزها.

ترميز المحتوى وJSON درس مجاني في Swift Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Swift Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Swift Academy 4 دروس في المجموع.

بروتوكول Content

تتوافق النماذج التي تنتقل عبر HTTP مع Content. ويعتمد Content على Codable في Swift، ويضيف إمكانية فك ترميزها من أجسام الطلبات وترميزها في الاستجابات تلقائيًا.

import Vapor

struct Todo: Content {
    var id: Int?
    var title: String
    var done: Bool
}

ترميز الاستجابة بصيغة JSON

أعيدوا أي قيمة من نوع Content من أحد المعالجات، وسيحوّلها Vapor إلى JSON ويضبط لكم ترويسة Content-Type الصحيحة.

app.get("todo") { req -> Todo in
    Todo(id: 1, title: "Learn Vapor", done: false)
}

فك ترميز جسم الطلب

اقرؤوا حمولة محددة النوع من طلب وارد باستخدام req.content.decode(_:). يفحص Vapor قيمة Content-Type ويحلّل JSON (أو بيانات النموذج) وفقًا لذلك.

app.post("todo") { req -> Todo in
    let incoming = try req.content.decode(Todo.self)
    return incoming
}

المصفوفات بوصفها Content

تُرمَّز مجموعات أنواع Content تلقائيًا إلى مصفوفات JSON. أعيدوا [Todo] وسيتلقى العميل قائمة JSON.

app.get("todos") { req -> [Todo] in
    [Todo(id: 1, title: "A", done: false),
     Todo(id: 2, title: "B", done: true)]
}

مفاتيح الترميز المخصصة

بما أن Content يتوافق مع Codable، يمكنكم تعيين أسماء خصائص Swift إلى مفاتيح JSON مختلفة باستخدام CodingKeys، وهو أمر مفيد لواجهات API التي تستخدم snake_case.

struct User: Content {
    var firstName: String
    enum CodingKeys: String, CodingKey {
        case firstName = "first_name"
    }
}

ضبط مُرمّز JSON

يمكنكم ضبط استراتيجية ترميز عامة، مثل تحويل جميع المفاتيح إلى snake_case أو تنسيق التواريخ وفق ISO-8601، عبر ContentConfiguration.

let encoder = JSONEncoder()
encoder.keyEncodingStrategy = .convertToSnakeCase
encoder.dateEncodingStrategy = .iso8601
ContentConfiguration.global.use(encoder: encoder, for: .json)

التحقق من صحة المحتوى المُفكك ترميزه

يتيح بروتوكول Validatable في Vapor التصريح بقواعد التحقق. استدعوا try Todo.validate(content: req) قبل فك الترميز لرفض الإدخال غير الصالح مع خطأ 400 واضح.

extension Todo: Validatable {
    static func validations(_ v: inout Validations) {
        v.add("title", as: String.self, is: !.empty)
    }
}

استخدام التحقق في أحد المعالجات

تحققوا أولًا، ثم فكّوا الترميز. إذا فشل التحقق، يطرح Vapor الخطأ تلقائيًا ويتلقى العميل استجابة خطأ توضيحية.

app.post("todo") { req -> Todo in
    try Todo.validate(content: req)
    return try req.content.decode(Todo.self)
}

فصل DTOs الخاصة بالطلب والاستجابة

من الممارسات الجيدة الاحتفاظ بأنواع منفصلة للإدخال والإخراج. مثلًا، استخدموا CreateTodo بلا معرّف للطلبات، وTodo كاملًا للاستجابات. يفصل ذلك واجهة API عن النماذج الداخلية.

struct CreateTodo: Content {
    var title: String
}
struct TodoResponse: Content {
    var id: Int
    var title: String
}

ترميز سلاسل الاستعلام

تعمل آلية Content نفسها على فك ترميز سلاسل الاستعلام إلى بنية عبر req.query.decode(_:)، وهي مثالية لمعلمات التصفية وترقيم الصفحات.

struct Page: Content {
    var page: Int?
    var size: Int?
}
app.get("items") { req -> String in
    let p = try req.query.decode(Page.self)
    return "page=" + String(p.page ?? 1)
}

إرجاع حالة مخصصة مع Content

للتحكم في الجسم والحالة معًا، أنشئوا Response ورمّزوا المحتوى داخله، أو أعيدوا بنية شبيهة بالصف. يحدد المثال أدناه الحالة 201 Created مع جسم JSON.

app.post("todo") { req -> Response in
    let todo = try req.content.decode(Todo.self)
    let res = Response(status: .created)
    try res.content.encode(todo)
    return res
}

اختبار سريع: Content وJSON

اختبروا معرفتكم بالترميز.

مراجعة: ترميز Content وJSON

تعلّمتم كيفية انتقال البيانات عبر الشبكة في Vapor:

اجعلوا النماذج تتوافق مع Content (المبني على Codable).
أعيدوا المحتوى لترميز JSON؛ واستخدموا req.content.decode لقراءة الأجسام.
خصّصوا المفاتيح والتواريخ عبر CodingKeys وContentConfiguration.
تحققوا من صحة الإدخال باستخدام Validatable، وفكّروا في فصل DTOs الخاصة بالطلب والاستجابة.

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

هل درس «ترميز المحتوى وJSON» مجاني؟

نعم — نص درس «ترميز المحتوى وJSON» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Swift Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Swift Academy 4 دروس في المجموع.

ماذا ستتعلم في «ترميز المحتوى وJSON»؟

فك ترميز أجسام الطلبات والاستجابات ورمّزها. تتمرن على Swift Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Swift Academy؟

لا تُشترط خبرة سابقة. Swift Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «ترميز المحتوى وJSON»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Swift Academy هذا؟

نعم. كل درس في Swift Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Swift Academy