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

สรุป

เกริ่นนำ

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

การระบุ

เนมสเปซที่มีการจัดการอาจได้รับการจัดการเป็นแบบใดแบบหนึ่งจาก 4 แบบ ดังนี้

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

การพัฒนา

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

ถัดไป

เนมสเปซที่จัดการด้วยการกำหนด Next เป็นเครื่องบ่งชี้ให้นักพัฒนาซอฟต์แวร์และผู้รวมระบบทราบว่า 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 ต่อไป

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

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

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

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

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

หากโค้ดจะอยู่ข้างๆ และยังไม่ได้แทนที่โค้ดปัจจุบัน การกำหนดดังกล่าวควรย้ายไปยัง Next หากโค้ดคือการแทนที่โค้ดปัจจุบัน การระบุสถานะควรย้ายข้อมูลไปยังส่วนปัจจุบัน

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

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

เมื่อมีการกำหนดเวอร์ชันเดิม โค้ดดังกล่าวจะถูกนำออกจาก Weave SDK ทั้งหมด

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

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

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

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

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

สำหรับตัวอย่างที่ใช้งานได้ สมมติว่ามีโปรไฟล์ 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 ได้มาถึงจุดที่จำเป็นต้องมีการพัฒนา 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 

#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 

สร้างส่วนหัวที่เข้ากันได้

อย่างไรก็ตาม การย้ายส่วนหัวที่มีอยู่ไปยังตำแหน่งใหม่และจัดการเนมสเปซอย่างเดียวนั้นไม่เพียงพอที่จะตรวจสอบว่าการทำให้ใช้งานได้ที่มีอยู่จะทำงานโดยไม่มีการเปลี่ยนแปลง เนื่องจากทั้งหมดใช้คำสั่ง 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 

#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 

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

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

• 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) การทำเช่นนี้จะช่วยให้มีการพัฒนา API ต่อไปโดยไม่ต้องเปลี่ยนแปลงคำสั่ง include ของโปรเจ็กต์อย่างต่อเนื่องเมื่อ API เหล่านั้นไหลผ่านlifecycleที่มีการจัดการ

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

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

#include 

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy