صمّم واجهة برمجة جهاز دورة متقدمة في مسار البرمجة. كل درس يفتح دائرة مصباح WiFi (LED على GPIO 8) بكود C++ جديد، وتتحدث مع المصباح كما تفعل التطبيقات: طلبات ورموز حالة وJSON. تستغرق نحو ست ساعات.
ما تبنيه، درسًا بعد درس
- Resources and routes: a routing table, paths that name things, and why
GET /turnOnis a bug that switches the lamp on at 3 in the morning. You add a/deviceresource of your own. - الطرق (Methods): PUT تستبدل، PATCH تغيّر جزءاً، POST تنشئ (مع 201 وترويسة Location)، DELETE تحذف (مع 204). الآمن والمتساوي التأثير (idempotent)، و405 مع ترويسة Allow لطريقة لا يقبلها المسار.
- مخططات JSON: عقد المصباح بصيغة JSON Schema، وPUT تفحص كل حقل وتجيب 422 بكل المشكلات دفعة واحدة، ورفض الحقل المكتوب خطأً بدل تجاهله.
- الأخطاء: 400 و409 و422 و503، وترويسة Retry-After تخبرك متى تحاول مجدداً، وشكل خطأ واحد لكل الأخطاء، وقواعد إعادة المحاولة التي ينبغي للعميل اتباعها.
- رموز المصادقة: رموز bearer، والفرق بين 401 و403، ومقارنة بزمن ثابت، ورموز تُبعد عن السجلات، وحديث صادق عن أين يخزّن جهاز حقيقي أسراره (ليس في الكود، وفوق TLS فقط).
- الإصدارات: إعادة تسمية كاسرة تحصل على
/v2، و/v1يبقى يعمل مع ترويسة Sunset، وكلاهما عرضان لمصباح واحد، وحقل مضاف لا يحتاج إصداراً جديداً أصلاً.
المهمة النهائية: واجهة برمجة مصباح موثقة
الدرس الأخير يسلّم الإصدار 1 من API كاملة: المسارات، والطرق، ومخططًا مُتحققًا منه، وشكل خطأ واحدًا، ورموزًا. جدول المسارات هو مصدر الحقيقة الوحيد، لذلك فإن GET /v1/docs يُولَّد منه ولا يمكن أن يبتعد عن الكود. مجموعة اختبارات العقد (من نوع test) تستدعي أربعة عشر حالة كما يفعل العميل، معظمها أخطاء، وتطبع contract: 14 of 14 passed. تضيف مسار فحص صحة مع توثيقه واختباره في ثلاثة أسطر، ثم تكتب دليل API الذي يحتاجه مطوّر التطبيقات.
كيف تصل الطلبات إلى المصباح
The editor's network is simulated (see WiFi, simulated):
العميل الوحيد القادر على الوصول إلى خادم الويب على لوحة هو لوحة الويب، وهي ترسل طلبات GET بلا ترويسات. أما دورة API فتحتاج إلى PUT وPATCH وDELETE وأجسام JSON وترويسة Authorization، لذلك فإن لكل كود طريقًا ثانيًا: الشاشة التسلسلية هي أداة curl صغيرة. اكتب PUT /lamp {"on":true,"brightness":40} and it
prints the status, one header and the body. Both ways in reach the same
route() function, which is good design anyway: a handler should not care
how a request arrived.
لا يوجد TLS على الشبكة المحاكاة، لذلك يمكن قراءة كل بايت. الرموز في الأكواد رموز تجريبية، عامة عن قصد، ودرس المصادقة يوضح ما يجب أن يفعله منتج حقيقي بدلًا من ذلك.
قبل أن تبدأ
ينبغي أن تكون مرتاحًا مع C++ على ESP32-C3 ومع WiFi وخادم الويب عليه. دورة الأجهزة المتصلة تغطي جانب الشبكة. وبعدها، تأخذ دورة الأنظمة الموزعة بثلاث لوحات أفكار إعادة المحاولة والتساوي التأثير وتطبقها على ثلاث لوحات.