dart项目规范

生生世世是所说的

已于 2023-09-15 20:39:01 修改

阅读量106

点赞数

分类专栏： grpc flutter 文章标签： flutter

于 2023-09-15 20:38:59 首次发布

本文链接：https://blog.csdn.net/qq_42901723/article/details/132910208

版权

grpc 同时被 2 个专栏收录

13 篇文章 0 订阅

订阅专栏

flutter

9 篇文章 0 订阅

订阅专栏

dart项目结构

假设有一个名称为 enchilada 的完整的包目录（基本用到了所有的子目录），那么它的目录结构看起来像下面这样：

enchilada/ .dart_tool/ * .packages * pubspec.yaml pubspec.lock ** LICENSE README.md CHANGELOG.md benchmark/ make_lunch.dart bin/ enchilada doc/ api/ *** getting_started.md example/ main.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_tool 和 .packages 是由pub get 生成的，不需要纳入版本管理；

** pubspec.lock 也是由 pub get 命令生成的，除非你的包是应用程序包，否则也不建议纳入版本管理；

*** doc/api 目录是有dartdoc命令运行后生成的。不要纳入版本管理。

关于pubspec(dart的项目依赖管理)

enchilada/
  pubspec.yaml
  pubspec.lock

所有包都有 pubspec, 一文件命名为 pubspec.yaml,在整个包的根目录,这是使包成为包的关键文件.使用dart pub get, dart pub upgrade, or dart pub downgrade 在包下会创建 lockfile即项目依赖锁, 名为pubspec.lock.如果你的程序是一个应用程序包(application package),那把pubspec.lock文件放入到发布的源代码中,不然不要.

想知道更多的话, 请看 pubspec page.

LICENSE-许可证

enchilada/
  LICENSE

如果你打算发布你的包,包含一个许可证叫做LICENSE.我们推荐使用OSI-approved license such as BSD-3-Clause, 好让他人可以使用你的项目继续开发(在中国别这么干).

README.md

enchilada/
  README.md

在开源项目中非常出名的文件README 描述整个项目.这在pub社区中尤为重要.当你上传你的项目到 pub.dev site, 你的README.md 将会被—以Markdown的形式加载—在你发布的包的页面.这个文件会向人们完美的介绍你的项目.

想要知道怎么写出更棒的README,查看Writing package pages.

CHANGELOG.md

enchilada/
  CHANGELOG.md

包含一个 CHANGELOG.md 文件，其中包含每个软件包版本的部分，以及帮助软件包用户升级的注释。软件包的用户经常查看更改日志以发现错误修复和新功能，或者确定升级到软件包的最新版本需要花费多少精力。

要支持解析 CHANGELOG.md 的工具，请使用以下格式：

每个版本都有自己的带有标题的部分。
版本标题要么全部为 1 级，要么全部为 2 级。
版本标题文本包含包版本号，可以选择添加前缀“v”。

当你把包上传到pub.dev site, 你包的CHANGELOG.md 文件(有的话) 会出现在 Changelog 标签中, 以 Markdown 形式加载.https://pub.flutter-io.cn/packages/markdown

这是个CHANGELOG.md 的例子. 如示例所示，您可以添加小版本号。

# 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.

Public- 公共目录

您的包中的两个目录对其他包是公开的：lib and bin.。您将public libraries(公共库) 放在 lib 中，将public tools(公共工具)放在 bin 中。

Public lib-公共库

以下目录结构显示 enchilada 的 lib 部分:

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

许多包(packages)定义了其他包可以导入和使用的 Dart 库。这些公共 Dart 库文件位于名为 lib 的目录中。

大多数包定义了单个库以供用户导入。在这种情况下，其名称通常应与包的名称相同，例如此处示例中的 enchilada.dart。但您也可以使用对您的包有意义的任何名称来定义其他库。

当您这样做时，用户可以使用包的名称和库文件导入这些库，如下所示：

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

如果您想组织你的公共库，您还可以在 lib 内创建子目录。如果这样做，用户将在导入时指定该路径。假设您有以下文件层次结构:

enchilada/
  lib/
    some/
      path/
        olives.dart

用户导入 olives.dart，如下所示:

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

请注意，只有库才应位于 lib 中。 入口点——带有 main() 函数的 Dart 脚本——不能进入 lib。如果您将 Dart 脚本放入 lib 中，您会发现它包含的任何 package: 导入都无法解析。相反，您的入口点应该位于适当的入口点目录( entrypoint directory)中。

info 针对网络应用程序的提示：为了在开发网络应用程序时获得最佳性能，请将实现文件( implementation files)放在 /lib/src 下，而不是放在 /lib 下的其他位置。另外，避免导入 package:package_name/src/...

想知道关于packages的更多信息, 查看Creating packages.

Public tools-公共工具

放置在 bin 目录内的 Dart 脚本是公开的。如果您位于包的目录中，你可以用 dart run 在任何导入了这个包中的包中运行bin中的脚本.

在任何目录中, 你可用 run scriptszaidart pub global activate.

如果您打算依赖您的包，并且希望您的脚本对您的包是私有的，请将它们放在顶级工具目录中。如果您不希望您的包被依赖，您可以将脚本留在 bin 中。

Public assets-公共资源目录

enchilada/
  lib/
    guacamole.css

当大多数包让你去复用dart代码时,你还可以复用其他类型的内容.打个比方,一个关于Bootstrap的包可能含有大量的CSS文件让开发者去使用.

这些位于顶lib目录的顶层中。您可以将任何类型的文件放入其中，并按照您喜欢的方式使用子目录对其进行组织。

Implementation files-内部公共库实现即源码(src)目录

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

src目录是针对自己的lib中公共库文件的代码实现,即开发者所要编写的源代码.

lib 内的库是公开可见的：其他包可以自由导入它们。但包的大部分代码都是内部实现库，只能由包本身导入和使用。它们位于名为 src 的 lib 子目录中。如果可以帮助您组织内容，您可以在其中创建子目录。

您可以自由地从同一包中的其他 Dart 代码中导入位于 lib/src 中的库（如 lib 中的其他库、bin 中的脚本和测试），但绝对不应该从另一个包的 lib/src 目录中导入。这些文件不是包的公共 API 的一部分，它们的更改可能会破坏您的代码。

如何从自己的包中导入库取决于库的位置：

当reaching inside or outside lib/ (lint: avoid_relative_lib_imports){在lib目录内或者外部时可使用package}, use package:.
其他情况下, prefer relative imports(用相对路径).

举例:

// When importing from lib/beans.dart
import 'src/beans.dart';

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

您在此处使用的名称（在本例中为 enchilada）是您在 pubspec中为包指定的名称。

Web files

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

对于 Web 包，请将入口点代码（包含“main()”和支持文件（例如 CSS 或 HTML）的 Dart 脚本）放置在“web”下。如果您愿意，您可以将“web”目录组织成子目录。

把library code放置到lib目录下,

Put library code under lib.如果该库不是通过“web”下的代码或其他包直接导入的，请将其放在“lib/src”下. 把 web-based examples 放到example目录下`. 查看Public assets来获取放置公共资源的提示,像是图片.

Command-line apps-命令行工具

enchilada/
  bin/
    enchilada

一些包定义了可以直接从命令行运行的程序。这些可以是 shell 脚本或任何其他脚本语言，包括 Dart。

如果您的包定义了这样的代码，请将其放入名为“bin”的目录中。如果您使用以下命令 dart pub global进行设置，则可以从命令行上的任何位置运行该脚本.

Tests and benchmarks-测试和性能测试

enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

Every package should have tests. With pub, the convention is that these go in a test directory (or some directory inside it if you like) and have _test at the end of their file names.

每个包都应该有测试。对于 pub，惯例是这些文件位于“test”目录中（如果您愿意，也可以在其中的某个目录中），并在文件名末尾添加“_test”。

通常，这些使用 test 包.

enchilada/
  benchmark/
    make_lunch.dart

具有性能关键代码的软件包还可能包括基准测试代码。这些测试 API 不是为了正确性，而是为了速度（或内存使用，或者可能是其他经验指标）。

Documentation-文档

enchilada/
  doc/
    api/
    getting_started.md

如果您有代码和测试，那么您可能需要的下一部分是良好的文档。它位于名为“doc”的目录中。

当你使用dart doc 工具时, 它会替代已经生成的api接口文档说明, 默认, 放置在 doc/api.

自API文档可以从源代码生成,你不应当将文档放入发布的源代码中.

除了生成的“api”之外，我们没有任何关于您编写的文档的格式或组织的指南。使用您喜欢的任何标记格式。

Examples-示例代码

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”选项卡将显示“example/README.md”的内容（解析为“[Markdown”。）] (markdown | Dart Package "Markdown.)")

Internal tools and scripts-内部自定义工具

enchilada/
  tool/
    generate_docs.dart

成熟的软件包通常很少有人们在开发软件包本身时运行的帮助脚本和程序。想想测试运行器、文档生成器或其他自动化功能。

与“bin”中的脚本不同，这些脚本不适合包的外部用户。如果您有其中任何一个，请将它们放在名为“tool”的目录中。

Project-specific caching for tools-特定于项目的工具缓存

*注意不要将.dart_tool/目录签入源代码管理。相反，请将“.dart_tool/”保留在“.gitignore”中。

.**dart_tool**/ 目录是在您运行 **dart pub get** 时创建的，并且可能随时被删除。各种工具使用此目录来缓存特定于您的项目和/或本地计算机的文件。 .**dart_tool**/ 目录永远不应该被签入源代码管理系统，或者在机器之间复制。

删除.dart_tool/目录通常也是安全的，尽管某些工具可能需要重新计算缓存的信息。

示例： dart pub get 工具会将依赖项下载并提取到全局目录$PUB_CACHE ，然后编写一个.dart_tool/package_config.json文件将包名称映射到全局$PUB_CACHE目录中的目录。 .dart_tool/package_config.json 文件由其他工具（例如分析器和编译器）在需要解析诸如 import 'package:foo/foo.dart' 之类的语句时使用。

在开发需要特定于项目的缓存的工具时，您可以考虑使用“.dart_tool/”目录，因为大多数用户已经使用“.gitignore”忽略它。在用户的“.dart_tool/”目录中缓存工具文件时，您应该使用唯一的子目录。为了避免冲突，为名为“”的包保留了“.dart_tool//”形式的子目录。如果您的工具不是通过pub.dev 网站分发的，您可以考虑发布一个占位符包，以保留唯一的姓名。

示例： package:build 提供了用于编写代码生成步骤的框架。运行这些构建步骤时，文件会缓存在“.dart_tool/build/”中。这有助于加快构建步骤的未来重新运行。

report_problem 请注意： 开发想要在.dart_tool/中缓存文件的工具时，请确保以下几点：