创建软件包

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。