爲什麼需要開發自己的 Go 庫
在編程語言中,包(Package)和庫(Library)是代碼組織和複用的重要工具。在 Go 中,包是代碼的基本組織單位,每個 Go 程序都由包構成。包的作用是幫助組織代碼,提供封裝和代碼複用的機制。
Go 包可以包含函數、類型、變量和常量等,這些元素可以被其他包引用和使用。例如,Go 的標準庫提供了大量的包,如 net/http
包提供了 HTTP 客戶端和服務器實現,fmt
包提供了格式化、I/O 函數等。
而庫是一種特殊的包,不包含 main
函數,不能被直接運行,但可以被其他程序引用。庫通常包含一些常用的功能或算法,如字符串處理、數學計算、網絡通信等。
開發自己的 Go 庫的優點:
- 複用性:當在多個項目中需要使用相同的功能時,可以將這些功能封裝在一個庫中,然後在需要的地方引用他。這樣可以避免重複編寫相同的代碼,提高編程效率。
- 可維護性:當需要修改某個功能時,只需修改對應的庫,而不需要在多個地方進行修改,這樣可以使代碼更易於理解和維護。
- 可測試性:爲每個庫編寫單元測試,確保他們的功能正確。修改代碼時,可以運行這些測試來檢查是否引入了新的錯誤。
接下來,將以 Asiatz(github.com/mazeyqian/asiatz)爲例,詳細演示如何創建一個規範的 Go 庫。
Asiatz 主要功能是進行時區轉換,特別是對亞洲時區的處理,他能夠將各種時區轉換爲 UTC 時間。
utcTime, err := asiatz.ShanghaiToUTC("08:00")
if err != nil {
// handle error
}
fmt.Println(utcTime) // Output: 00:00
第 1 步:創建目錄
在本地創建一個新的目錄,名爲 asiatz
。這個目錄將包含所有的源代碼、測試和文檔文件。
mkdir asiatz
cd asiatz
第 2 步:初始化項目
2.1 初始化 Go 模塊
在 asiatz
目錄下,運行 go mod init <domain>/<username>/<module-name>
來初始化 Go 模塊。
go mod init github.com/mazeyqian/asiatz
項目結構:
asiatz
└── go.mod
2.2 創建文件
創建一個新的 Go 文件,名爲 asiatz.go
。在此文件中,定義一個名爲 asiatz
的包,並編寫相對應的功能函數。
項目結構:
asiatz
├── asiatz.go
└── go.mod
代碼示例:
package asiatz
import (
"fmt"
"strconv"
)
// ToUTC converts a time string (HH:mm) from a specified timezone to UTC time string (HH:mm).
func ToUTC(timezoneOffset float64, time string) (string, error) {
hour, err := strconv.Atoi(time[:2])
if err != nil {
return "", err
}
minute, err := strconv.Atoi(time[3:])
if err != nil {
return "", err
}
totalMinutes := hour*60 + minute
utcTotalMinutes := ((totalMinutes-int(timezoneOffset*60))%1440 + 1440) % 1440
utcHour := utcTotalMinutes / 60
utcMinute := utcTotalMinutes % 60
utcTime := fmt.Sprintf("%02d:%02d", utcHour, utcMinute)
return utcTime, nil
}
// ShanghaiToUTC converts a Shanghai time string (HH:mm) to UTC time string (HH:mm).
// For example, "08:00" in Shanghai is equivalent to "00:00" in UTC.
func ShanghaiToUTC(shanghaiTime string) (string, error) {
return ToUTC(8, shanghaiTime)
}
第 3 步:編寫測試
Go 提供了內置的測試框架,可以方便地編寫和運行測試用例,以確保代碼的正確性和穩定性。
在 asiatz
目錄下創建一個新的 Go 文件,名爲 asiatz_test.go
。在這個文件中編寫測試用例來測試 asiatz.go
中的函數。
項目結構:
asiatz
├── asiatz.go
├── asiatz_test.go
└── go.mod
代碼示例:
package asiatz
import "testing"
type testConversion struct {
time string
expected string
}
var tests = map[string][]testConversion{
"Shanghai": {
{"01:00", "17:00"},
{"23:59", "15:59"},
},
// Others
}
func runConversionTests(t *testing.T, tests []testConversion, conversionFunc func(string) (string, error)) {
for _, test := range tests {
actual, err := conversionFunc(test.time)
if err != nil {
t.Errorf("Unexpected error for %s: %v", test.time, err)
continue
}
if actual != test.expected {
t.Errorf("Expected %s for %s but got %s", test.expected, test.time, actual)
}
}
}
func TestAllConversions(t *testing.T) {
for timezone, tests := range tests {
t.Run(timezone, func(t *testing.T) {
switch timezone {
case "Shanghai":
runConversionTests(t, tests, ShanghaiToUTC)
// Others
default:
t.Errorf("Unexpected timezone %s", timezone)
}
})
}
}
查看完整的用例可見:github.com/mazeyqian/asiatz/blob/main/asiatz_test.go
在當前目錄下運行 go test
查看結果:
PASS
ok github.com/mazeyqian/asiatz 0.449s
第 4 步:編寫文檔
爲了方便其他人理解和使用 Asiatz 庫,需要編寫相應的使用文檔。文檔應包括庫的目的、功能函數的用法、使用示例和注意事項等。
在 asiatz
目錄下,創建一個新的 README.md
文件,並在其中編寫文檔。
項目結構:
asiatz
├── asiatz.go
├── asiatz_test.go
├── go.mod
└── README.md
文檔示例:
第 5 步:發佈
5.1 上傳
將 Asiatz 庫上傳到 GitHub 或其他代碼託管平臺,使其他人可以方便地獲取和使用。
go get github.com/mazeyqian/asiatz
5.2 版本控制
在 Git 倉庫上,還可以使用標籤來管理庫的不同版本。
git tag v1.0.0
git push origin v1.0.0
例如 Asiatz 目前有四個版本:v1.0.0
、v1.1.0
、v1.1.1
、v1.1.2
,分別可以用以下命令獲取:
go get github.com/mazeyqian/[email protected]
go get github.com/mazeyqian/[email protected]
go get github.com/mazeyqian/[email protected]
go get github.com/mazeyqian/[email protected]
第 6 步:在真實項目中使用
以 Go 項目 github.com/mazeyqian/go-gin-gee 爲例,首先在項目目錄(go-gin-gee
)下運行命令 go get github.com/mazeyqian/asiatz
獲取 Asiatz 庫,然後引入使用即可:
// https://github.com/mazeyqian/go-gin-gee/blob/main/internal/api/controllers/schedules-controller.go
package controllers
import (
"log"
"github.com/mazeyqian/asiatz"
)
func Check() {
// ...
utcTime, err := asiatz.ShanghaiToUTC("10:00")
if err != nil {
// handle error
}
log.Println("UTC Time:", utcTime) // Output: 02:00
// ...
}
總結
本文以 Asiatz 庫爲例,詳細演示瞭如何從零開始創建、測試併發布自己的 Go 庫。無論是新手,還是有經驗的開發者;動手實踐,開發併發布自己的庫,不僅可以提高代碼的複用性和維護性,提高自己的技能,還可以爲社區做出貢獻。
版權聲明
本博客所有的原創文章,作者皆保留版權。轉載必須包含本聲明,保持本文完整,並以超鏈接形式註明作者後除和本文原始地址:https://blog.mazey.net/4150.html
(完)