Flutter子包规范检查插件subpackage_lint的使用

插件介绍

subpackage_lint 是一个包含一组用于强制执行子包最佳实践的Lint规则的Flutter/Dart插件。它帮助开发者确保在项目中使用子包（subpackages）时遵循良好的组织和导入习惯。

子包哲学

子包或“轻量级包”是将代码分割成独立模块的方法，而无需引入额外构建工具的开销或在多个地方管理代码。通过这种方式，可以将一个功能的所有相关代码集中在一起，并像对待独立库一样处理它们，但仍然保持在同一项目中，允许根据需要灵活地覆盖规则。

一个典型的子包结构如下：

/my_subpackage
├── my_subpackage.dart
└── /src
    ├── /a_folder
    │   └── another_private_file.dart
    ├── a_private_file.dart
    └── some_public_file.dart

其中，顶级目录下的 my_subpackage.dart 文件负责导出所有希望公开的文件和类。例如：

// my_subpackage/my_subpackage.dart

/// 这里是对这个子包作用的描述
/// 当悬停在这个库文件的导入上时，IDE会显示此注释。
library my_subpackage;

export 'src/some_public_file.dart'; // 只导出公共文件或类

导入规则

• 在子包内部：使用相对路径进行导入，避免出现 /src/ 的路径。

  • 正确示例：

    import 'a_private_file.dart';
    import '../some_public_file.dart';
    

  • 错误示例：

    import '../src/a_private_file.dart';
    import 'package:my_app/my_subpackage/my_subpackage.dart';
    import 'package:my_app/my_subpackage/src/a_private_file.dart';
    import '../my_subpackage.dart';
    

• 导入子包：应始终导入库文件而不是直接导入 src 目录中的文件。

  • 正确示例：

    import 'package:my_app/my_subpackage/my_subpackage.dart';
    

  • 错误示例：

    import 'package:my_app/my_subpackage/src/some_public_file.dart'
    import '../../my_subpackage/src/some_public_file.dart';
    import '../../my_subpackage/my_subpackage.dart';
    

快速开始

要开始使用 subpackage_lint，请按照以下步骤操作：

1. 添加依赖项：编辑项目的 pubspec.yaml 文件，添加 custom_lint 和 subpackage_lint 到 dev_dependencies 中。

   dev_dependencies:
     custom_lint:
     subpackage_lint:
   

2. 配置分析选项：在 analysis_options.yaml 文件中启用插件。

   analyzer:
     plugins:
       - custom_lint
   

3. 限制目录与排除文件（可选）：如果需要对某些特定目录应用规则或者排除某些文件，可以在 analysis_options.yaml 中进一步配置。

   custom_lint:
     rules:
       - avoid_src_import_from_other_subpackage:
         directories:
           - "lib/my_subpackage" # 仅检查此目录内的导入
         exclude:
           - "lib/my/excluded/file.dart"
           - "**_test.dart"
           - "**.g.dart"
       - avoid_src_import_from_same_package:
         directories:
           - "lib"
         exclude:
           - "lib/my/excluded/directory/**"
           - "**_test.dart"
       - avoid_package_import_for_same_package:
         directories:
           - "lib"
         exclude:
           - "**_test.dart"
   

已知问题

目前存在一个问题，即排除文件的功能对于相对路径可能不完全有效，特别是在 lib 目录之外的情况下。如果遇到此类问题，请前往 GitHub 提交 issue。

示例代码

下面是一个简单的例子，展示了如何在一个 Flutter 应用中正确导入子包的功能：

// example/lib/main.dart

// 使用子包的库导入
import 'package:example/feature/feature.dart';

void main() {
  exampleFunction();
}

通过遵循上述指南，您可以更好地管理和维护大型 Flutter 项目中的代码结构，同时利用 subpackage_lint 确保代码质量的一致性。