dart-package-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dart Package Management

Dart 包管理

Goal

目标

Configures and manages Dart packages, monorepo workspaces, and directory layouts. Enforces

pubspec.yaml

standards, dependency resolution, and strict public/private API boundaries. Assumes a modern Dart environment (SDK >= 3.6.0) utilizing the official package layout conventions and workspace features for multi-package repositories.

配置并管理Dart包、单仓库工作区（monorepo workspaces）和目录布局。强制执行

pubspec.yaml

标准、依赖项解析以及严格的公共/私有API边界。假设使用现代Dart环境（SDK >= 3.6.0），遵循官方包布局规范和多包仓库的工作区特性。

Instructions

操作步骤

Determine Repository Architecture Evaluate the user's project scope using the following Decision Logic:
- Is the project a single standalone package? -> Proceed to Step 2a (Standard Package).
- Does the project contain multiple interdependent packages? -> Proceed to Step 2b (Monorepo Workspace).
- STOP AND ASK THE USER: If the repository structure is ambiguous, ask: "Should this project be configured as a single Dart package or a monorepo workspace containing multiple packages?"

Configure
pubspec.yaml
Based on the architecture decision, generate the appropriate configuration files.

Step 2a: Standard Package Create a standard

pubspec.yaml

at the project root.

yaml

name: package_name
description: >-
  A concise description of the package (60-180 characters).
version: 1.0.0
homepage: https://example.com/package_name
environment:
  sdk: ^3.6.0
dependencies:
  path: ^1.9.0
dev_dependencies:
  test: ^2.4.0

Step 2b: Monorepo Workspace Create a root

pubspec.yaml

to define the workspace. Use glob patterns (

) to automatically include sub-packages.

yaml

name: root_workspace
publish_to: none
environment:
  sdk: ^3.6.0
workspace:
  - packages/*

For each child package (e.g.,

packages/client_package/pubspec.yaml

), enforce the

resolution: workspace

directive and ensure the SDK constraint matches the root.

yaml

name: client_package
description: Client implementation for the workspace.
version: 0.1.0
environment:
  sdk: ^3.6.0
resolution: workspace
dependencies:
  shared_package: ^1.0.0 # Resolves locally within the workspace

Scaffold Package Layout Enforce the standard Dart directory structure. Create the following directories and files as needed:
- ```
lib/
```
  : Publicly exported libraries and assets.
- ```
lib/src/
```
  : Private implementation files.
- ```
bin/
```
  : Public command-line executables.
- ```
tool/
```
  : Internal development scripts.
- ```
test/
```
  : Unit and integration tests.
- ```
example/
```
  : Usage examples.

Implement Import Boundaries Apply strict import rules based on file location.

Within
lib/
reaching into
lib/src/
: Use relative imports.

dart

// lib/my_package.dart
import 'src/internal_logic.dart';

Outside
lib/
(e.g.,
test/
,
bin/
,
example/
) reaching into
lib/src/
: Use

package:

imports.

dart

// test/my_package_test.dart
import 'package:my_package/src/internal_logic.dart';

Manage Dependencies and State Execute package resolution commands to generate the

package_config.json

and

pubspec.lock

files.

bash

# For initial setup or adding new dependencies
dart pub get

# To upgrade existing dependencies to their latest compatible versions
dart pub upgrade

Validate and Fix Verify the configuration state.
- Run
```
dart pub workspace list
```
  (if in a monorepo) to ensure all child packages are recognized.
- Run
```
dart analyze
```
  to catch import boundary violations (
```
avoid_relative_lib_imports
```
  ).
- If
```
dart pub get
```
  fails due to a stray
```
pubspec.yaml
```
  in a non-workspace directory, delete the stray file or add it to the
```
workspace:
```
  list, then re-run
```
dart pub get
```
  .

确定仓库架构 使用以下决策逻辑评估用户的项目范围：
- 项目是单个独立包吗？ → 进入步骤2a（标准包）。
- 项目包含多个相互依赖的包吗？ → 进入步骤2b（Monorepo工作区）。
- 停止并询问用户： 如果仓库结构不明确，请询问：“此项目应配置为单个Dart包，还是包含多个包的Monorepo工作区？”

配置
pubspec.yaml
根据架构决策，生成对应的配置文件。

步骤2a：标准包 在项目根目录创建标准的

pubspec.yaml

文件。

yaml

name: package_name
description: >-
  A concise description of the package (60-180 characters).
version: 1.0.0
homepage: https://example.com/package_name
environment:
  sdk: ^3.6.0
dependencies:
  path: ^1.9.0
dev_dependencies:
  test: ^2.4.0

步骤2b：Monorepo工作区 创建根目录的

pubspec.yaml

来定义工作区。使用通配符模式（

）自动包含子包。

yaml

name: root_workspace
publish_to: none
environment:
  sdk: ^3.6.0
workspace:
  - packages/*

对于每个子包（例如

packages/client_package/pubspec.yaml

），强制执行

resolution: workspace

指令，并确保SDK约束与根目录一致。

yaml

name: client_package
description: Client implementation for the workspace.
version: 0.1.0
environment:
  sdk: ^3.6.0
resolution: workspace
dependencies:
  shared_package: ^1.0.0 # Resolves locally within the workspace

搭建包目录结构 强制执行标准的Dart目录结构。根据需要创建以下目录和文件：
- ```
lib/
```
  : 公开导出的库和资源。
- ```
lib/src/
```
  : 私有实现文件。
- ```
bin/
```
  : 公开的命令行可执行文件。
- ```
tool/
```
  : 内部开发脚本。
- ```
test/
```
  : 单元和集成测试。
- ```
example/
```
  : 使用示例。

实现导入边界 根据文件位置应用严格的导入规则。

在
lib/
内部导入
lib/src/
中的文件：使用相对导入。

dart

// lib/my_package.dart
import 'src/internal_logic.dart';

在
lib/
外部（如
test/
、
bin/
、
example/
）导入
lib/src/
中的文件：使用

package:

导入。

dart

// test/my_package_test.dart
import 'package:my_package/src/internal_logic.dart';

管理依赖项与状态 执行包解析命令以生成

package_config.json

和

pubspec.lock

文件。

bash

# For initial setup or adding new dependencies
dart pub get

# To upgrade existing dependencies to their latest compatible versions
dart pub upgrade

验证与修复 验证配置状态。
- 运行
```
dart pub workspace list
```
  （如果是单仓库）以确保所有子包都能被识别。
- 运行
```
dart analyze
```
  来捕获导入边界违规（
```
avoid_relative_lib_imports
```
  规则）。
- 如果由于非工作区目录中存在多余的
```
pubspec.yaml
```
  导致
```
dart pub get
```
  失败，请删除该多余文件或将其添加到
```
workspace:
```
  列表中，然后重新运行
```
dart pub get
```
  。

Constraints

约束条件

DO maintain a valid
```
pubspec.yaml
```
with clear version constraints (prefer
```
^
```
syntax, e.g.,
```
^2.1.0
```
).
DO follow the
```
lib/
```
directory convention for public exports; never place entrypoints (
```
main()
```
) directly in
```
lib/
```
.

DO use

dart pub get

and

dart pub upgrade

to manage the

.dart_tool/package_config.json

DO implement workspaces in monorepos to share dependencies across local packages.
DO ensure all public assets (e.g., CSS, images) are listed correctly in the pubspec or placed in the top-level
```
lib/
```
directory for web/asset sharing.
DO NOT check the
```
.dart_tool/
```
directory into source control; ensure it is added to
```
.gitignore
```
.
DO NOT use
```
resolution: workspace
```
on packages with an SDK constraint lower than
```
^3.6.0
```
.
DO NOT import from another package's
```
lib/src/
```
directory under any circumstances.
Related Skills:
```
dart-api-design
```
.

务必维护有效的
```
pubspec.yaml
```
文件，使用清晰的版本约束（优先使用
```
^
```
语法，例如
```
^2.1.0
```
）。
务必遵循
```
lib/
```
目录的公共导出约定；切勿将入口点（
```
main()
```
）直接放在
```
lib/
```
中。

务必使用

dart pub get

和

dart pub upgrade

来管理

.dart_tool/package_config.json

。

务必在单仓库（monorepo）中实现工作区，以便在本地包之间共享依赖项。
务必确保所有公共资源（如CSS、图片）在pubspec中正确列出，或放置在顶层
```
lib/
```
目录中以用于Web/资源共享。
切勿将
```
.dart_tool/
```
目录提交到版本控制系统；确保将其添加到
```
.gitignore
```
中。
切勿在SDK约束低于
```
^3.6.0
```
的包上使用
```
resolution: workspace
```
。
任何情况下都切勿从其他包的
```
lib/src/
```
目录导入内容。
相关技能：
```
dart-api-design
```
。