Google cam kết thúc đẩy công bằng chủng tộc cho Cộng đồng người da đen. Xem cách thực hiện.

Trang này được dịch bởi Cloud Translation API.

Không gian tên được quản lý

Tóm tắt

Giới thiệu

Không gian tên được quản lý được sử dụng trong SDK Weave để cung cấp cho cả nhà phát triển và nhà tích hợp SDK Weave thông tin hướng dẫn và nội dung phụ về việc chỉ định các nhóm API cụ thể trong SDK. Nhờ đó, họ có thể lập kế hoạch và dự đoán lộ trình di chuyển trên các bản phát hành SDK của Weave và có thể quản lý nhiều API Weave đồng thời cho một mô-đun nhất định.

Chỉ định

Bạn có thể quản lý vùng chứa tên được quản lý theo một trong 4 cách chỉ định sau:

Quá trình phát triển

Mọi không gian tên được quản lý bằng chỉ định Phát triển đều là chỉ báo cho các nhà phát triển và nhà tích hợp biết rằng các API có trong đó đang trong quá trình phát triển tích cực, có thể thay đổi và không được hỗ trợ chính thức. Các nhà tích hợp thường không nên sử dụng các API này trừ phi được hướng dẫn cụ thể về việc sử dụng.

Bất kỳ không gian tên nào được quản lý bằng chỉ định Next đều là một chỉ báo cho các nhà phát triển và nhà tích hợp biết rằng các API có trong đó dù phần lớn đã hoàn thành phần lớn quá trình phát triển nhưng vẫn có thể thay đổi và được hỗ trợ cho mục đích đánh giá sớm. Các API được chỉ định đại diện cho mặt trước tiếp theo trong API Weave SDK và sẽ trở thành các API mặc định, hiện tại ở chu kỳ thay đổi chính trong thời gian sắp tới.

Khả năng tương thích ngược, cả từ góc độ API và giao thức không dây, có thể tồn tại nhưng không được đảm bảo trong các API được chỉ định.

Việc chỉ định không gian tên được quản lý Next một cách hiệu quả giúp các nhà phát triển và nhà tích hợp nắm được hướng đi của SDK Weave bằng cách gợi ý API nào sẽ trở thành API mặc định, hiện tại trong bản phát hành sau này.

Bạn không bắt buộc phải chỉ định không gian tên được quản lý Tiếp theo để không gian tên được quản lý có thể chuyển đổi trong một vòng đời mà không cần sử dụng (xem phần Vòng đời không gian tên được quản lý).

Hồ sơ

Mọi không gian tên được quản lý bằng chỉ định Hiện tại hoặc bất kỳ không gian tên không được quản lý nào (tức là thiếu thông tin chỉ định không gian tên được quản lý) đều đại diện cho API hiện tại, mặc định, được hỗ trợ chính thức cho phần hoặc mô-đun đó của Weave SDK. Mặc dù vẫn có thể không ngừng cải tiến các API như vậy, nhưng các thay đổi phần lớn sẽ là khả năng tương thích ngược và gia tăng dần. Các API này cần được duy trì.

Bạn không bắt buộc phải chỉ định không gian tên được quản lý hiện tại để không gian tên được quản lý có thể chuyển đổi trong một vòng đời mà không cần sử dụng tên đó (xem phần Vòng đời không gian tên được quản lý). Trên thực tế, mọi không gian tên không được quản lý đều được đặt hoàn toàn là Dòng thời gian.

Cũ

Mọi không gian tên được quản lý bằng chỉ định Cũ đều là một chỉ báo cho các nhà phát triển và nhà tích hợp biết rằng các API có trong đó không còn được dùng nữa và được thay thế bằng một API mới, hiện tại. Các API này đại diện cho API trước đây là API hiện tại.

Các API được chỉ định sẽ biến mất hoàn toàn trong bản phát hành chính tiếp theo của Weave SDK; do đó, nhà phát triển và nhà tích hợp nên lên kế hoạch di chuyển khỏi các API này nếu có ý định tiếp tục sử dụng các bản phát hành SDK của Weave.

Vòng đời không gian tên được quản lý

Hình dưới đây minh hoạ vòng đời của vùng chứa tên được quản lý khi vùng chứa tên này chuyển đổi từ giai đoạn Phát triển và có thể là cũ:

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

Nếu bạn sử dụng không gian tên đó, vòng đời không gian tên được quản lý sẽ bắt đầu bằng chỉ định Phát triển.

Khi quá trình phát triển hoàn tất và mã đã sẵn sàng để đánh giá cũng như tích hợp, trạng thái chỉ định sẽ chuyển sang trạng thái Tiếp theo hoặc Hiện tại. Ngoài ra, hệ thống có thể loại bỏ hoàn toàn thông tin chỉ định và vùng chứa tên được quản lý không còn được sử dụng nữa. Điều này có nghĩa là chỉ định này có thể được ngầm định là Hiện tại.

Nếu mã này tồn tại song song và chưa thay thế cho mã hiện tại, thì chỉ định sẽ chuyển sang Tiếp theo. Nếu mã này thay thế mã hiện tại, thì chỉ định sẽ chuyển sang trạng thái Hiện tại.

Khi sử dụng Chỉ định Tiếp theo, sau khi mã trải qua số chu kỳ phát hành và đánh giá mong muốn, chỉ định này chuyển sang Chỉ định hiện tại hoặc một lần nữa, Chỉ định có thể bị loại bỏ hoàn toàn.

Khi sử dụng chỉ định Hiện tại, nếu mã mới được thay thế bằng mã mới nhưng vẫn cần được duy trì trong một số chu kỳ phát hành, thì chỉ định sẽ chuyển sang Phiên bản cũ.

Từ chỉ định Kế thừa, mã cuối cùng sẽ bị xoá hoàn toàn khỏi SDK Weave.

Sử dụng vùng tên được quản lý

Người dùng Weave SDK có thể tương tác với không gian tên được quản lý với tư cách là nhà phát triển, mở rộng và duy trì mã hiện có hoặc với tư cách là nhà tích hợp, tích hợp Weave vào ứng dụng, nền tảng và mã hệ thống của riêng họ. Hai phần sau đây trình bày chi tiết các đề xuất về cách xử lý không gian tên do Weave quản lý theo hai góc nhìn đó.

Sử dụng Không gian tên được quản lý với tư cách là Nhà phát triển

Trọng tâm chính của nhà phát triển Weave SDK là cải thiện và phát triển các API cũng như chức năng mới của Weave SDK, đồng thời hỗ trợ các triển khai API và chức năng hiện có.

Trong trường hợp không thể đáp ứng cả hai khía cạnh trọng tâm này theo cách tương thích ngược trong cùng một API, vùng chứa tên được quản lý sẽ cung cấp cơ chế quản lý song song các API này theo cách không làm gián đoạn việc triển khai API và chức năng hiện có.

Một ví dụ đang hoạt động là giả sử một hồ sơ Weave, Mercury, hiện đang tồn tại trong hệ phân cấp không gian tên không được quản lý sau đây:

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

// ...

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

và các tiêu đề công khai sau đây:

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

trong đó Mercury.hpp là tiêu đề mô-đun "ô". Hầu hết các trình tích hợp chỉ bao gồm tiêu đề "ô" của mô-đun như sau:

#include

Tuy nhiên, sự phát triển của Mercury hiện đã đạt đến mức cần thiết phải phát triển thế hệ API tiếp theo và có khả năng là giao thức không dây không tương thích ngược với các hoạt động triển khai hiện có. Việc sử dụng không gian tên được quản lý có thể giúp bạn làm được việc này mà không làm hỏng các hoạt động triển khai hiện có.

Di chuyển vùng tên hiện tại sang vùng tên hiện tại

Với mục tiêu tiếp tục hỗ trợ bản phát hành API hiện tại và chức năng cho các công cụ tích hợp đã triển khai hiện có, nhiệm vụ đầu tiên là di chuyển mã hiện tại:

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

Lưu ý: ngoài việc di chuyển tệp, tiêu đề có các trình bảo vệ cho tệp đã di chuyển cũng nên được đổi tên và có thể trang trí chúng bằng "_CURRENT", vì các tệp mới, có tên tương tự sẽ được tạo ở vị trí bên dưới.

Khi mã được di chuyển, bước tiếp theo là quản lý không gian tên có chỉ định phù hợp, tại đây là "Current" (Hiện tại). Trước tiên, hãy tạo một tiêu đề xác định không gian tên được quản lý, dưới dạng "Current/MercuryManagedNamespace.hpp". Bạn nên tạo tiêu đề như vậy để lặp lại nội dung này trong từng tệp tiêu đề khi có nhiều tệp tiêu đề.

% 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

Tiếp theo, hãy đưa tiêu đề này vào trước các lệnh include khác dành riêng cho mô-đun trong tiêu đề hiện có. Ví dụ:

#include 

#include

Tạo tiêu đề tương thích

Tuy nhiên, việc di chuyển các tiêu đề hiện có sang vị trí mới và chỉ quản lý không gian tên của chúng là chưa đủ để đảm bảo rằng các hoạt động triển khai hiện tại sẽ hoạt động mà không có thay đổi nào vì tất cả đều sử dụng lệnh bao gồm các tiêu đề vừa được di chuyển ở trên.

Để giải quyết vấn đề này, bạn phải tạo các tiêu đề của trình bao bọc khả năng tương thích có tên khớp với các tiêu đề vừa được di chuyển.

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

Nếu bạn chỉ tạo một không gian tên được quản lý do chỉ định Hiện tại mà không tạo không gian tên được quản lý là Phát triển hoặc Tiếp theo đi kèm, thì nội dung của các tệp này có thể chỉ cần bao gồm một tiêu đề gồm tiêu đề bảo vệ và một lệnh include chỉ định tiêu đề mới di chuyển có cùng tên:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Tuy nhiên, nếu một không gian tên được quản lý là Phát triển hoặc Tiếp theo đang được tạo ra để đáp ứng quá trình phát triển mới, không tương thích, thì bạn cần cải thiện một chút.

Như trước đây, một tiêu đề cho cấu hình không gian tên được quản lý sẽ được tạo, tại đây dưới dạng MercuryManagedNamespace.hpp. Xin nhắc lại, bạn nên lặp lại nội dung này trong từng tệp tiêu đề khi có nhiều tệp tiêu đề.

% 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

Xin lưu ý rằng, như mong muốn, vùng chứa tên được quản lý sẽ được chỉ định là "Hiện tại" mặc định nếu chưa xác định cấu hình nào.

Với tiêu đề này, bạn hiện có thể chỉnh sửa các tiêu đề của trình bao bọc khả năng tương thích để chứa:

#include 

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

hoặc bất kỳ thành phần nào phù hợp với trường hợp sử dụng quản lý không gian tên đang dùng.

Tạo nội dung phát triển

Hiện tại, cơ sở hạ tầng đã sẵn sàng để bắt đầu xây dựng chức năng và API mới cùng với các chức năng và API hiện có.

% 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

Tất nhiên, nếu một mô-đun đơn giản hơn nhiều so với ví dụ trình bày ở đây và không có nhiều lớp, nguồn, tệp hoặc tiêu đề, thì bạn có thể thực hiện tất cả những điều này trong cùng một tệp tiêu đề mà không cần di chuyển tệp xung quanh cũng như tạo nhiều tiêu đề cấu hình và khả năng tương thích độc lập. Tuy nhiên, qua ví dụ phức tạp này, nó sẽ truyền cảm hứng cho các giải pháp không gian tên được quản lý theo một chuỗi từ phức tạp đến đơn giản.

Sử dụng không gian tên được quản lý làm công cụ tích hợp

Trọng tâm chính của nhà tích hợp SDK Weave là bao gồm các tiêu đề API công khai Weave SDK thích hợp, đồng thời tích hợp và phát triển các ứng dụng dựa trên các tiêu đề đó.

Như một ví dụ minh hoạ, một lần nữa giả sử một hồ sơ Weave có tên là Mercury, có các không gian tên được quản lý là Next-, current- và Legacy. Các tiêu đề công khai có cấu trúc như sau:

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

trong đó Mercury.hpp là tiêu đề mô-đun "ô".

Trừ phi trường hợp sử dụng hiện tại thúc đẩy việc thêm mô-đun không gian tên được quản lý trong Weave một cách rõ ràng, ví dụ:

#include

tốt nhất là tham chiếu các tiêu đề công khai của mô-đun Weave theo đường dẫn mặc định, không được quản lý của chúng (ví dụ: Weave/Profiles/Mercury/Mercury.hpp). Nhờ vậy, bạn có thể tiếp tục phát triển API mà không cần liên tục thay đổi các lệnh include của dự án khi các API đó lưu chuyển qua lifecycle được quản lý.

Theo chiến lược này, quá trình triển khai có thể nhắm mục tiêu lại mã theo chỉ định không gian tên được quản lý khác, chẳng hạn như chỉ định Hiện tại bằng cách chỉ định cấu hình mong muốn trong bộ tiền xử lý C/C++. Bạn có thể thực hiện việc này qua dòng lệnh, trong mã nguồn hoặc trong tiêu đề cấu hình hoặc tiền tố:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

và sử dụng đường dẫn không được quản lý / chưa đủ điều kiện bao gồm:

#include

Khi thông tin chỉ định không gian tên được quản lý thay đổi đối với các API được nhắm mục tiêu (ví dụ: từ Hiện tại thành Cũ), bạn chỉ cần nhắm mục tiêu lại bằng cách điều chỉnh định nghĩa của bộ tiền xử lý:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy