Flutter配置管理插件configuration_service的使用

此插件使应用程序能够有效地利用JSON配置文件。特别适用于后端服务或用Dart编写的CLI工具，但也可以与Flutter一起使用。

特性

• 类型安全处理JSON配置文件
• 不需要代码生成
• 处理可选值和必需值
• 如果值缺失可以使用默认值
• 支持环境变量（方便注入密钥）

开始使用

假设有一个名为config.json的配置文件，其内容如下：

{
    "enable_graphql_playground": true,
    "enable_introspection": true,
    "enable_schema_download": true
}

为了在应用中加载这样的配置文件，创建一个继承自ConfigurationService的类MyConfigurationService，并定义每个配置值的类型属性：

class MyConfigurationService extends ConfigurationService {
  // ConfigurationValue<bool> 定义一个布尔值。你可以使用bool, int, String, List<> 以及你自己的复杂类型（详见下方）。
  final enableGraphQLPlayground = ConfigurationValue<bool>(
    // 配置文件中值的名称
    name: "enable_graphql_playground",
    // 可选参数，如果配置文件中不存在该值，则使用默认值
    defaultValue: const Optional(false),
  );

  final enableIntrospection = ConfigurationValue<bool>(
    name: "enable_introspection",
    // 值可以被标记为必需。如果配置文件中缺少该值，将抛出异常。
    isRequired: true,
  );

  final enableSchemaDownload = ConfigurationValue<bool>(
    name: "enable_schema_download",
    defaultValue: const Optional(false),
  );

  final authVerifyToken = ConfigurationValue<bool>(
    name: "auth.verify_token",
    defaultValue: const Optional(true),
  );

  MyConfigurationService() {
    // 注册所有配置值，以便加载器可以识别它们
    register(enableGraphQLPlayground);
    register(enableIntrospection);
    register(enableSchemaDownload);
    register(authVerifyToken);
  }
}

加载配置文件使用loadFromJson()方法：

void main() async {
  final configurationService = MyConfigurationService();
  await configurationService.loadFromJson(
    filePath: 'config.json',
    allowEnvironmentOverrides: true,
    configurationEnvironmentVariable: 'SAMPLE_CONFIGURATION',
  );

  print(
      'auth.verify_token was present in the configuration file: ${configurationService.authVerifyToken.hasValue(ignoreDefault: true)}');
  print(
      'auth.verify_token has a value (default or explicit): ${configurationService.authVerifyToken.hasValue()}');
  print(
      'auth.verify_token is set to: ${configurationService.authVerifyToken.value}');
}

使用说明

访问配置文件中的值

假设存在以下配置文件：

{ "test": true }

以下代码会读取它：

final configurationValue = ConfigurationValue<bool>(name: 'test');

final configurationService = ConfigurationService();
configurationService.register(configurationValue);
await configurationService.loadFromJson(filePath: 'config.json');

print(configurationValue.value); // 输出 "true"

检查值是否存在

final configurationValue = ConfigurationValue<bool>(name: 'test');

final configurationService = ConfigurationService();
configurationService.register(configurationValue);
await configurationService.loadFromJson(filePath: 'config.json');

print(configurationValue.hasValue()); // 如果值存在于config.json中，则输出 "true"

使用默认值

final configurationValue = ConfigurationValue<bool>(name: 'test', defaultValue: Optional(true));

final configurationService = ConfigurationService();
configurationService.register(configurationValue);
await configurationService.loadFromJson(filePath: 'config.json');

print(configurationValue.hasValue()); // 即使在config.json中不存在，也会输出 "true"
print(configurationValue.hasValue(ignoreDefaults: true)); // 只有当值存在于config.json中时才输出 "true"

标记值为必需

final configurationValue = ConfigurationValue<bool>(name: 'test', isRequired: true);

final configurationService = ConfigurationService();
configurationService.register(configurationValue);

// 如果找不到 "test" 将抛出异常
await configurationService.loadFromJson(filePath: 'config.json');

print(configurationValue.value);

允许环境变量覆盖

使用allowEnvironmentOverrides优先考虑环境变量中的值。环境变量名通过将配置值的名称转换为CONSTANT_CASE来确定。

例如：

• verify_token 变为 VERIFY_TOKEN
• auth.verify_token 变为 AUTH_VERIFY_TOKEN

final configurationValue = ConfigurationValue<bool>(name: 'test', isRequired: true);

final configurationService = ConfigurationService();
configurationService.register(configurationValue);

await configurationService.loadFromJson(
  filePath: 'config.json',
  allowEnvironmentOverrides: true,
);

print(configurationValue.value); // 输出从环境变量TEST中找到的值，否则输出配置文件中的值

使用配置文件的部分

通常，分区配置文件以提高可维护性是有益的。可以通过使用点表示法指定配置值的层次结构。

假设以下配置文件：

{
  "auth": {
    "verify_token": true
  }
}

可以通过指定auth.verify_token作为其名称来访问该值。

使用复杂类型

configuration_service 原生支持 int, String 和 bool 以及相应的 List 类型。要加载自定义复杂类型，注册类型时指定反序列化方法：

configurationService.register(authEntityIdFallback, deserializers: {
      EntityIdFallbackConfig: EntityIdFallbackConfig.fromJson,
    });