送給學Go或者轉Go同學的一套編碼規範

程式設計師祝融發表於2022-12-09
Go


有沒有 xdm 是從別的語言轉 Go 的，比如 Java 、php 等，有兄弟在剛開始學的時候疑惑怎麼能寫出來優秀的程式碼。最近在專案中也 codereview 了不少 Go 語言的程式碼，有必要總結下程式碼規範，算是一個筆記記錄了。

說在前面，這只是我們團隊的一套規範而已。

今天我們聊一下 Go 的編碼規範，大概分為幾大模組，如注包/變數/常量命名、基本語法、函式、錯誤處理、心得等。

1. 程式碼風格

1.1 程式碼格式

  • 程式碼必須用 gofmt 進行格式化，goland 可以配置，可以自行搜尋一下配置
  • 我們編寫的程式碼每行應該不超過 120 個字元，超出部分用換行解決。
  • 單個檔案最大行數最大不超過 800 行.
  • 單個函式最大行數不超過 80 行。
  • import 規範
    • 不要使用相對路徑引入包，例如 import ../util/net
    • 在匯入包時，多個相同包名衝突時，必須使用匯入別名
// bad
"github.com/google/uuid"

// good
uuid "github.com/google/uuid"
  • 匯入的包建議分組，引用匿名包建議用一個新的分組，並加上註釋方便後面小夥伴閱讀
import (
    // Go 標準庫
    "fmt"

    //第三方包
    "github.com/jinzhu/gorm"
    "github.com/google/uuid"
    "github.com/go-redis/redis/v8"

    // 匿名包
    /import mysql driver
    _"github.com/jinzhu/gorm/dialects/mysql"

    // 內部包
    slice "xxx.local/pkg/v1/goslice"
    meta "xxx.local/pkg/v1/meta"
    gomap "xxx.local/pkg/v2/gomap"
)

1.2 宣告、初始化和定義

  • 一個函式需要使用多個變數時，可以在函式最開頭處使用 var 宣告。在函式外部宣告的變數不能使用 :=，會踩坑，不知道的可以評論區留言（要評論不易呀）！
var (
    port = 8081
    metricServerPort = 2001
)
  • 在初始化結構體用 &struct 代替 new(struct)，確保與結構體初始化一致，初始化結構體時換行。
// bad
stu := new(S)
stu.Name = "張三"

// good
stu := &S{
    Name:"李四"
}
  • 使用 make 在宣告 map、array 等應該指定容器的容量，從而達到預先分配內容。
users := make(map[int]string, 10)

tags := make([]int, 0, 10)
  • 使用標準 var 關鍵字事，不要指定型別，除非它與表示式的型別不同。
// bad
var _f string F()

func F() string {
    return "hello world!"
}

// good 
var _f F()

func F() string {
    return "hello world!"
}

1.3 error 處理

  • 若函式返回 error， 必須對 error 進行處理，如果業務允許可以用 _ 接受忽略。對應 defer 可以不用顯式進行處理。
// bad
func InitConfig() error {
    ...
}
InitConfig()


// good
func InitConfig() error {
    ...
}
err := InitConfig()
if err != nil {
    ...
}
// or 
_ := InitConfig()
  • error 作為返回值時必須作為最後一個引數返回
// bad
func InitConfig() (error,int) {
    ...
}

// good 
func InitConfig() (int, error) {
    ...
}
  • 錯誤需要單獨處理，儘量不要與其他的邏輯耦合在一起。
// bad
res, err := InitConfig()
if err != nil || res != nil {
    return err
}

// good
res, err := InitConfig()
if err != nil {
    return err
}
if res != nil {
    return fmt.Errorf("invalid result")
}

1.4 panic處理

  • 業務程式碼中禁止丟擲 panic 錯誤。
  • panic 只允許出現在在服務啟動之前，如讀取配置、連結儲存（redis、mysql 等）。
  • 業務程式碼中建議用 error 而不是 panic 來傳遞。

1.5 單元測試

  • 每個重要的函式都要編寫測試用例，合併程式碼要自動化執行一下所有的 test。
  • 檔案命名 xxx_test.go。
  • 函式命名建議使用 Test函式名。

2. 命名規範

在每個語言中，命名規範在程式碼規範中非常重要，一個統一的、精確的命名不僅僅可以提高程式碼的可讀性，也可以讓人覺的這個同志真的會呀。牛！

2.1 包命名規範

  • 包名必須與目錄名一致（這和其他 php、Java 還是有一點不太一樣的），儘量採取有意義、簡短的包名，不要與 go 的標準庫名稱一樣。
  • 包名小寫，沒有下劃線，可以使用中劃線隔開，使用多級目錄來劃分目錄。
  • 包名不要出現複數命名。
  • 包名命名儘量簡單一目瞭然，ge：user、log。

2.2 檔案命名規範

  • 檔名要見名思義，儘量簡而短
  • 檔名小寫，組合詞用下劃線分割

2.3 函式命名規範

  • 與 php、Java 一樣，必須遵循駝峰規範，Go 語言中需要根據訪問的控制決定大駝峰還是小駝峰。
  • 單元測試的函式用大駝峰，TestFunc。

2.4 結構體命名規範

  • 與 php、Java 一樣，必須遵循駝峰規範，Go 語言中需要根據訪問的控制決定大駝峰還是小駝峰。
  • 避免使用 info 、data 這種無意義的名稱。
  • 命名使用名詞而非動詞。
  • 結構體在宣告和初始化的時候需要換行，eg：
type Student struct{
    Name string
    Age uint8
}

student := Student{
    Name: "張三",
    Age: 18,
}

2.5 變數命名規範

  • 和 php、Java 一樣，必須遵循駝峰規範，Go 語言中需要根據訪問的控制決定大駝峰還是小駝峰。
  • 若變數為私有時，可以使用小寫命名。
  • 區域性變數可以簡寫，eg：i 表示 index。
  • 若變數代表 bool 值，則可以使用 Is 、Can、Has 字首命名，eg：
var isExit bool
var canReturn bool

2.6 常量命名規範

  • 必須遵循駝峰規範，Go 語言中需要根據訪問的控制決定大駝峰還是小駝峰。
  • 若代表列舉值，需要先建立。
type Code int

const (
    ErrNotFound Code = iota
    ErrFatal
)

3. 型別

3.1 字串

好像學過的語言中，都是從字串開始說起的。就像寫程式碼第一行都是從 Hello World！一樣！同意的點贊哈。

  • 字串判空值
// bad
if s == "" {
    ...
}

// good
if len(s) == 0 {
    ...
}
  • 字串去除前後子串。
// bad
var s1 "hello world"
var s2 "hello"
var s3 strings.TrimPrefix(s1, s2)

// good
var s1 "hello world"
var s2 "hello"
var s3 string

if strings.HasPrefix(s1, s2){
    s3 = s1[len(s2):]
}

3.2 切片 slice

  • 宣告 slice。
// bad
s := []string{}
s := make([]string, 10)

// good
var s []string
s := make([]string, 0, 10)
  • 非空判斷。
//bad
if len(slice) >0 {
    ...
}

// good
if slice != nil && len(slice) > 0 {
    ...
}
  • slice copy。
// bad
var b1,b2 []byte
for i, v := range b1 {
    b2[i] = v
}
for i := range b1 {
    b2[i] = b1[i]
}

// good
copy(b2,b1)
  • slice 新增。
// bad
var a,b []int
for _, v := range a {
    b = append(b,v)
}

// good
var a, b []int
b := append(b, a...)

3.4 結構體 struct

  • 初始化需要多行。
type Student struct{
    Name string
    Age uint8
}

student := Student{
    Name: "張三",
    Age: 18,
}

4. 控制語句

4.1 if

  • if 可以用區域性變數的方式初始化。
if err := InitConfig; err != nil {
    return err
}

4.2 for

  • 不允許在 for 中使用 defer， defer 只在函式結束時才會執行。
// bad
for file := range files {
    fd, err := os.Open(file)
    if err != nil {
        return err
    }
    defer fd.close()

}

// good
for file := range files{
    func() {
        fd,err := os.open(file)
        if err！=nil {
            return err
        }
        defer fd.close()
    }()
}

4.3 range

  • 如果不需要 key 直接用 _ 忽略，value 也一樣。
for _, v := range students {
    ...
}

for i, _ := range students {
    ...
}

for i, v := range students {
    ...
}

注： 若操作指標時請注意不能直接用 s := v。想知道可以評論區告訴我哦！

4.4 switch

  • 和其他語言不一樣，必須要有 defalt
switch type {
    case 1:
        fmt.Println("type = 1")
        break
     case 2:
        fmt.Println("type = 2")
        break
     default :
        fmt.Println("unKnown type")
}

4.5 goto

  • 業務中不允許使用 goto。
  • 框架和公共工具也不允許使用 goto。

5. 函式

  • 傳參和返回的變數小寫字母。
  • 傳入引數時slice、map、interface、chan 禁止傳遞指標型別。
  • 採用值傳遞，不用指標傳值。
  • 入參個數不能超出 5 個，超過的可以用 struct 傳值。

5.1 函式引數

  • 返回值超出 1 個時，需要用變數名返回。
  • 多個返回值可以用 struct 傳。

5.2 defer

  • 當操作資源、或者事物需要提交回滾時，可以在建立開始下方就使用 defer 釋放資源。
  • 建立資源後判斷 error，非 error 情況後在用 defer 釋放。

5.3 程式碼巢狀

  • 為了程式碼可讀性，為了世界和平，儘量別用太多的巢狀，因為真的很難有人類能看懂。

6. 日常使用感悟

  • 能不用全域性變數就不用，可以用引數傳值的方式，這樣可以大大降低耦合，更有利於單元測試。
  • 衣服開發中，在函式間多用 context 傳遞上下文，在請求開始時可以生成一個 request_id，便於鏈路、日誌追蹤。

6.1 提高效能

  • 在業務開發中，儘量使用 strconv 來替代 fmt。
  • 我們在使用 string 字串型別時，當修改的場景較多，儘量在使用時用 []byte 來替代。因為每次對 string 的修改都需要重新在申請記憶體。

6.2 避免踩坑

  • append 要小心自動擴容的情況，最好在申明時分配好容量，避免擴容所帶來的效能上的損耗以及分配新的記憶體地址。若不能確定容量，應選擇一個比較大一點的值。
  • 併發場景下，map 非執行緒安全，需要加鎖。還有一種評論區告訴我吧。
  • interface 在編譯期間無法被檢查，使用上會出現 panic，需要注意

7. 總結

本篇很講了 Go 語言的編碼規範，當時想說的，規範是大家預定的東西，每個公司、團隊都會有不一樣的規範，只要大家一起遵循就好啦。你可以根據自己團隊的需求，定一套屬於自己團隊的專案規範。如果想小夥伴一起遵循，可以藉助一些工具來保障執行度。

講了很多，雖然很基礎，希望對於剛剛轉 Go 語言，或者剛學習 Go 語言的同學有幫助吧。今天就到這裡了。希望得到大家的一鍵三連。感謝！

歡迎關注微信【程式設計師祝融】，原文連結：mp.weixin.qq.com/s/lfjP9DEia2WL4Ua...

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章