管理 Go 模块

本页面介绍如何管理存储在 Artifact Registry 中的打包 Go 模块。

准备工作

  1. 如果目标代码库不存在，请创建新代码库。选择 Go 作为代码库格式。
  2. 验证您是否拥有访问代码库所需的权限。
  3. （可选）为 gcloud 命令配置默认值。
  4. 安装 Go 1.15 或更高版本。

  5. 安装 package-go-module gcloud CLI 插件：

    gcloud components install package-go-module

  6. 配置 Go 以进行 Artifact Registry 身份验证。

必需的角色

如需获取管理模块所需的权限，请让管理员授予您代码库的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

上传模块

代码库模式：标准

如需将模块打包并上传到您的代码库，请运行以下命令：

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

请替换以下内容：

  • 将 PROJECT 替换为 Google Cloud 项目 ID。
  • 将 REPOSITORY 替换为存储软件包的代码库的名称。
  • 将 LOCATION 替换为代码库的单区域或多区域位置。
  • 将 MODULE_PATH 替换为模块路径。例如：example.com/foo 如需了解详情，请参阅 Go 模块参考文档。
  • 将 VERSION 替换为模块的语义版本，格式为 vX.Y.Z，其中 X 是主要版本，Y 是次要版本，Z 是补丁版本。
  • 将 SOURCE_LOCATION 替换为 Go 模块的根目录。如果您省略 --source 标志，则默认为当前目录。

模块会上传到 Artifact Registry。

如需详细了解如何创建 Go 模块，请参阅此教程。

上传新的模块版本

代码库模式：标准

如需在配置默认值时将新版本的模块上传到默认项目、代码库和位置，请使用新版本号运行以下命令：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

将 VERSION 替换为已更新模块的版本。例如，如需上传路径为 example.com/foo 的模块的 0.1.1 版本，请运行以下命令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

如需将模块标记为预发布版本，请在 VERSION 后面添加短划线，并附加模块的预发布标识符：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

将 PRE_RELEASE_IDENTIFIERS 替换为以英文句点分隔的 ASCII 字母数字字符和连字符。例如，如需使用路径为 example.com/foo 模块（由 alpha.x.12m.5 标识）上传模块的预发布版本，请运行以下命令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

上传新的主要版本

代码库模式：标准

主要版本不向后兼容以前的版本。为防止用户导入破坏性更改，v1 之后的主要版本的模块路径必须与先前版本的模块路径不同。以 v2 开头，主要版本会添加到模块路径的末尾。

例如，example.com/foo 的 v2.0.0 的模块路径为 example.com/foo/v2。

建议的最佳做法是，在以主要版本后缀命名的单独目录中开发 v1 之后的主要版本。

如需在配置默认值的情况下上传模块的新主要版本 2.0.0（使用 example.com/foo 路径指向默认项目、代码库和位置），请执行以下操作：

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

列出模块

代码库模式：标准

配置默认值后，运行以下命令，检查默认项目、代码库和位置中上传的 Go 模块：

  gcloud artifacts packages list

输出将类似于以下内容：

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

查看模块版本详情

代码库模式：标准

运行以下命令，查看配置默认值后默认项目、代码库和位置的模块版本：

  gcloud artifacts versions list --package=MODULE_PATH

输出将类似于以下内容：

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

将模块用作依赖项

代码库模式：标准

如需导入存储在 Artifact Registry 中的模块，您需要指示 Go 从 Artifact Registry 中查找依赖项，并绕过校验和数据库。按照为 Go 设置身份验证中的说明设置身份验证和 Go 环境。

  1. 如果您使用短期有效凭据向 Artifact Registry 进行身份验证，则需要运行以下命令来刷新 OAuth 令牌：

      GOPROXY=proxy.golang.org \
  go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@latest refresh

  2. 如果您的模块还没有 go.mod 文件，请将目录更改为您的模块文件夹，然后运行 go mod init 为您的软件包创建 go.mod 文件。

      go mod init MODULE_PATH

    将 MODULE_PATH 替换为存储在 Artifact Registry 中的模块的模块路径。如需了解详情，请参阅 Go 模块参考文档。

  3. 如需要求使用存储在 Artifact Registry 中的模块版本，请修改 go.mod 文件以如下所示：

    
module example.com/bar

go 1.19

require example.com/foo v0.1.0

    请替换以下内容：

    • example.com/foo 是所需模块的模块路径
    • v0.1.0 是存储在 Artifact Registry 中的版本

  4. 在 main.go 文件的 import 部分照常添加模块路径。

    例如，如需导入路径为 example.com/foo 存储在 Artifact Registry 中的模块，导入部分可能如下所示：

      
  package main

  import (
    foo "example.com/foo"
  )

  func main() {

    ...

  }

  5. 运行 go mod tidy 以下载依赖项：

      go mod tidy

  6. 照常运行模块：

      go run .

    系统会下载存储在 Artifact Registry 中的模块并将其用作依赖项。

删除已打包的 Go 模块

代码库模式：标准

您可以删除软件包及其所有版本，也可以删除特定版本。

  • 软件包一经删除便无法撤消。

在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。

如需删除软件包，请按如下所述操作：

控制台

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

  2. 在代码库列表中，点击相应代码库。

    软件包页面列出代码库中的软件包。

  3. 选择要删除的软件包。

  4. 点击删除。

  5. 在确认对话框中，点击删除。

gcloud

运行以下命令：

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

地点

  • PACKAGE 是代码库中的软件包名称。
  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
  • --async 会立即返回结果，而无需等待正在进行的操作完成。

如需删除软件包的版本，请按如下所述操作：

控制台

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

  2. 在代码库列表中，点击相应代码库。

    软件包页面列出代码库中的软件包。

  3. 点击一个软件包以查看它的版本。

  4. 选择您要删除的版本。

  5. 点击删除。

  6. 在确认对话框中，点击删除。

gcloud

运行以下命令：

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

地点

  • PACKAGE 是代码库中的软件包名称。
  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
  • --async 会立即返回结果，而无需等待正在进行的操作完成。

后续步骤