كيفية تصميم واجهات برمجة التطبيقات التي لا تمتص

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

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

كن صريحًا

ربما هذا هو أهم نصيحة. إذا كان لديك طريقة تسمى getUser وتسبب بعض الآثار الجانبية دون أن تكون صريحًا بشأن ذلك ، فقد يؤدي ذلك إلى الكثير من المشاكل.

لا تقم بتعديل الحالة المشتركة القابلة للتغيير دون أن تكون صريحًا بشأنها. إذا قمت بالاتصال بـ getUser ، فأنا أتوقع أن يعود مجرد مستخدم ، وليس زيادة user_id بمقدار 1 على طول الطريق. قد تفكر في استخدام هياكل البيانات غير القابلة للتغيير.

قم بترميز أكبر قدر ممكن من السلوك في اسم الأسلوب / الفئة / الوحدة النمطية ضمن حدود معقولة. لا تتوقع أن يذهب المستخدمون إلى مصدر الغوص للكشف عن السلوك الخفي الذي لا يكشف عنه الاسم. ستوفر على نفسك الكثير من الألم.

حافظ على مساحة سطح API الخاصة بك صغيرة

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

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

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

التنفيذ التوقعي هو المسؤول عن كميات مخزية من ساعات البرمجة الضائعة. ممارسة YAGNI.

تقليل المرجل

التعامل مع أكبر عدد ممكن من تفاصيل التنفيذ داخليا لتخفيف العبء على العملاء. كلما كان على المستهلك القيام به ، قل عدد الأخطاء التي يجب عليك التعامل معها.

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

تقليل التبعيات

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

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

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

إرجاع حالات خطأ ذات معنى

يمكن أن أزعجني طوال اليوم حول مدى عدم وجود بنية عديمة الفائدة في كثير من الحالات. هذا يعني حرفيا لا شيء.

"يا وحدة ، أعطني مستخدم"

"كلا. هنا لا شيء بدلاً من ذلك "

هذا يعطيني أي معلومات حول الخطأ الذي حدث وما الذي يمكنني القيام به لتحسين الموقف. إذا كان لدينا بدلاً من ذلك طريقة موثقة للتعبير عن حالات الخطأ المتوقعة في نطاق مشكلتنا مثل Error.USER_NOT_CREATED أو Error.USER_DELETED ، هذا يعطيني المزيد من البيانات القابلة للتنفيذ ويساعدني في تصحيح المشكلة.

يجب أن تتبع رسائل الخطأ نفس الإرشادات. تحتاج إلى تسجيل الدخول قبل المتابعة أفضل بكثير من LOL! هناك خطأ ما.

حفظ استثناءات لحالات استثنائية حقا

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

الاستثناءات تميل إلى التعرض بشدة في أرض جافا. الاستثناءات للتعامل مع الحالات الاستثنائية حقا. هل حقا لا تتوقع أن getUser قد لا يجد مستخدم؟ لا ترمي UserNotFoundException. إرجاع حالة خطأ مناسبة بدلاً من ذلك.

إذا كان هناك فشل حقيقي ، فمن الأفضل دائمًا أن تفشل سريعًا.

كما يقول جيك وارتون:

"الشيء الوحيد الأسوأ من البرنامج المعطل هو أنه لا يتعطل ويستمر في حالة غير محددة."

توثيق كل الأشياء

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

يجب أن تتكون الوثائق الجيدة من:

  1. نظرة عامة عالية المستوى على الوحدة بأكملها وكيفية عملها
  2. Javadocs ، Heredocs ، Rdocs أو أيًا من طرقها وبروتوكولاتها العامة
  3. نموذج التعليمات البرمجية التي تبين كيفية استخدامها

ليس كل التجريدات تتطلب نفس المستوى من الوثائق. فئة صغيرة لا تحتاج إلى رمز عينة على سبيل المثال.

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

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

الوثائق المركزة والكافية ، ومع ذلك ، هو دائما مفيدة.

اكتب الاختبارات

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

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

"لماذا تكتب الوثائق على الإطلاق إذا كان لدي اختبارات؟" قد تسأل. في خطر استخدام تشبيه ضعيف ، إذا كانت الوثائق هي دليل المستخدم لواجهة برمجة التطبيقات الخاصة بك ، فحينئذٍ تكون الاختبارات هي مرجع تعليمات شفرة التشغيل x86.

اجعلها قابلة للاختبار

اختبار التعليمات البرمجية الخاصة بك هو شيء واحد. كتابة واجهات برمجة التطبيقات التي تمكن أولئك الذين يستخدمونها لاختبار التعليمات البرمجية الخاصة بهم بسهولة آخر. سيتم تأجيل المطورين الذين يهتمون بالاختبارات من خلال واجهات برمجة التطبيقات التي تجعل من الصعب عليهم سخرية / كبحهم في حالات الاختبار.

يمكنك استخدام خيارات التكوين لإصدارات تصحيح الأخطاء والإصدارات حيثما كان ذلك ممكنًا. غالبًا ما تحتاج الأشياء إلى التصرف بشكل مختلف قليلاً في بيئات التكامل المستمر / النشر المستمر عن سلوكها في الإنتاج. حساب لهذا.

السماح لاختيار المستخدم

لن يرغب كل مستهلك في استهلاك واجهات برمجة التطبيقات الخاصة بك بنفس الطريقة. قد يريد البعض متزامن. قد يفضل البعض الآخر عمليات الاسترجاعات غير المتزامنة أو العقود المستقبلية أو الوعود أو ملاحظات Rx.

السماح للمستهلكين بالقدرة على اختيار ما يريدون قدر الإمكان. كلما تمكنت واجهة برمجة التطبيقات (API) الخاصة بك من الاندماج بسهولة في البرمجة الحالية وبيئة النظام ، زاد احتمال استخدام الناس لها.

لا تسمح بالكثير من اختيارات المستخدم

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

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

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

استنتاج

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

إذا أعجبك هذا ، فانقر فوق أدناه. لقد لاحظت كل واحد وأنا ممتن لكل واحد منهم.

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