如何创建一个dart package

推荐一个作者的package，一个方便flutter初学者使用编写计算器的库。
点击获取

创建packages

dart生态使用pakcage来分享ku或者工具。下面我们来看一下最常见的库的package的创建。

库的组成

下面的示意图展示了最简单的库结构：

库的最基本组成：

pubspec文件

dart应用也是使用这个文件，这个文件中没有特殊的标识符说明当前的项目是package还是app。

lib 文件夹

如我们所想，库代码放在lib文件夹中。给文件夹是公开可访问的。你可以重建一个子目录，通常来说，实现代码放在lib/src文件夹下。src文件夹应该认为是私有的。其他package不应该直接从src文件夹中import。你可以export src文件夹中的文件。

提示 当声明了`library`指令，会依据路径和文件名生成唯一的tag。因此我们一般应该忽略这个声明，除非你打算生成library-level等级的文档。

构建一个library package

独立的小的库组成的library pacage是最容易维护，扩展，测试的。
大多数的例子，每个类应该是个小的library，除非某些类之间有紧密的关系。

提示你也许听说过`part`指令，它允许你把ku分写道几个小的dart文件中。在创建小的ku时，建议不要使用part指令。

在lib文件夹下创建一个主要的库文件，形式如lib/<package-name>.dart,用来导出所有的公共接口。这样用户就可以通过一个文件导入所有的功能。

lib文件夹也许包括其他的接口文件，像是一些no-src的，例如也许你的库是跨平台的，你创建了分开的入口。比如依赖dart:io或者dart:html的。一些库做了import前缀，用来指明不同的导入需求（当主库不能适应使用环境时）。

我来看下现实中的库的组织结构。shelf库提供了创建webserver的简单方法，它提供了常用的dart package结构。

主库shelf.dart的到处内容。

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库也包含一个小的库：shelf_io。这个用来处理来自dart:io的HttpRequest对象。

web app提示:为了编译时的性能，建议把是下代码放到`lib/src`文件夹下，也要避免使用`package:package_name/src..`这类导入方法。

import 库文件

当导入一个库文件，你可以使用package:指令加上文件uri路径。

import 'package:utilities/utilities.dart';

当文件都在lib文件夹中/外时可以使用相对路径导入。
然而又是你必须使用package:引入一个文件，不管它始在lib内还是外。如果有疑问就用package:,它都能胜任。

下面视图，说明引入lib/foo/a.dart的不同方式。

提示:图中使用的`import'../foo/a/dart';可以使用`import 'package:my_package/foo/a.dart`。

条件引入

如果你的库支持多个平台，那么你可能需要考虑按条件引入和导出库文件。通常的情况是支持web和本地平台。

想要有条件的引入和导出，你需要检查dart:*的存在。整个例子根据不同的存在导出文件。

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation

代码做的事：

• 一个应用能够使dart:io，导出src/hw_io.dart.
• 一个应用使用dart:html，导出src/hw_html.dart.
• 其他的导出dart:hw_one.dart。

条件导出和上面的代码基本一样，但是使用的是import指令。

提示 条件导出和引入只是检查库是否在当前平台可用，而不是实际导入或使用。

所有的条件导出不行hi是新建一样的api，例如这里的dart:io实现。

import 'dart:io';

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

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

这里有一个默认实现，这是一部分抛出错误的代码。

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编写测试文件。把测试代码放到test文件夹（顶级目录）中。

如果你编写了命令行工具想要别人使用，那么把它们放到bin文件夹中，这是惯例。实现使用pub global active运行命令行工具。把命令放到pubspec的executables字段域下面，这样允许用户直接运行，而不需要调用pub global run，来运行。

在你的项目里添加example顶级文件夹，对于怎么使用你的库是有用的。

开发时使用的工具或者命令行文件而不是最终给用户使用的，放到tool文件夹中。

发布到pub.dev网址你需要添加的其他文件包括README.md以及CHANGELOG.md。其他内容可以查看pub package layout conventions。

文档

你可以使用dartdoc工具生成文档。文档使用文档注释——///来解析。

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

可以通过shelf document来查看生成的文档示例。

提示 想要生成时包含任何ligrary-level的文档，你需要声明library指令。

发布开源库

如果你的库是开源的，我们建议把它分享到pub.dev网站。发布和更新你的代码使用pub publish命令。它会上传你的代码然后生成或者更新页面。查看示例shelf package。或者查看发布这一张，了解如何准备和发布你的package。

pub.dev网站不只是保存你的package，而且会生成和host你的package api文档。最新生成的文档会在package的About tab。更多示例查看shelf package的API docs。更多的版本查看pacage页面的Version tab。

为了使你的package文档看起来不错，跟随下面做。

• 发布前，运行dartdoc工具来生成文档。
• 发布后检查Version tab，保证成功生成。
• 如果文档没有生成，查看Version tab，查看文档导出。