跨平台开发 / 系统课时

组织库、导入与私有成员

组织库、导入与私有成员

当一个 Dart 程序从单文件增长到多个功能模块时,真正需要控制的是“谁依赖谁”和“哪些名字允许外部使用”。本篇用一个可运行的小包拆开公开入口与实现文件,并验证 import、导出边界和下划线私有语义。

学习目标

  • 使用 import、导入前缀和公开入口组织库依赖。
  • 理解以下划线开头的名字是库级私有,而不是单纯的类级私有。
  • 通过 lib/ 与 lib/src/ 拆分实现,只暴露稳定的公开 API。

把公开入口与实现拆开

在 Dart 中,每个独立的 Dart 文件默认都可以形成一个库;library 指令并不是普通项目的必需项。一个实用的包结构是:把对外入口放在 lib/,把实现细节放在 lib/src/,再由入口文件显式导出需要公开的名字。

先创建项目根目录下的 pubspec.yaml。这是配置片段,用于声明包名和 SDK 约束:

yaml
name: module_demo
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"

配置生效后,package:module_demo/... 会以这个包名解析 lib/ 下的库。

下面的 lib/src/user_profile.dart 是片段示例,作为包内部实现文件使用:

dart
class UserProfile {
  UserProfile(String rawName) : name = _normalizeName(rawName);

  final String name;

  String get label => 'User: $name';
}

String formatDisplayName(String rawName) => _normalizeName(rawName);

String _normalizeName(String rawName) {
  final cleaned = rawName.trim();
  if (cleaned.isEmpty) return '';

  // 规范化连续空白,并统一每个单词的大小写。
  return cleaned.split(RegExp(r'\s+')).map((word) {
    return '${word[0].toUpperCase()}${word.substring(1).toLowerCase()}';
  }).join(' ');
}

不要让调用方直接依赖 lib/src/。增加公开入口 lib/module_demo.dart,只导出准备长期维护的 API。下面同样是片段示例:

dart
export 'src/user_profile.dart' show UserProfile, formatDisplayName;

show 让公开面保持可控。以后即使内部文件继续增加辅助函数,只要没有从入口导出,调用方就不需要知道这些实现名字。

从另一个库导入公开 API

在 bin/main.dart 中导入包入口,并使用 as profiles 给导入库增加前缀。前缀适合解决同名冲突,也能让调用位置更容易看出 API 来自哪个库。

dart
import 'package:module_demo/module_demo.dart' as profiles;

void main() {
  final user = profiles.UserProfile('  ada   lovelace  ');

  print(user.label);
  print(profiles.formatDisplayName('  dart language  '));
}

在项目根目录执行:

bash
dart run bin/main.dart

预期输出:

text
User: Ada Lovelace
Dart Language

如果实际 SDK 路径或工具输出带有环境信息,相关内容可能不同,但这两行程序输出应保持一致。

理解下划线为什么是库级私有

_normalizeName 的下划线不是“只允许当前类访问”的修饰符,而是让这个标识符只在声明它的库内可见。因此,同一个库里的其他声明可以访问它;另一个库即使知道名字,也不能把它当作公开 API 使用。

这里的 bin/main.dart 与 lib/src/user_profile.dart 属于不同库,所以主程序只能通过 UserProfile 和 formatDisplayName 间接使用规范化逻辑。类中的 _field、_method() 与顶层的 _function() 遵循同样的库级私有规则。

验证模块边界

先让分析器检查导入路径、类型和公开名称:

bash
dart analyze

预期输出:

text
Analyzing module_demo...
No issues found!

如果把主程序改成直接调用 _normalizeName,分析器会把它视为当前库中不存在的公开名称;正确修复方式不是去掉所有私有标记,而是决定调用方是否真的需要这个能力。需要就提供稳定的公开函数,不需要就继续把实现留在库内部。

文件拆分的目标也不是“一个类一个文件”,而是让公开 API 与实现变化解耦。入口文件保持小而稳定,业务实现按职责拆进多个库,调用方只导入需要的入口,这样模块关系会比把所有代码堆在单一 main.dart 中更清晰。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

组织库、导入与私有成员

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通