Rails/api app

استعمال ريلز في التطبيقات التي تعتمد على الواجهة البرمجية فقط

في هذا الدليل ستتعلم:

ما تقدمه ريلز للتطبيقات ذات الواجهة البرمجية فقط.
كيفية ضبط ريلز للبدء دون أي ميزات للمتصفح.
كيفية تحديد البرامج الوسيطة (middleware) التي تريد تضمينها.
كيفية تحديد الوحدات لاستخدامها في وحدة التحكم الخاصة بك.

ما الذي يعنيه «تطبيق ذو واجهة برمجية فقط»؟

تقليديًا، عندما قال الناس أنهم استخدموا ريلز كـ "واجهة برمجية"، فقد كان يعني توفير واجهة برمجية يمكن الوصول إليها برمجيًا جنبًا إلى جنب مع تطبيق الويب الخاص بهم. على سبيل المثال، يوفر GitHub واجهة برمجية يمكنك استخدامها من العملاء المخصصين.

مع ظهور إطارات العمل من جانب العميل، يستخدم المزيد من المطورين ريلز لإنشاء واجهة خلفية مشتركة بين تطبيقات الويب والتطبيقات المحلية الأخرى.

على سبيل المثال، يستخدم Twitter واجهة برمجة التطبيقات العامة في تطبيق الويب الخاص به، والذي أنشئت كموقع ثابت يستهلك موارد JSON.

بدلًا من استخدام ريلز لإنشاء لغة HTML تتواصل مع الخادم من خلال النماذج والروابط، يعالج العديد من المطورين تطبيقات الويب الخاصة بهم على أنها مجرد عميل واجهة برمجة تطبيقات تُسلَّم بتنسيق HTML مع JavaScript ويستهلك واجهة برمجة تطبيقات JSON.

يغطي هذا الدليل بناء تطبيق ريلز يخدم موارد JSON إلى عميل واجهة برمجة التطبيقات، بما في ذلك أطر عمل العميل.

لماذا تستخدم ريلز لواجهة برمجة تطبيقات JSON؟

السؤال الأول الذي يفكر فيه الكثير من الأشخاص عند التفكير في إنشاء واجهة برمجة تطبيقات JSON باستخدام ريلز هو: "أليس استخدام ريلز لاستخراج بعض JSON أمر مبالغ فيه بشدة؟ ألا يجب فقط أن أستخدم شيئًا مثل Sinatra؟".

لواجهة برمجة تطبيقات بسيطة للغاية، قد يكون هذا صحيحًا. ومع ذلك، فحتى في تطبيقات HTML الضخمة، فإن معظم شيفرة التطبيق تقع خارج طبقة الواجهة.

السبب في أن معظم الناس يستخدمون ريلز هو أنه يوفر مجموعة من الافتراضات التي تسمح للمطورين تسرع وتيرة العمل، دون الحاجة إلى اتخاذ الكثير من القرارات التافهة.

لنلقِ نظرة على بعض الأشياء غير التقليدية التي توفرها ريلز والتي لا تزال سارية على تطبيقات واجهة برمجة التطبيقات.

التعامل مع الطبقة الوسيطة:

إعادة التحميل: تدعم تطبيقات ريلز إعادة التحميل الشفاف. هذا يعمل حتى إذا أصبح التطبيق الخاص بك كبيرًا وإعادة تشغيل الخادم لكل طلب تصبح عملية غير قابل للتطبيق.
وضع التطوير: تأتي تطبيقات ريلز مع الافتراضات الذكية للتطوير، مما يجعل التطوير مسليًا دون المساس بأداء وقت الإنتاج.
وضع الإختبار: يشبه وضع التطوير.
التسجيل: تسجل تطبيقات ريلز كل طلب، مع مستوى من التفصيل والإسهاب المناسب للوضع الحالي. تتضمن سجلات ريلز قيد التطوير معلومات حول بيئة الطلب و استعلامات قاعدة البيانات ومعلومات الأداء الأساسية.
الأمن: يكتشف ريلز هجمات انتحال IP ويعطلها ويتعامل مع توقيعات التشفير بطريقة حذرة من حدوث هجوم التوقيت. لا تعرف ما هو هجوم انتحال IP أو هجوم التوقيت؟ حسنًا.
تحليل المعامل: هل تريد تحديد المعاملات على أنها JSON بدلًا من أنها سلسلة مشفرة لعناوين URL؟ ليس هناك أى مشكلة. ستعمل ريلز على فك شفرة JSON وجعلها متوفرة في params. هل ترغب في استخدام المعاملات المتداخلة لعناوين URL المتداخلة؟ هذا يعمل أيضًا.
طلبات GET المشروطة: يعالج ريلز طلبات GET المشروطة (ETag و Last-Modified) وإرجاع عبر معالجة ترويسات الطلب وإعادة ترويسات الرد المناسب ورمز الحالة. كل ما عليك القيام به هو استخدام ?stale الذي يتحقق من وحدة التحكم، وسيتولى ريلز جميع تفاصيل HTTP نيابة عنك.
طلبات HEAD: ستحول ريلز طلبات HEAD إلى GET، وتعيد الترويسات فقط إلى المخرج. هذا يجعل HEAD يعمل بشكل موثوق في جميع واجهات برمجة التطبيقات ريلز.

على الرغم من أنه يمكنك بناء هذه البرامج من خلال البرامج الوسيطة من Rack الموجودة حاليًا، توضح هذه القائمة أن حزمة البرامج الوسيطة ريلز الافتراضية توفر الكثير من القيمة، حتى إذا كنت "تقوم فقط بإنشاء JSON".

يتعامل مع طبقة الإجراء Pack:

توجيه الموارد: إذا كنت تقوم بإنشاء واجهة برمجة تطبيقات JSON RESTful، فستحتاج إلى استخدام جهاز التوجيه ريلز. تعني الخرائط النظيفة والتقليدية من HTTP إلى وحدات التحكم عدم الحاجة إلى قضاء بعض الوقت في التفكير في كيفية تصميم واجهة برمجة التطبيقات الخاصة بك من حيث HTTP.
إنشاء عنوان URL: الجانب الآخر للتوجيه هو إنشاء عنوان URL. تتضمن واجهة برمجة التطبيقات الجيدة المستندة إلى HTTP عناوين URL (راجع واجهة برمجة تطبيقات GitHub Gist على سبيل المثال).
ردود راس الصفحة وإعادة التوجيه: head :no_content و(redirect_to user_url(current_user تأتي في متناول اليدين. بالتأكيد، يمكنك إضافة رد رؤوس الصفحة يدويًا، ولكن لماذا؟
التخزين المؤقت: يوفر ريلز الصفحة، والتخزين المؤقت للإجراء والتجزئة. يكون التخزين المؤقت للشفرة مفيدًا بشكل خاص عند إنشاء كائن JSON متداخل.
استيثاق Basic و Digest و Token: تأتي ريلز مع دعم خارج الصندوق لثلاثة أنواع من استيثاق HTTP.
الأجهزة: يحتوي ريلز على واجهة برمجة تطبيقات للأجهزة تعمل على تشغيل معالجات مسجلة لمجموعة متنوعة من الأحداث، مثل معالجة الإجراءات، وإرسال ملف أو بيانات، وإعادة توجيه، و استعلامات قاعدة البيانات. تأتي حمولة كل حدث مع المعلومات ذات الصلة (لحدث معالجة الإجراءات، تتضمن الحمولة وحدة التحكم، الإجراء، المعاملات، نسق الطلب، طريقة الطلب والمسار الكامل للطلب).
المولدات: غالبا ما تكون مفيدة لتوليد مورد والحصول على النموذج الخاص بك، وحدة التحكم، وحزم اختبار، والمسارات التي أُنشئت لك في أمر واحد لمزيد من التغيير والتبديل. نفس الهجرات وغيرها.
المكونات الإضافية: تأتي العديد من مكتبات الجهات الخارجية مع دعم ريلز التي تقلل أو تقضي على تكلفة إعداد ولصق المكتبة وإطار الويب. يتضمن ذلك أشياء مثل إلغاء المولدات الافتراضية وإضافة مهام Rake وتكريم اختيارات ريلز (مثل التسجيل وذاكرة التخزين المؤقت الخلفية).

وبطبيعة الحال، فإن عملية التمهيد ريلز تجمع جميع المكونات المسجلة. على سبيل المثال، عملية التمهيد ريلز هي ما يستخدم ملف config / database.yml الخاص بك عند تكوين Active Record.

الإصدار المختصر هو: قد لا تكون قد فكرت في أي أجزاء من ريلز لا تزال قابلة للتطبيق حتى إذا قمت بإزالة طبقة الواجهة، ولكن الإجابة تبين أنها أكثر من ذلك.

التكوين الأساسي

إذا كنت بصدد إنشاء تطبيق ريلز سيكون خادم API أولاً وقبل كل شيء، فيمكنك البدء بمجموعة فرعية أكثر تحديدًا من ريلز وإضافة ميزات حسب الحاجة.

إنشاء تطبيق جديد

يمكنك إنشاء تطبيق api ريلز جديد:

$ ريلز new my_api --api

هذا سيفعل ثلاثة أمور أساسية بالنسبة لك:

قم بتكوين التطبيق الخاص بك لتبدأ بمجموعة محدودة من البرامج الوسيطة أكثر من المعتاد. وبالتحديد، لن تتضمن أي برامج وسيطة مفيدة بشكل أساسي لتطبيقات المستعرض (مثل دعم ملفات تعريف الارتباط) بشكل افتراضي.
جعل ApplicationController ترث من ActionController :: API بدلاً من ActionController :: Base. كما هو الحال مع البرامج الوسيطة ، سيؤدي هذا إلى إهمال أي وحدات تحكم في الإجراء تعمل على توفير وظائف تستخدم بشكل رئيسي من قبل تطبيقات المستعرض.
قم بتكوين المولدات لتخطي إنشاء الواجهات والمساعدات والممتلكات عند إنشاء مورد جديد.

تغيير تطبيق موجود

إذا كنت تريد أن تأخذ تطبيقًا موجودًا وجعله أحد تطبيقات واجهة برمجة التطبيقات، فاطلع على الخطوات التالية.

في config / application.rb أضف السطر التالي في أعلى تعريف فئة التطبيق:

config.api_only = true

في config / environments / development.rb، اضبط config.debug_exception_response_format لتهيئة التنسيق المستخدم في الإستجابة عند حدوث أخطاء في وضع التطوير.

لعرض صفحة HTML تحتوي على معلومات تصحيح الأخطاء، استخدم القيمة :default.

config.debug_exception_response_format = :default

لتقديم معلومات التصحيح التي تحتفظ بتنسيق الاستجابة، استخدم القيمة :api.

config.debug_exception_response_format = :api

بشكل افتراضي، يتعين config.debug_exception_response_format على :api، عند تعيين config.api_only على true.

أخيرًا، داخل app/controllers/application_controller.rb، بدلاً من:

class ApplicationController < ActionController::Base

End

افعل:

class ApplicationController < ActionController::API

End

اختيار البرامج الوسيطة

يأتي تطبيق API مع الوسيطة التالية افتراضيًا:

Rack::Sendfile
ActionDispatch::Static
ActionDispatch::Executor
ActiveSupport::Cache::Strategy::LocalCache::Middleware
Rack::Runtime
ActionDispatch::RequestId
ActionDispatch::RemoteIp
ريلز::Rack::Logger
ActionDispatch::ShowExceptions
ActionDispatch::DebugExceptions
ActionDispatch::Reloader
ActionDispatch::Callbacks
ActiveRecord::Migration::CheckPending
Rack::Head
Rack::ConditionalGet
Rack::ETag

انظر قسم البرامج الوسيطة الداخلية من دليل الحامل لمزيد من المعلومات عنهم.

قد تضيف الإضافات الأخرى، بما في ذلك Active Record، برامج وسيطة إضافية. بشكل عام، تكون هذه البرامج الوسيطة ملزمة لنوع التطبيق الذي تبنيه، ولها معنى في تطبيق ريلز فقط API.

يمكنك الحصول على قائمة بجميع البرامج الوسيطة في تطبيقك عبر:

$ ريلز middleware

استخدام التخزين المؤقت للبرامج الوسيطة

بشكل افتراضي، سيضيف ريلز وسيطًا يوفر مخزنًا مؤقتًا يستند إلى تكوين التطبيق الخاص بك (ذاكرة التخزين المؤقت بشكل افتراضي). هذا يعني أن ذاكرة التخزين المؤقت HTTP المضمنة ستعتمد عليه.

على سبيل المثال، باستخدام التابع stale؟:

def show

@post = Post.find(params[:id])

if stale?(last_modified: @post.updated_at)

render json: @post

end

End

استدعاء إلى stale؟ و يقارن رأس الصفحة If-Modified-Since في الطلب مع @ post.updated_at. إذا كان رأس الصفحة أحدث من التعديل الأخير، يعرض هذا الإجراء استجابة "304 غير معدلة". بخلاف ذلك، سيعرض الاستجابة و تضمن في رأس الصفحة Last-Modified.

عادة، تستخدم هذه الآلية على أساس كل عميل. تتيح لنا الوسيطة مشاركة آلية التخزين المؤقت هذه عبر العملاء. يمكننا تمكين التخزين المؤقت عبر العميل في استدعاء إلى stale؟:

def show

@post = Post.find(params[:id])

if stale?(last_modified: @post.updated_at, public: true)

render json: @post

end

End

وهذا يعني أن ذاكرة وسيطة التخزين المؤقت تخزن القيمة Last-Modified لعنوان URL في ذاكرة التخزين المؤقت ريلز، وإضافة عنوان If-Modified-Since إلى أي طلبات واردة لاحقة لنفس عنوان URL.

فكر في ذلك كتخزين مؤقت للصفحة باستخدام دلالات HTTP.

استخدام Rack::Sendfile

عند استخدام التابع send_file داخل وحدة تحكم ريلز، يعين رأس الصفحة X-Sendfile

Rack :: Sendfile مسؤولة عن إرسال الملف بالفعل.

إذا كان خادم الواجهة الأمامية يدعم إرسال الملفات المتسارعة ، سيلغي Rack :: Sendfile تحميل الملف الفعلي الذي يرسل العمل إلى الخادم الأمامي.

يمكنك تكوين اسم رأس الصفحة التي يستخدمها خادم الواجهة الأمامية لهذا الغرض باستخدام config.action_dispatch.x_sendfile_header في ملف تكوين البيئة المناسبة .

يمكنك معرفة المزيد حول كيفية استخدام Rack :: Sendfile مع front-ends الشائعة في وثائق Rack :: Sendfile.

في ما يلي بعض القيم لرأس الصفحة هذا لبعض الخوادم الشائعة، بمجرد تهيئة هذه الخوادم لدعم إرسال الملفات بسرعة:

# Apache and lighttpd

config.action_dispatch.x_sendfile_header = "X-Sendfile"

# Nginx

config.action_dispatch.x_sendfile_header = "X-Accel-Redirect"

تأكد من إعدادات تكوين الخادم الخاص بك لدعم هذه الخيارات باتباع الإرشادات الموجودة في الوثائق Rack :: Sendfile.

استخدام ActionDispatch::Request

ActionDispatch::Request#params سوف يأخذ المعاملات من العميل بتنسيق JSON وإتاحتها في وحدة التحكم داخل params.

لاستخدام هذا، سيحتاج العميل إلى تقديم طلب باستخدام معاملات JSON-encoded وتحديد نوع المحتوى كــ application/json.

إليك مثال في jQuery:

jQuery.ajax({

type: 'POST',

url: '/people',

dataType: 'json',

contentType: 'application/json',

data: JSON.stringify({ person: { firstName: "Yehuda", lastName: "Katz" } }),

success: function(json) { }

});

سيشاهد ActionDispatch :: Request نوع المحتوى وستكون المعاملات الخاصة بك:

{ :person => { :firstName => "Yehuda", :lastName => "Katz" } }

البرامج الوسيطة الأخرى

يحتوي ريلز على عدد من البرامج الوسيطة الأخرى التي قد ترغب في استخدامها في تطبيق واجهة برمجة التطبيقات، خاصة إذا كان أحد عملاء واجهة برمجة التطبيقات هو المتصفح:

Rack::MethodOverride.
ActionDispatch::Cookies.
ActionDispatch::Flash.
لإدارة الجلسة:

ActionDispatch::Session::CacheStore.
ActionDispatch::Session::CookieStore.
ActionDispatch::Session::MemCacheStore.

يمكن إضافة أي من هذه البرامج الوسيطة عبر:

config.middleware.use Rack::MethodOverride

إزالة البرامج الوسيطة

إذا كنت لا ترغب في استخدام برامج وسيطة ضُمنت افتراضيًا في مجموعة البرامج الوسيطة لـ API فقط، فيمكنك إزالتها باستخدام:

config.middleware.delete ::Rack::Sendfile

ضع في اعتبارك أن إزالة هذه الوسيطة ستزيل الدعم لميزات معينة في وحدة التحكم بالعمل.

اختيار وحدات التحكم

يأتي تطبيق API (باستخدام ActionController :: API) مع وحدات التحكم التالية بشكل افتراضي:

ActionController::UrlFor: يجعل url_for والمساعدين المتشابهين متاحة.
ActionController::Redirecting: يقدم الدعم redirect_to.
AbstractController::Rendering و ActionController::ApiRendering: الدعم الأساسي للتقديم.
ActionController::Renderers::All: يدعم render :json والاصدقاء.
ActionController::ConditionalGet: يدعم stale؟.
ActionController::BasicImplicitRender: يتأكد من عرض استجابة فارغ، إذا لم يكن هناك استجابة صريحة.
ActionController::StrongParameters: دعم المعاملات للقائمة البيضاء بالاشتراك مع تعيين كتلة نموذج نشط.
ActionController::ForceSSL: تدعم force_ssl.
ActionController::DataStreaming: تدعم send_file و send_data.
AbstractController::Callbacks: يدعم before_action و المساعدين المشابهين.
ActionController::Rescue: يدعم rescue_from.
ActionController::Instrumentation: دعم خطافات الأجهزة المحددة من قبل وحدة التحكم في الإجراء (انظر دليل الأجهزة لمزيد من المعلومات حول هذا الأمر).
ActionController::ParamsWrapper: يلف تجزئة المعاملات في التجزئة المتداخلة، بحيث لا تضطر إلى تحديد عناصر الجذر لإرسال طلبات POST على سبيل المثال.
ActionController::Head: دعم لإعادة الإستجابة بدون محتوى، فقط رؤوس الصفحات.

قد تضيف الإضافات الأخرى وحدات إضافية. يمكنك الحصول على قائمة بجميع الوحدات المضمّنة في ActionController :: API في وحدة التحكم في ريلز:

$ bin/ريلز c

>> ActionController::API.ancestors - ActionController::Metal.ancestors

=> [ActionController::API,

ActiveRecord::Railties::ControllerRuntime,

ActionDispatch::Routing::RouteSet::MountedHelpers,

ActionController::ParamsWrapper,

... ,

AbstractController::Rendering,

ActionView::ViewPaths]

إضافة وحدات أخرى

تعرف جميع وحدات "التحكّم في الإجراءات" بالوحدات التابعة لها، لذا يمكنك أن تشعر بإدراج أي وحدات في وحدات التحكم لديك، ويتضمن جميع الاعتمادات وإعدادها أيضًا.

بعض الوحدات الشائعة التي قد ترغب في إضافتها:

AbstractController::Translation: دعم l و t توابع الموقع و الترجمة.
دعم استيثاق HTTP الأساسية أو digest أو الرمز المميز:

ActionController::HttpAuthentication::Basic::ControllerMethods.
ActionController::HttpAuthentication::Digest::ControllerMethods,
ActionController::HttpAuthentication::Token::ControllerMethods.

ActionView::Layouts: دعم للتخطيطات عند التقديم.
ActionController::MimeResponds: دعم respond_to.
ActionController::Cookies: تدعم cookies، والتي تتضمن دعم ملفات تعريف الارتباط الموقعة والمشفرة. هذا يتطلب ملفات تعريف الارتباط الوسيطة.

أفضل مكان لإضافة وحدة نمطية هو في ApplicationController الخاص بك، ولكن يمكنك أيضًا إضافة وحدات نمطية إلى وحدات التحكم الفردية.

المراجع:

استخدام ريلز لتطبيقات API فقط.