Flutter动作执行工具插件actions_toolkit_dart的使用

Flutter动作执行工具插件actions_toolkit_dart的使用

简介

actions_toolkit_dart 是一个为 GitHub Actions 编写的 Dart 工具包。它提供了核心功能，用于设置结果、日志记录、注册密钥和导出变量等操作。这个工具包是官方 actions/toolkit 的 Dart 版本移植。

安装

你可以通过以下两种方式安装 actions_toolkit_dart：

1. 使用 dart pub add 命令：

   $ dart pub add actions_toolkit_dart
   

2. 手动添加到 pubspec.yaml 文件中：

   dependencies:
     actions_toolkit_dart: ^0.5.1
   

导入包

在 Dart 文件中导入 actions_toolkit_dart 包：

import 'package:actions_toolkit_dart/core.dart' as core;

使用示例

1. 输入/输出 (Inputs/Outputs)

你可以使用 getInput 和 getBooleanInput 来读取 GitHub Actions 的输入参数，并使用 setOutput 来设置输出参数。

// 获取输入参数
final myInput = core.getInput(name: 'inputName', options: const core.InputOptions(required: true));
final myBooleanInput = core.getBooleanInput(name: 'booleanInputName', options: const core.InputOptions(required: true));
final myMultilineInput = core.getMultilineInput(name: 'multilineInputName', options: const core.InputOptions(required: true));

// 设置输出参数
core.setOutput(name: 'outputKey', value: 'outputVal');

2. 导出环境变量 (Exporting Variables)

由于每个步骤在独立的进程中运行，你可以使用 exportVariable 将变量导出到当前步骤和后续步骤的环境变量中。

core.exportVariable(name: 'envVar', value: 'Val');

3. 设置密钥 (Setting a Secret)

设置密钥可以确保其在日志中被屏蔽。

core.setSecret('myPassword');

4. 路径操作 (PATH Manipulation)

使用 addPath 可以将工具的路径添加到作业的 PATH 环境变量中，而不会影响机器或容器的状态。

core.addPath('/path/to/my_tool');

5. 设置退出代码 (Exit codes)

你应该使用此库来设置失败的退出代码。如果未设置状态且脚本运行完成，则会导致成功。

try {
  // 执行某些操作
}
catch (err) {
  // setFailed 记录消息并设置失败的退出代码
  core.setFailed('Action failed with error $err');
}

6. 日志记录 (Logging)

你可以使用 debug、warning、info 和 notice 方法进行日志记录。

import 'package:actions_toolkit_dart/core.dart' as core;

try {
  core.debug('Inside try block');

  core.warning('myInput was not set');

  if (core.isDebug()) {
    // curl -v https://github.com
  } else {
    // curl https://github.com
  }

  // 执行某些操作
  core.info('Output to the actions build log');

  core.notice('This is a message that will also emit an annotation');
}
catch (err) {
  core.error('Error $err, action may still succeed though');
}

7. 折叠输出 (Foldable Groups)

此库还可以将输出包裹在可折叠的组中。

import 'package:actions_toolkit_dart/core.dart' as core;

// 手动包裹输出
core.startGroup('Do some function');
doSomeFunction();
core.endGroup();

// 包裹异步函数调用
const result = await core.group('Do something async', () async {
  const response = await doSomeHTTPRequest();
  return response;
});

8. 注解 (Annotations)

此库有三种方法可以生成注解，这些注解会显示在 GitHub Actions 页面和 Pull Requests 中。

core.error('This is a bad error. This will also fail the build.');

core.warning("Something went wrong, but it's not bad enough to fail the build.");

core.notice('Something happened that you might want to know about.');

完整示例 Demo

以下是一个完整的示例，展示了如何使用 actions_toolkit_dart 创建一个简单的 GitHub Action：

import 'package:actions_toolkit_dart/core.dart' as core;

void main() async {
  try {
    // 获取输入参数
    final inputName = core.getInput(name: 'inputName', options: const core.InputOptions(required: true));
    final booleanInput = core.getBooleanInput(name: 'booleanInputName', options: const core.InputOptions(required: true));
    final multilineInput = core.getMultilineInput(name: 'multilineInputName', options: const core.InputOptions(required: true));

    // 设置输出参数
    core.setOutput(name: 'outputKey', value: 'outputVal');

    // 导出环境变量
    core.exportVariable(name: 'envVar', value: 'Val');

    // 设置密钥
    core.setSecret('myPassword');

    // 路径操作
    core.addPath('/path/to/my_tool');

    // 日志记录
    core.debug('Inside try block');
    core.warning('myInput was not set');
    core.info('Output to the actions build log');
    core.notice('This is a message that will also emit an annotation');

    // 折叠输出
    core.startGroup('Do some function');
    doSomeFunction();
    core.endGroup();

    // 包裹异步函数调用
    const result = await core.group('Do something async', () async {
      const response = await doSomeHTTPRequest();
      return response;
    });

    // 输出结果
    core.info('Result: $result');
  } catch (err) {
    // 设置失败的退出代码
    core.setFailed('Action failed with error $err');
  }
}

void doSomeFunction() {
  // 模拟一些操作
  core.info('Doing some function...');
}

Future<String> doSomeHTTPRequest() async {
  // 模拟 HTTP 请求
  await Future.delayed(Duration(seconds: 2));
  return 'HTTP Response';
}