Flutter嵌入式配置插件embedded_config的使用

Flutter嵌入式配置插件embedded_config的使用

embedded_config 是一个允许在构建时将应用程序配置直接嵌入到源代码中的包。该插件旨在解决不同构建环境（例如开发环境和生产环境）需要不同应用程序配置的问题。通过使用 Dart 的构建系统（build_runner），可以为每个环境创建单独的 build.yaml 文件，并结合此包嵌入不同的配置。构建时，可以通过 build_runner 的 --config 选项选择所需的环境。

目录

• 安装
• 创建嵌入式配置类
• 映射配置来源
• 合并配置
• 内联配置来源
• 复杂配置模型
• 环境变量

使用方法

1. 安装

embedded_config 依赖于 build_runner 包。为了避免将 build_runner 作为普通依赖项添加，embedded_config 提供了一个伙伴包 embedded_config_annotations。

• 在 pubspec.yaml 中添加以下依赖项：

dependencies:
  embedded_config_annotations: ^0.3.0

dev_dependencies:
  embedded_config: ^0.4.0
  build_runner: ^2.0.0

2. 创建嵌入式配置类

配置是通过生成一个扩展抽象“嵌入式配置”类的类来嵌入到应用程序中的。生成的扩展类包含来自配置源的硬编码配置值。

1. 创建一个带有 @EmbeddedConfig 注解的抽象类：
   • 该类必须有一个默认的 const 构造函数。
   • 可以在类中定义抽象 getter，这些 getter 将映射到配置源中的键。

// file: app_config.dart

import 'package:embedded_config_annotations/embedded_config_annotations.dart';

// 添加生成的文件作为 part
part 'app_config.embedded.dart';

@EmbeddedConfig('app_config')
abstract class AppConfig {
  // 获取 API URL
  String get apiUrl;

  // 获取 Auth 配置
  AppAuthConfig get auth;

  // 必须声明一个默认的 const 构造函数
  const AppConfig();
}

// 由于这个类表示配置中的子对象，因此需要指定从配置根到该对象的路径
@EmbeddedConfig('app_config', path: ['auth'])
abstract class AppAuthConfig {
  // 获取客户端 ID，值将从环境变量 AUTH_CLIENT_ID 中获取
  String get clientId;

  const AppAuthConfig();
}

1. 暴露生成的类：
   • 可以通过 static const 单例方式暴露生成的类。

@EmbeddedConfig('app_config')
abstract class AppConfig {
  static const AppConfig instance = _$AppConfigEmbedded();

  String get apiUrl;
  AppAuthConfig get auth;

  const AppConfig();
}

3. 映射配置来源

接下来，我们需要实际的配置。配置可以指定在应用程序包中的配置文件或 build.yaml 文件中。有效的配置文件包括 JSON 和 YAML 格式的文件。

1. 在 build.yaml 中配置 embedded_config：
   • 将配置源键（如 app_config）映射到 JSON 或 YAML 文件。

targets:
  $default:
    builders:
      embedded_config:
        options:
          # 将配置源键 'app_config' 映射到 'lib/app_config.json' 文件
          app_config: 'lib/app_config.json'

1. 配置文件示例：
   • 假设 app_config.json 文件内容如下：

{
  "apiUrl": "/api",
  "auth": {
    "clientId": "$AUTH_CLIENT_ID"
  }
}

1. 生成的文件：
   • 构建后，会生成一个名为 app_config.embedded.dart 的文件，其中包含硬编码的配置值。

part of 'app_config.dart';

class _$AppConfigEmbedded extends AppConfig {
  const _$AppConfigEmbedded();

  @override
  final apiUrl = '/api';

  @override
  final auth = _$AppAuthConfigEmbedded();
}

class _$AppAuthConfigEmbedded extends AppAuthConfig {
  const _$AppAuthConfigEmbedded();

  @override
  final clientId = 'your_client_id';  // 从环境变量 AUTH_CLIENT_ID 获取
}

合并配置

可以将多个配置源映射到同一个注解类。例如，可以定义一个基础的 app_config.json 文件和环境特定的 app_config.dev.json 和 app_config.prod.json 文件。在 build.dev.yaml 文件中，可以将 dev JSON 文件映射到基础文件上，而在 build.prod.yaml 文件中映射 prod 文件。

targets:
  $default:
    builders:
      embedded_config:
        options:
          app_config:
            source:
              - 'lib/app_config.json'
              - 'lib/app_config.dev.json'

内联配置来源

配置也可以直接在 build.yaml 文件中指定。这可以通过 inline 属性完成。

targets:
  $default:
    builders:
      embedded_config:
        options:
          app_config:
            inline:
              apiUrl: '/api2'

复杂配置模型

当配置不是扁平的键值对时，可以使用多个注解的嵌入式配置类。这通过设置 @EmbeddedConfig 注解的 path 属性来实现。path 是一个从配置根到所需子对象的配置键列表。

@EmbeddedConfig('app_config')
abstract class AppConfig {
  String get prop1;
  AppSubConfig get sub;

  const AppConfig();
}

@EmbeddedConfig('app_config', path: ['sub'])
abstract class AppSubConfig {
  String get prop2;
  AppSub2Config get sub2;

  const AppSubConfig();
}

@EmbeddedConfig('app_config', path: ['sub', 'sub2'])
abstract class AppSub2Config {
  String get prop3;

  const AppSub2Config();
}

环境变量

环境变量可以替换配置中的任何字符串值。这通过以 $ 开头的值来实现。例如，$BUILD_ID 将被替换为环境变量 BUILD_ID 的值。

转义环境变量

如果配置值以 $ 开头但不希望被替换为环境变量，可以使用 \ 进行转义。

{
  "value": "\$BUILD_ID"
}

示例：嵌入 CI 构建标识符

可以通过环境变量将 CI 构建标识符嵌入到应用程序中。

import 'package:embedded_config_annotations/embedded_config_annotations.dart';

@EmbeddedConfig('environment')
abstract class Environment {
  String get buildId;

  const Environment();
}

可以在 JSON 源中指定环境变量：

{
  "buildId": "$BUILD_ID"
}

或者在 build.yaml 中内联指定：

targets:
  $default:
    builders:
      embedded_config:
        options:
          environment:
            inline:
              buildId: '$BUILD_ID'

完整示例 Demo

假设我们有一个多级 JSON 配置文件 app_config.json，并且希望将其嵌入到应用程序中，同时使用环境变量。

1. 配置文件 app_config.json

{
  "apiUrl": "/api",
  "auth": {
    "clientId": "$AUTH_CLIENT_ID"
  }
}

2. Dart 类 app_config.dart

// file: lib/app_config.dart

import 'package:embedded_config_annotations/embedded_config_annotations.dart';

part 'app_config.embedded.dart';

@EmbeddedConfig('app_config')
abstract class AppConfig {
  static const AppConfig instance = _$AppConfigEmbedded();

  String get apiUrl;
  AppAuthConfig get auth;

  const AppConfig();
}

@EmbeddedConfig('app_config', path: ['auth'])
abstract class AppAuthConfig {
  String get clientId;

  const AppAuthConfig();
}

3. build.yaml 配置

targets:
  $default:
    builders:
      embedded_config:
        options:
          app_config: 'lib/app_config.json'

4. 使用配置

在应用程序中使用嵌入的配置：

void main() {
  print('API URL: ${AppConfig.instance.apiUrl}');
  print('Client ID: ${AppConfig.instance.auth.clientId}');
}