Flutter环境变量管理插件envystic的使用

Envystic 是一个用于简化 Dart 和 Flutter 项目中环境变量管理的包。它通过提供一个方便且结构化的管理方式来定义和访问环境变量，从而确保代码更干净和安全。

功能

• 轻松管理环境变量: Envystic 通过提供一个方便且结构化的管理方式来定义和访问环境变量。
• 安全变量存储: Envystic 允许你提供一个可选的加密密钥来加密环境变量的值，增强敏感信息的安全性。
• 基于注解: 使用注解定义环境变量非常简单。Envystic 和 EnvysticField 注解帮助生成访问环境变量所需的代码。
• 高级加载选项: Envystic 支持高级加载选项，允许从不同的来源获取环境变量，包括远程配置、系统环境变量或预存储的选项。
• 支持 Flutter 和 Dart: Envystic 设计为与 Flutter 和 Dart 项目无缝协作，允许在不同类型的应用程序中一致地管理环境变量。

安装

Flutter 项目

flutter pub add envystic && flutter pub add --dev envystic_generator build_runner

Dart 项目

dart pub add envystic && dart pub add --dev envystic_generator build_runner

使用

步骤1: 导入 envystic 包

import 'package:envystic/envystic.dart';

步骤2: 定义环境变量类

part 'env.g.dart';

enum RoleEnum {
  editor, author, viewer
}

@envystic
class Env extends _$Env {
  const Env._();

  // 如果不需要加密，可以省略 `encryptionKey`
  factory Env({
    String? encryptionKey,
    ValuesPriority? valuesPriority,
  }) = _Env;

  factory Env.define({
    required String key1,
    // .env 文件中的 'FOO' 值将被使用
    @EnvysticField(name: 'FOO') int? key2,
    required RoleEnum role,
  }) = _EnvDefine;

  // 忽略
  String get drink => 'Coffee';
}

步骤3: 生成环境变量类

dart run build_runner build

这会根据代码库中的注解生成必要的代码。

步骤4: 访问环境变量

void main() {
  final env = Env();
  // 访问环境变量
  print(env.key1); 
  print(env.key2);
  print(env.role);
  print(env.drink); // "Coffee"
}

配置

@envystic 注解支持以下可选参数：

• path: 指定环境变量文件的路径。如果不提供，默认路径为 .env。
• keyFormat: 指定环境文件（如 .env 文件）中键名的格式。可以选择不同的命名约定，如 kebab-case, snake_case, PascalCase 或 SCREAMING_SNAKE_CASE。
• generateEncryption: 确定是否生成 encryptionKeyOutput 如果它尚未存在。如果设置为 true，Envystic 将自动创建一个 encryption 密钥以增强安全性。
• encryptionKeyOutput: 指定用于保存 encryption 密钥的文件路径。如果 generateEncryption 设置为 true 且此参数为 null，则默认路径 env_encryption.key 将用于存储加密密钥。或者，如果你将 encryptionKeyOutput 设置为 null 并且 generateEncryption 不是 true，则不会应用加密，而是对值进行 base64 编码以提供基本级别的保护。

这些配置选项提供了高效的环境变量管理。可以根据需要自定义文件路径、键命名约定并增强安全性。

EnvysticAll 注解

@EnvysticAll 注解提供了一种自动加载环境文件中所有键的方式，而无需单独指定它们。

示例:

import 'package:envystic/envystic.dart';
import 'package:firebase_remote_config/firebase_remote_config';

part 'env_all.g.dart';

int? specialKeyFetch({
  required RemoteConfig remoteConfig,
  int defaultVal = 42,
}) {
  int remoteVal = remoteConfig.getInt("specialKey");
  remoteVal = remoteVal == 0 ? defaultVal : remoteVal;
  return remoteVal;
}

int? specialKeyLoader() =>
    specialKeyFetch(remoteConfig: getRemoteConfigInstance());

@EnvysticAll(
  path: '.env.example',
  encryptionKeyOutput: 'example.key',
)
class EnvAll extends _$EnvAll {
  const EnvAll._();

  // 如果不需要加密，可以省略 `encryptionKey`
  factory EnvAll({
    String? encryptionKey,
    ValuesPriority? valuesPriority,
  }) = _EnvAll;

  factory EnvAll.define({
    @EnvysticField(name: 'MY_SPECIAL_KEY', customLoader: specialKeyLoader)
    int? specialKey,
  }) = _EnvAllDefine;

  String get drink => 'Coffee';
}

void main() {
  var envAll = EnvAll(encryptionKey: encryptionKey);
  // 访问所有加载的环境变量
  print(envAll.specialKey); // 这个打印从 Firebase Remote Config 获取的值
  envAll = envAll.copyWith(
      valuesPriority: ValuesPriority(
    custom:
        0, // 改变这个为更高的值（例如：3）如果你想从 customLoader 而不是 .env 文件中获取
  ));
  print(envAll.specialKey); // 这个打印从 EnvAll 生成类中预存储的值
  envAll = envAll.copyWith(
      valuesPriority: ValuesPriority(
    stored: 0,
  ));
  print(envAll.specialKey); // 这个打印从运行系统环境变量 MY_SPECIAL_KEY 获取的值
  print(envAll.key1);
  print(envAll.key2);
  print(envAll.foo);
  print(envAll.bar);
  ...
}

建议使用 @Envystic 注解而不是 @EnvysticAll。使用 @Envystic 可以仅指定所需字段，减少类的负载，并确保更好的可维护性。

全局配置

可以通过 build.yaml 文件或命令行选项覆盖每个注解类中的 null 参数。以下是配置选项的方法：

方法1: 通过 build.yaml

1. 打开你的 build.yaml 文件，如果不存在则创建一个。
2. 查找 targets 部分并定位到 $default 目标。
3. 在 $default 目标下找到或添加 envystic_generator|envystic 构建器并修改选项如下：

targets:
  $default:
    builders:
      envystic_generator|envystic:
        options:
          # 选择所需的键格式：none, kebab, snake, pascal, 或 screamingSnake
          key_format: screamingSnake
          # 确定是否生成加密密钥输出，如果它尚未存在
          # 设置为 true 以启用生成加密密钥
          generate_encryption: true
          # `encryption_key_output` 用于保存加密密钥的文件路径
          # 如果 `generate_encryption` 为 true 且未设置 `encryption_key_output`，则默认值 'env_encryption.key' 将被使用
          # 注释掉以下行并设置 `generate_encryption` 为 false
          # 以排除 dotenv 值的加密
          encryption_key_output: env_encryption_output.key

方法2: 通过命令行

1. 打开终端或命令提示符。
2. 使用以下命令指定所需的配置：

dart run build_runner build --define envystic_generator:envystic=generate_encryption=true --define envystic_generator:envystic=encryption_key_output=env_encryption_output.key

通过这些全局配置选项，你可以定制 Envystic 如何处理环境变量。key_format 允许你选择所需的键名称格式（如 kebab-case, snake_case, PascalCase, SCREAMING_SNAKE_CASE 等）。generate_encryption 选项让你决定是否生成加密密钥以增强安全性，并且你可以指定文件路径使用 encryption_key_output。

通过设置这些全局选项，你可以确保在所有注解类中一致的行为，使在 Dart 和 Flutter 项目中管理环境变量变得更加容易和维护。

方法

T get<T>(String envKey)

从加载的环境条目中检索与给定 envKey 关联的值。 返回值的类型基于实际字段类型推断。

示例:

final myValue = env.get<int>('MY_SPECIAL_KEY');

在这个例子中，MY_SPECIAL_KEY 是从加载的环境条目中按指定的 integer 类型检索的。如果键不存在或值无法转换为指定类型，此方法将抛出异常。

T? tryGet<T>(String envKey)

尝试从加载的环境条目中检索与给定 envKey 关联的值。 如果键不存在或值无法转换为指定类型，此方法将返回 null 而不是抛出异常。

T getForField<T>(String fieldName)

从加载的环境条目中检索与给定 fieldName 关联的值。 返回值的类型基于指定的泛型类型 T 推断。

示例:

final myValue = env.getForField<int>('specialKey');

bool isKeyExists(String envKey)

检查提供的 envKey 是否存在于加载的环境键中。 如果键存在返回 true，否则返回 false。

String? getFieldName(String envKey)

获取与提供的 envKey 关联的字段名。 如果 envKey 存在，则返回相应的字段名；否则返回 null。

重要事项

在使用 Envystic 包管理 Dart/Flutter 项目的环境变量时，需要注意以下几点：

1. 依赖于构建工具: Envystic 依赖于 build_runner 工具来根据注解生成必要的代码。为了确保生成的代码始终与更改保持同步，请执行以下步骤：
   • 每次修改注解的环境类时，执行以下命令以重新生成必要的代码：

     dart run build_runner build
     

   • 注意，build_runner 不会自动检测 .env 文件的变化。因此，在运行构建命令之前，必须使用以下命令清理之前的构建：

     dart run build_runner clean