Ruby Academy · درس

واجهات JSON البرمجية

إرجاع JSON

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

لماذا نستخدم واجهات JSON؟

يُعد JSON تنسيق البيانات القياسي لواجهات API على الويب. يرسل العملاء البيانات المنظّمة ويستقبلونها بدلًا من HTML.

مستقل عن اللغة
يتوافق بسهولة مع Hash والمصفوفات في Ruby
خفيف وسهل القراءة للبشر

تتعامل المكتبة القياسية في Ruby مع JSON عبر الوحدة json.

require 'json'

data = { name: 'Ada', langs: ['Ruby', 'Python'] }
puts data.to_json

تحويل Ruby إلى JSON

استدعوا to_json على Hash أو مصفوفة، أو استخدموا JSON.generate.

تتحول الرموز والسلاسل إلى مفاتيح JSON
تُحوّل البنى المتداخلة بصورة递归ية

require 'json'

user = { id: 1, active: true, tags: ['admin'] }
puts JSON.generate(user)

تنسيق JSON بصورة واضحة

لإخراج سهل القراءة، استخدموا JSON.pretty_generate.

يضيف المسافات البادئة والأسطر الجديدة
مفيد جدًا لتصحيح الأخطاء والسجلات
تجنّبوه في استجابات الإنتاج لتوفير البايتات

require 'json'

config = { server: { host: 'localhost', port: 4567 } }
puts JSON.pretty_generate(config)

تحليل إدخال JSON

استخدموا JSON.parse لتحويل سلسلة JSON الواردة إلى كائنات Ruby.

تكون المفاتيح سلاسل نصية افتراضيًا
مرّروا symbolize_names: true لاستخدام مفاتيح الرموز

require 'json'

raw = '{"name": "Ada", "age": 30}'
data = JSON.parse(raw)
puts data['name']
puts data['age']

المفاتيح المحوّلة إلى رموز

تتميّز مفاتيح الرموز بسهولة الاستخدام، كما أن البحث عنها أسرع قليلًا.

فعّلوها باستخدام symbolize_names: true
انتبهوا إلى أن الإدخال غير الموثوق قد ينشئ عددًا كبيرًا من الرموز

require 'json'

raw = '{"city": "Istanbul"}'
data = JSON.parse(raw, symbolize_names: true)
puts data[:city]

إرجاع JSON من Sinatra

في مسار Sinatra، حدّد نوع المحتوى وأرجع سلسلة JSON.

content_type :json يضبط الترويسة
أرجع hash.to_json باعتباره النص الأساسي للاستجابة

require 'sinatra'
require 'json'

get '/api/status' do
  content_type :json
  { status: 'ok', time: Time.now.to_i }.to_json
end

قراءة نص طلب JSON

بالنسبة إلى واجهات POST البرمجية، اقرأ النص الخام ثم حلّله.

يعطيك request.body.read السلسلة الخام
حلّلها باستخدام JSON.parse

require 'sinatra'
require 'json'

post '/api/users' do
  payload = JSON.parse(request.body.read)
  content_type :json
  { created: payload['name'] }.to_json
end

إنشاء Hash لاستجابة API

حافظ على اتساق الاستجابات بإنشاء Hash منظّم قبل إجراء التسلسل.

ضع البيانات تحت مفتاح data
ضمّن الحالة والبيانات الوصفية

require 'json'

def api_response(data, status: 'ok')
  { status: status, data: data }.to_json
end

puts api_response({ id: 1, name: 'Ada' })

معالجة أخطاء التحليل

يؤدي JSON غير الصحيح إلى رفع JSON::ParserError. احرص دائمًا على اعتراضه.

أرجع حالة 400 Bad Request إلى العميل
لا تسمح أبدًا لخطأ التحليل بالتسبب في تعطل التطبيق

require 'json'

begin
  JSON.parse('{ broken')
rescue JSON::ParserError => e
  puts "Invalid JSON: #{e.message}"
end

إجراء التسلسل لمصفوفات الكائنات

تتحول المجموعات بصورة طبيعية إلى مصفوفات JSON.

تتحول مصفوفة من Hash إلى مصفوفة من الكائنات
استخدم map لتشكيل كل سجل

require 'json'

users = [{ id: 1, name: 'Ada' }, { id: 2, name: 'Bob' }]
output = users.map { |u| { name: u[:name] } }
puts output.to_json

تخصيص to_json للكائنات

يمكنك تعليم فئة كيفية إجراء التسلسل من خلال تعريف to_json أو as_json.

حوّل الحالة الداخلية إلى Hash عادي
أخفِ الحقول الخاصة عن API

require 'json'

class User
  def initialize(id, name)
    @id = id
    @name = name
  end

  def to_json(*)
    { id: @id, name: @name }.to_json
  end
end

puts User.new(1, 'Ada').to_json

تحقق سريع

تأكد من معرفتك بواجهات JSON البرمجية.

مراجعة

لقد تعلمت كيفية إنشاء واجهات JSON البرمجية:

استدعاء require 'json' من المكتبة القياسية
يُجري to_json / JSON.generate تسلسل Ruby إلى JSON
يفك JSON.parse تسلسل JSON الوارد
اضبط content_type :json في مسارات Sinatra
اعترض JSON::ParserError دائمًا

ستستكشف بعد ذلك Rack والبرمجيات الوسيطة.

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

هل درس «واجهات JSON البرمجية» مجاني؟

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

ماذا ستتعلم في «واجهات JSON البرمجية»؟

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

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

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

كم من الوقت يستغرق درس «واجهات JSON البرمجية»؟

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

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

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

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

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