The basics of Go modules are refined, and the six core concepts are fully analyzed (on)

Click on "Cloud Recommendation Big Coffee", get the official recommended boutique content, and learn technology without getting lost!

How is the path defined when developing in Go? What changes did Go Mudules bring to this end? This article will comprehensively introduce the six core concepts of Go modules, including design concepts and compatibility principles. Mastering these technical points is of great value for the management and maintenance of Go modules.

In the previous article, the author introduced how to create a Go module module using the classic hello world as an example. What needs to be explained is that a module can contain multiple packages, and they can be published, packaged, and packaged together. Versioned. At the same time, Go Modules can also be downloaded through the version management system (github, gitlab) or goproxy proxy. Before using Go Modules, it is recommended that you clarify the six core concepts that are closely related to facilitate your deeper understanding in the later development and use process.

When we use the Go language for development, we often encounter paths like "example.com/test" or "example.com/test/pkg/log". How are these paths defined and what is the relationship between the two? What role does it play in Go Modules? What new concepts does the introduction of Go Modules introduce to existing packages, and how do they work together? What are the new requirements for compatibility? Let's look together.

One: Module Path

Go uses "module path" to distinguish different module modules, which are defined in the go.mod file, which also contains other dependencies required for the compilation of this module. If a directory contains the go.mod file, then this directory is the root directory of the Go module.

In addition, we will also introduce the concept of packages, which existed before the advent of Go Modules. The "package" in a Go module is a collection of some source code files in the same directory, these files will be compiled together. The "package path" is the combination of the module path and the subdirectory (relative path to the module root directory). For example, there is a package in the html directory under the module "golang.org/x/net", and the path of this package is "golang.org/x/net/html".

The summary is: A code repository can contain multiple Go modules, and a Go module can contain multiple Go packages.

The module path is the canonical name of a Go module, used to distinguish between different modules. At the same time, it is also the path prefix of the Go package under this module. In theory, the module path should contain at least two key information:

The role of the module
Where to get the module

Two: Version number and compatibility principle

The version number is equivalent to a read-only snapshot of a module. It can be an official release version or a pre-release version. Each version starts with the letter v, followed by a semantic version, such as v1.0.0.

In summary, the semantic version consists of three non-negative integers separated by dots (major version, minor version, and patch version, from left to right). The patch version can be followed by an optional pre-release string beginning with a hyphen. The pre-release string or patch version can be followed by a build metadata string beginning with a plus sign. For example, v0.0.0, v1.12.134, v8.0.5-pre, v2.0.9+meta, etc. are all valid versions.

The information in the version number represents whether this version is a stable version and whether it maintains compatibility with the previous version.

When some incompatible changes occur to the maintained module, such as modifying the externally callable interface or function, the major version number needs to be incremented, and the minor version number and patch version number are set to zero. For example, a package is removed from the module.

When adding some new functions or interfaces to the module does not affect the compatibility of the module, you need to increment the minor version number and set the patch version number to zero.

When some bugs are fixed or some optimizations are made, you only need to increment the patch version number, because these changes will not change the already public interfaces.

The pre-release suffix indicates that the version number is a pre-release version. The pre-release version number will be sorted before the official version number. For example, v1.2.3-pre will be arranged before v1.2.3.

Metadata suffixes will be ignored in version comparison, code bases in version control will ignore tags with build metadata, but build metadata will be retained in the version specified in the go.mod file. If a module has not been migrated to Go Modules and the major version number is 2 or higher, the +incompatible suffix will be added to the version number.

If the major version number of a version is 0 or it has a pre-release version suffix, then this version is considered an unstable version. Generally, unstable versions are not subject to compatibility restrictions. For example, v0.2.0 may be incompatible with v0.1.0, and v1.5.0-beta may also be incompatible with v1.5.0.

Go can obtain modules through tags, branches, and commit hashes, even if these naming does not follow these rules. In the main module, the go command will automatically convert these revisions into standard version numbers, which are called pseudo-versions. For example, when the following command is executed:

go get -d golang.org/x/net@daa7c041

Go will convert the specified hash daa7c041 into a pseudo version number v0.0.0-20191109021931-daa7c04131f5. The canonical version is required outside the main module. If a non-canonical version like master appears in the go.mod file, the go command will report an error.

Three: Pseudo version number

The pseudo version number is a pre-release version number format, which contains the specified commit hash value. In addition, for code bases that are not tagged, a pseudo version number can also be used to indicate a certain version, which can be easily tested before a certain version is officially released. For example, each pseudo version number has three parts:

The base version prefix (vX.0.0 or vX.YZ-0), which is either derived from the semantic version tag before the revision, or from vX.0.0 (if there is no such tag).
Timestamp (yyyymmddhhmmss), which is the UTC time when the commit was created. In Git, this is the commit time.
The commit identifier (abcdefabcdef), which is the 12-character prefix of the commit hash, or in Subversion, is a revision number padded with zeros.

Under these three parts, it is divided into the following situations:

If there is no base version before, then pseudo version numbers such as vX.0.0-yyyymmddhhmmss-abcdefabcdef will be enabled. The major version number X needs to match the suffix of the major version number of the module.

If the previous base version number is a pre-release version like vX.YZ-pre, then vX.Y.Zpre.0.yyyymmddhhmmss-abcdefabcdef will be adopted.

If the previous base version number is an official version like vX.YZ, then vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef will be adopted. For example, if the base version number is v1.2.3, The pseudo version number may be v1.2.4-0.20191109021931-daa7c04131f5.

Based on different basic version numbers, it is possible for multiple pseudo version numbers to point to the same commit hash. This happens when a pseudo version number that is lower than the existing one is tagged.

The pseudo version number introduced above carries two very useful information:

1. The pseudo version number will be higher than these existing base version numbers, but will be lower than other pseudo version numbers generated later.
2. Pseudo-versions with the same base version prefix are sorted in chronological order.

The pseudo version number does not need to be manually specified. Many Go commands can accept a commit hash or branch name, and then automatically convert it into a pseudo version number (or a label if it exists). For example:

go get -d example.com/mod@master
go list -m -json example.com/mod@abcd1234

In this article, we introduced the three concepts of module path, version number and compatibility principle, and pseudo version number. In the next article, we will continue to introduce the core concepts of Go Modules, including the main version number suffix, parsing package path to module Please stay tuned for the path process and go.mod file. In addition, Tencent cloud goproxy Enterprise has been commercialized, need to understand the students can click here .

wonderful articles: 161b0c17a3aadf The Go language restarts, the past, present and basic use of Go Modules

"Yunjian Big Coffee" is a special column for Tencent's cloud plus community. Cloud recommendation officials specially invite industry leaders to focus on the implementation of cutting-edge technologies and theoretical practice, and continue to interpret hot technologies in the cloud era and explore new opportunities for industry development. Click one-click to subscribe to , and we will regularly push premium content for you.