Flutter配置管理插件conduit_config的使用

Flutter配置管理插件conduit_config的使用

conduit_config 是一个用于在Dart和Flutter项目中安全地管理YAML配置文件的库。它通过将YAML文件映射到Dart对象来确保类型和名称的安全性。以下是关于如何使用 conduit_config 的详细说明和完整示例。

基本用法

conduit_config 的基本用法非常简单，它会将YAML文件中的键值对映射到Dart类的属性上。这样可以确保在运行时检查YAML值的类型，并且防止键名拼写错误。

假设你想要配置应用程序的端口和服务器头信息，你可以定义一个继承自 Configuration 的类：

import 'package:conduit_config/conduit_config.dart';
import 'dart:io';

class ApplicationConfiguration extends Configuration {
  ApplicationConfiguration(String fileName) : super.fromFile(File(fileName));

  int port; // 端口号
  String serverHeader; // 服务器头信息
}

对应的YAML文件 config.yaml 应该包含这两个大小写敏感的键：

port: 8000
serverHeader: booyah/1

要读取配置文件，你可以这样做：

void main() {
  var config = ApplicationConfiguration("config.yaml");
  print("${config.port}"); // 输出: 8000
  print("${config.serverHeader}"); // 输出: "booyah/1"
}

如果 port 不是整数或缺失，或者 serverHeader 不是字符串或缺失，程序将会抛出异常。

高级用法

可选属性

你可以标记 Configuration 中的属性为可选，这样即使某些键在YAML文件中缺失也不会抛出异常，而是返回 null。

class ApplicationConfiguration extends Configuration {
  ApplicationConfiguration(String fileName) : super.fromFile(File(fileName));

  int port;

  [@optionalConfiguration](/user/optionalConfiguration)
  String serverHeader;
}

如果 serverHeader 在YAML文件中被省略，它的值将是 null，而不会抛出异常。

内置配置类

conduit_config 提供了两个内置的 Configuration 类：DatabaseConfiguration 和 APIConfiguration，它们包含了常见的配置项。

例如，你可以嵌套 DatabaseConfiguration 来配置数据库：

class ApplicationConfiguration extends Configuration {
  ApplicationConfiguration(String fileName) : super.fromFile(File(fileName));

  int port;
  DatabaseConfiguration userDatabase;
}

对应的YAML文件可以是：

port: 8000
userDatabase:
  databaseName: dartstuff
  host: stablekernel.com
  port: 5432

使用数组和映射

你还可以使用数组和映射，其中的值可以是基本类型或 Configuration 的子类。

class ApplicationConfiguration extends Configuration {
  ApplicationConfiguration(String fileName) : super.fromFile(File(fileName));

  Map<String, DatabaseConfiguration> databases;
}

对应的YAML文件可以是：

databases:
  db1:
    databaseName: dartstuff
    host: stablekernel.com
    port: 5432
  db2:
    databaseName: otherstuff
    host: somewhereoutthere.com
    port: 5432

你可以这样访问这些配置：

var config = ApplicationConfiguration("config.yaml");

var databaseOne = config.databases["db1"];
await database.connect(
  databaseOne.host,
  databaseOne.port,
  databaseOne.databaseName,
);

多种YAML表示形式

一个配置可以有多种YAML表示形式。例如，DatabaseConfiguration 可以表示为一个包含各个组件（用户名、主机等）的 Map<String, dynamic>，也可以表示为一个连接字符串（如 postgres://user:password@host:port/database）。你可以通过重写 decode 方法来实现这种行为。

class AuthorityConfiguration extends Configuration {
  String username;
  String password;

  void decode(dynamic anyValue) {
    if (anyValue is! String) {
      throw ConfigurationException("Expected a String for AuthorityConfiguration.");
    }

    List<String> parts = anyValue.split(":");
    if (parts.length != 2) {
      throw ConfigurationException("Invalid format for AuthorityConfiguration.");
    }

    username = parts.first;
    password = parts.last;
  }
}

这个配置可以在以下两种情况下读取：

authority:
  username: "Bob"
  password: "Fred"

// 或者

authority: "Bob:Fred"

使用环境变量

你还可以在配置文件中引用环境变量。只需使用 $VARIABLE 语法作为值即可。

port: $PORT

当读取配置文件时，$PORT 将被替换为名为 PORT 的环境变量的值。

完整示例

下面是一个完整的示例，展示了如何使用 conduit_config 来管理应用程序的配置。

1. 创建 config.yaml 文件：

port: 8000
serverHeader: booyah/1
userDatabase:
  databaseName: dartstuff
  host: stablekernel.com
  port: 5432
databases:
  db1:
    databaseName: dartstuff
    host: stablekernel.com
    port: 5432
  db2:
    databaseName: otherstuff
    host: somewhereoutthere.com
    port: 5432
authority: "Bob:Fred"
port: $PORT

1. 创建 main.dart 文件：

import 'package:conduit_config/conduit_config.dart';
import 'dart:io';

class ApplicationConfiguration extends Configuration {
  ApplicationConfiguration(String fileName) : super.fromFile(File(fileName));

  int port;
  String serverHeader;

  [@optionalConfiguration](/user/optionalConfiguration)
  DatabaseConfiguration userDatabase;

  Map<String, DatabaseConfiguration> databases;

  AuthorityConfiguration authority;
}

class AuthorityConfiguration extends Configuration {
  String username;
  String password;

  void decode(dynamic anyValue) {
    if (anyValue is! String) {
      throw ConfigurationException("Expected a String for AuthorityConfiguration.");
    }

    List<String> parts = anyValue.split(":");
    if (parts.length != 2) {
      throw ConfigurationException("Invalid format for AuthorityConfiguration.");
    }

    username = parts.first;
    password = parts.last;
  }
}

void main() async {
  // 设置环境变量 PORT
  Platform.environment['PORT'] = '9000';

  // 读取配置文件
  var config = ApplicationConfiguration("config.yaml");

  // 打印配置信息
  print("Port: ${config.port}"); // 输出: 9000 (来自环境变量)
  print("Server Header: ${config.serverHeader}"); // 输出: booyah/1
  print("User Database Host: ${config.userDatabase?.host}"); // 输出: stablekernel.com
  print("Authority Username: ${config.authority.username}"); // 输出: Bob
  print("Authority Password: ${config.authority.password}"); // 输出: Fred

  // 访问嵌套的数据库配置
  var databaseOne = config.databases["db1"];
  if (databaseOne != null) {
    print("Database 1 Host: ${databaseOne.host}"); // 输出: stablekernel.com
    print("Database 1 Port: ${databaseOne.port}"); // 输出: 5432
    print("Database 1 Name: ${databaseOne.databaseName}"); // 输出: dartstuff
  }

  var databaseTwo = config.databases["db2"];
  if (databaseTwo != null) {
    print("Database 2 Host: ${databaseTwo.host}"); // 输出: somewhereoutthere.com
    print("Database 2 Port: ${databaseTwo.port}"); // 输出: 5432
    print("Database 2 Name: ${databaseTwo.databaseName}"); // 输出: otherstuff
  }
}