你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Functions Go 开发人员参考

Important

Azure Functions 对 Go 的支持目前处于公共预览阶段。在预览期间，Go 函数应用仅在 Flex Consumption 计划中受支持。

Azure Functions是一种无服务器计算服务，可用于运行事件驱动代码，而无需预配或管理基础结构。 Go 工作进程使你能够使用 Go 原生编写 Azure Functions，并与 Azure Functions 触发器生态系统深度集成。

本指南可帮助你：

了解 Go 编程模型
创建和构建项目代码
使用触发器
在本地和Azure中部署和运行应用

若要了解一般Azure Functions开发的详细信息，请参阅 Azure Functions 开发人员参考。

入门

选择适合工作流的环境，开始使用 Azure Functions for Go：

命令行快速入门

先决条件

Go 1.24 或更高版本
Azure Functions Core Tools4.12 或更高版本。运行 func --version 以验证已安装的版本。
创建 Azure 资源或将包部署到 Azure 时，需要使用 Azure CLI 版本 2.87.0 或更高版本。运行 az version 以验证已安装的版本。

编程模型

Go 工作器使用代码优先的编程模型。使用惯用的 Go 处理程序定义无服务器函数及其触发器。

入口点

每个 Go 项目都以一个main()函数开头，该函数会创建一个FunctionApp、注册函数并启动工作器：

package main

import (
    "fmt"
    "net/http"

    "github.com/azure/azure-functions-golang-worker/sdk"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()

    app.HTTP("hello", hello,
        sdk.WithMethods("GET", "POST"),
        sdk.WithAuth("anonymous"),
    )

    worker.Start(app)
}

func hello(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    fmt.Fprintf(w, "Hello, %s!", name)
}

函数注册

使用 Fluent Builder API 和功能选项模式注册函数。每个触发器类型对 App 对象都有一个注册方法：

// HTTP trigger
app.HTTP("myHttpFunc", handler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

// Timer trigger
app.Timer("myTimerFunc", handler,
    sdk.WithSchedule("0 */5 * * * *"),
)

// Azure Cosmos DB trigger
app.CosmosDB("myCosmosFunc", handler,
    sdk.WithDatabase("mydb"),
    sdk.WithContainer("mycontainer"),
    sdk.WithConnection("CosmosDBConnection"),
)

// Azure Service Bus trigger
app.ServiceBusQueue("myServiceBusFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("ServiceBusConnection"),
)

// Event Hubs trigger
app.EventHub("myEventHubFunc", handler,
    sdk.WithEventHubName("myeventhub"),
    sdk.WithConnection("EventHubConnection"),
)

// Event Grid trigger
app.EventGrid("myEventGridFunc", handler)

// Blob trigger (extension model)
app.Blob("myBlobFunc", handler,
    sdk.WithPath("mycontainer/{name}"),
    sdk.WithConnection("AzureWebJobsStorage"),
)

项目结构

Azure Functions的 Go 代码项目是标准的 Go 模块。运行 func init --worker-runtime go时，将生成以下文件：

my-function-app/
├── host.json              # Host configuration
├── local.settings.json    # Local settings (connection strings, app settings)
├── go.mod                 # Go module file
├── go.sum                 # Go module checksums
└── main.go                # Entry point with function registrations

host.json

该文件 host.json 包含主机级配置选项。有关详细信息，请参阅 host.json 参考。

local.settings.json

该文件 local.settings.json 存储本地开发期间使用的应用设置和连接字符串。此文件未发布到Azure。有关详细信息，请参阅本地设置文件。

触发器

Go 工作线程根据其依赖要求将触发器分为两个层级：

核心触发器

核心触发器通过 gRPC 以内联方式接收其负载数据。 Azure Functions 主机将触发器数据序列化为 gRPC 消息，而处理程序将其反序列化为类型化的 Go 结构体。这些触发器具有：

具备编译时安全性的类型化处理程序签名
不需要外部Azure SDK依赖项：只需要encoding/json
有限有效负载：更改源文档、消息和事件是离散的、大小有限的对象

支持的核心触发器：

Trigger	处理程序签名	注册方法
HTTP	`func(http.ResponseWriter, *http.Request)`	`app.HTTP()`
Timer	`TimerHandler`	`app.Timer()`
Azure Cosmos DB	`func(context.Context, []bindings.CosmosDocument) error`	`app.CosmosDB()`
Azure 服务总线（队列）	`ServiceBusHandler`	`app.ServiceBusQueue()`
Azure 服务总线（主题）	`ServiceBusHandler`	`app.ServiceBusTopic()`
事件中心	`EventHubHandler`	`app.EventHub()`
事件网格	`EventGridHandler`	`app.EventGrid()`

扩展触发器

扩展触发器提供经过身份验证的Azure SDK客户端而不是原始数据。主机仅发送元数据（例如容器名称和 Blob 路径），而工作器则构建一个作用域限定于特定资源的客户端。这些触发器具有：

SDK 客户端注入：处理程序接收随时可用的客户端
隔离的依赖项：Azure SDK 包位于 triggers/<name>/
流式处理支持：支持在不通过 gRPC 缓冲的情况下读取大型有效负载

若要使用扩展触发器，请为该扩展包添加一个空白导入：

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"

Trigger	处理程序接收	注册方法
Blob 存储	`*blob.Client`	`app.Blob()`

Blob 触发器示例

package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob"
    "github.com/azure/azure-functions-golang-worker/sdk"
    _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()
    app.Blob("processBlobTrigger", processBlob,
        sdk.WithPath("samples-workitems/{name}"),
        sdk.WithConnection("AzureWebJobsStorage"),
    )
    worker.Start(app)
}

func processBlob(ctx context.Context, client *blob.Client) error {
    get, err := client.DownloadStream(ctx, nil)
    if err != nil {
        return fmt.Errorf("download error: %w", err)
    }
    data, _ := io.ReadAll(get.Body)
    get.Body.Close()
    log.Printf("Blob size: %d bytes", len(data))
    return nil
}

HTTP 触发器

HTTP 触发器处理程序使用标准的 Go net/http 类型，因此 Go 开发者会立刻感到熟悉：

func myHandler(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    w.Header().Set("Content-Type", "application/json")
    fmt.Fprintf(w, `{"message": "Hello, %s!"}`, name)
}

注册带有方法和授权级别的 HTTP 函数：

app.HTTP("myApi", myHandler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

HTTP 流式传输

Go 工作器支持 HTTP 流式传输，适用于服务器发送事件或发送大量响应数据等场景：

func streamHandler(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming not supported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream")
    for i := 0; i < 10; i++ {
        fmt.Fprintf(w, "data: message %d\n\n", i)
        flusher.Flush()
    }
}

定时触发器

计时器触发器按 cron 表达式定义的计划运行：

app.Timer("myScheduledFunc", timerHandler,
    sdk.WithSchedule("0 */5 * * * *"),
)

func timerHandler(ctx context.Context, timer bindings.TimerInfo) error {
    log.Printf("Timer trigger executed at: %s", timer.ScheduleStatus.Next)
    return nil
}

依赖管理

Go 代码项目使用标准 Go 模块进行依赖项管理。

初始化新模块：
```
go mod init myapp
```
添加 Azure Functions Go 工作器 SDK：
```
go get github.com/azure/azure-functions-golang-worker
```
对于 Blob 触发器的支持，依赖项会通过 triggers/blob 的空白导入自动包含。
整理依赖项：
```
go mod tidy
```

在本地运行

使用 Azure Functions Core Tools 在本地运行项目：

func start

Core Tools 会自动：

从 FUNCTIONS_WORKER_RUNTIME = "native" 中检测 local.settings.json。
当存在 go.mod 文件时，将原生工作器运行时解析为 Go。
运行 go build -o bin/app . 以根据您的本地操作系统编译项目。
启动Azure Functions主机，该主机通过 gRPC 与编译的二进制文件通信。
显示函数终结点（例如 http://localhost:7071/api/hello）。

使用 local.settings.json 配置用于本地开发的环境变量：

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "",
        "FUNCTIONS_WORKER_RUNTIME": "native"
    }
}

AzureWebJobsStorage生成的值对于 Go 项目为空。在本地开发期间使用需要主机存储的触发器时，请将其设置为存储帐户连接字符串或 UseDevelopmentStorage=true。

部署

编译和打包

Azure Functions Core Tools 版本 4.12 或更高版本可处理常见本地和 Azure 部署流程中的 Go 构建：

func start 会先将你的项目构建为适用于你的本地操作系统的 bin/app，然后再启动本地 Functions 主机。
func azure functionapp publish生成、打包项目并将其部署到Azure中的现有函数应用。
func pack 将你的项目构建为适用于 Linux x64 的 bin/app，并创建可部署的 .zip 包。

打包Azure时，生成的 .zip 文件包含 Linux Functions 主机所需的文件。编译的二进制文件作为 bin/app 存储在本地项目中，但 Core Tools 将其放在部署包的根目录中作为应用。

如果使用 func pack --no-build，则必须在打包之前生成 Linux x64 二进制文件：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/app .

使用 Core Tools 进行部署

使用 func azure functionapp publish 将 Go 项目部署到 Azure 中的现有函数应用：

func azure functionapp publish <APP_NAME>

将 <APP_NAME> 替换为你的函数应用的名称。

部署 zip 包

当需要单独创建部署包与发布时使用 func pack ：

创建可部署的 ZIP 构件：
```
func pack
```

使用Azure CLI部署包：

az functionapp deployment source config-zip --resource-group <RESOURCE_GROUP> --name <APP_NAME> --src <ZIP_FILE_PATH>

func pack 生成的包已准备好在 Azure 中运行，因此在部署它时不要请求远程构建。

Docker 支持

可以在容器中运行 Go 代码项目。初始化一个支持 Docker 的项目：

func init --worker-runtime go --docker

该命令会生成一个 Dockerfile 以及标准项目文件。

遥测和可观测性

Azure Functions Go 工作器支持结构化日志记录和基于 OpenTelemetry 的可观测性。使用标准 log/slog 包中的上下文感知方法（例如 slog.InfoContext）将日志与当前函数调用相关联。若要启用 OpenTelemetry，请在应用中配置 Functions 主机并注册 Go 辅助角色 OpenTelemetry 中间件。有关设置说明，请参阅将 OpenTelemetry 与 Azure Functions。

已知限制（预览版）

在公共预览版期间，存在以下限制：

不支持 func new。通过直接编辑 main.go 来添加函数。
在公开预览期间，Durable Functions 暂不支持 Go。
Go 函数应用仅在 Azure 中在 Linux 上运行。
预览期间仅支持触发器中列出的触发器。
Core Tools 中的 Go 打包目前面向 Linux x64 应用。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-06-03