lcbo api
1.0.0
مرحبًا، مرحبًا بكم في LCBO API؟
إذا وجدت نفسك هنا تتساءل "ما هي واجهة LCBO API؟"، دعني أشرح لك ذلك. في أونتاريو، كندا، تتم جميع مبيعات المشروبات الكحولية من خلال شركة مملوكة للحكومة تسمى مجلس مراقبة المشروبات الكحولية في أونتاريو (LCBO) الذي يتولى بيع المشروبات الكحولية بالتجزئة وتوزيعها في جميع أنحاء المقاطعة. لدى LCBO العديد من متاجر البيع بالتجزئة وموقع ويب يستضيف كتالوجًا لكل منتج ومتجر وحتى مستويات المخزون. ينشرون كتالوجًا موسميًا يحتوي على وصفات ومقالات افتتاحية ومحتويات أخرى تسمى الطعام والشراب. كما أنهم يساهمون أيضًا بمليارات الدولارات من الإيرادات لنظام الرعاية الصحية العام لدينا سنويًا. إنه موقف رائع عندما تفكر في الأمر، الأماكن الأخرى لديها أنظمة مماثلة ولكن على حد علمي لا يوجد أي منها لديه اتساع وعمق LCBO. إذن، الآن أنت تعرف ما هو، رائع جدًا، أليس كذلك؟
قد يكون هذا مثيرًا للاهتمام بالنسبة لك حتى لو كنت لا تعيش في أونتاريو، كندا، إذا:
طوال فترة هذا المشروع، كافحت بشكل كبير مع فكرة قبول الدعم المالي. من ناحية، كانت LCBO API في حاجة إليها، ومن ناحية أخرى كنت أشعر بالضجر من المضاعفات التي قد تسببها. حسنًا، الآن لدي الحل الأمثل لهذه المشكلة!
أخضع الآن لعلاج سرطان الدم، وتحديدًا سرطان الغدد الليمفاوية في الخلايا البائية الكبيرة المنتشر. سأكتب المزيد عن ذلك قريبًا في مكان آخر، لكن خلال العام الماضي دعمني الناس من كل مكان بكل طريقة ممكنة، وقد غيرني ذلك. أريد أن نفعل شيئًا كبيرًا لإظهار أننا نهتم أيضًا!
إذا كنت تريد دعم هذا المشروع في الماضي، فيرجى التبرع لـ Hamilton Health Sciences نيابة عن LCBO API، فهم ينقذون حياتي.
تبرع لعلوم الصحة هاميلتون
أنا أخضع للعلاج في مركز جورافينسكي للسرطان، ولكن في الحقيقة يمكنك اختيار أي خيار، أو ترك الخيار الافتراضي. لا يهم إذا كان المبلغ صغيرًا أو كبيرًا، فسوف يقومون بإخطاري عند التبرع. سأقوم بجدولة قائمة لتتبع المجموع، دعونا نرى مقدار المبلغ الذي يمكننا جمعه!
أخيرًا، أود أن أشير بشكل خاص إلى مكان عملي، Crowdmark. لقد كانوا طيبين ومتفهمين بشكل لا يصدق خلال كل هذا، ولم أكن لأتمكن من القيام بذلك بدونهم. نحن نعمل بلا كلل من أجل تعزيز الوضع الراهن للتقييم في التعليم العالي. إذا كنت مهتمًا بالتعليم والتعلم، فأنا أحثك على التحقق منا.
في خريف عام 2008، كنت مطور ويب حديثًا ولدي بضع سنوات من الخبرة. كنت جائعًا للتحدي وبعض الاعتراف. أصبحت التطبيقات أمرًا شائعًا في ذلك الوقت وأردت إنشاء تطبيق بشدة. قررت أنني أرغب في إنشاء واحدة تتطلب مني إنشاء واجهة برمجة التطبيقات (API) هذه أولاً. لم أقم ببناء هذا التطبيق مطلقًا؟
إذا نظرت إلى قاعدة البيانات هذه لفترة كافية، فمن المحتمل أن تجد لحظات من الإحباط، والطرق المسدودة، والأمور المربكة، وما إلى ذلك. آمل حقًا ألا تركز على ذلك أو على أي سلبية قد تجدها. لم أعد ذلك الشخص بعد الآن، ولا أريدك أن تكون ذلك الشخص أيضًا. أنا كتاب مفتوح في هذا الشأن! افتح موضوعًا واسألني سؤالاً، وسأكون صادقًا ومحترمًا قدر الإمكان، وأطلب منك فقط أن تفعل الشيء نفسه.
أنا أقوم بإطلاق هذا المشروع تحت GNU GPLv3، وأعتقد أن هذا هو الخيار الأكثر عدلاً ومسؤولية لمشروع مثل هذا. إذا كنت تشعر بشكل مختلف، افتح قضية ويمكننا إجراء مناقشة مفتوحة حول هذا الموضوع. أطلب فقط، بكل احترام، عدم إعادة استخدام العلامة التجارية والتصميم. لا أوافق على إعادة استخدام الوثائق، ولكن يجب تغيير التصميم والهوية والعلامة التجارية إذا كنت تريد نشر الإصدار المنعزل الخاص بك من هذا التطبيق.
ماذا لو بدلاً من تطبيق متجانس يحاول القيام بكل شيء بأسلوب واحد، في مكان واحد، فكرنا بشكل أكبر؟ ماذا لو كان الزاحف مشروعًا منفصلاً مرة أخرى، مسؤولاً عن جمع البيانات وتطبيعها، ويمكن للآخرين إنشاء عقد واجهة برمجة التطبيقات (API) في أي نظام أساسي يرغبون فيه، وستسجل هذه العقد لدى موفر البيانات وتتلقى البيانات المحدثة بمجرد إتاحتها وتوفر تلك البيانات إلى المستخدمين من جميع الأنواع المختلفة.
بدلاً من العشرات من خوادم API المشابهة التي تحاول القيام بنفس الشيء، والقتال من أجل موارد LCBO.com، يمكننا تركيز جهودنا على بناء القيمة على هذه البيانات بدلاً من القتال من أجل الملكية عليها. يمكننا إشراك تخصصات أخرى لتوليد قيمة جديدة تتجاوز ما هو واضح، وإشراك مجتمعات البيرة والنبيذ الحرفية، والبناء على ذلك، وجعلها أكبر من مجرد أونتاريو.
لا أعرف مدى جدوى شيء من هذا القبيل، ولكنني أعلم أنه إذا كان الآخرون مهتمين فإنني أرغب في إجراء هذه المناقشات.
أيضًا، ربما ينبغي لنا أن نفكر في فرض رسوم معقولة على مستخدمي الشركات للوصول إلى عقد API، ويمكن استخدام هذه الأموال لتمويل تكاليف الاستضافة للحفاظ على استدامة الأمور، ويمكن استخدامها أيضًا لتمويل برامج الدعم للأشخاص الذين لا يستطيعون الشرب، أو من لا يريد أن يشرب، أو من يريد أن يشرب أقل، لرد الجميل لمجتمعاتنا ولإحداث فرق فعليًا.
لكنني بحاجة إلى مساعدة الآخرين في تقاسم عبء الحفاظ على كل هذا وإدارته، فصحتي وسعادتي وصحة عائلتي هي الأولوية رقم 1، تليها مسيرتي المهنية، ثم أصدقائي ومجتمعي. لا يمكن لهذا المشروع أن يكون مصدر الوقت الأول بالنسبة لي بعد الآن، فهو غير مستدام بالنسبة لي، وليس صحيًا بالنسبة لي. ولكن إذا ألهمتك هذه الرسالة، فيرجى التواصل معي، من الأفضل أن تكون علنيًا، ولكن على انفراد في البداية فلا بأس أيضًا.
آمل أن هذا يثير لك!
لم أستطع أن أمنع نفسي، لقد كتبت المزيد عن أفكاري حول هذا الموضوع: doc/lcboapi-propose.md
الآن، بعد أن انتهينا من ذلك، يمكننا أن نبدأ في التعرف على من فعلت هذا حقًا من أجله، وما الذي جعلني متحمسًا وألهمني للقيام بذلك في المقام الأول: فرصة التعلم والنمو ومساعدة الآخرين على فعل الشيء نفسه. لأولئك منكم الذين لديهم فضول، دعونا نرى أين يذهب هذا؟
ربما يمكنك تشغيل التطبيق مباشرة على البيئة المضيفة لديك، فهو لا يتطلب أي شيء فاخر للغاية فيما يتعلق بتبعيات النظام. أقوم بالتطوير على أجهزة Apple، وإذا قمت بذلك أيضًا، فقد تنجح في استخدام Postgres.app وHomebrew لتثبيت Redis. بخلاف ذلك، يمكنك استخدام Docker.
إذا كانت لديك خبرة مع نظام أساسي آخر، فيرجى تقديم علاقة عامة أو مشكلة ويمكننا العمل على إضافة النظام الأساسي الخاص بك إلى الملف التمهيدي.
وأيضًا، إذا كان ما يلي هنا غير منطقي بالنسبة لك، فافتح مشكلة، ربما يمكننا عمل تسجيل للشاشة لتوضيح العملية، أو ربما يقوم شخص ما جيد في ذلك بتنفيذ ذلك؟
ما أصفه أدناه هو طريقة واحدة فقط لإعداد بيئة تطوير لتشغيل LCBO API على جهاز الكمبيوتر الخاص بك. إذا كان لدى الآخرين تحسينات (هناك مجال للكثيرين، برنامج نصي لنقطة الدخول لتشغيل قاعدة بيانات التطوير على سبيل المثال) أو حتى أساليب مختلفة، مثل استخدام Vagrant + VirtualBox، أو فتح مشكلة أو علاقات عامة، يسعدني إضافتها.
إذا كنت تريد المساعدة، أريد تمكينك.
config/secrets.yml و .envأولاً، ستحتاج إلى إعداد بعض التكوينات غير المتوفرة في المستودع العام. السبب وراء ذلك هو حماية البيانات الخاصة مثل مفاتيح API والرموز السرية، ولكن أيضًا لأن بعض المطورين قد يفضلون إعدادات مختلفة قليلاً لتفضيلاتهم الشخصية وأشياء من هذا القبيل.
هناك ملفان ستحتاج إلى إنشائهما، config/secrets.yml و .env . توجد إصدارات قالب في الريبو ضمن config/secrets.yml.example و .env.example ، يمكنك نسخ هذه الملفات للبدء:
cp config/secrets.yml.example config/secrets.yml
cp .env.example .env
إذا كنت ترغب فقط في تشغيل التطبيق والوصول إليه محليًا، فمن الجيد أن تبدأ في هذه المرحلة. إذا كنت تريد أن تكون قادرًا على استخدام الزاحف وجعله يحفظ لقطة محفوظة في Amazon S3، فسوف تحتاج إلى إضافة بيانات اعتماد AWS الخاصة بك وحاوية البيانات إلى config/secrets.yml .
أما بقية الإعدادات فهي إما مهمة حقًا فقط في بيئة الإنتاج، أو لا يتم استخدامها حقًا، أو مهمة فقط إذا كنت لا تحب التفضيل الافتراضي. كما هو الحال دائمًا، إذا كنت بحاجة إلى توضيح، فافتح وأصدر، ويسعدني تقديم المساعدة.
أولاً، ستحتاج إلى تثبيت عميل Docker لنظامك، ويمكنك معرفة ذلك هنا. بمجرد تثبيت Docker، يمكنك بدء الأمور:
بعد ذلك، سوف تحتاج إلى بناء الحاويات:
docker-compose build
عندما يتم ذلك، يمكنك تشغيل كل شيء عن طريق إصدار:
docker-compose up
في هذه المرحلة، ليس لديك أي بيانات في قاعدة البيانات، لذلك إذا قمت بتحميل التطبيق http://localhost:3000، فلن يفعل الكثير، فهو يخدم البيانات بعد كل شيء، ولا توجد بيانات فيه. لذلك دعونا نفعل شيئا حيال ذلك.
المضي قدما وأغلق الحاويات:
Ctrl-C
وهذا يعني الضغط على مفاتيح Control + C في وقت واحد.
يمكنك تنزيل أرشيف لأحدث تفريغ لقاعدة بيانات الإنتاج من حسابي الشخصي على Amazon S3 هنا. يرجى ملاحظة أن هناك جداول حساسة (رسائل البريد الإلكتروني والمستخدمين والمفاتيح) وقد تم استبعاد تلك البيانات من هذا الملف.
قم بتنزيل واستخراج الأرشيف في دليل tmp لهذا المشروع:
cd tmp
curl -O https://heycarsten.s3.amazonaws.com/lcboapi-2019-01-21.tgz
tar xzf lcboapi-2019-01-21.tgz
cd ..
يبلغ حجم الملف حوالي 300 ميجابايت، لذا قد يستغرق التنزيل بعض الوقت اعتمادًا على سرعة الاتصال لديك (يحدث هذا على الخط الذي يبدأ بـ curl ).
بمجرد تنزيل ملف قاعدة البيانات واستخراجه، يمكنك تحميل البيانات إلى قاعدة البيانات:
docker-compose run --rm app rake db:create
docker-compose run --rm app bash -c 'pv tmp/lcboapi-2019-01-21.sql | psql -q -h db -U $POSTGRES_USER $POSTGRES_DB > /dev/null'
السطر الأول، المنتهي بـ rake db:create سينشئ مخططات قاعدة البيانات في Postgres للتطوير والاختبار، وسيقوم السطر الثاني بتحميل تفريغ قاعدة البيانات في قاعدة بيانات التطوير. يشير شريط التقدم إلى مقدار البيانات التي تم نقلها إلى قاعدة البيانات، وبمجرد اكتمال ذلك سيتم إنشاء الفهارس. قد يستغرق هذا بعض الوقت اعتمادًا على جهازك، فهو يحتوي على قدر لا بأس به من البيانات. ثم يمكنك تشغيل التطبيق مرة أخرى:
docker-compose up
يمكنك أيضًا حذف الأرشيف وملف SQL المستخرج بأمان من دليل tmp الخاص بك أيضًا في هذه المرحلة.
إذا كنت تجد كتابة
docker-composeمرارًا وتكرارًا أمرًا مملاً، فابحث في الأسماء المستعارة لـ Shellيمكنك إضافة سطر اسم مستعار إلى ملف تعريف Shell الخاص بك مثل
alias dc=docker-composeومن ثم يمكنك فقط كتابةdcبدلاً من الاضطرار إلى كتابةdocker-composeفي كل مرة. ✅فكر في الأسماء المستعارة الأخرى التي يمكنك إنشاؤها لتحسين هذا الأمر بشكل أكبر؟
انتقل الآن إلى http://localhost:3000/products/438457
بوم. لديك LCBO API قيد التشغيل على جهاز الكمبيوتر الخاص بك! ؟ ؟ ؟
عند الانتهاء من العمل على التطبيق، ما عليك سوى الضغط على Ctrl+C لإغلاق كل شيء. في المرة القادمة التي تريد فيها العمل عليها مرة أخرى، قم بتشغيل docker-compose up وستكون جاهزًا للبدء!
إذا قمت بإضافة جوهرة جديدة إلى Gemfile ، فستحتاج إلى إعادة تثبيت الحزم وتحديث التبعيات. يعد Docker جيدًا جدًا في القيام بذلك، حيث يمكنه معرفة متى يتغير Gemfile ، ويعرف كيفية إعادة بناء حاوية app لك.
لتشغيل وحدة تحكم Rails وفحص الكائنات داخل التطبيق:
docker-compose exec app rails c
بمجرد تشغيل ذلك، يمكنك القيام بأشياء مثل:
جلب المنتج الأول في قاعدة البيانات:
Product.first
ابحث عن متجر LCBO للبيع بالتجزئة رقم 25 (متجري المحلي):
Store.find(25)
إذا قمت بتغيير الرمز في التطبيق، فسوف تحتاج إلى إصدار reload! الأمر في وحدة التحكم لتحديث التغييرات.
داخل مجلد spec ، ستجد مجموعة الاختبار لـ LCBO API. ومن المؤسف أنها ليست شاملة، ولكنها ليست سيئة للغاية أيضا. لقد كافحت طوال حياتي المهنية للحفاظ على مجموعات الاختبار التي أشعر بالرضا عنها. يجب علينا تحسين هذه الاختبارات!
لتشغيل مجموعة الاختبار:
docker-compose exec app rspec
سترى مجموعة من النقاط الخضراء . ، يمثل كل واحد منهم حالة اختبار تم اجتيازها. هذا جيد. في حالة حدوث فشل سترى حرف F باللون الأحمر، فهذا أمر سيء... مجرد مزاح! في الواقع انه جيد! تمنحك الاختبارات القدرة على تغيير الأشياء في قاعدة التعليمات البرمجية الموجودة ومعرفة ما إذا كنت تتسبب في أي تراجعات في الوظائف الحالية. بالطبع لا يوجد شيء مثالي، لكن يمكنني أن أقول لك دون أدنى شك، من خلال الخبرة، الاختبارات جيدة.
نظرًا لأن التطبيقات تصبح أكبر وأكبر وأكثر تعقيدًا، فإن عدم إجراء اختبارات يصبح كابوسًا حقيقيًا، مما يجعل تغيير التطبيق الخاص بك وإضافة الميزات عملية هشة للغاية. يمكن لأشياء مثل استخدام اللغات مع أنظمة الكتابة وغيرها من نماذج البرمجة المختلفة أن تقطع شوطًا طويلًا للمساعدة في هذا أيضًا، لكنني أرى أنه لا يوجد بديل حقًا لمجموعة اختبار قبول قوية على الأقل.
هذا هو الجزء من LCBO API الذي يجعل الأمر برمته ممكنًا. من الصعب إنشاء وصيانة برامج الزحف الخاصة بمواقع الويب المعقدة. يحتوي الإصدار الأول من LCBO API على مجموعة اختبار كاملة للزاحف، وعندما تغير كل شيء منذ سنوات عديدة، تخليت عن قاعدة التعليمات البرمجية هذه وقمت ببناء شيء ما بأسرع ما يمكن في هذا الإصدار.
يقع منطق الزاحف في lib/crawler.rb ، ومن هناك سترى جميع المهام المتنوعة التي تحدث بالتتابع لتشمل الزحف الكامل لمواقع LCBO الإلكترونية.
يقع منطق المحلل اللغوي في lib/lcbo.rb وجميع الملفات المتنوعة داخل lib/lcbo/* ، وهذا يشمل جميع الطلبات المتنوعة التي يجب حدوثها، والكود المسؤول عن تحويل البيانات من تلك الطلبات إلى بيانات منظمة والتي يمكن أن تذهب في نهاية المطاف إلى قاعدة البيانات.
لقد صممت الزاحف لتنفيذ الطلبات بشكل تسلسلي، وهذا أسلوب جيد جدًا يجب اتباعه عند الزحف إلى موقع ويب واحد. إنه أمر بسيط بالنسبة للطريق الذي يكون دائمًا هو أفضل طريق يمكنك اتباعه إذا استطعت، وهو مهذب. يمكننا إيقاف وظائف AWS Lambda والزحف إلى كل صفحة على LCBO.com في بضع ثوانٍ، ولكن هذا سيكون أمرًا غير لائق، ومن المحتمل أن نقوم بـ DDoS على موقع الويب الخاص بهم للحظات، وهذا ليس جيدًا.
/manager )يشمل هذا تطبيق Ember، عندما تقوم بالتسجيل/الدخول إلى LCBO API وإنشاء مفاتيح API، فهذا هو ما تتفاعل معه. إنه قديم جدًا، ولم أحاول بنائه. لقد كنت أستخدم Ember منذ اليوم الأول، لذا إذا كانت لديك أي أسئلة حول هذا الأمر، فطرح المشكلات. سأستمتع حقًا بمناقشة هذا الجزء من LCBO API والعمل معكم جميعًا لتحسينه.
/static ) يحتوي هذا على موقع وسيط، عندما تزور lcboapi.com فهذا هو ما تبحث عنه. ويحتوي أيضًا على تطبيق React صغير جدًا (قديم أيضًا) وهو تطبيق "جربه" الموجود على يمين الصفحة الرئيسية. يحتوي على Gemfile الخاص به ويقوم بإنشاء برنامج نصي static/generate ، وعند تشغيله، يقوم بإنشاء الموقع ومزامنة التغييرات في المجلد public . في تطبيقات Rails، يتم تقديم المجلد public كمحتوى ثابت.
هناك الكثير من الطرق المسدودة في قاعدة التعليمات البرمجية هذه، والفروع التي قطعت 40-60-80% من الطريق إلى الميزة ثم توقفت، والتجارب، وما إلى ذلك. كما هو الحال دائمًا، إذا وجدت شيئًا يعجبك؟ ما عليك سوى تقديم مشكلة وسأرد عليها في أقرب وقت ممكن.
سيكون من الرائع أيضًا أن نتمكن من ربط بعض الطرق المسدودة هنا، سأكون مهتمًا جدًا بإضافة JSON:API وGraphQL أخيرًا. تصميم استجابة واجهة برمجة التطبيقات الحالي يعود إلى عام 2008!!! بطريقة ما أنا مندهش من أنه لا أحد يشتكي من ذلك على الإطلاق.
الميزة رقم 1 الأكثر طلبًا والتي لم أقم بتنفيذها مطلقًا هي الفئات، إنها موجودة هنا نوعًا ما، لقد نسيت لماذا لم أشحنها مطلقًا، لا أتذكر ما هي الأشياء النهائية التي يجب وضعها في مكانها الصحيح، ولكن ربما يكون ذلك أمرًا جيدًا أولاً شيء لمعالجة؟ هناك أيضًا المنتجون والأصول التي لم يتم الانتهاء منها أبدًا.
لدي أيضًا مجموعة كاملة من عمليات إعادة الشراء الأخرى والتجارب الصغيرة التي أجريتها على مر السنين، لقد كنت دائمًا مفتونًا بفكرة التنبؤ بمستوى المخزون، في مكان ما توجد أداة تحليل تفريغ مجموعة البيانات مكتوبة بلغة Go لتحليل عمليات تفريغ CSV لمخزون منتج معين على مدى مجموعة من الوقت. سأكون سعيدًا بنشر هذه الأشياء أيضًا إذا كان هناك اهتمام.
سأترك الأمر هنا الآن وسأنتظر الرد منك. أرغب في الاستمرار في الإضافة إلى قاعدة المعرفة هذه بأي طريقة يرغب الأشخاص في رؤيتها (تسجيلات الشاشة، والمقابلات، والوثائق المضمنة، وما إلى ذلك). وأريدك أيضًا أن تفعل الشيء نفسه، إذا لم تكن متأكدًا، فاسأل. ❤️
