Go workspaces使用指北

在 Go 1.18 之前如果你需要开发中使用多个模块，你需要在每个模块的 go.mod 文件中手动管理依赖关系。Go 1.18 引入了工作区模式，允许你在同一个工作区中同时处理多个模块，而无需频繁修改每个模块的 go.mod 文件。这对于需要同时处理多个相关模块的开发者来说，是一个巨大的便利。

工作区概述

工作区模式通过一个 go.work 文件来管理多个模块的依赖关系。这个文件位于工作区的根目录下，包含了 use 和 replace 指令，用于指定要使用的模块和替换特定模块的版本。

主要特点

• 统一管理依赖：通过 go.work 文件统一管理多个模块的依赖，无需修改每个模块的 go.mod 文件。
• 灵活的工作流程：支持多种工作流程，如在上游模块中添加功能并在自己的模块中使用，或者在同一仓库中处理多个相互依赖的模块。
• 简化依赖切换：可以通过注释掉 go.work 文件中的 use 指令来快速切换不同的依赖配置。

创建工作区

初始化工作区

在工作区的根目录下运行以下命令来初始化工作区：

go work init [模块目录1] [模块目录2]

如果不指定模块目录，会创建一个空的工作区。

添加模块到工作区

可以使用以下命令将模块添加到工作区：

go work use [模块目录]

或者手动编辑 go.work 文件添加 use 指令。

递归添加模块

如果工作区目录下有多个模块，可以使用以下命令递归添加所有包含 go.mod 文件的目录：

go work use -r .

go.work 文件结构‍

go.work 文件的结构类似于 go.mod 文件，包含以下几个指令：

• go: 指定 Go 工具链的版本，例如 go 1.18。
• use: 指定要使用的模块，参数是模块目录的相对路径。
• replace: 替换特定模块的版本，类似于 go.mod 文件中的 replace 指令。

示例：

go 1.18

use (
    ./path-to-upstream-mod-dir
    ./path-to-your-module
)

replace (
    example.com/module v1.0.0 => ./local-module
)

常见工作流程

在上游模块中添加功能并使用在自己的模块中

• 创建工作区目录。
• 克隆上游模块并添加功能。
• 初始化工作区：

go work init [上游模块路径]

• 添加自己的模块到工作区：

go work use [自己的模块路径]

• 编译、运行和测试自己的模块，使用上游模块的新功能。
• 发布上游模块和自己的模块。

处理同一仓库中的多个相互依赖的模块

• 创建工作区目录。
• 克隆包含多个模块的仓库。
• 初始化工作区并添加所有相关模块：

go work init [模块1路径] [模块2路径]

• 在 go.work 文件中指定所有相关模块：

go 1.18

use (
    ./tools
    ./tools/groundhog
)

• 在工作区中进行开发，本地更改会自动反映到所有相关模块中。

切换不同的依赖配置

你可以创建多个工作区目录，每个目录对应不同的 go.work 文件，或者在同一个 go.work 文件中通过注释掉不需要的 use 指令来切换依赖配置。

仍然使用 GOPATH？

如果你还在使用 GOPATH，工作区模式也可以帮助你。你可以在 GOPATH 的根目录下创建一个工作区：

• 在 GOPATH 根目录下初始化工作区：

go work init

• 使用 go work use 命令添加本地模块或特定版本的依赖。
• 使用 go work replace 命令替换现有依赖。

工作区命令

Go 1.18 引入了以下命令来管理工作区：

• go work init: 初始化工作区。
• go work use: 添加模块到工作区。
• go work sync: 将 go.work 文件中的依赖信息同步到每个模块的 go.mod 文件中。
• go work edit: 通过命令行编辑 go.work 文件（主要用于工具和脚本）。

启用工作区模式

工作区模式通过 GOWORK 环境变量启用。如果 GOWORK 指向一个以 .work 结尾的文件，go 命令就会进入工作区模式。

你可以通过以下命令查看当前使用的 go.work 文件：

go env GOWORK

常用命令

在工作区模式下，以下命令会根据 go.work 文件中的配置自动处理依赖关系：

• go list
• go build
• go test
• go run
• go vet

以 xcc 项目为例展示如何使用 workspaces

• 在xcc根目录执行go work init
• 编辑 go.work 文件。

go 1.20

use (
  ./srv/uas
  ./core
  ./stack
  ./srv/sys
  ./srv/acd
  ./srv/byd
  ./srv/xcc
  ./srv/xuc
  ./srv/uc
  ./srv/ebl
  ./srv/finance
  ./srv/cdr
  ./srv/xdialer
  ./srv/logger
  ./srv/record
  ./srv/bydr
  ./srv/update
  ./srv/sharding
  ./cli/syncer
  ./stack/cmd/protoc-gen-stack
)

replace (
  github.com/coreos/bbolt => go.etcd.io/bbolt v1.3.4
)

这样xcc的工作区就创建好了。那么工作区有什么好处呢？首先go的 语言服务器（language server) gopls 和 vscode 的go extension， 会识别工作区，并自动识别依赖关系，从而提供更好的代码提示、跳转等功能。

比如 uas 服务需要引用本地的 core 模块，之前需要写 replace xswitch.cn/core => ../../core。在使用了 workspaces 之后，可以直接在项目中使用 xswitch.cn/core。工作区会根据 go.work 文件自动处理依赖关系，所以不需要再手动修改 go.mod 文件。