{"id":"l-sw-4-2","courseId":"swift-essentials","lang":"ar","kind":"lesson","summary":"اجلب JSON عبر الـ API غير المتزامن في URLSession، وافحص حالة HTTP، وفكّ ترميزه إلى structs من نوع Codable، واعرض حالات التحميل والنجاح والفشل في SwiftUI.","html":"

يسجّل Pocket Budget المصاريف بالدولار، لكنك تنفق في إجازتك باليورو والجنيه المصري. وللتحويل، يحتاج التطبيق إلى أسعار الصرف لهذا اليوم من خادم. يستبدل هذا الدرس Task.sleep التمثيلية من الدرس السابق بطلب حقيقي: ابنِ URL، واجلب البيانات، وافحص الاستجابة، وفكّ ترميز الـ JSON إلى أنواع Swift، ثم اعرضها. هذه الخطوات هي نفسها مع معظم الـ APIs التي ستستدعيها في حياتك.

\n

تستخدم الأمثلة endpoint بديلًا، https://api.example.com/v1/latest?base=USD. ضع مكانه مزوّدًا حقيقيًا لأسعار الصرف (لمعظمهم باقة مجانية) وعدّل الـ struct ليطابق الـ JSON الخاص به. تبدو الاستجابة هكذا:

\n
JSON
{\n  \"base\": \"USD\",\n  \"updated_at\": \"2026-10-02T06:00:00Z\",\n  \"rates\": { \"EUR\": 0.92, \"GBP\": 0.79, \"EGP\": 48.31 }\n}
\n

اعكس شكل الـ JSON باستخدام Codable

\n
RatesResponse.swift
import Foundation\n\nstruct RatesResponse: Decodable {\n    let base: String\n    let updatedAt: Date\n    let rates: [String: Decimal]\n}
\n

يطلب Decodable من الـ compiler أن يولّد الكود الذي يقرأ هذا النوع من صيغة خارجية. يجب أن تطابق أسماء الخصائص مفاتيح الـ JSON وأن تناسب الأنواع: كائن JSON يصبح قاموسًا، والرقم يمكن فكّ ترميزه إلى Decimal، والمفتاح الغائب أو النوع الخاطئ يرمي DecodingError يسمّي المشكلة. استخدم Codable (أي Decodable مع Encodable) حين ترسل النوع أيضًا. والـ struct مبني من أجزاء Sendable، فهو Sendable أيضًا ويستطيع الانتقال بأمان من كود الشبكة إلى الـ main actor.

\n

الـ JSON يقول updated_at، وأسلوب Swift يقول updatedAt. بدل إعادة تسمية الخصائص، اضبط الـ decoder، كما يفعل العميل أدناه.

\n

اجلب، افحص، فكّ الترميز

\n
RateClient.swift
enum RateError: Error {\n    case badStatus(Int)\n}\n\nstruct RateClient {\n    let endpoint = URL(string: \"https://api.example.com/v1/latest\")!\n\n    func latest(base: String) async throws -> RatesResponse {\n        let url = endpoint.appending(queryItems: [URLQueryItem(name: \"base\", value: base)])\n\n        let (data, response) = try await URLSession.shared.data(from: url)\n\n        let status = (response as? HTTPURLResponse)?.statusCode ?? 0\n        guard status == 200 else {\n            throw RateError.badStatus(status)\n        }\n\n        let decoder = JSONDecoder()\n        decoder.keyDecodingStrategy = .convertFromSnakeCase\n        decoder.dateDecodingStrategy = .iso8601\n        return try decoder.decode(RatesResponse.self, from: data)\n    }\n}
\n

امشِ عليه بالترتيب. تبني appending(queryItems:) العنوان ...latest?base=USD وتطبّق الـ percent-encoding على القيم تلقائيًا، وهذا أكثر أمانًا من لصق النصوص ببعضها. والفكّ القسري على URL(string:) من النوع المقبول الذي رأيته في درس الـ optionals: قيمة كتبتها بنفسك، تعني nil فيها خطأً إملائيًا.

\n

URLSession.shared.data(from:) هو الـ API غير المتزامن: يعلّق التنفيذ حتى تصل الاستجابة كاملة، ويعيد بايتات الجسم مع URLResponse. يرمي خطأً عند فشل النقل، مثل انعدام الاتصال أو انتهاء المهلة أو الإلغاء، لكنه لا يرمي عند أخطاء HTTP. ولهذا وُجدت جملة guard.

\n

يربط .convertFromSnakeCase المفتاح updated_at بـ updatedAt لكل المفاتيح، ويقرأ .iso8601 صيغة الطابع الزمني التي تستخدمها معظم الـ APIs. ثم إما أن تعيد decode كائن RatesResponse مكتمل البناء أو ترمي خطأً.

\n
\n خمس خطوات من اليسار إلى اليمين: ابنِ الـ URL، واجلب باستخدام data(from:)، وافحص رمز الحالة، وفكّ ترميز الـ JSON إلى RatesResponse، ثم اضبط الـ state على الـ main actor فيتحدّث الـ view.\n \n ابنِ الـ URL\n query items\n \n \n اجلب\n data(from:)\n \n \n افحص\n الحالة 200\n \n \n فكّ الترميز\n JSONDecoder\n \n \n اعرض\n main actor\n أي خطوة قد ترمي خطأً؛ وcatch واحدة في النموذج تحوّله إلى حالة الفشل\n
من الـ URL إلى البكسلات
\n\n

وليست كل حالات الفشل تستحق الرسالة نفسها. فالـ URLError الذي يُرمى يحمل code، فتستطيع التمييز بين «غير متصل» (.notConnectedToInternet) و«انتهت المهلة» (.timedOut)، وتقول “You’re offline. Rates will refresh when you reconnect” بدل اعتذار عام. المستخدمون يسامحون التطبيق الذي يشرح نفسه.

\n

حالات تحميل يثق بها الـ view

\n

فكرة الـ enum من درس الـ enums تؤتي ثمارها الآن. نموذج على الـ main actor يملك الـ state، والـ view يكتب switch عليها:

\n
RatesModel.swift
@MainActor\n@Observable\nfinal class RatesModel {\n    enum LoadState {\n        case idle\n        case loading\n        case loaded(RatesResponse)\n        case failed(String)\n    }\n\n    var state: LoadState = .idle\n    private let client = RateClient()\n\n    func load() async {\n        state = .loading\n        do {\n            let response = try await client.latest(base: \"USD\")\n            state = .loaded(response)\n        } catch {\n            state = .failed(error.localizedDescription)\n        }\n    }\n}
\n
RatesView.swift
struct RatesView: View {\n    @State private var model = RatesModel()\n\n    var body: some View {\n        List {\n            switch model.state {\n            case .idle, .loading:\n                ProgressView()\n            case .loaded(let response):\n                ForEach(response.rates.keys.sorted(), id: \\.self) { code in\n                    LabeledContent(code, value: response.rates[code] ?? 0,\n                                   format: .number.precision(.fractionLength(2...4)))\n                }\n            case .failed(let message):\n                ContentUnavailableView(\"Couldn't load rates\",\n                                       systemImage: \"wifi.exclamationmark\",\n                                       description: Text(message))\n            }\n        }\n        .navigationTitle(\"Exchange Rates\")\n        .task { await model.load() }\n        .refreshable { await model.load() }\n    }\n}
\n

تحمّل .task البيانات مرة واحدة حين تظهر الشاشة، ويضيف .refreshable السحب للتحديث بالدالة نفسها. ولأن RatesModel معلّم بـ @MainActor، يكون إسناد state آمنًا دائمًا للواجهة، وتتحقّق Swift 6 من ذلك عنك. وكل مسار خطأ ينتهي في .failed، فلا يحدّق المستخدم أبدًا في مؤشّر تحميل لن يتوقّف. ومفاتيح القاموس لا ترتيب لها، فيرتّبها الـ view ليحصل على قائمة ثابتة.

\n\n

يشترط iOS أيضًا HTTPS افتراضيًا عبر App Transport Security، فيفشل الـ URL الذي يبدأ بـ http:// العادي ما لم تُضِف استثناءً. استخدم HTTPS ولن تحتاج إلى استثناء أبدًا.

\n

صار Pocket Budget قادرًا على التحدّث مع العالم الخارجي. لكنه ما زال ينسى مصاريفه حين تغلقه، لذلك ستحفظها بعد ذلك على الجهاز باستخدام SwiftData.

\n","toc":[{"id":"sec-1","text":"اعكس شكل الـ JSON باستخدام Codable","level":2},{"id":"sec-2","text":"اجلب، افحص، فكّ الترميز","level":2},{"id":"sec-3","text":"حالات تحميل يثق بها الـ view","level":2}],"takeaways":["try await URLSession.shared.data(from: url) يعيد جسم الاستجابة والاستجابة نفسها؛ ويرمي خطأً عند فشل الشبكة، لكن ليس عند أخطاء HTTP مثل 404 أو 500.","افحص دائمًا رمز الحالة في HTTPURLResponse قبل فكّ الترميز، وحوّل الحالة السيئة إلى خطأ خاص بك.","اعكس شكل الـ JSON في structs من نوع Decodable؛ وkeyDecodingStrategy وdateDecodingStrategy يتعاملان مع المفاتيح بصيغة snake_case والتواريخ بصيغة ISO 8601.","صِف دورة حياة الشاشة كـ enum اسمه LoadState، فلا يمكن أبدًا عرض التحميل والبيانات والأخطاء في الوقت نفسه."],"further":[{"title":"Fetching website data into memory","url":"https://developer.apple.com/documentation/foundation/fetching-website-data-into-memory"},{"title":"Encoding and Decoding Custom Types","url":"https://developer.apple.com/documentation/foundation/encoding-and-decoding-custom-types"},{"title":"URLSession","url":"https://developer.apple.com/documentation/foundation/urlsession"}],"quiz":[{"q":"

يجيب الخادم على طلب بالحالة HTTP 500 وصفحة خطأ بصيغة HTML. ماذا يفعل try await URLSession.shared.data(from: url)؟

","options":[{"text":"يرمي URLError يحمل رمز الحالة.","why":"لا يرمي URLSession خطأً إلا حين يتعذّر إكمال الطلب. والحالة 500 استجابة مكتملة."},{"text":"يعيد الـ HTML على أنه data واستجابة قيمة statusCode فيها 500.","why":"صحيح. لهذا تفحص الحالة بنفسك قبل فكّ الترميز."},{"text":"يعيد المحاولة تلقائيًا حتى يحصل على 200.","why":"لا يعيد URLSession المحاولة عند أخطاء HTTP؛ سياسة إعادة المحاولة متروكة لك."}],"answer":1},{"q":"

في الـ JSON مفتاح اسمه updated_at، وفي الـ struct الخاص بك let updatedAt: Date. يفشل فكّ الترميز مع keyNotFound. ما أصغر إصلاح؟

","options":[{"text":"أعد تسمية الخاصية إلى updated_at.","why":"يعمل، لكنه يجرّ أسلوب التسمية الخاص بالخادم إلى كود Swift الخاص بك."},{"text":"اجعل الخاصية optional: let updatedAt: Date?.","why":"يختفي الخطأ، لكن التاريخ يصبح nil دائمًا لأن المفتاح ما زال لا يتطابق."},{"text":"اضبط decoder.keyDecodingStrategy = .convertFromSnakeCase.","why":"صحيح. يربط الـ decoder المفتاح updated_at بـ updatedAt لكل المفاتيح، فتبقى أسماؤك في Swift على أسلوبها المعتاد."}],"answer":2},{"q":"

لماذا تستخدم شاشة الأسعار enum واحدًا اسمه LoadState بدل الخصائص isLoading وrates وerrorMessage؟

","options":[{"text":"الخصائص المنفصلة تسمح بتركيبات مستحيلة، مثل التحميل والفشل معًا؛ أما الـ enum فيسمح بحالة واحدة بالضبط.","why":"صحيح. يكتب الـ view جملة switch على الـ enum ويعالج كل حالة مرة واحدة بالضبط."},{"text":"لا يستطيع SwiftUI مراقبة أكثر من خاصية واحدة في كل class.","why":"يتتبّع Observation كل خاصية يقرؤها الـ body؛ ليس هذا هو السبب."},{"text":"الـ enums تجعل طلبات الشبكة أسرع.","why":"الـ enum يغيّر طريقة وصف الـ state، لا سرعة تنفيذ الطلب."}],"answer":0}],"exercise":{"kind":"order","items":["start-task","set-loading","build-url","fetch","check-status","decode","set-loaded"],"title":"من ظهور الشاشة إلى الأسعار على الشاشة","prompt":"

رتّب خطوات شاشة أسعار الصرف في Pocket Budget بالترتيب الذي تحدث به وقت التشغيل، من لحظة ظهور الشاشة إلى لحظة ظهور الأسعار.

\n","hints":["لا شيء يحدث حتى يبدأ SwiftUI العمل غير المتزامن، ويجب أن يرى المستخدم مؤشّر تحميل قبل أن يبدأ أي استدعاء للشبكة.","لا يمكنك الجلب قبل أن يكون لديك URL، ولا يجب أن تفكّ الترميز قبل أن تعرف أن الاستجابة ناجحة.","الخطوة الأخيرة هي التي تجعل SwiftUI يعيد الرسم."],"explanation":"

تبدأ .task الدالة model.load() حين يظهر الـ view. يضبط النموذج .loading أولًا فيظهر مؤشّر التحميل فورًا. يبني العميل الـ URL مع الـ query items، ثم يعلّق URLSession.shared.data(from:) التنفيذ حتى تصل الاستجابة. يأتي فحص الحالة قبل فكّ الترميز، لأن URLSession لا يرمي خطأً عند 404 أو 500، وصفحة الخطأ ستفشل في فكّ الترميز برسالة مضلّلة. ينتج فكّ الترميز RatesResponse، وإسناد .loaded(response) على الـ main actor هو ما يجعل SwiftUI يعيد رسم القائمة.

\n

إن رمت أي خطوة بعد set-loading خطأً، تضبط catch الوحيدة في النموذج الحالة .failed(message) بدلًا من ذلك.

\n","checkLabels":{},"itemText":{"start-task":"ينفّذ SwiftUI ‏.task { await model.load() } عند ظهور الـ view","set-loading":"يضبط النموذج state = .loading، فيعرض الـ view ‏ProgressView","build-url":"ابنِ الـ URL: endpoint.appending(queryItems: [URLQueryItem(name: "base", value: "USD")])","fetch":"let (data, response) = try await URLSession.shared.data(from: url)","check-status":"افحص (response as? HTTPURLResponse)?.statusCode == 200، وإلا فارمِ RateError.badStatus","decode":"try decoder.decode(RatesResponse.self, from: data) مع استراتيجيتَي snake_case وISO 8601","set-loaded":"أسند state = .loaded(response) على الـ main actor، فيعيد SwiftUI رسم القائمة"}},"words":635,"readMinutes":4}