跨平台开发 / 系统课时
组织库、导入与私有成员
组织库、导入与私有成员
当一个 Dart 程序从单文件增长到多个功能模块时,真正需要控制的是“谁依赖谁”和“哪些名字允许外部使用”。本篇用一个可运行的小包拆开公开入口与实现文件,并验证 import、导出边界和下划线私有语义。
学习目标
- 使用
import、导入前缀和公开入口组织库依赖。 - 理解以下划线开头的名字是库级私有,而不是单纯的类级私有。
- 通过
lib/与lib/src/拆分实现,只暴露稳定的公开 API。
把公开入口与实现拆开
在 Dart 中,每个独立的 Dart 文件默认都可以形成一个库;library 指令并不是普通项目的必需项。一个实用的包结构是:把对外入口放在 lib/,把实现细节放在 lib/src/,再由入口文件显式导出需要公开的名字。
先创建项目根目录下的 pubspec.yaml。这是配置片段,用于声明包名和 SDK 约束:
name: module_demo
publish_to: none
environment:
sdk: ">=3.0.0 <4.0.0"配置生效后,package:module_demo/... 会以这个包名解析 lib/ 下的库。
下面的 lib/src/user_profile.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。下面同样是片段示例:
export 'src/user_profile.dart' show UserProfile, formatDisplayName;show 让公开面保持可控。以后即使内部文件继续增加辅助函数,只要没有从入口导出,调用方就不需要知道这些实现名字。
从另一个库导入公开 API
在 bin/main.dart 中导入包入口,并使用 as profiles 给导入库增加前缀。前缀适合解决同名冲突,也能让调用位置更容易看出 API 来自哪个库。
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 '));
}在项目根目录执行:
dart run bin/main.dart预期输出:
User: Ada Lovelace
Dart Language如果实际 SDK 路径或工具输出带有环境信息,相关内容可能不同,但这两行程序输出应保持一致。
理解下划线为什么是库级私有
_normalizeName 的下划线不是“只允许当前类访问”的修饰符,而是让这个标识符只在声明它的库内可见。因此,同一个库里的其他声明可以访问它;另一个库即使知道名字,也不能把它当作公开 API 使用。
这里的 bin/main.dart 与 lib/src/user_profile.dart 属于不同库,所以主程序只能通过 UserProfile 和 formatDisplayName 间接使用规范化逻辑。类中的 _field、_method() 与顶层的 _function() 遵循同样的库级私有规则。
验证模块边界
先让分析器检查导入路径、类型和公开名称:
dart analyze预期输出:
Analyzing module_demo...
No issues found!如果把主程序改成直接调用 _normalizeName,分析器会把它视为当前库中不存在的公开名称;正确修复方式不是去掉所有私有标记,而是决定调用方是否真的需要这个能力。需要就提供稳定的公开函数,不需要就继续把实现留在库内部。
文件拆分的目标也不是“一个类一个文件”,而是让公开 API 与实现变化解耦。入口文件保持小而稳定,业务实现按职责拆进多个库,调用方只导入需要的入口,这样模块关系会比把所有代码堆在单一 main.dart 中更清晰。