內容

套件佈局慣例

當您建立 pub 套件 時,我們建議您遵循本頁所述的慣例。它們說明如何整理套件內的檔案和目錄,以及如何命名項目。

以下是可能使用這些準則各個角落的完整套件 (名為 enchilada) 的範例

enchilada/
  .dart_tool/ *
  pubspec.yaml
  pubspec.lock **
  LICENSE
  README.md
  CHANGELOG.md
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ***
    getting_started.md
  example/
    main.dart
  hook/
    build.dart
  integration_test/
    app_test.dart
  lib/
    enchilada.dart
    tortilla.dart
    guacamole.css
    src/
      beans.dart
      queso.dart
  test/
    enchilada_test.dart
    tortilla_test.dart
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

* 執行 dart pub get 後,.dart_tool/ 目錄就會存在。請勿將其提交至原始碼控制。如需進一步瞭解,請參閱 專案特定工具快取

** 執行 dart pub get 後,pubspec.lock 檔案就會存在。除非您的套件是 應用程式套件,否則請勿將其納入原始碼控制。

*** 執行 dart doc 後,doc/api 目錄就會在本地存在。請勿將 api 目錄提交至原始碼控制。

pubspec

#
enchilada/
  pubspec.yaml
  pubspec.lock

每個套件在套件的根目錄中都有一個 pubspec,即一個名為 pubspec.yaml 的檔案。這就是它成為套件的原因。

在套件上執行 dart pub getdart pub upgradedart pub downgrade 會建立一個名為 pubspec.lock鎖定檔。如果您的套件是 應用程式套件,請將鎖定檔提交至原始碼控制。否則,請勿提交。

如需進一步資訊,請參閱 pubspec 頁面

LICENSE

#
enchilada/
  LICENSE

如果您要發布套件,請包含一個名為 LICENSE 的授權檔案。我們建議使用 OSI 核准的授權,例如 BSD-3-Clause,以便其他人可以重複使用您的作品。

README.md

#
enchilada/
  README.md

開源中非常常見的一個檔案是描述專案的 README 檔案。這在 pub 中特別重要。當您上傳到 pub.dev 網站 時,您的 README.md 檔案會顯示在套件頁面上,並以 Markdown 呈現。這是向人們介紹您的程式碼的絕佳位置。

有關如何撰寫精采 README 的指南,請參閱 撰寫套件頁面

CHANGELOG.md

#
enchilada/
  CHANGELOG.md

包含一個 CHANGELOG.md 檔案,其中包含套件每個版本的區段,並附有說明,以協助套件使用者升級。套件使用者通常會檢閱變更日誌以找出錯誤修正和新功能,或確定升級到套件最新版本的難度。

若要支援剖析 CHANGELOG.md 的工具,請使用下列格式

  • 每個版本都有自己的區段,並附有標題。
  • 版本標題全部都是 1 級或 2 級。
  • 版本標題文字包含套件版本號碼,前面可以選擇加上「v」作為前綴。

當您將套件上傳到 pub.dev 網站 時,套件的 CHANGELOG.md 檔案(如果有)會顯示在 變更日誌 標籤中,並以 Markdown 呈現。

以下是 CHANGELOG.md 檔案的範例。如範例所示,您可以新增小節。

markdown
# 1.0.1

* Fixed missing exclamation mark in `sayHi()` method.

# 1.0.0

* **Breaking change:** Removed deprecated `sayHello()` method.
* Initial stable release.

## Upgrading from 0.1.x

Change all calls to `sayHello()` to instead be to `sayHi()`.

# 0.1.1

* Deprecated the `sayHello()` method; use `sayHi()` instead.

# 0.1.0

* Initial development release.

公開目錄

#

套件中的兩個目錄對其他套件公開:libbin。您將 公開函式庫 放置在 lib 中,並將 公開工具 放置在 bin 中。

公開函式庫

#

下列目錄結構顯示 enchilada 的 lib 部分

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

許多 套件 定義其他套件可以匯入和使用的 Dart 函式庫。這些公開的 Dart 函式庫檔案會放在名為 lib 的目錄中。

大多數套件會定義一個使用者可以匯入的單一函式庫。在這種情況下,其名稱通常應該與套件名稱相同,例如此處範例中的 enchilada.dart。但您也可以定義其他函式庫,其名稱應符合您的套件意義。

當您這麼做時,使用者可以使用套件和程式庫檔案的名稱來匯入這些程式庫,如下所示

dart
import 'package:enchilada/enchilada.dart';
import 'package:enchilada/tortilla.dart';

如果您想整理您的公開程式庫,您也可以在 lib 內建立子目錄。如果您這麼做,使用者在匯入時會指定該路徑。假設您有下列檔案層級

enchilada/
  lib/
    some/
      path/
        olives.dart

使用者會如下匯入 olives.dart

dart
import 'package:enchilada/some/path/olives.dart';

請注意,只有程式庫應該在 lib 內。入口點(具有 main() 函式的 Dart 程式碼)不能放在 lib 內。如果您將 Dart 程式碼放在 lib 內,您會發現其中包含的任何 package: 匯入都無法解析。相反地,您的入口點應該放在適當的 入口點目錄 中。

如需有關套件的更多資訊,請參閱 建立套件

公開工具

#

放置在 bin 目錄內的 Dart 程式碼是公開的。如果您在套件的目錄內,您可以使用 dart run 來執行套件所依賴的任何其他套件的 bin 目錄中的程式碼。從任何目錄,您可以 執行程式碼,這些程式碼來自您已使用 dart pub global activate 啟用的套件。

如果您打算讓您的套件被依賴,而且您希望您的程式碼對您的套件是私密的,請將它們放在頂層 tool 目錄中。如果您不打算讓您的套件被依賴,您可以將您的程式碼留在 bin 中。

公開資產

#
enchilada/
  lib/
    guacamole.css

雖然大多數套件的存在是為了讓您重複使用 Dart 程式碼,但您也可以重複使用其他類型的內容。例如,Bootstrap 的套件可能包含多個 CSS 檔案供套件使用者使用。

這些檔案會放在頂層 lib 目錄中。您可以將任何類型的檔案放在那裡,並使用子目錄隨意整理。

實作檔案

#
enchilada/
  lib/
    src/
      beans.dart
      queso.dart

lib 內的程式庫是公開可見的:其他套件可以自由匯入它們。但是,套件的大部分程式碼都是內部實作程式庫,這些程式庫應該只由套件本身匯入和使用。這些程式庫會放在 lib 的一個子目錄中,稱為 src。如果您需要整理事物,您可以在其中建立子目錄。

你可以自由地從同一個套件中的其他 Dart 程式碼匯入位於 lib/src 的函式庫(就像 lib 中的其他函式庫、bin 中的指令碼和測試),但你絕不應該從其他套件的 lib/src 目錄匯入。這些檔案不是套件公開 API 的一部分,它們可能會以破壞你程式碼的方式變更。

你從自己的套件匯入函式庫的方式取決於函式庫的位置

例如

lib/beans.dart
dart
// When importing from within lib:
import 'src/beans.dart';
test/beans_test.dart
dart
// When importing from outside lib:
import 'package:enchilada/src/beans.dart';

你在此處使用的名稱(在本例中為 enchilada)是你在其 pubspec 中為套件指定的。

網頁檔案

#
enchilada/
  web/
    index.html
    main.dart
    style.css

對於網路套件,請將進入點程式碼(包括 main() 的 Dart 程式碼和支援檔案,例如 CSS 或 HTML)放在 web 下。如果你願意,可以將 web 目錄整理成子目錄。

函式庫程式碼 放在 lib 下。如果函式庫未由 web 下的程式碼或其他套件直接匯入,請將其放在 lib/src 下。將 基於網路的範例 放在 example 下。請參閱 公開資產 以取得有關放置資產(例如影像)的提示。

命令列應用程式

#
enchilada/
  bin/
    enchilada

有些套件定義可以直接從命令列執行的程式。這些程式可以是 shell 程式碼或任何其他指令碼語言,包括 Dart。

如果你的套件定義了此類程式碼,請將其放在名為 bin 的目錄中。如果你使用 dart pub global 設定它,你可以從命令列上的任何位置執行該指令碼。

測試和基準

#
enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

每個套件都應該有測試。使用 pub 時,慣例是將這些測試中的大部分放在 test 目錄(或其內部的某個目錄,如果你願意)中,並在其檔案名稱的結尾加上 _test

通常,這些測試使用 test 套件。

enchilada/
  integration_test/
    app_test.dart

Flutter 應用程式套件也可能有特殊的整合測試,這些測試使用 integration_test 套件。這些測試存在於自己的 integration_test 目錄中。

其他套件可能會選擇遵循類似的模式,將較慢的整合測試與單元測試分開,但請注意,預設情況下 dart test 不會執行這些測試。你必須使用 dart test integration_test 明確執行它們。

enchilada/
  benchmark/
    make_lunch.dart

具有效能關鍵程式碼的套件也可能包含 基準測試。這些測試不是針對正確性測試 API,而是針對速度(或記憶體使用,或其他經驗指標)測試 API。

文件

#
enchilada/
  doc/
    api/
    getting_started.md

如果您有程式碼和測試,您可能想要的下一個部分就是良好的文件。它會放在一個名為 doc 的目錄中。

當您執行 dart doc 工具時,它會將 API 文件預設放置在 doc/api 中。由於 API 文件是由原始程式碼產生的,因此您不應該將它放在原始碼控管中。

除了產生的 api 外,我們對於您撰寫的文件格式或組織方式沒有任何準則。請使用您偏好的任何標記格式。

範例

#
enchilada/
  example/
    main.dart

程式碼、測試、文件,您的使用者還能想要什麼?當然是使用您的套件的獨立範例程式!這些會放在 example 目錄中。如果範例很複雜並使用多個檔案,請考慮為每個範例建立一個目錄。否則,您可以將每個範例直接放在 example 中。

在您的範例中,請使用 package: 來匯入您自己的套件中的檔案。這可確保您的套件中的範例程式碼看起來完全就像套件外部的程式碼一樣。

如果您可能會發布您的套件,請考慮建立一個範例檔案,其名稱為下列其中之一

  • example/example[.md]
  • example[/lib]/main.dart
  • example[/lib]/package_name.dart
  • example[/lib]/package_name_example.dart
  • example[/lib]/example.dart
  • example/README[.md]

當您發布一個包含以上檔案之一或多個檔案的套件時,pub.dev 網站會建立一個 範例 標籤來顯示它找到的第一個檔案(按上述清單中顯示的順序搜尋)。例如,如果您的套件在其 example 目錄中有許多檔案,包括一個名為 README.md 的檔案,則您的套件的範例標籤會顯示 example/README.md 的內容(解析為 Markdown)。

內部工具和指令碼

#
enchilada/
  tool/
    generate_docs.dart

成熟的套件通常有小型的輔助腳本和程式,人們在開發套件本身時會執行這些腳本和程式。想想看像測試執行器、文件產生器或其他自動化程式碼之類的東西。

bin 中的腳本不同,這些 不是 給套件的外部使用者使用的。如果您有其中任何一個,請將它們放在一個名為 tool 的目錄中。

掛勾

#
enchilada/
  hook/
    build.dart

套件可以定義由 Dart 和 Flutter SDK 呼叫的掛勾。這些掛勾有預先定義的 CLI,如果存在,SDK 工具將會呼叫它們。

由於這些掛勾是由 dartflutter 工具在執行和建置時呼叫,因此這些掛勾的依賴項必須是常規依賴項,而不是 dev_dependencies

工具專用的專案快取

#

執行 dart pub get 時會建立 .dart_tool/ 目錄,且隨時可能會將其刪除。各種工具會使用此目錄快取專屬於您的專案和/或本機電腦的檔案。切勿將 .dart_tool/ 目錄提交至原始碼控制,或在電腦之間複製。

刪除 .dart_tool/ 目錄通常也是安全的,儘管某些工具可能需要重新計算快取資訊。

範例: dart pub get 工具會將依賴項下載並解壓縮至全域 $PUB_CACHE 目錄,然後撰寫 .dart_tool/package_config.json 檔案,將套件名稱對應至全域 $PUB_CACHE 目錄中的目錄。當分析器和編譯器需要解析 import 'package:foo/foo.dart' 等陳述式時,會使用 .dart_tool/package_config.json 檔案。

在開發需要專案特定快取的工具時,您可以考慮使用 .dart_tool/ 目錄,因為大多數使用者已使用 .gitignore 忽略它。在使用者的 .dart_tool/ 目錄中快取工具檔案時,您應該使用唯一的子目錄。為了避免衝突,.dart_tool/<tool_package_name>/ 形式的子目錄保留給名為 <tool_package_name> 的套件。如果您的工具並未透過 pub.dev 網站 發布,您可以考慮發布一個佔位套件,以保留唯一的名稱。

範例: package:build 提供一個用於撰寫程式碼產生步驟的架構。在執行這些建置步驟時,檔案會快取在 .dart_tool/build/ 中。這有助於加速未來重新執行建置步驟。