Flutter配置管理插件conf的使用

conf 是一个Dart包，用于定义配置模式并从多个来源加载配置值，例如：

• 命令行参数
• 环境变量
• 从命令行参数或环境变量中的JSON字符串
• JSON文件
• YAML文件

这些来源以可配置的顺序覆盖彼此。

安装

在 pubspec.yaml 文件中添加 conf 作为依赖项：

dart pub add conf

示例

完整的示例可以在 这里 查看。

模式

在可以加载配置值之前，你需要定义一个模式。我建议将模式拆分成多个类，每个类包含相关的配置值。例如，如果你有一个需要连接到数据库的服务器，你可能会定义一个 DatabaseConfiguration 类，其中包含数据库URL、用户名和密码：

class DatabaseConfiguration {
  DatabaseConfiguration({
    required this.url,
    required this.username,
    required this.password,
  });

  factory DatabaseConfiguration._factory(Map<String, Object?> map) => 
      DatabaseConfiguration(
        url: map['url']! as Uri,
        username: map['username']! as String,
        password: map['password']! as String,
      );

  static final schema = ConfObject(
    propertiesMap: {
      'url': ConfUri(),
      'username': ConfString(),
      'password': ConfString(),
    },
    factory: DatabaseConfiguration._factory,
  );

  final Uri url;
  final String username;
  final String password;
}

注意 DatabaseConfiguration 类有一个 schema 字段，它定义了该类的配置模式。schema 字段是一个 ConfObject，它定义了该类的配置属性及其如何从属性值映射创建 DatabaseConfiguration 实例。

现在我们定义一个 ServerConfiguration 类，它包含 DatabaseConfiguration 以及监听的端口和地址：

class ServerConfiguration {
  ServerConfiguration({
    required this.port,
    required this.address,
    required this.database,
  });

  factory ServerConfiguration._factory(Map<String, Object?> map) =>
      ServerConfiguration(
        port: map['port']! as int,
        address: map['address']! as InternetAddress,
        database: map['database']! as DatabaseConfiguration,
      );

  static final schema = ConfObject(
    propertiesMap: {
      'port': ConfDefault(ConfInteger(), defaultValue: 8080),
      'address': ConfDefault(
        ConfInternetAddress(),
        defaultValue: InternetAddress.loopbackIPv4,
      ),
      'database': DatabaseConfiguration.schema,
    },
    factory: ServerConfiguration._factory,
  );

  final int port;
  final InternetAddress address;
  final DatabaseConfiguration database;
}

在这里我们使用 ConfDefault 类为 port 和 address 属性定义默认值。我们还使用 DatabaseConfiguration.schema 字段来定义 database 属性。

标量值

conf 提供了许多内置的标量值模式类，用于加载标量值：

• ConfBool
• ConfNumber
• ConfInteger
• ConfDouble
• ConfString
• ConfDateTime
• ConfUri
• ConfInternetAddress
• ConfEnum

你也可以通过扩展 ConfScalar 类或其子类来自定义标量值模式类。例如，这是 ConfInternetAddress 类的实现：

class ConfInternetAddress extends ParseConfScalar<InternetAddress> {
  ConfInternetAddress() : super('InternetAddress');

  @override
  InternetAddress parse(String value) {
    final address = InternetAddress.tryParse(value);
    if (address == null) {
      throw FormatException(
        'Expected an IPv4 or IPv6 address but got "$value".',
      );
    }
    return address;
  }
}

加载配置

要加载 ServerConfiguration，我们需要一个 ConfigurationSource，它提供配置值。为了简单起见，我们将直接在代码中提供配置值：

final source = CombiningSource([
  CommandLineSource(['--database.username=test']),
  EnvironmentSource({
    'PORT': '4567',
    'DATABASE_URL': 'postgres://localhost:5432/db',
    'DATABASE_USERNAME': 'dev',
    'DATABASE_PASSWORD': 'password',
  })
]);

try {
  final configuration = await ServerConfiguration.schema.load(source);
  // 对配置进行处理。
} on ConfigurationException catch (error) {
  stderr.writeln(error);
  exitCode = 1;
}

如果加载配置失败，load 将抛出 ConfigurationException。conf 不会在遇到第一个错误后停止。相反，它会收集所有错误并在 ConfigurationException.errors 中提供它们。这允许你一次性显示所有错误，而不是一次解决一个错误。

上述示例演示了 conf 的核心功能之一：能够从具有不同格式的多个来源加载配置值。

conf 会根据模式为每个配置值推断环境变量名称。例如，port 属性从 PORT 环境变量加载，而 database.url 属性从 DATABASE_URL 加载。

命令行格式化配置值略有不同。例如，database.username 属性从 --database.username 命令行参数加载。

因为我们首先指定了 CommandLineSource，所以 database.username 属性从命令行参数而不是环境变量加载。

配置源

ConfigurationSource 是配置值的低级表示形式，使加载配置值变得容易，来源包括：

• CommandLineSource：从命令行参数加载配置值。
• EnvironmentSource：从环境变量加载配置值。
• DataSource：从JSON样式的数据结构加载配置值。通常用于从JSON和YAML文件加载配置值。
• CombiningSource：将多个来源组合成一个来源。

应用程序源

AppSources 提供了一种简单的方法，以适合Dart应用程序（如服务器）的方式加载配置源。

AppSources 假设应用程序定义了一组配置文件。配置文件是一组命名的配置值。例如，服务器可能有一个 dev 配置文件用于开发，一个 prod 配置文件用于生产。多个配置文件可以同时激活，并由 Profiles 类表示。

enum Profile {
  dev,
  prod,
  test;

  /// 当前活动的配置文件。
  static Profiles<Profile> get active => Profiles.active as Profiles<Profile>;
}

你可以在 --profiles 命令行参数或 PROFILES 环境变量中指定活动的配置文件，以逗号分隔列表的形式。例如：

$ dart run server.dart --profiles="dev,test"

继续上一节中的示例，我们可以使用 AppSources.load 来加载一个 CombiningSource，它结合了命令行和环境源以及配置文件源，这些源位于已知位置。

class ServerConfiguration {

  // ...

  static Future<ServerConfiguration> load(
    List<String> arguments, {
    Set<Profile>? additionalProfiles,
  }) async {
    final sources = await AppSources.load(
      arguments: arguments,
      allProfiles: Profile.values,
      defaultProfiles: {Profile.dev},
      additionalProfiles: additionalProfiles,
    );
    return schema.load(sources);
  }

  // ...

}