# 代码包和包引入

和很多现代编程语言一样，Go代码包（package）来组织管理代码。 我们必须先引入一个代码包（除了`builtin`标准库包）才能使用其中导出的代码要素（比如函数、类型、变量和具名常量等）。 此篇文章将讲解Go代码包和代码包引入（import）。

### 包引入

下面这个简短的程序（假设它存在一个名为`simple-import-demo.go`的源文件中）引入了一个标准库包。

    package main

    import "fmt"

    func main() {
    	fmt.Println("Go has", 25, "keywords.")
    }

对此程序的一些解释：

- 第一行指定了源文件`simple-import-demo.go`所处的包名为`main`。 程序入口`main`函数必须处于一个名为`main`的代码包中。
- 第三行通过使用`import`关键字引入了`fmt`标准库包。 在此源文件中，`fmt`标准库包将用`fmt`标识符来表示。 标识符`fmt`称为`fmt`标准库包的引入名称。（后续某节将详述代码包的引入名称）。
- `fmt`标准库包中声明了很多终端打印函数供其它代码包使用。 `Println`函数是其中之一。 它可以将不定数量参数的字符串表示形式输出到标准输出中。 第六行调用了此`Println`函数。 注意在此调用中，函数名之前需要带上前缀`fmt.`，其中`fmt`是`Println`函数所处的代码包的引入名称。 `aImportName.AnExportedIdentifier`这种形式称为一个限定标识符（qualified identifier）。
- `fmt.Println`函数调用接受任意数量的实参并且对实参的类型没有任何限制。 所以此程序中的此函数调用的三个实参的类型将被推断为它们各自的默认类型：`string`、`int`和`string`。
- 对于一个`fmt.Println`函数调用，任何两个相邻的实参的输出之间将被插入一个空格字符，并且在最后将输出一个空行字符。

下面是上面这个程序的运行结果：

    $ go run simple-import-demo.go
    Go has 25 keywords.

当一个代码包被引入一个Go源文件时，只有此代码包中的导出代码要素（名称为大写字母的变量、常量、函数、定义类型和类型别名等）可以在此源文件被使用。 比如上例中的`Println`函数即为一个导出代码要素，所以它可以在上面的程序源文件中使用。

前面几篇文章中使用的内置函数`print`和`println`提供了和`fmt`标准库包中的对应函数相似的功能。 内置函数可以不用引入任何代码包而直接使用。

注意：`print`和`println`这两个内置函数不推荐使用在生产环境，因为它们不保证一定会出现在以后的Go版本中。

我们可以访问Go官网（墙内版）来查看各个标准库包的文档， 我们也可以开启一个本地文档服务器来查看这些文档。

一个包引入也可称为一个包声明。一个包声明只在当前包含此声明的源文件内可见。

另外一个例子：

    package main

    import "fmt"
    import "math/rand"

    func main() {
    	fmt.Printf("下一个伪随机数是%v。\n", rand.Uint32())
    }

这个例子多引入了一个`math/rand`标准库包。 此包是`math`标准库包中的一个子包。 此包提供了一些函数来产生伪随机数序列。

一些解释：

- 在此例中，`math/rand`标准库包的引入名是`rand`。 `rand.Uint32()`函数调用将返回一个`uint32`类型的随机数。
- `Printf`函数是`fmt`标准库包中提供的另外一个常用终端打印函数。 一个`Printf`函数调用必须带有至少一个实参，并且第一个实参的类型必须为`string`。 此第一个实参指定了此调用的打印格式。此格式中的`%v`在打印结果将被对应的后续实参的字符串表示形式所取代。 比如上列中的`%v`在打印结果中将被`rand.Uint32()`函数调用所返回的随机数所取代。 打印格式中的`\n`表示一个换行符，这在基本类型和它们的字面量表示一文中已经解释过。

上面这个程序的输出如下：

    下一个伪随机数是2596996162。

注意：在Go 1.20之前，如果我们希望上面的程序每次运行的时候输出一个不同的随机数，我们需要在程序启动的时候调用`rand.Seed`函数来设置一个不同的随机数种子。

多个包引入语句可以用一对小括号来合并成一个包引入语句。比如下面这例。

    package main

    // 一条包引入语句引入了三个代码包。
    import (
    	"fmt"
    	"math/rand"
    	"time"
    )

    func main() {
    	// 设置随机数种子（仅在Go 1.20之前需要）。
    	rand.Seed(time.Now().UnixNano())
    	fmt.Printf("下一个伪随机数是%v。\n", rand.Uint32())
    }

一些解释：

- 此例多引入了一个`time`标准库包。 此包提供了很多和时间相关的函数和类型。 其中`time.Time`和`time.Duration`是两个最常用的类型。
- 函数调用`time.Now()`将返回一个表示当前时间的类型为`time.Time`的值。
- `UnixNano`是类型`time.Time`的一个方法。 我们可以把方法看作是特殊的函数。方法将在Go中的方法一文中详述。 方法调用`aTime.UnixNano()`将返回从UTC时间的1970年一月一日到`aTime`所表示的时间之间的纳秒数。 返回结果的类型为`int64`，这也是`rand.Seed`函数的参数类型（注意：`rand.Seed`函数从Go 1.20开始被声明为废弃了）。 在上例中，此方法调用的结果用来设置随机数种子。

### 更多关于`fmt.Printf`函数调用的输出格式

从上面的例子中，我们已经了解到`fmt.Printf`函数调用的第一个实参中的`%v`在输出中将替换为后续的实参的字符串表示形式。 实际上，这种百分号开头的占位字符组合还有很多。下面是一些常用的占位字符组合：

- `%v`：将被替换为对应实参字符串表示形式。
- `%T`：将替换为对应实参的类型的字符串表示形式。
- `%x`：将替换为对应实参的十六进制表示。实参的类型可以为字符串、整数、整数数组（array）或者整数切片（slice）等。 （数组和切片将在以后的文章中讲解。）
- `%s`：将被替换为对应实参的字符串表示形式。实参的类型必须为字符串或者字节切片（byte slice）类型。
- `%%`：将被替换为一个百分号。

一个例子：

    package main

    import "fmt"

    func main() {
    	a, b := 123, "Go"
    	fmt.Printf("a == %v == 0x%x, b == %s\n", a, a, b)
    	fmt.Printf("type of a: %T, type of b: %T\n", a, b)
    	fmt.Printf("1%% 50%% 99%%\n")
    }

输出：

    a == 123 == 0x7b, b == Go
    type of a: int, type of b: string
    1% 50% 99%

请阅读`fmt`标准库包的文档以了解更多的占位字符组合。 我们也可以运行`go doc fmt`命令来在终端中查看`fmt`标准库包的文档。 运行`go doc fmt.Printf`命令可以查看`fmt.Printf`函数的文档。

### 代码包目录、代码包引入路径和代码包依赖关系

一个代码包可以由若干Go源文件组成。一个代码包的源文件须都处于同一个目录下。 一个目录（不包含子目录）下的所有源文件必须都处于同一个代码包中，亦即这些源文件开头的`package pkgname`语句必须一致。 所以，一个代码包对应着一个目录（不包含子目录），反之亦然。 对应着一个代码包的目录称为此代码包的目录。 一个代码包目录下的每个子目录对应的都是另外一个独立的代码包。

对于Go官方工具链来说，一个引入路径中包含有`internal`目录名的代码包被视为一个特殊的代码包。 它只能被此`internal`目录的直接父目录（和此父目录的子目录）中的代码包所引入。 比如，代码包`.../a/b/c/internal/d/e/f`和`.../a/b/c/internal`只能被引入路径含有`.../a/b/c`前缀的代码包引入。

当一个代码包中的某个文件引入了另外一个代码包，则我们说前者代码包依赖于后者代码包。

Go不支持循环引用（依赖）。 如果一个代码包`a`依赖于代码包`b`，同时代码包`b`依赖于代码包`c`，则代码包`c`中的源文件不能引入代码包`a`和代码包`b`，代码包`b`中的源文件也不能引入代码包`a`。

当然，一个代码包中的源文件不能也没必要引入此代码包本身。

今后，我们称一个程序中含有`main`入口函数的名称为`main`的代码包为程序代码包（或者命令代码包），称其它代码包为库代码包。 程序代码包不能被其它代码包引入。一个程序只能有一个程序代码包。

代码包目录的名称并不要求一定要和其对应的代码包的名称相同。 但是，库代码包目录的名称最好设为和其对应的代码包的名称相同。 因为一个代码包的引入路径中包含的是此包的目录名，但是此包的默认引入名为此包的名称。 如果两者不一致，会使人感到困惑。

另一方面，最好给每个程序代码包目录指定一个有意义的名字，而不是它的包名`main`。

### `init`函数

在一个代码包中，甚至一个源文件中，可以声明若干名为`init`的函数。 这些`init`函数必须不带任何输入参数和返回结果。

注意：我们不能声明名为`init`的包级变量、常量或者类型。

在程序运行时刻，在进入`main`入口函数之前，每个`init`函数在此包加载的时候将被（串行）执行并且只执行一遍。

下面这个简单的程序中有两个`init`函数：

    package main

    import "fmt"

    func init() {
    	fmt.Println("hi,", bob)
    }

    func main() {
    	fmt.Println("bye")
    }

    func init() {
    	fmt.Println("hello,", smith)
    }

    func titledName(who string) string {
    	return "Mr. " + who
    }

    var bob, smith = titledName("Bob"), titledName("Smith")

此程序的运行结果：

    hi, Mr. Bob
    hello, Mr. Smith
    bye

### 程序代码要素初始化顺序

一个程序中所涉及到的所有的在运行时刻要用到的代码包的加载是串行执行的。 在一个程序启动时，每个包中总是在它所有依赖的包都加载完成之后才开始加载。 程序代码包总是最后一个被加载的代码包。每个被用到的包会被而且仅会被加载一次。

在加载一个代码包的过程中，所有的声明在此包中的`init`函数将被串行调用并且仅调用执行一次。 一个代码包中声明的`init`函数的调用肯定晚于此代码包所依赖的代码包中声明的`init`函数。 所有的`init`函数都将在调用`main`入口函数之前被调用执行。

在同一个源文件中声明的`init`函数将按从上到下的顺序被调用执行。 对于声明在同一个包中的两个不同源文件中的两个`init`函数，Go语言白皮书推荐（但不强求）按照它们所处于的源文件的名称的词典序列（对英文来说，即字母顺序）来调用。 所以最好不要让声明在同一个包中的两个不同源文件中的两个`init`函数存在依赖关系。

在加载一个代码包的时候，此代码包中声明的所有包级变量都将在此包中的任何一个`init`函数执行之前初始化完毕。

在同一个包内，包级变量将尽量按照它们在代码中的出现顺序被初始化，但是一个包级变量的初始化肯定晚于它所依赖的其它包级变量。 比如，在下面的代码片段中，四个包级变量的初始化顺序依次为`y`、`z`、`x`、`w`。

    func f() int {
    	return z + y
    }

    func g() int {
    	return y/2
    }

    var (
    	w       = x
    	x, y, z = f(), 123, g()
    )

关于更具体的包级变量的初始化顺序，请阅读表达式估值顺序规则一文。

### 完整的引入声明语句形式

事实上，一个引入声明语句的完整形式为：

    import importname "path/to/package"

其中引入名`importname`是可选的，它的默认值为被引入的包的包名（不是目录名）。

事实上，在本文上面的例子中的包引入声明中，`importname`部分都被省略掉了，因为它们都分别和引入的代码包的包名相同。 这些引入声明等价于下面这些：

    import fmt "fmt"        // <=> import "fmt"
    import rand "math/rand" // <=> import "math/rand"
    import time "time"      // <=> import "time"

如果一个包引入声明中的`importname`没有省略，则限定标识符使用的前缀必须为`importname`，而不是被引入的包的名称。

引入声明语句的完整形式在日常编程中使用的频率不是很高。 但是在某些情况下，完整形式必须被使用。 比如，如果一个源文件引入的两个代码包的包名一样，为了防止使编译器产生困惑，我们至少需要用完整形式为其中一个包指定一个不同的引入名以区分这两个包。

下面是一个使用了完整引入声明语句形式的例子。

    package main

    import (
    	format "fmt"
    	random "math/rand"
    	"time"
    )

    func main() {
    	random.Seed(time.Now().UnixNano())
    	format.Print("一个随机数:", random.Uint32(), "\n")

    	// 下面这行编译不通过，因为rand不可识别。
    	/*
    	fmt.Print("一个随机数:", rand.Uint32(), "\n")
    	*/
    }

一些解释：

- 我们必须使用`format`和`random`，而不是`fmt`和`rand`，来做为限定标识符的前缀。
- `Print`是`fmt`标准库包中的另外一个函数。 和`Println`函数调用一样，一个`Print`函数调用也接受任意数量实参。 它将逐个打印出每个实参的字符串表示形式。如果相邻的两个实参都不是字符串类型，则在它们中间会打印一个空格字符。

一个完整引入声明语句形式的引入名`importname`可以是一个句点(`.`)。 这样的引入称为句点引入。使用被句点引入的包中的导出代码要素时，限定标识符的前缀必须省略。

例子：

    package main

    import (
    	. "fmt"
    	. "time"
    )

    func main() {
    	Println("Current time:", Now())
    }

在上面这个例子中，`Println`和`Now`函数调用不需要带任何前缀。

一般来说，句点引入不推荐使用，因为它们会导致较低的代码可读性。

一个完整引入声明语句形式的引入名`importname`可以是一个空标识符(`_`)。 这样的引入称为匿名引入。一个包被匿名引入的目的主要是为了加载这个包，从而使得这个包中的代码要素得以初始化。 被匿名引入的包中的`init`函数将被执行并且仅执行一遍。

在下面这个例子中，`net/http/pprof`标准库包中的所有`init`函数将在`main`入口函数开始执行之前全部执行一遍。

    package main

    import _ "net/http/pprof"

    func main() {
    	... // 做一些事情
    }

### 每个非匿名引入必须至少被使用一次

除了匿名引入，其它引入必须在代码中被使用一次。 比如，下面的程序编译不通过。

    package main

    import (
    	"net/http" // error: 引入未被使用
    	. "time"   // error: 引入未被使用
    )

    import (
    	format "fmt"  // okay: 下面被使用了一次
    	_ "math/rand" // okay: 匿名引入
    )

    func main() {
    	format.Println() // 使用"fmt"包
    }

### 模块

一个模块（module）为的若干代码包的集合。当被下载至本地后，这些代码包处于同一个目录（此模块的根目录）下。 一个模块可以有很多版本（版本号遵从Semantic Versioning规范）。 更多关于模块的概念和使用，请阅读官方文档。