Go 1.18 new features multi-module workspace tutorial - making multi-module development easy

Guided reading

• With the official release of go 1.18 on March 15, 2022, in addition to the performance improvement, the new version also introduces many new functions, including the long-awaited functional generics (Generics) of go, and also introduced Multi-module workspaces (Workspaces) and fuzzing (Fuzzing).
• There have been many tutorials about generics on the Internet. Here I introduce a practical function, how to use the multi-module workspace and tutorials.

• Go multi-module workspace makes it easier for developers to work on multiple modules at the same time, such as:

  It is convenient to debug dependent code (breakpoints, modify code), and troubleshoot dependent code bugs
  It is convenient for parallel development and debugging of multiple warehouses/modules at the same time

content

• Multi-module workspace
• Development Process Demonstration
• References

Multi-module workspace

illustrate

• Go uses a multi-module workspace, which makes it easier for developers to handle the development of multiple modules at the same time. Before Go 1.17, this could only be done using the go.mod replace directive, which can be a pain if you happen to be working on multiple modules at the same time. Every time you want to commit code, you have to delete 0623870cd682f6 in replace to make the module stable release version.
• Using the go 1.18 multi-module workspace feature makes this work simple and easy to handle. Below I will introduce how to use this function.
• Go multi-module workspace documentation, code sample access address https://github.com/link1st/link1st/tree/master/workspaces

Conditions of Use

• First we need go 1.18 or later go install

# 查看 go 版本
> go version
go version go1.18 darwin/amd64

go work Support command

• In general, it is recommended not to commit go.work file to git, as it is mainly used for local code development.
• It is recommended to execute under the path of: $GOPATH to generate go.work file

• go work init Initialize workspace file for generating go.work workspace file

  Initialize and write a new go.work to the current path, you can specify the code modules to be added
  Example: go work init ./hello adds the local repository hello to the workspace
  hello repository must be a repository managed by go mod dependencies ( ./hello/go.mod file must exist)

• go work use Add new module to workspace

  Command example:
  go work use ./example Add a module to the workspace
  go work use ./example ./example1 Add multiple modules to the workspace
  go work use -r ./example recursively ./example directory to the current workspace
  The delete command uses the go work edit -dropuse=./example function

• go work edit for editing go.work file

  You can use the edit command to edit and manually edit go.work file and the effect is the same
  Example:
  go work edit -fmt go.work reformat go.work file
  go work edit -replace=github.com/link1st/example=./example go.work Replacement Code Module
  go work edit -dropreplace=github.com/link1st/example Remove Replacement Code Module
  go work edit -use=./example go.work Add new module to workspace
  go work edit -dropuse=./example go.work remove module from workspace

• go work sync the workspace's build list to the workspace's module

• go env GOWORK

  View environment variables, view the current workspace file path
  You can check whether the workspace file is set correctly, go.work path cannot be found, you can use GOWORK to specify

> go env GOWORK
$GOPATH/src/link1st/link1st/workspaces/go.work

go.work file structure

• The file structure is similar to the go.mod file structure. It supports the Go version number, the specified workspace and the warehouse to be replaced.
• Example of file structure:

go 1.18

use (
    ./hello
    ./example
)

replace (
    github.com/link1st/example => ./example1
)

use specifies the module directory to use

• You can use go work use hello to add modules, or you can manually modify go.work workspace to add new modules
• The module path is added to the workspace, and the local code in use will be automatically used for code compilation when compiling, which is similar to replaces .

# 单模块结构
use ./hello

# 多模块结构
use (
    ./hello
    ./example
)

replaces replaces the dependency warehouse address

• replaces command is the same as the go.mod command, which is used to replace the repository address that the project depends on
• It should be noted that replaces and use cannot specify the same local path at the same time

Also specify the error message:
go: workspace module github.com/link1st/example is replaced at all versions in the go.work file. To fix, remove the replacement from the go.work file or specify the version at which to replace the module.

• Error example

Also specify the same local path in use and replace

go 1.18

use (
    ./hello
    ./example
)

replace (
    github.com/link1st/example => ./example
)

go.work file has higher priority than defined in go.mod

• When using the functions of and replace at the same time, specify different code warehouse paths

Replace the definition in go.mod with the local warehouse example

replace (
    github.com/link1st/example => ./example1
)

The definition in go.work is replaced with the local warehouse example1

replace (
    github.com/link1st/example => ./example1
)

• When the code is built, the code of the example1 warehouse specified by go.work is used, and the priority of go.work higher.

how to use

• In Go 1.18 go run and go build both use the workspace feature by default
• GOWORK can also specify the configuration go.work file location

export GOWORK="~/go/src/test/go.18/workspace/go.work"

How to disable the workspace

• Go global variable GOWORK set off to disable the workspace function

  export GOWORK=off

Development Process Demonstration

• Demonstrates how to use the multi-module workspace feature. In the current era of microservices, one person will maintain multiple code repositories, and in many cases multiple repositories are developed at the same time
• Suppose we are now developing the hello warehouse. The function implemented is to reverse and output the input string. The string reversal function depends on github.com/link1st/example (hereinafter collectively referred to as example ) warehouse implementation
• Create a new hello project

mkdir hello
cd hello
# 代码仓库启动 go mod 依赖管理，生成 go.mod 文件
go mod init github.com/link1st/link1st/workspaces/hello
# 下载依赖包
go get github.com/link1st/example
# 编写 main 文件
vim main.go

• main.go code

// Package main main 文件，go 多模块工作区演示代码
// 实现将输入的字符串反转输出并输出
package main

import (
    "flag"
    "fmt"

    "github.com/link1st/example/stringutil"
)

var (
    str = ""
)

func init() {
    flag.StringVar(&str, "str", str, "输入字符")
    flag.Parse()
}

func main() {
    if str == "" {
        fmt.Println("示例: go run main.go -str hello")
        fmt.Println("str 参数必填")
        flag.Usage()
        return
    }

    // 调用公共仓库，进行字符串反转
    str = stringutil.Reversal(str)
    // 输出反转后的字符串
    fmt.Println(str)
    return
}

• Run the code go run main.go -str "hello world" or go run github.com/link1st/link1st/workspaces/hello -str "hello world" and you can see that the reversed string of hello world is output

> go run main.go -str "hello world"
dlrow olleh

• At this point, the initial function has been completed, but the subsequent requirements change, not only need to output the reversed string, but also need to capitalize the string
• We need to go to the example repository to add the function of developing to uppercase the string

# 回到工作根目录，将 common 代码下载到本地进行添加新的功能
# 下载依赖的 example 包
git clone [e-mail]:link1st/example.git
# 在 example 包中添加 字符串大学的功能

• vim example/stringutil/to_upper.go code is as follows

// Package stringutil stringutil
package stringutil

import (
    "unicode"
)

// ToUpper 将字符串进行大写
func ToUpper(s string) string {
    r := []rune(s)
    for i := range r {
        r[i] = unicode.ToUpper(r[i])
    }
    return string(r)
}

• Since the code is still being debugged locally and has not been submitted to the git repository, the function of the Go multi-module workspace needs to be used at this time.
• Enter the project root directory and initialize the module we are developing now

# 初始化 go.work 文件
go work init  ./hello ./example
# 查看 go.work 文件内容
cat go.work

• The file structure is as follows

go 1.18

use (
    ./example
    ./hello
)

• Back to hello project, vim main.go adds the uppercase function of strings.

func main() {
    ...

    // 调用公共仓库，进行字符串反转
    str = stringutil.Reversal(str)
    // 增加字符大写的功能
    str = stringutil.ToUpper(str)
    // 输出反转后的字符串
    fmt.Println(str)
    
    ...
}

• run the code

  It can be seen that the reversed and uppercase string of is output. The uppercase function is only local and not submitted to git, so we can realize parallel development on two modules at the same time.

go run main.go -str "hello world"
DLROW OLLEH

• At this point, the demo code has been completed

Summarize

• Using the Go multi-module workspace feature allows us to easily switch work between multiple modules and is more adaptable to modern microservice architecture development.

references

Go 1.18 New Features Multi-module Workspace Tutorial

Go 1.18 is released!

Tutorial: Getting started with multi-module workspaces

go-1.18-features