创建 package

在 Dart 生态系统中使用 packages 实现共享软件，比如一些库和工具。本章将通过最常见的 Package 来介绍如何创建一个 Package。

若要为 package 创建一个初始化的目录和结构，使用 dart create 命令，并加入 package 作为命令参数来创建：

$ dart create -t package <PACKAGE_NAME>

下图展示了最简单的 Package 的结构：

Package 的最基本要求包括：

pubspec 文件
Package 的 pubspec.yaml 文件与 应用程序的 pubspec.yaml 文件 相同— pubspec.yaml 文件中并没有特别的指出这个 Package 是一个库。

lib 目录
如你所料，库的代码位于 lib 目录下，且对于其他 Package 是公开的。你可以根据需要在 lib 下任意创建组织文件结构。按照惯例，实现代码会放在 lib/src 目录下。 lib/src 目录下的代码被认为是私有的。其他 Package 应该永远不需要导入 src/... 目录下代码。通过导出 lib/src 目录的文件到一个 lib 目录的文件，实现对 lib/src 目录中 API 的公开。

在创建一个小的，独立的 Package 时（称之为 Mini Library），它非常容易维护，扩展和测试。大多数情况下，除非存在两个类紧密耦合的情况，否则每个类都应该将自己视为一个 Mini Library 。

直接在 lib 目录下创建“主” Library 文件，lib/<package-name>.dart，该文件导出所有的公开的 API 。这样就可以允许使用者导入单个文件就能够获得 Library 的所有功能。

lib 目录还可能包含其他可导入的非 src 代码。例如，主 Library 可能是跨平台的，但创建的独立 Library 依赖于 dart:io 或 dart:js_interop 。 Some packages have separate libraries that are meant to be imported with a prefix, when the main library is not.

这里让我们来看下一个真实 Library Package 的组织结构：shelf 。 shelf Package 提供了一种使用 Dart 创建 Web 服务器的简便方法，它是一种 Dart Package 的常用结构：

主 Library 文件 shelf.dart 在 lib 目录下，通过 shelf.dart 文件导出 lib/src 目录下的若干文件。为了不导出过多的 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 Package 中同样包含了 Mini Library：shelf_io 。适配器用来处理来自 dart:io 的 HttpRequest 对象。

在从其他 package 导入库文件时，使用 package: 命令来指定文件的 URI 。

import 'package:utilities/utilities.dart';

在两个文件都在 lib 目录中，或两个文件都在 lib 目录外，我们都可以使用相对路径的方式导入 Library 。但是，如果两个文件不都在 lib 目录中，需要对 lib 内或者 lib 外进行查找，那么此时必须要使用 package: 导入。如果对当前使用存在疑惑，那么直接 package: ； package: 满足所有情况。

下面图片展示分别从 lib 和 web 目录中导入 lib/foo/a.dart 。

如果你的 library 支持多平台，那么你应该会用到条件导入或条件导出 library 文件。常见的用例是，一个库同时支持 Web 和 Native 平台。

为了使用条件导入或条件导出，你需要检查是否存在 dart:* 库。下面是一个条件导出代码的样例，它将检查是否存在 dart:io and dart:html 库：

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 的 app 中（例如一个命令行应用），导出 src/hw_io.dart。

• 在一个 web 应用中可以使用 dart:js_interop 导出 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!';

这是一个默认实现，它会导致抛出 UnsupportedErrors：

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);
}

一个设计良好的 Package 很容易被测试。我们建议使用 test Package 编写测试用例，并将测试代码放到 Package 根目录的 test 目录中。

如果要创建一个公用的命令行工具，应该将这些工具放到公共目录 bin 中。使用 dart pub global activate 命令行来运行工具。在 pubspec 的 executables 部分 列出的工具允许用户直接运行它而无需调用 dart pub global run。

在 Library 中包含一个 example 程序演示如何使用 Library 是非常有用的。 example 程序在 Package 根目录的 example 目录中。

在开发过程中任何非公开的工具或可执行程序，应该放到 tool 文件夹。

如果要将 Library 发布到 Pub 网站还要求一些其他的文件来描述 发布的 Package ，例如：README.md 和 CHANGELOG.md 文件。更多关于如何组织 Package 目录的内容，参见 Pub Package 布局约定。

使用 dart doc 可以为 Library 生成 API 文档。 dartdoc 解析源文件去查找使用 /// 语法标注的 文档注释：

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

文档生成示例，参见 shelf 文档。

若要自动生成任何库级别的文档，请添加一个 library 指令并直接在其上方附加注释。更多详情，请参阅文档 Effective Dart: Documentation。

如果 Library 是开源的，我们建议将他共享到 Pub 网站。使用 pub publish 来发布或者更新 Library，该命令将会上传 Package 并创建或更新其页面。示例参见 shelf Package 页面。有关如何准备发布 Package 的详细内容，参见 发布 Package。

Pub.dev 网站不仅仅是 Dart Packages 的发布网站， Pub 网站不仅用于托管 Package ，还能够生成托管 Package 的 API 参考文档。最新生成的文档的链接位于 Package 的 About 选项卡中; 示例参见 shelf Package 的 API 文档。链接到以前版本的文档，位于 Package 页面的 Versions 选项卡中。

为了确保 Package 的 API 文档在 Pub 网站上看起来更美观，请遵循以下步骤：

• 在发布 Package 前，请通过执行 dart doc 工具确保文档能够生成成功且符合预期。

• 在发布 Package 后，请检查 Versions 选项卡，确保文档生成成功。

• 如果文档没有生成，点击 Versions 选项卡中的 failed 查看 dartdoc 的输出。

通过运用以下资源来了解学习更多关于 Library Package 的内容：

• 在 库及可见性 中涵盖了库文件使用的内容。

• Package 文档非常有用，尤其是 Package 结构约定.

• 什么不应该被提交包含了关于什么文件不应该被提交到源码仓库的介绍。

• dart-lang 组织下的最新 Package 常常是最佳实践的提现。可以参考学些以下这些实例： dart_style， path， shelf， source_gen 以及 test 。

除非另有说明，文档之所提及适用于 Dart 3.5.4 版本，本页面最后更新时间: 2024-12-02。 查看文档源码 或者 报告页面问题。