Dart包开发：如何隐藏公共类中不对外暴露的内部方法？

先明确@internal的作用限制 #

@internal是meta包提供的注解，仅用于静态分析提示，本身不会从语法层面限制外部访问，所以只加注解不会真正隐藏方法。

推荐方案1：使用Dart原生私有标识符（最彻底） #

Dart中以下划线_开头的类、方法、属性默认是库私有，仅在声明它的Dart库（同个library，或通过part/part of关联的文件组）内可访问，外部导入后完全看不到这些成员，是成本最低的彻底隐藏方案。

修改后的示例代码如下：

/// 基础抽象类 [ImageData]
abstract class ImageData  {
  const ImageData();

  /// 包内使用：从 [dto] 创建 [ImageData] 实例
  factory ImageData._fromDto(dto.ImageData object) {
    switch (object.type) {
      case dto.ImageData_Type.pathType:
        return PathImageData(path: object.path);
      case dto.ImageData_Type.rawImageType:
        return RawImageData._fromDto(object.rawImage);
      default:
        throw const PluginInvokeException();
    }
  }

  /// 包内使用：生成 [dto.ImageData] 对象
  dto.ImageData _toDto();
}

子类修改示例：

class RawImageData extends ImageData {
  final Uint8List data;
  final RawImageDataType type;
  final int width;
  final int height;

  const RawImageData({
    required this.data,
    required this.type,
    required this.width,
    required this.height,
  }) : super();

  /// 包内使用：从 [dto] 创建 [RawImageData] 实例
  factory RawImageData._fromDto(dto.RawImage object) {
    return RawImageData(
      data: Uint8List.fromList(object.raw),
      type: typeFromDtoEnum(object.type),
      width: object.size.width,
      height: object.size.height,
    );
  }

  @override
  dto.ImageData _toDto() {
    return dto.ImageData(
      type: dto.ImageData_Type.rawImageType,
      rawImage: toDtoRawImage(),
    );
  }
}

方案2：@internal配合静态检查（不改动方法名场景） #

如果你因为内部跨库调用等原因不能用下划线命名，可以通过配置静态分析规则，强制外部使用@internal标记的成员时报错：

• 第一步：确保pubspec.yaml中已经依赖meta包：

dependencies:
  meta: ^1.10.0

• 第二步：在包根目录的analysis_options.yaml中开启对应lint规则：

include: package:flutter_lints/flutter.yaml

linter:
  rules:
    # 禁止外部使用本包标记为@internal的成员
    - invalid_use_of_internal_member
    # 禁止外部导入本包src目录下的内部代码
    - implementation_imports

配置完成后，外部项目导入你的包并调用这些@internal方法时，IDE会直接标红，执行dart analyze会返回错误，能有效阻止开发者误用内部API。

补充约定 #

遵循Dart包开发规范，所有内部实现代码都放在包的lib/src/目录下，对外仅暴露lib/根目录的导出文件，配合implementation_imports lint规则，可以避免外部误导入内部实现文件。

内容的提问来源于stack exchange，提问作者EvGeniy Ilyin