建立軟體包

Dart 生態系統使用 軟體包來共享軟體，如庫和工具。本頁介紹如何建立標準的共享 軟體包。

要建立軟體包的初始目錄和結構，請使用 dart create 命令和 package 模板

dart create -t package <PACKAGE_NAME>

下圖顯示了軟體包最簡單的佈局

庫的最低要求是：

pubspec 檔案

庫的 pubspec.yaml 檔案與應用程式軟體包的檔案相同——沒有特殊標記表明該軟體包是庫。

lib 目錄

正如您所料，庫程式碼位於 lib 目錄下，並對其他軟體包公開。您可以根據需要，在 lib 下建立任何層級結構。按照約定，實現程式碼放置在 lib/src 下。lib/src 下的程式碼被認為是私有的；其他軟體包通常不需要匯入 src/...。要使 lib/src 下的 API 公開，您可以從直接位於 lib 下的檔案中匯出 lib/src 檔案。

當您建立小型、獨立的庫（稱為迷你庫）時，軟體包最易於維護、擴充套件和測試。在大多數情況下，每個類都應位於自己的迷你庫中，除非您遇到兩個類緊密耦合的情況。

直接在 lib 下建立一個“主”庫檔案，即 lib/<package-name>.dart，該檔案匯出所有公共 API。這允許使用者透過匯入單個檔案來獲取庫的所有功能。

lib 目錄可能還包含其他可匯入的非 src 庫。例如，您的主庫可能跨平臺工作，但您建立了依賴於 dart:io 或 dart:js_interop 的單獨庫。一些軟體包有獨立的庫，旨在在主庫不被匯入字首時，透過字首匯入。

讓我們看看一個真實世界軟體包的組織結構：shelf。shelf 軟體包提供了一種使用 Dart 建立 Web 伺服器的簡便方法，並且其佈局結構是 Dart 軟體包常用的。

直接在 lib 下，主庫檔案 shelf.dart 從 lib/src 中的多個檔案匯出 API。為避免暴露超出預期的 API，並向開發者提供軟體包整個公共 API 的概覽，shelf.dart 使用 show 精確指定要匯出的符號

export 'src/cascade.dart' show Cascade;
export 'src/handler.dart' show Handler;
export 'src/hijack_exception.dart' show HijackException;
export 'src/middleware.dart' show Middleware, createMiddleware;
export 'src/middleware/add_chunked_encoding.dart' show addChunkedEncoding;
export 'src/middleware/logger.dart' show logRequests;
export 'src/middleware_extensions.dart' show MiddlewareExtensions;
export 'src/pipeline.dart' show Pipeline;
export 'src/request.dart' show Request;
export 'src/response.dart' show Response;
export 'src/server.dart' show Server;
export 'src/server_handler.dart' show ServerHandler;

shelf 軟體包還包含一個迷你庫：shelf_io。此介面卡處理來自 dart:io 的 HttpRequest 物件。

從其他軟體包匯入庫檔案時，使用 package: 指令來指定該檔案的 URI。

import 'package:utilities/utilities.dart';

從您自己的軟體包匯入庫檔案時，如果兩個檔案都在 lib 內部，或兩個檔案都在 lib 外部，請使用相對路徑。當匯入的檔案在 lib 中且匯入者在 lib 外部時，請使用 package:。

下圖顯示瞭如何從 lib 和 web 匯入 lib/foo/a.dart。

如果您的庫支援多個平臺，那麼您可能需要條件匯入或匯出庫檔案。一個常見的用例是同時支援 Web 和原生平臺的庫。

要條件匯入或匯出，您需要檢查是否存在 dart:* 庫。這是一個條件匯出程式碼示例，它檢查是否存在 dart:io 和 dart:js_interop：

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation

該程式碼的作用如下：

• 在可以使用 dart:io 的應用（例如，命令列應用）中，匯出 src/hw_io.dart。
• 在可以使用 dart:js_interop 的應用（Web 應用）中，匯出 src/hw_web.dart。
• 否則，匯出 src/hw_none.dart。

要條件匯入檔案，請使用與上述相同的程式碼，但將 export 更改為 import。

所有條件匯出的庫都必須實現相同的 API。例如，以下是 dart:io 的實現：

import 'dart:io';

void alarm([String? text]) {
  stderr.writeln(text ?? message);
}

String get message => 'Hello World from the VM!';

以下是預設實現，它使用丟擲 UnsupportedError 的存根：

void alarm([String? text]) => throw UnsupportedError('hw_none alarm');

String get message => throw UnsupportedError('hw_none message');

在任何平臺上，您都可以匯入包含條件匯出程式碼的庫。

import 'package:hw_mp/hw_mp.dart';

void main() {
  print(message);
}

精心設計的軟體包易於測試。我們建議您使用 test 軟體包編寫測試，並將測試程式碼放在軟體包頂層的 test 目錄下。

如果您建立了任何面向公眾使用的命令列工具，請將其放在公開的 bin 目錄下。使用 dart pub global activate 從命令列執行工具。在 pubspec 的 executables 部分中列出該工具，允許使用者直接執行它，而無需呼叫 dart pub global run。

如果包含如何使用庫的示例，將會很有幫助。這應放在軟體包頂層的 example 目錄下。

您在開發過程中建立的任何不供公眾使用的工具或可執行檔案都應放在 tool 目錄下。

如果您要將庫釋出到 pub.dev 網站，所需的其他檔案，如 README.md 和 CHANGELOG.md，已在 釋出軟體包中描述。有關如何組織軟體包目錄的更多資訊，請參閱 pub 軟體包佈局約定。

您可以使用 dart doc 工具為您的庫生成 API 文件。dart doc 會解析原始碼，查詢使用 /// 語法的 文件註釋。

/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

有關生成文件的示例，請參閱 shelf 文件。

要在生成的文件中包含任何 庫級文件，請新增 library 指令，並將註釋直接附加在其上方。有關編寫庫文件的方法和原因，請參閱 高效 Dart：文件。

如果您的庫是開源的，我們建議將其共享到 pub.dev 網站。要釋出或更新庫，請使用 pub publish，它會上傳您的軟體包並建立或更新其頁面。例如，請參閱 shelf 軟體包的頁面。有關如何準備軟體包以進行釋出的詳細資訊，請參閱 釋出軟體包。

pub.dev 網站不僅託管您的軟體包，還會生成並託管您軟體包的 API 參考文件。最新生成的文件連結位於軟體包的 關於框中；例如，請參閱 shelf 軟體包的 API 文件。指向先前版本文件的連結位於軟體包頁面的 版本選項卡中。

為確保您的軟體包 API 文件在 pub.dev 網站上呈現良好，請遵循以下步驟：

• 在釋出軟體包之前，執行 dart doc 工具，以確保您的文件成功生成並符合預期。
• 釋出軟體包後，檢查 版本選項卡，確保文件成功生成。
• 如果文件完全未能生成，請在 版本選項卡中點選 失敗以檢視 dart doc 的輸出。

使用以下資源瞭解更多關於軟體包的資訊：

• 庫和匯入涵蓋了庫檔案的使用。
• 軟體包文件很有用，特別是軟體包佈局約定。
• 不應提交的內容涵蓋了不應檢入原始碼倉庫的內容。
• dart-lang組織下的新軟體包傾向於展示最佳實踐。請考慮研究這些示例：dart_style、path、shelf、source_gen和test。