Dart基礎之 庫（libraries）和可見性（visibility）

前言

import和library指令能夠幫助你建立模塊化且可共享的代碼庫。 庫（library）不只提供API，並且是隱私的單元：如下劃線（_）開頭的標識符僅在庫內部可見。 每一個Dart應用程序都是一個庫，即便它不使用library指令。

庫可使用包分發。

使用庫

使用import指定一個庫的命名空間在另一個庫的範圍中使用。

例如，Dart Web應用程序一般使用dart:html庫，能夠像這樣導入：

import 'dart:html';
複製代碼

import的惟一必需參數是指定庫的URI。 對於內置庫，URI具備特殊的dart:scheme。 對於其餘庫，可使用文件系統路徑或package:scheme。 package:scheme指定的庫由包管理器（例如pub工具）提供。 例如：

import 'package:test/test.dart';
複製代碼

注意：URI表明統一資源標識符。 URL（統一資源定位符）是一種常見的URI。

指定一個庫的前綴

若是你導入兩個庫，這兩個庫衝突了，那麼能夠爲一個或兩個庫指定一個前綴。 例如，若是library1和library2都具備Element類，那麼你可能使用如下代碼：

import 'package:lib1/lib1.dart';
import 'package:lib2/lib2.dart' as lib2;

// 使用 lib1 中的 Element 
Element element1 = Element();

// 使用 lib2 中的 Element 
lib2.Element element2 = lib2.Element();
複製代碼

只導入庫的一部分

若是你只用到了庫的一部分，你能夠選擇性的導入，例如：

// 只導入 foo
import 'package:lib1/lib1.dart' show foo;

// 除了 foo 其餘都導入
import 'package:lib2/lib2.dart' hide foo;
複製代碼

延遲加載一個庫

延遲加載（也稱爲懶加載 lazy loading）能夠容許一個 web app 當用到庫的時候纔去加載。如下是一些可能用到延遲加載的狀況：

• 減小一個 web app 的初始化啓動時間
• 作 A/B testing - 一個嘗試可替代方案的算法
• 加載很難用到的函數，例如可選的 screens 和 dialogs

僅dart2js支持延遲加載。 Flutter，Dart VM和dartdevc不支持延遲加載。 有關更多信息，請參見問題＃33118和問題＃27776。

延遲加載一個庫，你必須在第一次導入的時候用 deferred as

import 'package:greetings/hello.dart' deferred as hello;
複製代碼

當你須要該庫時，調用loadLibrary()來使用庫的標識符。

Future greet() async {
  await hello.loadLibrary();
  hello.printGreeting();
}
複製代碼

在前面的代碼中，關鍵詞await會暫停執行直到庫被加載好。

你能夠調用loadLibray()屢次加載一個庫，但這個庫只會被加載一次。

當你使用延遲加載時，請記住：

• 在導入文件過程當中，一個延遲加載庫的常量不是常量了。記住，這些常量不會存在直到延遲庫加載好。
• 在導入文件過程當中，你不能使用延遲庫中的類型。因此考慮把接口類型移到一個庫中，同時導入它和延遲庫。
• Dart 隱式插入loadLibrary()到你定義使用deferred as namespace的命名空間。loadLibrary()函數返回一個 Future

實現一個庫

Dart生態系統使用包來共享軟件，例如庫和工具。 該頁面告訴你如何建立一個包，重點介紹最多見的包，庫包（library package）。

一個庫包由什麼組成

下面的演示圖展現了一個最簡單的庫包的結構：

一個庫包最少須要：

pubspec 文件 pubspec.yaml文件對於一個庫和一個應用包來講都是相同的--沒有特殊的設計來區分一個包是一個庫。

lib 目錄 就像你想的，lib 目錄下放的是這個庫的代碼，而且對於其餘包是公開的。你能夠在 lib 目錄下建立任何層級。爲了方便，實現的代碼是放在 lib/src下的。在 lib/src下的代碼能夠考慮設置成私有的；其餘包不須要導入 src/...。爲了讓你在 lib/src 下的 APIs 公開， 你能夠從一個直接在 lib 目錄下的文件中導出lib/src下的文件。

注意：未指定library指令時，會根據每一個庫的路徑和文件名爲它們生成一個惟一標記。 所以，咱們建議你從代碼中省略library指令，除非你打算生成庫級文檔。

組織一個庫包

建立小型的單個庫（稱爲迷你庫）時，庫包最容易維護，擴展和測試。 在大多數狀況下，每一個類都應位於本身的微型庫中，除非你遇到兩個類緊密耦合的狀況。

注意：你可能據說過part指令，該指令可將庫拆分爲多個Dart文件。 咱們建議你避免使用part而是建立小型庫。

在lib, lib/.dart下直接建立一個main庫文件，該文件將導出全部公共API。 這使用戶能夠經過導入單個文件來得到庫的全部功能。

lib目錄可能還包括其餘可導入的非src庫。 例如，也許你的主庫跨平臺工做，可是你建立了依賴dart:io或dart:html的單獨的庫。 某些軟件包具備單獨的庫，但若是沒有主庫，則應使用前綴導入。

讓咱們看一下現實世界中庫包的結構：shelf。 shelf包提供了一種使用Dart建立Web服務器的簡便方法，並以Dart庫包經常使用的結構進行佈局：

直接在lib下，主庫文件， shelf.dart，從lib/src導出幾個文件：

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/handlers/logger.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/pipeline.dart';
export 'src/request.dart';
export 'src/response.dart';
export 'src/server.dart';
export 'src/server_handler.dart';
複製代碼

shelf包也包含了一個mini 庫：shelf_io。這個適配器處理了從 dart:io 中的 HttpRequest 對象。

Web應用程序提示：爲了在使用dartdevc開發時得到最佳性能，請將實現文件放在/lib/src下，而不是在/lib下的其餘地方。 另外，避免導入package:package_name/src/....

導入庫文件

當你導入一個庫文件時，可使用package:直接指定它的 URI

import 'package:utilities/utilities.dart';
複製代碼

不管文件是否是在 lib 目錄內外，你均可以用相對路徑導入一個庫，可是你必須使用package:。當你有疑問的時候，直接使用package:指令在全部狀況下都管用。

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

注意：儘管lib圖形使用相對導入（import'../foo/a.dart'）顯示lib/bar/b.dart，但它能夠改用package:指令（import'package：my_package/foo/ a.dart'）。

提供額外的文件

設計良好的庫包易於測試。 咱們建議你使用test包編寫測試，並將測試代碼放在包頂部的test目錄中。

若是你建立任何供公衆使用的命令行工具，請將其放置在bin目錄中，該目錄是公共的。 使用pub global activate啓用從命令行運行工具的功能。 在pubspec的可執行文件部分列出該工具後，用戶無需調用pub global run就能夠直接運行它。

提供一個如何使用你的庫的例子會很是有用。 能夠放在包的頂級目錄example中。

你在開發過程當中建立的任何非公共使用的工具或可執行文件均可以放入tool目錄。

若是將庫發佈到Pub站點，則須要的其餘文件（如README和CHANGELOG）在發佈包中進行了描述。 有關如何組織包目錄的更多信息，請參見pub包佈局約定。

爲一個庫寫文檔

你可使用dartdoc工具爲你的庫生成API文檔。 Dartdoc解析源以查找使用///語法的文檔註釋：

/// 負責處理在 ui 中更新 badge 的事件
void updateBadge() {
  ...
}
複製代碼

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

注意：要在生成的文檔中包括任何庫級別的文檔，必須指定庫指令。 請參閱問題1082。

分發開源庫

若是你的庫是開源的，咱們建議在Pub網站上共享它。 要發佈或更新庫，請使用pub publish，它會上傳你的軟件包並建立或更新其頁面。 例如，請參閱shelf包頁面。 有關如何準備要發佈包的詳細信息，請參見發佈包。

發佈網站不只託管你的軟件包，並且還生成並託管你的軟件包的API參考文檔。 軟件包的About框中提供了最新生成的文檔的連接； 例如，請參閱書架包裝的API文檔。 程序包頁面的Versions標籤中的指向先前版本文檔的連接。

爲確保你的軟件包的API文檔在發佈網站上看起來不錯，請按照如下步驟操做：

• 在發佈包以前，請運行dartdoc工具，以確保你的文檔生成成功而且外觀符合預期。
• 發佈包後，請檢查Versions選項卡，以確保文檔已成功生成。
• 若是文檔根本沒有生成，請在Versions標籤中單擊failed以查看dartdoc輸出。

資源

使用如下資源來了解有關庫包的更多信息：

• 語言導覽中的庫和可見性涵蓋了使用庫文件的狀況。
• 包文檔很是有用，尤爲是包佈局約定。
• 不提交的內容涵蓋了不該檢入源代碼存儲庫中的內容。
• dart-lang組織下的較新的庫軟件包傾向於顯示最佳實踐。 考慮研究如下示例：dart_style，path，shelf，source_gen和test。