代管命名空間
摘要
簡介
Weave SDK 中使用代管命名空間，為 Weave SDK 開發人員和整合商一樣，針對 SDK 內特定 API 組合的設計提供通告指南和副文字，方便他們規劃和預測整個 Weave SDK 版本的遷移路徑，甚至可能管理指定模組的多個並行 Weave API。
職稱
受管理的命名空間可以做為下列四種主題的管理：
開發
凡是透過「開發」指定管理的命名空間，都代表開發人員和整合商瞭解其中所含的 API 仍在開發階段、隨時可能變更，也不獲得正式支援。除非整合商明確指示，否則不建議使用這些 API。
繼續
透過 Next 標示管理的任何命名空間可指示開發人員和整合商，即便其中所含的 API 已大部分完成主動開發，可能仍隨時可能變更，並且支援早期評估。指定 API 代表 Weave SDK API 的下一個進化前端，並會在不久的不久後成為現行的預設 API。
從 API 和無線通訊協定的角度來看，回溯相容性可能存在，但無法保證 API 的保證。
「Next 代管的命名空間」標示能提示開發人員和整合商瞭解未來版本將支援哪些 Weave SDK，藉此掌握 Weave SDK 的發展方向。
下一個代管命名空間是選擇性的，如此一來，代管命名空間可能會在不使用該生命週期的情況下轉換整個生命週期 (請參閱代管命名空間生命週期)。
目前
凡是透過「目前的指定名稱」管理的命名空間，或任何非受管命名空間 (意即沒有指定代管命名空間) 都代表 Weave SDK 該部分或模組目前、預設且官方支援的 API。雖然這類 API 可能還會持續強化，但大部分變更將會漸進且回溯相容性，但 API 和無線更新都應維持原樣。
「目前代管的命名空間」是選擇性的，因此代管命名空間可能會在不使用該生命週期的情況下轉換到生命週期 (請參閱代管命名空間生命週期)。事實上，所有非代管的命名空間都是隱含的。
舊版
任何透過舊版標示管理的命名空間，都代表開發人員和整合商指出包含的 API 已淘汰，並取代目前最新的 API。這些 API 代表的是舊版目前的 API。
因此指定的 API 會在下一個主要 Weave SDK 版本中完全消失。因此，如果開發人員和整合商打算保留 Weave SDK 的頂尖版本，開發人員和整合人員應就這些 API 的遷移作業規劃遷移計畫。
代管命名空間生命週期
下圖說明代管命名空間從開發和可能轉換為舊版的生命週期：
.-------------. .- - - . .- - - - -. .--------. | Development | -.-> Next -.-> Current ---> | Legacy | '-------------' | '- - - ' | ' - - - - ' '--------' | | '-------------'
如果採用的話，代管命名空間生命週期會從「開發」的指定開始著手。
當開發完成後，程式碼可供評估和整合時，標示會遷移至「Next」或「Current」。或者，您也可以完全捨棄指定，並且不再使用代管命名空間，有效使標示隱含的「Current」。
如果程式碼是與程式碼一起使用，但尚未取代目前的程式碼，則標示應遷移到 Next。如果程式碼是要取代目前的程式碼，則標示應遷移至 Current。
使用 Next 標示時，在程式碼完成所需的版本和評估週期後，標示會遷移至 Current，或再次捨棄指定。
使用「Current」標示時，如果程式碼需要由新程式碼取代，但仍需維護多個發布週期，標示會遷移至「舊版」。
從舊版的標示中，程式碼最終會完全從 Weave SDK 中移除。
使用代管執行個體群組
Weave SDK 使用者可以以開發人員身分與受管理的命名空間互動，也可以擴充和維護現有程式碼，或是成為整合商，將 Weave 整合至自己的應用程式、平台和系統程式碼中。以下兩個章節將詳細說明從這兩個觀點處理 Weave 代管的命名空間。
以開發人員的身分使用代管命名空間
Weave SDK 開發人員的重點在於強化及開發新的 Weave SDK API 和功能，並在許多情況下，同時支援現有 API 和功能部署。
如果無法在同一 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 是「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」)。首先，建立一個將代管命名空間定義為「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
建立相容性標頭
不過，將現有標頭移至新的位置及管理其命名空間並不足以確保現有的部署可在不變更的情況下運作，因為它們全都使用了在上方移動指定標頭的 include 指令。
為解決這個問題，必須建立名稱與剛才移動相符的相容性包裝函式標頭。
% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp如果只建立一個目前指定的代管命名空間，而未一併建立開發或下一個指定的代管命名空間，則這些檔案的內容可直接包含標頭 include 和 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
請注意，這在需要時，代管命名空間的指定名稱是「Current」 (如有需要)。如未定義任何設定
有了這個標頭，您現在可以編輯相容性包裝函式標頭，使其包含以下內容：
#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 整合商的重點在於納入適當的 Weave SDK 公用 API 標頭，以及針對這些標頭整合及開發應用程式。
我們再舉一個實際範例來假設：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 是「umbrella」標題。
除非當下的用途明確，否則在 Weave 內明確加入命名空間管理模組，例如：
#include
因此，建議您使用未受管理的預設路徑參照 Weave 模組的公開標頭 (例如 Weave/Profiles/Mercury/Mercury.hpp)。這樣您就能追蹤 API 開發作業的進度，而不必持續變更專案的 include 指令，這些 API 會在代管生命週期中生效。
採用這項策略後，部署作業就能重新鎖定其程式碼，採用不同的代管命名空間標示 (例如「Current 」屬性)，方法是在 C/C++ 預先處理器中指定所需設定。您可以在指令列、原始碼、設定或前置字串標頭中執行這項操作：
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current並使用未受管理 / 不合格的 include 路徑：
#include
當目標 API 的代管命名空間標示變更 (例如從 Current 改為舊版) 時，只要調整預先處理器定義即可重新指定目標即可：
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy