跳至主要内容

[Golang] Modules and Packages

參考資料

TL;DR​

  • Package：由一個以上的 .go 檔組成，放在同一個資料夾中
  • Module：由一個以上的 packages 組成，並且由一個版本
  • Repository：由一個以上的 modules 組成

基本操作​

不論是 module 或 package，都可以在本地匯入，不一定要發到遠端 repository。

# 在 hello 資料夾中
$ go mod init example.com/user/hello    # 宣告 module_path，通常會和該 repository 的 url 位置一致
$ go install .                          # 編譯該 module 並將執行檔放到 GOBIN，因此在 GOBIN 資料夾中會出現 hello 的執行檔
$ go get <package_name>@none      # 移除 go.mod 中特定 module，但不會移除對應的 binary

$ go mod tidy             # 移除沒用到的套件

💡 安裝到 GOBIN 資料夾的檔案名稱，會是在 go.mod 檔案中第一行定義 module path 中路徑的最後一個。因此若 module_path 是 example.com/user/hello 則在 GOBIN 中的檔名會是 hello；若 module_path 是 example/user 則在 GOBIN 資料夾中的檔名會是 user。

若我們在 go module 中有使用其他的遠端（第三方）套件，當執行 go install、go build 或 go run 時，go 會自動下載該 remote module，並記錄在 go.mod 檔案中。這些遠端套件會自動下載到 $GOPATH/pkg/mod 的資料夾中。當有不同的 module 之間需要使用相同版本的第三方套件時，會共用這些下載的內容，因此這些內容會是「唯讀」。若想要刪除這些第三方套件的內容，可以輸入 go clean -modcache。

設定 GOPATH​

參考：Go 起步安裝設定 > 設定 GOPATH

# ~/.zshrc
export GOPATH=$HOME/go

# 可以直接在 Terminal 執行 GOPATH 中的 bin
export PATH=$PATH:$GOPATH/bin

Packages​

Package Scope：同一個 Package 來的變數和方法是共享的​

  • 在 Go 語言中，並沒有區分 public、private 或 protected，而是根據變數名稱的第一個字母大小寫來判斷能否被外部引用。
  • 在同一個 package 中變數、函式、常數和 type，都隸屬於同一個 package scope，因此雖然可能在不同支檔案內，但只要隸屬於同一個 package，都可以使用（visible）。
  • 如果需要讓 package 內的變數或函式等能夠在 package 外部被使用，則該變數的第一個字母要大寫才能讓外部引用（Exported names），否則的話會無法使用

舉例來說，有兩隻檔案，他們在同一個資料夾內，且都屬於 main 這個 package：

// ---
// greetings.go
// ---
package main

import "fmt"

var points = []int{20, 90, 100, 45, 70}

func sayHello(name string) {
  fmt.Println("Hello", name)
}

// ---
// main.go
// ---
package main

import "fmt"

func main() {
  sayHello("Aaron")

  for _, v := range points {
    fmt.Println(v)
  }
}

雖然 points 和 sayHello 是在 greetings.go 這支檔案，但在 main.go 這支檔案，是可以取用到（visible）這些變數的。

要留意執行程式的時候要寫：

$ go run main.go greetings.go

留意變數是在 Package Scope 或 Function Scope​

要留意 package scope 和 function scope 的差別。假設有兩隻檔案 main.go 和 score.go，當中有一變數叫 score：

// ---
// score.go
// ---

package main

import "fmt"

func showScore() {
  // 在 score.go 中，並沒有 score 這個變數
  fmt.Println(score)
}

// ---
// main.go
// ---
package main

// score 這個變數是在 package scope
var score int = 87

func main() {
  // showScore 仍然可以取得 score 這個變數
  showScore()
}
信息

即時 score 這個變數不是在 main.go 中，只要它是在 main 這個 package scope 下，就可以被取用到，不管 showScore 是在哪裡被執行。

然而，如果是把 score 這個變數放在 Function Scope 下，則可能會無法被其他 function 所取用，例如：

// main.go
package main

func main() {
  // 如果變數放在 function scope 內，雖然 showScore 是在同一個 function 內被執行
  // 但會無法取用到 score 這個變數
  var score int = 87
  showScore()
}

Executable or Reusable Package​

  • Go 的程式碼都是以 package 的方式在組織，一個 package 就是在「同一資料夾」中的許多 GO 檔案。
  • 同一個 package 的所有 Go 檔案會放在同一個資料夾內；而這個資料夾內的所有檔案也都會屬於同一個 package，有相同的 package 名稱。
  • 通常 package 的名稱會跟著 folder 的名稱，舉例來說，若檔案放在 math/rand 資料夾中，則該套件會稱作 rand。
  • 有兩種不同類型的 package：
    • executable package：是用來產生我們可以執行的檔案，一定會包含 package main 並且帶有名為 main 的函式，只有這個檔案可以被執行（run）和編譯（build），並且不能被其他檔案給匯入。
    • reusable package(library package)：類似 "helpers" 或常稱作 library / dependency，目的是可以放入可重複使用的程式邏輯，它是不能被直接執行的，可以使用任何的名稱。

在 Go 裡面要區別這兩種 Package 的主要方式就是利用「package 名稱」，當使用 main 當做 package 名稱時，就會被當作 executable package，因此接著執行 go build <fileName> 時，會產生一支執行檔；但是當使用 main 以外的名稱是，都會被當作是 reusable package，因此當使用 go build 指令時，不會產生任何檔案。

關於 main

在 Golang 中 main 就是程式執行時的進入點（entry point），所以 Golang 在執行時，會先去找到名為 main 的 package，並執行這個 package 中的 main function。除非你的程式並不是要直接被執行的（not executable package），否則一定要有 main。

要匯入 reusable package 只需要：

// 匯入單一個 package
import "fmt"

// 匯入多個 packages（不用逗號）
import (
  "fmt"
  "strings"
)
// go-hello-world/main.go
package main

import (
  "fmt"

  // 把 foo 這個 package 的方法都放到這隻檔案中，如此不用使用 foo.HelloWorld（不建議）
  . "go-hello-world/foo"

  // 將模組轉換為別名，可以使用 bar.HelloWorld
  bar "go-hello-world/foo"

  // 沒有用到這個 package，但要 init 它
  _ "go-hello-world/foo"
)

func main() {
  fmt.Println(bar.HelloWorld())
  fmt.Println("Hello main")
}
// go-hello-world/foo/helloworld.go

package foo

import "fmt"

func init() {
  fmt.Println("This is init of helloworld")
}

// HelloWorld ...
func HelloWorld() string {
  return "Hello World"
}

Package name: coding style and convention​

在 Go 中，package 的名稱應該是短而清楚，以小寫（lower case）命名，同時不包含底線（under_scores）或小寫駝峰（mixedCaps），並且通常會是名詞（noun），例如 time、list、或 http。

在幫 package 命名的時候，試想自己就是使用該 pkg 的開發者，用這種角度來替自己的 pkg 命名。

另外，由於使用者在匯入該 package 後，使用時一定會需要使用該 package 的 name 作為前綴，因此在 package 中的變數名稱盡可能不要和 package name 重複。例如，

  • 在 http package 中如果要使用 Server，不需要使用 http.HTTPServer，而是可以直接使用 http.Server
  • 當在 uuid 的 package 要產生一組 uuid.UUID 時，不需要使用 uuid.NewUUID() 的方法，而是可以直接使用 uuid.New()，也就是說如果回傳的型別名稱（UUID）和該 pkg 的名稱相同時，可以直接將該方法命名成 New，而不用是 NewOOO
    • time.Now() 會回傳 time.Time
  • 如果 pkg 會回傳的 struct 名稱不同於 package 本身的名稱時，則可以使用 NewOOO
    • time.NewTicker()
    • uuid.NewRandom()

💡 雖然 pkg 中 variable name 的前綴會盡量不和 package name 重複，但很常見的情況是在該 pkg 中有其同名的 struct，例如 time pkg 中有名為 Time 的 struct，因此型別會是 time.Time，

不好的用法：

  • 盡可能不要使用 util, common, misc 這類的名稱作為 package name，因為這對使用者來說是沒有意義的名字，而是去想使用者這如果要用這些方法的話，最有可能使用到的關鍵字是什麼。
  • 見範例「Break up generic packages」

go tool 找 package 的邏輯​

go tool 會使用 $GOPATH 來找對應的 package，假設引入的 package 路徑是 "github.com/user/hello"，那麼 go tool 就會去找 $GOPATH/src/github.com/user/hello。

Modules​

參考資料
# 在 Go 1.11 後即支援 module
# $ export GO111MODULE=on

# go mod init [module_path]
$ go mod init example.com/user/hello  # 宣告 module path
$ go mod tidy        # 移除沒用到的 library
$ go mod download    # 下載套件（go build 和 go test 也會自動下載）

$ go get [library]   # 新增或更新 package 到 Module 內
$ go get -u ./...    # 等同於，go get -u=patch ./...
$ go get foo@master. # 下載特定版本的 go package

$ go list -m all      # 印出 module 正在使用的所有套件
$ go list -m -versions [package]   # 列出所有此套件可下載的版本
$ go list -u -m all   # 檢視有無任何 minor 或 patch 的更新

# 如果有 go.mod 的話，可以使用這個指令來執行
$ go run .
  • 要啟動 module 的功能，需要使用下列其中一種方式：
    • 在專案中建立 go.mod 檔，可以使用 go mod init
    • export GO111MODULE=on，預設是 auto（有 go.mod 就會啟用），也可以設成 on 或 off
  • 使用 module 可以開發者在 GOPATH 外寫 golang
  • 如果套件是在 module 中，go import package 的路徑會是 module path 加上 subdirectory。
  • 在一個專案中通常只會有一個 module（但也可以有多個），並且放在專案的根目錄，module 裡面會集合所有相關聯的 Go packages。在 go.mod 中會宣告 module path，這是用來匯入所有在此 module 中的路徑的前綴（path prefix），同時它也讓 go 的工具知道要去哪裡下載它。
  • 透過 Modules 可以準確紀錄相依的套件，讓程式能再次被編譯。
  • 總結來說：
    • 一個 repository 會包含一個或以上的 Go modules
    • 每個 module 會包含一個或以上的 Go packages
    • 每個 package 會包含一個或以上的檔案在「單一資料夾」中
  • 在執行 go build 或 go test 時，會根據 imports 的內容自動添加套件，並更新 go.mod。
  • 當需要的時候，可以直接在 go.mod 指定特定的版本，或使用 go get，例如 go get foo@v1.2.3, go get foo@master, go get foo@e3702bed2

基本結構​

Module Path and Root​

Root 指的是 go.mod 和 go.sum 所在的位置。

Path 這是 module 的路徑。

舉例來說：

// go.mod
module example.com/foo-bar
  • module root 是指 go.mod 檔案的位置
  • module path 則是指 example.com/foo-bar

go.mod​

在 root directory 中會透過 go.mod 來定義 Module，而 Module 的原始碼可以放在 GOPATH 外，有四種指令 module, require, replace, exclude 可以使用：

// go.mod
// 定義 module path
module example.com/go-playground

// go 的版本
go 1.22.2

// direct dependencies：定義相依套件的版本
require (
    github.com/some/dependency v1.2.3
    github.com/another/dependency/v4 v4.0.0
)

// indirect dependencies：這個套件並不是直接在這個專案中被引用，但我們使用的套件會相依到這個套件。
require indirect/dependency/v3 v3.3.1 //indirect


/**
 * replace 和 exclude 這兩個命令都只能用在當前模組（即， `main`），否則將會在編譯時被忽略。
 **/

// replace
// 將某一個 dependency 的版本換成另一個版本

// exclude
exclude outdated/dependency v3.4.1  // 用來忽略不要使用特定版本的套件

go.sum​

目的是要確保相依的套件版本正確且沒有被竄改，確保每次的 build 都是一致、可以被複驗的。

// go.sum
// <module> <version> <file tree hash>
// <module> <version>/go.mod <go.mod hash>
github.com/ajg/form v1.5.1 h1:t9c7v8JUKu/XxOGBU0yjNpaMloxGEJhUkqFRq0ibGeU=
github.com/ajg/form v1.5.1/go.mod h1:uL1WgH+h2mgNtvBq0339dVnzXdBETtL2LeUXaIv25UY=

go.mod 是在 module 初始化（initialized）是建立，go.sum 則是在 module 第一次 build 時建立。

使用方式​

建立 module​

# 在哪裡執行這個 command，module 就會建立在哪

# 如果你的 module 就放在 GOPATH 中，或在 GOPATH 外，但已經有 mod init 過的 repo
go mod init

# 如果 module 在 GOPATH 外，且尚未 init
go mod init [path]

module path 會取決於相對於 GOPATH 的路徑或 VCS：

  • 如果 module 是在 $GOPATH/src/github.com/x/y，則你的 module path 會是 github.com/x/y。
  • 如果 module 是在 $GOPATH 外，而且這個 repo 已經 mod init 過了

安裝套件（add dependencies）​

預設的情況下，套件會安裝在 $GOPATH/pkg/mod 底下。

安裝套件的方式包含：

  1. 直接在 source code 中加入套件，Go 會在 build 時自動把這些 package 下載
  2. 使用 go get 安裝
  3. 如果是測試會用到的套件，則會在執行 go test 時下載

和套件有關的指令​

  • 下面這些指令在執行時，會「安裝」程式中有用到的套件，但「不會清除」用不到的套件：go build, go clean, go fix, go fmt, go generate, go get, go install, go list, go run。
  • 下面這些指令除了會安裝 build 所需要的套件，也會「安裝」執行測試所需的套件，同樣「不會清除」用不到的套件：go test, go vet
  • 和 mod 有關，會安裝套件的指令：go mod tidy, go mod vendor, go mod why, go mod download

其他​

  • 階層關係上：Module > Package > Directory

跨檔案引用函式​

從下面的例子中可以看到，雖然 main.go 裡面有一個函式是定義在 state.go 的檔案中，但因為它們屬於同一個 package，所以當從 Terminal 執行 go run main.go state.go 時，程式可以正確執行。

或者也可以輸入 go run *.go：

// main.go
package main

func main() {
  printState()
}
// state.go
package main

import "fmt"

func printState() {
  fmt.Println("California")
}

套件載入的流程​

在 golang 中，使用某一個套件時，go 會先去 GOROOT 找看看是不是內建的函式庫，如果找不到的話，會去 GOPATH 內找，如果都找不到的話，就無法使用。

參考​