เนมสเปซที่มีการจัดการ

สรุป

บทนำ

เราใช้เนมสเปซที่มีการจัดการใน Weave SDK เพื่อให้ทั้งนักพัฒนาและผู้ผสานรวม Weave SDK ให้คำแนะนำและข้อความย่อยเกี่ยวกับการระบุชุด API หนึ่งๆ ภายใน SDK ดังกล่าว เพื่อให้พวกเขาวางแผนและคาดการณ์เส้นทางการย้ายข้อมูลของตนในรุ่นของ Weave SDK ได้ รวมทั้งอาจจัดการ Weave API หลายรายการพร้อมกันสำหรับโมดูลที่ระบุได้

การระบุ

เนมสเปซที่มีการจัดการอาจได้รับการจัดการโดยกำหนด 1 ใน 4 ประเภทต่อไปนี้

• การพัฒนา
• ถัดไป
• ปัจจุบัน
• เดิม

การพัฒนา

เนมสเปซใดๆ ที่จัดการโดยมีการกำหนดสถานะการพัฒนาเป็นตัวบ่งชี้ให้นักพัฒนาซอฟต์แวร์และผู้รวมบริการทราบว่า API ที่อยู่ภายในนั้นอยู่ระหว่างการพัฒนา อาจมีการเปลี่ยนแปลง และจะไม่ได้รับการรองรับอย่างเป็นทางการ โดยทั่วไปผู้ผสานรวมโปรแกรมจะไม่แนะนำให้ใช้ API เหล่านี้ เว้นแต่จะได้รับคำสั่งมาให้ใช้โดยเฉพาะ

ถัดไป

เนมสเปซใดๆ ที่จัดการด้วยการกำหนดรุ่นถัดไปจะเป็นตัวบ่งชี้ให้นักพัฒนาซอฟต์แวร์และผู้ผสานรวมระบบทราบ API ที่มีอยู่ในขณะที่ส่วนใหญ่การพัฒนาที่มีการใช้งานเสร็จสมบูรณ์แล้ว อาจยังมีการเปลี่ยนแปลงและได้รับการสนับสนุนเพื่อการประเมินล่วงหน้า API ที่กำหนดให้เป็นตัวแทนของสิ่งที่พัฒนาไปอีกขั้นใน Weave SDK API และจะกลายเป็น API เริ่มต้นในปัจจุบันในรอบการเปิดตัวที่สำคัญในเร็วๆ นี้

อาจมีความเข้ากันได้แบบย้อนหลังทั้งจาก API และโปรโตคอลผ่านสายเคเบิล แต่จะไม่มีการรับประกันใน API ที่กำหนด

การกำหนดเนมสเปซที่มีการจัดการใน Next ช่วยให้นักพัฒนาซอฟต์แวร์และผู้ผสานการทำงานสามารถดูทิศทางของ Weave SDK ได้อย่างมีประสิทธิภาพ ด้วยการบอกใบ้เกี่ยวกับสิ่งที่จะกลายเป็น API เริ่มต้นในปัจจุบันในรุ่นถัดไป

การกำหนดเนมสเปซที่มีการจัดการถัดไปเป็นตัวเลือกเพื่อให้เนมสเปซที่มีการจัดการผ่านช่วงวงจรการใช้งานได้โดยไม่ต้องใช้ (โปรดดูวงจร Namespace ที่มีการจัดการ)

ปัจจุบัน

เนมสเปซใดก็ตามที่มีการจัดการด้วยการกำหนดปัจจุบัน หรือเนมสเปซที่ไม่มีการจัดการ (เช่น ไม่มีการระบุเนมสเปซที่มีการจัดการ) จะแสดง API ที่ได้รับการสนับสนุนอย่างเป็นทางการในปัจจุบันและเป็นค่าเริ่มต้นสำหรับส่วนหรือโมดูลดังกล่าวของ Weave SDK แม้ว่าอาจยังมีการปรับปรุง API ดังกล่าวอย่างต่อเนื่อง แต่การเปลี่ยนแปลงส่วนใหญ่จะมีความเข้ากันได้แบบเพิ่มเติมและแบบย้อนหลัง ควรดูแลรักษาทั้ง API และการเชื่อมต่อผ่านสายแทน

การกำหนดเนมสเปซที่มีการจัดการในปัจจุบันเป็นตัวเลือกที่ไม่บังคับเพื่อให้เนมสเปซที่มีการจัดการผ่านช่วงการใช้งานได้โดยไม่ต้องใช้ (โปรดดูวงจร Namespace ที่มีการจัดการ) ที่จริงแล้วเนมสเปซที่ไม่มีการจัดการทั้งหมดจะเป็นปัจจุบันโดยปริยาย

รุ่นเดิม

เนมสเปซใดก็ตามที่มีการจัดการด้วยการกำหนดรูปแบบเดิมเป็นตัวบ่งชี้ให้นักพัฒนาซอฟต์แวร์และผู้ผสานการทำงานทราบว่า API ที่มีอยู่ภายในนั้นเลิกใช้งานแล้ว และแทนที่ด้วย API ใหม่ในปัจจุบัน API เหล่านี้เป็นตัวแทนของ API ปัจจุบันก่อนหน้านี้

API ที่ระบุจึงจะหายไปทั้งหมดใน Weave SDK เวอร์ชันหลักครั้งถัดไป ดังนั้น นักพัฒนาซอฟต์แวร์และผู้ผสานรวมระบบควรกำหนดแผนการย้ายข้อมูลออกจาก API เหล่านี้หากตั้งใจที่จะก้าวตามระดับชั้นนำของรุ่น Weave SDK

วงจร Namespace ที่มีการจัดการ

รูปต่อไปนี้แสดงวงจรของเนมสเปซที่มีการจัดการเมื่อเปลี่ยนจากโหมดการพัฒนาและอาจเป็นแบบเดิม

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

หากมีการใช้งาน วงจรของเนมสเปซที่มีการจัดการจะเริ่มต้นด้วยการกำหนด "การพัฒนา"

เมื่อการพัฒนาเสร็จสมบูรณ์และโค้ดพร้อมสำหรับการประเมินและผสานรวมแล้ว การกำหนดจะย้ายไปยัง "ถัดไป" หรือ "ปัจจุบัน" อีกทางเลือกหนึ่งคือ การกำหนดอาจถูกยกเลิกทั้งหมดและไม่มีการใช้งานเนมสเปซที่มีการจัดการอีกต่อไป ทำให้การระบุปัจจุบันอย่างชัดเจนโดยปริยาย

หากโค้ดอยู่ระหว่างใช้งานและยังไม่ได้แทนที่โค้ดปัจจุบัน การกำหนดโค้ดควรย้ายข้อมูลไปยัง "ถัดไป" หากโค้ดเป็นการแทนที่โค้ดปัจจุบัน การกำหนดรหัสควรย้ายข้อมูลไปยังเวอร์ชันปัจจุบัน

ใช้การกำหนดสถานะถัดไป หลังจากที่โค้ดผ่านจำนวนรอบการเผยแพร่และการประเมินที่ต้องการแล้ว การกำหนดจะย้ายไปยัง "ปัจจุบัน" หรือ "การกำหนดสถานะ" อาจถูกยกเลิกไปเลย

หากใช้การกำหนดปัจจุบัน หากโค้ดมีการแทนที่ด้วยโค้ดใหม่ แต่ยังคงต้องมีการดูแลรักษาเป็นเวลาหลายรอบการเผยแพร่ การกำหนดจะย้ายข้อมูลไปยังเวอร์ชันเดิม

แต่จากการระบุสถานะแบบเดิม โค้ดจะถูกนำออกจาก Weave SDK ในที่สุด

การใช้เนมสเปซที่มีการจัดการ

ผู้ใช้ Weave SDK อาจโต้ตอบกับเนมสเปซที่มีการจัดการในฐานะนักพัฒนาซอฟต์แวร์ ขยายและดูแลรักษาโค้ดที่มีอยู่ หรือในฐานะผู้ผสานการทำงานที่ผสานรวม Weave เข้ากับแอปพลิเคชัน แพลตฟอร์ม และโค้ดระบบของตน คำแนะนำแบบละเอียด 2 ส่วนต่อไปนี้มีไว้สำหรับการจัดการเนมสเปซที่มีการจัดการของ Weave จาก 2 มุมมองนี้

การใช้เนมสเปซที่มีการจัดการในฐานะนักพัฒนาซอฟต์แวร์

เป้าหมายหลักของนักพัฒนาซอฟต์แวร์ Weave SDK คือการปรับปรุงและพัฒนา API และฟังก์ชันการทำงานใหม่ๆ ของ Weave SDK API และในหลายๆ กรณี ในเวลาเดียวกันก็สนับสนุนการติดตั้งใช้งาน API และฟังก์ชันต่างๆ ที่มีอยู่ด้วย

ในกรณีที่ไม่สามารถตอบสนองทั้ง 2 ด้านนี้ได้อย่างเข้ากันแบบย้อนหลังภายใน API เดียวกัน เนมสเปซที่มีการจัดการจะมีกลไกในการจัดการ API เหล่านี้พร้อมกันในลักษณะที่ไม่รบกวนการทำให้ API และฟังก์ชันการทำงานที่มีอยู่ใช้งานได้

ตัวอย่างที่ใช้ได้คือ Mercury เป็นโปรไฟล์ Weave ซึ่งปัจจุบันอยู่ภายใต้ลำดับชั้นของเนมสเปซต่อไปนี้ที่ไม่มีการจัดการ

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 เป็นโมดูล "umbrella" ส่วนหัว ผู้ผสานรวมระบบส่วนใหญ่จะใช้เพียงโมดูล "umbrella" ส่วนหัวตามที่แสดง:

#include 

อย่างไรก็ตาม บริษัทพัฒนา Mercury ได้มาถึงจุดที่จำเป็นต้องพัฒนา API รุ่นถัดไป และอาจเป็นโปรโตคอลผ่านสายเคเบิลที่ไม่สามารถใช้ร่วมกับการติดตั้งใช้งานที่มีอยู่เดิมย้อนหลังได้ การใช้เนมสเปซที่มีการจัดการจะช่วยแก้ปัญหานี้ได้โดยไม่ทำให้การทำให้ใช้งานได้ที่มีอยู่เหล่านี้เสียหาย

ย้ายเนมสเปซที่มีอยู่ไปยังเนมสเปซปัจจุบัน

งานแรกคือการย้ายโค้ดปัจจุบันโดยมีเป้าหมายที่จะสนับสนุน API รุ่นปัจจุบันและฟังก์ชันสำหรับการผสานรวมที่ทำให้ใช้งานได้อยู่แล้วต่อไป

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

โปรดทราบว่านอกเหนือจากการย้ายไฟล์แล้ว ส่วนหัวรวมถึงการป้องกันสำหรับไฟล์ที่ถูกย้ายควรเปลี่ยนชื่อด้วย ซึ่งอาจตกแต่งไฟล์ด้วย "_CURRENT" เนื่องจากไฟล์ใหม่ที่มีชื่อเหมือนกันจะสร้างขึ้นในตำแหน่งด้านล่าง

เมื่อย้ายโค้ดแล้ว ขั้นตอนถัดไปคือการจัดการเนมสเปซที่มีการกำหนดที่เหมาะสมที่นี่ "ปัจจุบัน" ขั้นแรก ให้สร้างส่วนหัวที่กำหนดเนมสเปซที่มีการจัดการเป็น "Current/MercuryManagedNamespace.hpp" การสร้างส่วนหัวเช่นนี้ ขอแนะนำให้ทำซ้ำและทำซ้ำเนื้อหานี้ในไฟล์ส่วนหัวแต่ละไฟล์เมื่อมีไฟล์ส่วนหัวหลายไฟล์

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

#include <Weave/Support/ManagedNamespace.hpp>

#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 

สร้างส่วนหัวความเข้ากันได้

อย่างไรก็ตาม การย้ายส่วนหัวที่มีอยู่ไปยังตำแหน่งใหม่และจัดการเนมสเปซเพียงอย่างเดียวนั้นไม่เพียงพอที่จะทำให้การใช้งานที่มีอยู่จะทำงานโดยไม่มีการเปลี่ยนแปลง เนื่องจากทั้งหมดนี้ใช้คำสั่ง include ที่ระบุส่วนหัวที่เพิ่งย้ายไปอยู่ด้านบน

หากต้องการแก้ไขปัญหานี้ คุณต้องสร้างส่วนหัว Wrapper ความเข้ากันได้กับชื่อที่ตรงกับชื่อที่เพิ่งย้าย

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

หากมีการสร้างเฉพาะเนมสเปซที่มีการจัดการซึ่งมีการระบุในปัจจุบัน โดยไม่สร้างเนมสเปซที่มีการจัดการซึ่งกำหนดการพัฒนาหรือการกำหนดถัดไปเพื่อประกอบเข้ากับเนมสเปซดังกล่าว เนื้อหาของไฟล์เหล่านี้จะประกอบด้วยส่วนหัวที่มี guard และคำสั่ง include ที่ระบุส่วนหัวที่ย้ายใหม่ซึ่งมีชื่อเดียวกัน

#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 <Weave/Support/ManagedNamespace.hpp>

#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

โปรดทราบว่าค่าเริ่มต้นนี้จะกำหนดเนมสเปซที่มีการจัดการเป็น "ปัจจุบัน" ได้ตามต้องการ ถ้าไม่ได้กำหนดการกำหนดค่าไว้

เมื่อใช้ส่วนหัวนี้ คุณจะสามารถแก้ไขส่วนหัว Wrapper ความเข้ากันได้ให้มีสิ่งต่อไปนี้

#include 

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

หรืออะไรก็ตามที่เหมาะสำหรับกรณีการใช้งานการจัดการเนมสเปซที่มีอยู่

สร้างเนื้อหาการพัฒนา

ในตอนนี้ โครงสร้างพื้นฐานพร้อมแล้วที่จะเริ่มสร้างฟังก์ชันการทำงานและ API ใหม่ควบคู่ไปกับ API ที่มีอยู่

% 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 <Weave/Support/ManagedNamespace.hpp>

#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 คือการรวมส่วนหัว API สาธารณะของ Weave SDK ที่เหมาะสม และการผสานรวมและพัฒนาแอปพลิเคชันกับส่วนหัวเหล่านี้

ตัวอย่างที่ใช้ได้คือ Mercury เป็นโปรไฟล์ของ Weave ที่มีเนมสเปซที่มีการจัดการซึ่งกำหนดเป็น 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 เป็นโมดูล "umbrella" ส่วนหัว

เว้นแต่กรณีที่ Use Case นั้นกระตุ้นให้รวมโมดูลเนมสเปซที่มีการจัดการภายใน Weave อย่างชัดเจน ตัวอย่างเช่น

#include 

วิธีที่ดีที่สุดคือการอ้างอิงส่วนหัวสาธารณะของโมดูล Weave ตามเส้นทางที่เป็นค่าเริ่มต้นที่ไม่มีการจัดการ (เช่น Weave/Profiles/Mercury/Mercury.hpp) การทำเช่นนี้จะช่วยให้เกิดการพัฒนา API อย่างต่อเนื่องโดยไม่ต้องเปลี่ยนคำสั่งของโปรเจ็กต์อย่างต่อเนื่องเมื่อ API เหล่านั้นไหลผ่านวงจรที่มีการจัดการ

เมื่อทำตามกลยุทธ์นี้แล้ว การทำให้ใช้งานได้จะสามารถกำหนดเป้าหมายโค้ดใหม่ในการกำหนดเนมสเปซที่มีการจัดการแบบอื่น เช่น การระบุปัจจุบัน โดยระบุการกำหนดค่าที่ต้องการในตัวประมวลผล C/C++ ล่วงหน้า ซึ่งสามารถดำเนินการในบรรทัดคำสั่ง ในซอร์สโค้ด หรือในส่วนหัวของการกำหนดค่าหรือคำนำหน้า ดังนี้

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

และใช้เส้นทาง include ที่ไม่มีการจัดการ / ไม่เข้าเกณฑ์ ดังนี้

#include 

เมื่อใดและในกรณีที่การกำหนดเนมสเปซที่มีการจัดการมีการเปลี่ยนแปลงสำหรับ API เป้าหมาย เช่น จากปัจจุบันเป็นแบบเดิม เพียงกำหนดเป้าหมายใหม่โดยการปรับคำจำกัดความของผู้ประมวลผลข้อมูลล่วงหน้าดังนี้

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy