Flutter配置管理插件bro_config_manager的使用

目录

• 介绍
• 使用
  • 演示
  • 配置文件夹结构
  • 配置文件内容
  • 用环境变量覆盖配置文件
  • 使用环境变量
    • 演示
    • 平台特定环境变量
    • 点env文件
    • 构建环境变量
  • 总结

介绍

这个包包含了配置管理器的抽象类。配置管理器可以被其他管理器和其他类用来从特定文件中读取应用程序配置。

这个包受node config包的启发。

这个包基于bro_abstract_manager包。

使用

演示

配置管理器使用的配置文件会根据构建应用程序时使用的环境（dev、staging 或 prod）进行调整。为此，在构建应用程序时，您需要指定要使用的环境。这可以通过在构建应用程序时使用 --dart-define 选项来实现。

要使用的环境值为 APP_ENV，其值必须是 dev、staging 或 prod（development 和 production 也是可用的）。

配置管理器将在 assets/configs 目录中查找配置文件。该目录必须作为资产添加到 pubspec.yaml 文件中。 配置文件夹路径可以通过构造函数的 configFolderPath 参数更改。

配置文件夹结构

配置管理器将在 assets/configs 目录中查找配置文件。配置文件必须是 JSON 或 YAML 文件（文件扩展名可以是 .json、.yaml 或 .yml）。配置管理器将按以下顺序解析这些文件：

1. default.{json|yaml|yml}：此文件包含所有配置的默认值，不依赖于环境。
2. {environment}.{json|yaml|yml}：此文件包含依赖于环境的值。环境由 APP_ENV 变量指定。 注意：文件名只能是 development、staging 或 production。
3. local.{json|yaml|yml}：此文件包含特定于本地环境的值。该文件仅限于设备，并且不应提交到仓库。

如果这些文件之一不存在，配置管理器不会抛出错误。它只会使用其他文件中的值。只有当预期的变量在任何文件中都找不到其值时，配置管理器才会抛出错误。

配置文件内容

配置文件的结构是一个 Map<String, dynamic>，其中键是变量名称。您可以创建配置文件的层次结构以使其更易读。

避免在变量名称中使用 .，因为它可能会导致解析失败。

变量值可以是 YAML 值。以下是配置文件的一个示例：

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    # 这是日志记录器的全局级别，可以通过以下路径访问：
    # `logger.globalLevel`
    globalLevel: debug

    # 这包含控制台日志记录器的设置
    console:
        # 这是控制台日志记录器的级别，可以通过以下路径访问：
        # `logger.console.level`
        level: debug

        # 如果为真，则启用控制台日志记录器
        enabled: true

    # 这包含文件日志记录器的设置
    file:
        # 这是文件日志记录器的级别，可以通过以下路径访问：
        # `logger.file.level`
        level: debug

        # 如果为真，则启用文件日志记录器
        enabled: true

用环境变量覆盖配置文件

您可以使用环境变量覆盖配置文件中的值。

为此，您需要创建一个映射文件，将环境变量映射到配置变量。映射文件必须是 JSON 或 YAML 文件，并且必须命名为 env_mapping.{json|yaml|yml}。

映射文件的结构与配置文件相同，唯一的区别是值是环境变量名称。

如果您想解析非字符串值，可以通过以下语法指定值类型：

key:
    __name: ENV_VAR_NAME
    __format: int

以下是映射文件的一个示例：

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    # 这是日志记录器的全局级别，可以通过以下路径访问：
    # `logger.globalLevel`
    globalLevel: LOGGER_GLOBAL_LEVEL

    # 这包含控制台日志记录器的设置
    console:
        # 这是控制台日志记录器的级别，可以通过以下路径访问：
        # `logger.console.level`
        level: LOGGER_CONSOLE_LEVEL

        # 如果为真，则启用控制台日志记录器
        enabled:
            __name: LOGGER_CONSOLE_ENABLED
            __format: bool

    # 这包含文件日志记录器的设置
    file:
        # 这是文件日志记录器的级别，可以通过以下路径访问：
        # `logger.file.level`
        level: LOGGER_FILE_LEVEL

        # 如果为真，则启用文件日志记录器
        enabled:
            __name: LOGGER_FILE_ENABLED
            __format: bool

支持的类型有：

• int,
• double,
• bool,
• string,
• object（这将解析值为 JSON 对象），
• array（这将解析值为 JSON 数组）。

使用环境变量

演示

要使用环境变量，您需要在 assets/configs 目录中添加映射文件。

平台特定环境变量

首先，应用程序将尝试在平台特定变量中找到环境变量的值。

点env文件

然后，您可以使用 .env 文件来设置环境变量。.env 文件必须命名为 {environment}.env，其中 {environment} 是您要使用的环境。

我们不建议将 .env 文件提交到仓库，因为它们可能包含敏感数据。

该库使用了 flutter_dotenv包 来解析 .env 文件。

配置管理器将按以下顺序解析环境文件：

1. .env：此文件包含所有环境变量的用户值。
2. default.env：此文件包含所有环境变量的默认值。
3. {environment}.env：此文件包含依赖于环境的值。
4. local.env：此文件包含特定于本地环境的值。

构建环境变量

您还可以通过使用 --dart-define 选项直接在构建命令中设置环境变量。

这些值将覆盖 .env 文件中的值。

请注意，构建命令中设置的值只能在运行时通过常量键访问。

总结

总结一下，配置管理器将按以下顺序查找值：

1. default.{json|yaml|yml}：所有配置的默认值。
2. {environment}.{json|yaml|yml}：依赖于环境的值。
3. local.{json|yaml|yml}：特定于本地环境的值。
4. 平台特定环境变量。
5. .env 文件。
   • .env：所有环境变量的用户值。
   • default.env：所有环境变量的默认值。
   • {environment}.env：依赖于环境的值。
   • local.env：特定于本地环境的值。
6. 构建环境变量。

完整示例

示例代码

pubspec.yaml

name: bro_config_manager_example
description: A sample project to demonstrate the usage of bro_config_manager.

dependencies:
  flutter:
    sdk: flutter
  bro_abstract_manager: ^1.0.0
  bro_config_manager: ^1.0.0
  flutter_dotenv: ^5.0.0

flutter:
  assets:
    - assets/configs/

main.dart

import 'package:flutter/material.dart';
import 'package:bro_abstract_manager/abstract_manager.dart';
import 'package:bro_config_manager/config_manager.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async {
  // 初始化 dotenv
  await dotenv.load(fileName: "assets/configs/.env");

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Bro Config Manager Example'),
        ),
        body: Center(
          child: ConfigReader(),
        ),
      ),
    );
  }
}

class ConfigReader extends StatefulWidget {
  @override
  _ConfigReaderState createState() => _ConfigReaderState();
}

class _ConfigReaderState extends State<ConfigReader> {
  Map<String, dynamic> _config = {};

  @override
  void initState() {
    super.initState();
    // 初始化配置管理器
    ConfigManager().initialize(
      configFolderPath: 'assets/configs',
      defaultConfigFileName: 'default.yaml',
      envConfigFileName: 'dev.yaml', // 可以替换为 staging 或 prod
      localConfigFileName: 'local.yaml',
      envMappingFileName: 'env_mapping.yaml',
    ).then((_) {
      setState(() {
        _config = ConfigManager().getConfig();
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text('Global Logger Level: ${_config['logger']['globalLevel']}'),
        Text('Console Logger Enabled: ${_config['logger']['console']['enabled']}'),
        Text('File Logger Enabled: ${_config['logger']['file']['enabled']}'),
      ],
    );
  }
}

assets/configs/default.yaml

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    globalLevel: debug
    console:
        level: debug
        enabled: true
    file:
        level: debug
        enabled: true

assets/configs/dev.yaml

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    globalLevel: info
    console:
        level: info
        enabled: false
    file:
        level: info
        enabled: true

assets/configs/local.yaml

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    globalLevel: warning
    console:
        level: warning
        enabled: true
    file:
        level: warning
        enabled: false

assets/configs/env_mapping.yaml

# 这是存储与日志记录相关的配置变量的主要类别
logger:
    globalLevel: LOGGER_GLOBAL_LEVEL
    console:
        level: LOGGER_CONSOLE_LEVEL
        enabled:
            __name: LOGGER_CONSOLE_ENABLED
            __format: bool
    file:
        level: LOGGER_FILE_LEVEL
        enabled:
            __name: LOGGER_FILE_ENABLED
            __format: bool

assets/configs/.env

LOGGER_GLOBAL_LEVEL=debug
LOGGER_CONSOLE_LEVEL=info
LOGGER_CONSOLE_ENABLED=true
LOGGER_FILE_LEVEL=info
LOGGER_FILE_ENABLED=false

运行项目

确保您的 pubspec.yaml 文件正确配置并安装依赖项。然后运行以下命令来启动应用程序：

flutter run --dart-define APP_ENV=dev