包 API 参考

WARNING

Task 的包 API 仍处于实验阶段，可能存在破坏性变更。

这意味着与我们的 CLI 不同，我们可能在次要（甚至补丁）版本中对包 API 进行破坏性更改。我们会尽可能避免这种情况，但为了改进包 API 的整体设计，这可能是有必要的。

未来我们可能会稳定包 API。但目前尚未有此计划。现在，如果您需要在 Go 包中使用 Task，我们建议您在 go.mod 文件中固定版本。在可能的情况下，我们会尝试为包 API 的破坏性变更包含更新日志条目。

Task 主要是一个与任何编程语言无关的 CLI 工具。然而，它是用 Go 编写的，因此也可以作为 Go 包使用。如果您已在项目中使用 Go 并且需要以某种方式扩展 Task 的功能，这会非常有用。在本文档中，我们描述了 Task 的公共 API 接口以及如何使用它。如果您想为 Task 做贡献或更详细地了解其工作原理，这也可能有用。

关键包

以下包构成了 Task 包 API 的最重要部分。下面我们列出了它们的用途以及一些可用的关键类型：

`github.com/go-task/task/v3`

核心任务包提供了 Task 的大部分主要功能，包括从 Taskfile 获取和执行任务。目前，该包的绝大部分功能通过 task.Executor 公开，它允许用户从 Taskfile 获取和执行任务。

INFO

这是我们优化 API 时最有可能发生破坏性变更的包。

`github.com/go-task/task/v3/taskfile`

taskfile 包提供了从各种来源_读取_ Taskfile 的工具。这些来源可以是本地文件、远程文件，甚至内存中的字符串（通过 stdin）。

taskfile.Node - Taskfile 位置的引用。Node 是一个接口，有多个实现：
- taskfile.FileNode - 本地文件
- taskfile.HTTPNode - 通过 HTTP/HTTPS 的远程文件
- taskfile.GitNode - 通过 Git 的远程文件
- taskfile.StdinNode - 内存中的字符串（通过 stdin）
taskfile.Reader - 接受一个 Node 并从中读取 Taskfile。
taskfile.Snippet - 主要用于呈现 Taskfile 错误。代码段存储 Taskfile 中围绕给定行号和列的一小部分。输出可以在 CLI 中进行语法高亮显示，并包含行/列指示器。

`github.com/go-task/task/v3/taskfile/ast`

AST 代表"抽象语法树"。AST 允许我们在 Go 中轻松表示 Taskfile 语法。该包提供了将 Taskfile YAML 解析为 AST 并将其存储在内存中的方法。

ast.TaskfileGraph - 表示一组 Taskfile 及其之间的依赖关系。
ast.Taskfile - 表示单个 Taskfile 或一组合并的 Taskfile。Taskfile 类型包含 Taskfile 语法的所有子类型，例如 tasks、includes、vars 等。为简洁起见，这里不一一列出。

`github.com/go-task/task/v3/errors`

包含 Task 中使用的所有错误类型。所有这些类型都实现了 errors.TaskError 接口，该接口封装了 Go 的标准 error 接口。这允许您对错误调用 Code 方法以获取任何错误的唯一退出代码。

读取 Taskfile

首先导入 github.com/go-task/task/v3/taskfile 包。这提供了将 Taskfile 读入内存所需的所有函数：

import (
    "github.com/go-task/task/v3/taskfile"
)

读取 Taskfile 是通过使用 taskfile.Reader 和 taskfile.Node 的实现来完成的。在此示例中，我们将使用 taskfile.FileNode 类型读取本地文件。您可以通过调用 taskfile.NewFileNode 函数来创建它：

node := taskfile.NewFileNode("Taskfile.yml", "./path/to/dir")

然后通过调用 taskfile.NewReader 函数并传递您想要使用的任何功能选项来创建读取器。例如，您可以向读取器传递一个调试函数，该函数将使用调试消息调用：

reader := taskfile.NewReader(
  taskfile.WithDebugFunc(func(s string) {
    slog.Debug(s)
  }),
)

现在一切都设置好了，您可以通过调用读取器上的 Read 方法并传递 Node 作为参数来读取 Taskfile（以及任何包含的 Taskfile）：

ctx := context.Background()
tfg, err := reader.Read(ctx, node)
// handle error

这将返回一个 ast.TaskfileGraph 实例，这是一个所有已解析 Taskfile 的"有向无环图"（DAG）。我们使用此图来存储和解析 Taskfile 中的 includes 指令。但大多数时候，您会需要合并的 Taskfile。为此，只需在 Taskfile 图上调用 Merge 方法：

tf, err := tfg.Merge()
// handle error

这将 DAG 编译成一个单一的 ast.Taskfile，包含我们从所有 Taskfile 读取的所有命名空间和任务。

INFO

我们计划在未来移除 AST 合并，因为它不必要地复杂，并且导致了许多作用域问题。

包 API 参考 ​

关键包 ​

github.com/go-task/task/v3 ​

github.com/go-task/task/v3/taskfile ​

github.com/go-task/task/v3/taskfile/ast ​

github.com/go-task/task/v3/errors ​