مساحات الاسم المُدارة

ملخّص

مقدمة

تُستخدم مساحات الاسم المُدارة في حزمة Weave SDK لتزويد كل من مطوّري برامج Weave SDK ومسؤولي الدمج على حد سواء بالإرشادات والنصوص الفرعية المُعلَن عنها بشأن تعيين مجموعات معينة من واجهات برمجة التطبيقات ضمن حزمة SDK، بحيث يمكنهم تخطيط وتوقع مسار النقل عبر إصدارات Weave SDK، وربما إدارة واجهات برمجة تطبيقات Weave متعددة ومتزامنة لوحدة معينة.

التصنيف

يمكن إدارة مساحات الاسم المُدارة كإحدى التصنيفات الأربعة:

• التطوير
• التالي
• الحالي
• الإصدار القديم

تطوير

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

التالي

إنّ أي مساحة اسم مُدارة باستخدام التصنيف "Next" (التالي) هي إشارة للمطوّرين وشركات الدمج بأنّ واجهات برمجة التطبيقات المضمّنة فيها قد تظلّ عرضة للتغيير، وهي متاحة لأغراض التقييم المبكر على الرغم من أنها قد أكملت التطوير النشط إلى حد كبير. وتمثِّل واجهات برمجة التطبيقات التي صُيِّفت كواجهة متطورة تالية في واجهة برمجة التطبيقات Weave SDK API وستصبح واجهات برمجة التطبيقات التلقائية الحالية في دورة الإصدارات الرئيسية في المستقبل القريب.

قد يوجد التوافق مع الأنظمة القديمة، من منظور واجهة برمجة التطبيقات والبروتوكول عبر الشبكة، ولكنه غير مضمون في واجهات برمجة التطبيقات التي تم تحديدها على هذا النحو.

إنّ تصنيف مساحة الاسم المُدارة في المرة التالية يوفر بشكل فعّال للمطوّرين وشركات الدمج إمكانية عرض حزمة تطوير البرامج Weave SDK من خلال الإشارة إلى واجهة برمجة التطبيقات التي ستصبح واجهة برمجة التطبيقات التلقائية الحالية في إصدار مستقبلي.

يكون تعيين مساحة الاسم المُدارة التالي اختياريًا، بحيث يمكن أن تنتقل مساحة الاسم المُدارة خلال مراحل نشاط بدون استخدامها (يمكنك الاطّلاع على دورة حياة مساحة الاسم المُدارة).

ملف

أي مساحة اسم مُدارة باستخدام التصنيف الحالي أو أي مساحة اسم غير مُدارة (أي تنقصها تسمية مساحة اسم مُدارة) تمثل واجهة برمجة التطبيقات الحالية والتلقائية والمعتمدة لذلك الجزء أو الوحدة من حزمة Weave SDK. وفي حين أنّه قد تكون هناك تحسينات مستمرة على واجهات برمجة التطبيقات هذه، ستشمل التغييرات إلى حدّ كبير التوافق التدريجي والتوافق مع الأنظمة القديمة، ويجب الحفاظ على كلّ من واجهة برمجة التطبيقات وعبر الإنترنت.

يُعد تعيين مساحة الاسم المُدارة حاليًا اختياريًا، بحيث يمكن أن تنتقل مساحة الاسم المُدارة خلال مراحل نشاط بدون استخدامها (يمكنك الاطّلاع على دورة حياة مساحة الاسم المُدارة). في الواقع، أي مساحة اسم غير مُدارة تكون حديثة بشكل ضمني.

قديمة

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

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

دورة حياة مساحة الاسم المُدارة

ويوضح الشكل التالي دورة حياة مساحة الاسم المُدارة أثناء انتقالها من التطوير، وربما إلى القديمة:

.-------------.      .- - - .      .- - - - -.      .--------.
| Development | -.->   Next   -.->   Current   ---> | Legacy |
'-------------'  |   '- - - '  |   ' - - - - '      '--------'
                 |             |
                 '-------------'

وفي حال استخدام مساحة الاسم المُدارة، تبدأ دورة حياة مساحة الاسم المُدارة بتسمية التطوير.

عند اكتمال التطوير ويكون الرمز البرمجي جاهزًا للتقييم والتكامل، ينتقل التصنيف إلى "Next" (التالي) أو "Current". وبدلاً من ذلك، قد يتم إسقاط التصنيف تمامًا ويتم إيقاف مساحة الاسم المُدارة، ما يجعل التعيين "حديث بشكل ضمني".

إذا كانت التعليمة البرمجية مفعَّلة إلى جانب الرمز الحالي ولم تحلّ محلّها بعد، يجب أن ينتقل التصنيف إلى "Next" (التالي). إذا كانت التعليمة البرمجية ستحل محل التعليمة البرمجية الحالية، فيجب أن ينتقل التصنيف إلى Currents.

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

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

من التصنيف Legacy، تتم في النهاية إزالة الرمز البرمجي من Weave SDK تمامًا.

استخدام مساحات الأسماء المُدارة

يمكن لمستخدمي حزمة SDK في Weave التفاعل مع مساحات الاسم المُدارة إما بصفتهم مطوّرين، أو يوسّعون نطاق الرموز الحالية ويحافظ عليها، أو بصفتهم شركة تكامل، يدمجون خدمة Weave في التطبيق والنظام الأساسي ورمز النظام الخاص بهم. يوضح القسمان التاليان بالتفصيل التوصيات للتعامل مع مساحات الاسم المُدارة في Weave من هذين المنظورين.

استخدام مساحات الأسماء المُدارة كمطوّر برامج

يتمثّل أحد النقاط الأساسية لمطوّري حزمة Weave SDK في تحسين واجهات برمجة تطبيقات Weave SDK ووظائفها وتطويرها، مع دعم عمليات نشر الوظائف وواجهة برمجة التطبيقات الحالية في الوقت نفسه.

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

كمثال عملي، افترض أن ملف Weave الشخصي، Mercury، موجود حاليًا ضمن التسلسل الهرمي التالي لمساحة الاسم غير المُدارة:

namespace nl {
namespace Weave {
namespace Profiles {
namespace Mercury {

// ...

}; // namespace Mercury
}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

والعناوين العامة التالية:

• Weave/Profiles/Mercury/Mercury.hpp
• Weave/Profiles/Mercury/Bar.hpp
• Weave/Profiles/Mercury/Foo.hpp
• Weave/Profiles/Mercury/Foobar.hpp

حيث يكون Mercury.hpp هو عنوان الوحدة "شمسية". تُضمِّن معظم شركات الدمج ببساطة عنوان "شمسية" الوحدة كما هو موضّح:

#include 

ومع ذلك، وصل تطوير شركة Mercury الآن إلى مرحلة تحتاج فيها إلى تطوير الجيل التالي من واجهات برمجة التطبيقات (APIs) وربما بروتوكول الاتصال عبر Wi-Fi الذي لا يتوافق مع الأنظمة القديمة لعمليات النشر الحالية. يمكن أن يساعد استخدام مساحات الاسم المُدارة في تحقيق ذلك بدون إيقاف عمليات النشر الحالية.

نقل مساحة الاسم الحالية إلى الحالية

بهدف مواصلة دعم الإصدار الحالي لواجهة برمجة التطبيقات والوظائف لعمليات الدمج الحالية المنشورة، تتمثل المهمة الأولى في نقل الرمز الحالي:

% cd src/lib/profiles/mercury
% mkdir Current
% mv Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp *.cpp Current/

ملاحظة، بالإضافة إلى نقل الملفات، يجب أيضًا إعادة تسمية العنوان واقيات الملفات المنقولة، وربما تزيينها بـ "_CURRENT"، نظرًا لأنه سيتم إنشاء الملفات الجديدة ذات الأسماء المتشابهة مكانها أدناه.

بعد نقل الرمز، تتمثل الخطوة التالية في إدارة مساحة الاسم باستخدام التصنيف المناسب، هنا 'Current'. أولاً، أنشئ عنوانًا يحدد مساحة الاسم المُدارة، على أنه "Current/MercuryManagedNamespace.hpp". يُفضل إنشاء مثل هذا العنوان عن تكرار هذا المحتوى وتكراره في كل ملف عنوان عندما يكون هناك ملفات عناوين متعددة.

% cat << EOF > Current/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current
#error Compiling Weave Mercury current-designation managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Current
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
EOF

بعد ذلك، ضمِّن هذا الرأس قبل توجيهات التضمين الأخرى الخاصة بالوحدة في العناوين الحالية. مثال:

#include 

#include 

إنشاء عناوين التوافق

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

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

% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp

إذا تم إنشاء مساحة اسم مُدارة محددة حاليًا فقط بدون إنشاء مساحة اسم مُدارة للتطوير أو التالي لمصاحبتها، يمكن أن تتألف محتويات هذه الملفات ببساطة من عنوان يتضمن guard وأمر تضمين يحدد الرأس الذي تم نقله حديثًا بالاسم نفسه:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

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

وكما في السابق، يتم إنشاء عنوان لضبط مساحة الاسم المُدارة، هنا على النحو التالي MercuryManagedNamespace.hpp. مرة أخرى، من المفضّل تكرار هذا المحتوى وتكراره في كل ملف عنوان عندما يكون هناك عدة ملفات عناوين.

% cat << EOF > MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE)                             \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current) \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development)
#error "WEAVE_CONFIG_MERCURY_NAMESPACE defined, but not as namespace kWeaveManagedNamespace_Current or kWeaveManagedNamespace_Development"
#endif

#if !defined(WEAVE_CONFIG_MERCURY_NAMESPACE)
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
EOF

لاحظ أن هذا الإعداد الافتراضي، كما هو مطلوب، هو تعيين مساحة الاسم المُدارة على "Current" في حال عدم تحديد أي إعداد.

بعد تنفيذ هذا العنوان، يمكن الآن تعديل رؤوس برامج تضمين التوافق لتشتمل على ما يلي:

#include 

#if WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development
#include 
#else
#include 
#endif // WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development

أو ما يتناسب مع حالة استخدام إدارة مساحة الاسم القائمة.

إنشاء محتوى للتطوير

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

% mkdir Development
% touch Development/Mercury.hpp Development/Bar.hpp Development/Foo.hpp Development/Foobar.hpp
% cat << EOF > Development/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development
#error Compiling Weave Mercury development-designated managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Development
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Development
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
EOF

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

استخدام مساحات الأسماء المُدارة في عملية الدمج

يتمثّل أحد النقاط الأساسية لشركة تكامل Weave SDK في تضمين عناوين واجهة برمجة التطبيقات العامة المناسبة لحزمة Weave SDK ودمج وتطوير التطبيقات وفقًا لها.

كمثال عملي، افترض مرة أخرى أن ملف Weave الشخصي، Mercury، يتضمن مساحات اسم مُدارة تم تعيينها لـ Next- وCurrent- وLegacy، والتي يتم تنظيم عناوينها العامة على النحو التالي:

• Weave/Profiles/Mercury/Mercury.hpp
• Weave/Profiles/Mercury/Bar.hpp
• Weave/Profiles/Mercury/Foo.hpp
• Weave/Profiles/Mercury/Foobar.hpp
• Weave/Profiles/Mercury/Next/Mercury.hpp
• Weave/Profiles/Mercury/Next/Bar.hpp
• Weave/Profiles/Mercury/Next/Foo.hpp
• Weave/Profiles/Mercury/Next/Foobar.hpp
• Weave/Profiles/Mercury/Current/Mercury.hpp
• Weave/Profiles/Mercury/Current/Bar.hpp
• Weave/Profiles/Mercury/Current/Foo.hpp
• Weave/Profiles/Mercury/Current/Foobar.hpp
• Weave/Profiles/Mercury/Legacy/Mercury.hpp
• Weave/Profiles/Mercury/Legacy/Bar.hpp
• Weave/Profiles/Mercury/Legacy/Foo.hpp
• Weave/Profiles/Mercury/Legacy/Foobar.hpp

حيث يكون Mercury.hpp هو عنوان الوحدة "شمسية".

ما لم تحفز حالة الاستخدام المطروحة تضمين وحدة مُدارة لمساحة الاسم ضمن Weave بشكل صريح، على سبيل المثال:

#include 

فمن الأفضل الإشارة إلى العناوين العامة لوحدة Weave من خلال مساراتها التلقائية غير المُدارة (على سبيل المثال، Weave/Profiles/Mercury/Mercury.hpp). ويسمح ذلك بمتابعة تقدّم تطوير واجهات برمجة التطبيقات بدون التغيير المستمر لتوجيهات تضمين المشروع أثناء تدفق واجهات برمجة التطبيقات هذه خلال lifecycle المُدارة.

وباتّباع هذه الاستراتيجية، يمكن لعمليات النشر بعد ذلك إعادة استهداف الرمز البرمجي الخاص بها في تصميم مختلف لمساحة الاسم المُدارة، مثل التعيين الحالي، من خلال تحديد الإعدادات المطلوبة في المعالج الأولي لـ C/C++. ويمكن إجراء ذلك في سطر الأوامر أو في رمز المصدر أو في عنوان إعداد أو عنوان بادئة:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

واستخدام مسار التضمين غير المُدار / غير المؤهَّل:

#include 

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy