Go 语言规范 - 编码风格篇

时间  2021-01-21
标签 html git github golang express json segmentfault 服务器 架构 app 栏目 字符编码 繁體版
原文   原文链接
当前版本: v1.0.20201106

GitHub: shockerli/go-code-guidehtml

命名规则

  • 站在调用者的角度，包不是给你本身用的
  • 简洁、且见名知义
  • 采用通用、大众熟知的缩写命名。好比buf而不是bufio
  • 若是缩写的名字会产生歧义，则放弃或换个

文件名

整个应用或包的主入口文件应当是 main.go，或与应用名称简写相同。git

好比：spiker 包的主入口文件是 spiker.go，应用的主入口文件是 main.gogithub

包名

  • 包名与目录名一致golang

    若是一个目录下同时出现多个 package，则编译失败：express

    found packages pkg (a.go) and pb (b.go) in XXX
  • 大多数使用命名导入的状况下，不须要重命名

    少让调用者去起别名，除非名字太烂json

  • 所有小写，没有下划线、大写。错误示例MyPackage、my_package、myPackage
  • 不用复数。例如net/url，而不是net/urls
  • 不用信息量不足的名字。错误示例common、lib、util

导入包

  • 若是程序包名称与导入路径的最后一个元素不匹配，则必须使用导入别名
import (
    client "example.com/client-go"
    trace "example.com/trace/v2"
)
  • 在全部其余状况下，除非导入之间有直接冲突，不然应避免导入别名
import (
    "net/http/pprof"
    gpprof "github.com/google/pprof"
)
  • 如遇重名，请保留标准包而别名自定义或第三方包
  • 在非测试文件（*_test.go）中，禁止使用 . 来简化导入包的对象调用
  • 禁止使用相对路径导入（./subpackage），全部导入路径必须符合 go get 标准

驼峰命名法

常量、变量、类型、结构体、接口、函数、方法、属性等，所有使用驼峰法 MixedCaps 或 mixedCaps。segmentfault

下划线开头的命名更不容许，Go 语言的公私有统一用大小写开头来区分。服务器

但有个例外，为了对相关的测试用例进行分组，函数名可能包含下划线，如：TestMyFunction_WhatIsBeingTested。架构

Bad:app

const ROLE_NAME = 10

Good:

const RoleName = 10

常量

  • 若是是枚举类型的常量，须要先建立相应类型
type Scheme string

const (
    Http  Scheme = "http"
    Https Scheme = "https"
)
  • 若是模块的功能较为复杂、常量名称容易混淆的状况下，为了更好地区分枚举类型，可使用完整的前缀
type Symbol string

const (
    SymbolAdd Symbol = "+"
    SymbolSub Symbol = "-"
)

变量

  • 在相对简单的环境（对象数量少、针对性强）中，能够将一些名称由完整单词简写为单个字母

    • user 能够简写为 u
    • userId 能够简写 uid
  • 若变量类型为 bool 类型，则名称应以 Has、Is、Can 或 Allow 开头
var isExist bool
var hasConflict bool
var canManage bool
var allowGitHook bool

URL

  • URL 命名所有小写
  • 用正斜杠 / 代表层级关系
  • 使用连字符 - 来提升长路径中名称的可读性
  • 不得在 URL 中使用下划线 _
  • URL 结尾不该包含正斜杠 /
  • 文件扩展名不该包含在 URL 中
  • URL 需见名知意，但不可暴露服务器架构

Bad:

/GetUserInfo
/photos_path
/My-Folder/my-doc/
/user/user-list

Good:

/user/list
/user/operator-logs

函数/方法名

  • 不要多此一举
  • 长命名并不会使其更具可读性，一份有用的说明文档一般比额外的长名更有价值

Bad:

once.DoOrWaitUntilDone(f)

Good:

once.Do(f)
  • 在 pkg 包中名为 New 的函数会返回一个 pkg.Pkg 类型的值
q := list.New()  // q is a *list.List
  • 当 pkg 包中某个函数的返回值类型为 pkg.Pkg （或 *pkg.Pkg ）时，函数名应省略类型名
start := time.Now()                                  // start is a time.Time
t, err := time.Parse(time.Kitchen, "6:06PM")         // t is a time.Time
  • 当函数返回的值类型为 pkg.T 且 T 不为 Pkg 时，函数名应包含 T 以便让用户代码更易理解
ticker := time.NewTicker(d)          // ticker is a *time.Ticker
timer := time.NewTimer(d)            // timer is a *time.Timer
  • 获取器/设置器

    Go 并不对获取器（getter）和设置器（setter）提供自动支持。针对某个变量或字段，获取器名字无需携带 Get，设置器名字以 Set 开头。

    若你有个名为 owner （小写，未导出）的字段，其获取器应当名为 Owner（大写，可导出）而非 GetOwner。

Bad:

owner := obj.GetOwner()
if owner != user {
    obj.SettingOwner(user)
}

Good:

owner := obj.Owner()
if owner != user {
    obj.SetOwner(user)
}
  • 若函数或方法为判断类型（返回值主要为 bool 类型），则名称应以 Has、Is、Can 或 Allow 等判断性动词开头
func HasPrefix(name string, prefixes []string) bool { ... }
func IsEntry(name string, entries []string) bool { ... }
func CanManage(name string) bool { ... }
func AllowGitHook() bool { ... }

接口名

按照约定，只包含一个方法的接口应当以该方法的名称加上 -er 后缀来命名，如 Reader、Writer、Formatter/CloseNotifier 等。

名词用于接口名，动词用于接口的方法名。

type Reader interface {
    Read(p []byte) (n int, err error)
}

Error

  • Error 类型的命名以 Error 结尾
type ParseError struct {
    Line, Col int
}
  • Error 类型的变量，以 Err开头
var ErrBadAction = errors.New("somepkg: a bad action was performed")
  • 返回类型为 Error 的变量缩写采用 err
func foo() {
    res, err := somepkgAction()
    if err != nil {
        if err == somepkg.ErrBadAction {
        }
        if pe, ok := err.(*somepkg.ParseError); ok {
             line, col := pe.Line, pe.Col
             // ....
        }
    }
}

其余

包内容的名字不能够包名开头，由于无需重复包名

http 包提供的 HTTP 服务名为 http.Server ，而非 HTTPServer 。用户代码经过 http.Server 引用该类型，所以没有歧义。

不一样包中的类型名能够相同，由于客户端可经过包名区分它们

例如，标准库中含有多个名为 Reader 的类型，包括 jpeg.Reader 、 bufio.Reader 和 csv.Reader。每一个包名搭配 Reader 都是个不错的类型名。

名词缩写表

缩写名 说明
ctx Context 或相关，好比 gin.Context

分号

Go 其实也是用分号（;）来结束语句，但 Go 与 JavaScript 同样不建议给单一语句末尾加分号，由于编译器会自动加分号。

像以下语句是彻底能够的：

go func() { for { dst <- <-src } }()

一般 Go 程序只在诸如 for 循环子句这样的地方使用分号，以此来将初始化器、条件及增量元素分开。若是你在一行中写多个语句，也须要用分号隔开。

if err := f(); err != nil {
    g()
}

也是由于这个缘由，函数或控制语句的左大括号毫不能放在下一行。

if i < f()  // 报错
{           // 报错
    g()
}

圆括号

控制结构（if、for 和 switch）不须要圆括号，语法上就不须要

文档

README、项目文档、接口文档等，中文文档的排版参考：中文文案排版指北

注释

  • 全部导出对象必须注释说明其用途，非导出对象根据状况进行注释
  • 若是对象可数且无明确指定数量的状况下，一概使用单数形式和通常进行时描述，不然使用复数形式
  • 包、函数、方法和类型的注释说明都是一个完整的句子
  • 句子类型的注释首字母均需大写，短语类型的注释首字母需小写
  • 注释的单行长度不能超过 80 个字符，超过请强制换行
  • 可导出对象的注释，必须以对象的名称做为开头
// FileInfo is the interface that describes a file and is returned by Stat and Lstat
type FileInfo interface { ...

// HasPrefix returns true if name has any string in given slice as prefix
func HasPrefix(name string, prefixes []string) bool { ...

单行注释&多行注释

  • 两种注释风格，单行注释 //，多行注释 /* ... */
  • 多行注释仅用于包级别的文档注释，除此以外请用单行注释。包注释通常放置到 doc.go 文件，且该文件仅包含文档注释内容
  • 单行注释符号与内容之间，请用一个空格隔开

Bad:

//Comments

Good:

// Comments

GoLand 可设置自动格式化：

Preferences > Editor > Code Style > Go > Other 勾选上 Add leading space to comments

包注释

  • 包级别的注释就是对包的介绍，只需在同个包的任一源文件中说明便可有效
  • 对于 main 包，通常只有一行简短的注释用以说明包的用途，且以项目名称开头
// Write project description
package main
  • 对于一个复杂项目的子包，通常状况下不须要包级别注释，除非是表明某个特定功能的模块
  • 对于简单的非 main 包，也可用一行注释归纳
  • 对于相对功能复杂的非 main 包，通常都会增长一些使用示例或基本说明，且以 Package <name> 开头
/*
Package http provides HTTP client and server implementations.
...
*/
package http
  • 特别复杂的包说明，可单首创建 doc.go 文件来加以说明

函数与方法

  • 若是一句话不足以说明所有问题，则可换行继续进行更加细致的描述
// Copy copies file from source to target path.
// It returns false and error when error occurs in underlying function calls.
  • 若函数或方法为判断类型（返回值主要为 bool 类型），则以 <name> returns true if 开头
// HasPrefix returns true if name has any string in given slice as prefix.
func HasPrefix(name string, prefixes []string) bool { ...

结构、接口及其它类型

  • 类型的定义通常都以单数形式描述：
// Request represents a request to run a command.
type Request struct { ...
  • 若是为接口，则通常以如下形式描述：
// FileInfo is the interface that describes a file and is returned by Stat and Lstat.
type FileInfo interface { ...
  • 若是结构体属性较多，需对属性添加注释
// Var variable for expression
type Var struct {
    Key   string      `json:"key"`   // variable key
    Value interface{} `json:"value"` // value
    Desc  string      `json:"desc"`  // variable description
}

其余说明

  • 当某个部分等待完成时，可用 TODO: 开头的注释来提醒维护人员。
  • 当某个部分存在已知问题进行须要修复或改进时，可用 FIXME: 开头的注释来提醒维护人员。
  • 当须要特别说明某个问题时，可用 NOTE: 开头的注释：
// NOTE: os.Chmod and os.Chtimes don't recognize symbolic link,
// which will lead "no such file or directory" error.
return os.Symlink(target, dest)

格式化

咱们没有太多可选的余地，由于 Go 已经规范好了，在 Go 世界没有此类战争。

缩进

缩进统一采用4个空格，禁用制表符。

EditorConfig 设置：

[{Makefile,go.mod,go.sum,*.go}]
indent_style = tab
indent_size = 4

或 GoLand 设置：

Preferences > Editor > Code Style > Go > Tabs and Indents

goland-tab-indent-w600

空行

  • 适当增长空行以保持代码段落清晰

其余

函数分组与顺序

  • 函数应按粗略的调用顺序排序
  • 同一文件中的函数应按接收者分组
  • 导出的函数应先出如今文件中，放在 struct、const 和 var 定义的后面。
  • 在定义类型以后，但在接收者的其他方法以前，可能会出现一个 newXYZ() / NewXYZ()。
  • 因为函数是按接收者分组的，所以普通工具函数应在文件末尾出现。
  • 所以，通常一个 struct 及相关方法组织为一个文件。

Bad:

func (s *something) Cost() {
    return calcCost(s.weights)
}

type something struct{ ... }

func calcCost(n int[]) int {...}

func (s *something) Stop() {...}

func newSomething() *something {
    return &something{}
}

Good:

type something struct{ ... }

func newSomething() *something {
    return &something{}
}

func (s *something) Cost() {
    return calcCost(s.weights)
}

func (s *something) Stop() {...}

func calcCost(n int[]) int {...}

减小嵌套

Bad:

for _, v := range data {
    if v.F1 == 1 {
        v = process(v)
        if err := v.Call(); err == nil {
            v.Send()
        } else {
            return err
        }
    } else {
        log.Printf("Invalid v: %v", v)
    }
}

Good:

for _, v := range data {
    if v.F1 != 1 {
        log.Printf("Invalid v: %v", v)
        continue
    }

    v = process(v)
    if err := v.Call(); err != nil {
        return err
    }
    v.Send()
}

没必要要的 else

  • 多数时候，咱们能够把 else 分支里的代码提取为初始化。

Bad:

var a int
if b {
    a = 100
} else {
    a = 10
}

Good:

a := 10
if b {
    a = 100
}

全局变量声明

  • 全局变量，必须使用 var 关键字
  • 请勿指定类型，除非它与表达式的类型不一样

Bad:

var a string = "abc"
var s string = F()
    
func F() string { return "A" }

Good:

var a = "abc"
// 因为 F() 已经明确了返回一个字符串类型，所以咱们没有必要显式指定 s 的类型
var s = F()
    
func F() string { return "A" }
  • 若是表达式的类型与所需的类型不彻底匹配，请指定类型
type myError struct{}

func (myError) Error() string { return "error" }

func F() myError { return myError{} }

var err error = F()
// F() 返回一个 myError 类型的实例，可是咱们要 error 类型

局部变量声明

  • 若是将变量明确设置为某个值，则应使用短变量声明形式（:=）

Bad:

var s string = "abc"

Good:

s := "abc"
  • 若是变量专用于引用，则使用 var 关键字更合适
func s() {
    var s string
    f(&s)
}
  • 若是变量是返回值，则定义在函数返回类型中
func f(list []int) (filtered []int) {
    for _, v := range list {
        if v > 10 {
            filtered = append(filtered, v)
        }
    }
    return
}

import 包导入分组与排序

  • 同一文件，若是导入多个包，对其进行分组
  • 标准包、第三方包、自定义包，分别分组、空行分隔、排序

Bad:

import "a"
import "golang.org/x/sys"
import "runtime"
import "github.com/gin-gonic/gin"
import "b"
import "fmt"

Good:

import (
    "fmt"
    "runtime"

    "a"
    "b"

    "github.com/gin-gonic/gin"
    "golang.org/x/sys"
)

GoLand 设置以下：

goland-import-w600

类似的声明进行分组

对于 var、const、type 等声明语句：

  • 将类似的声明放在一个组内

Bad:

const a = 1
const b = 2

var a = 1
var b = 2

type Area float64
type Volume float64

Good:

const (
    a = 1
    b = 2
)

var (
    a = 1
    b = 2
)

type (
    Area float64
    Volume float64
)
  • 仅将相关的声明放在一组，不要将不相关的声明放在一组

Bad:

type Operation int

const (
    Add Operation = iota + 1
    Subtract
    Multiply
    RoleName = "Role Name"
)

Good:

type Operation int

const (
    Add Operation = iota + 1
    Subtract
    Multiply
)

const RoleName = "Role Name"
  • 分组使用的位置没有限制，函数内也可以使用分组

Bad:

func f() string {
    var red = color.New(0xff0000)
    var green = color.New(0x00ff00)
    var blue = color.New(0x0000ff)

    // ...
}

Good:

func f() string {
    var (
        red   = color.New(0xff0000)
        green = color.New(0x00ff00)
        blue  = color.New(0x0000ff)
    )

    // ...
}

函数/方法的参数/返回类型顺序

  • 简单类型优先于复杂类型

Bad:

func F(u User, n int) {}

Good:

func F(n int, u User) {}
  • 尽量将同种类型的参数放在相邻位置，则只需写一次类型

Bad:

func F(a int, c string, b int) {}

Good:

func F(a, b int, c string) {}
  • error 永远在最后一个返回类型

Bad:

func F() (error, int) {}

Good:

func F() (int, error) {}

结构体属性顺序

咱们先看下示例：

结构体A - 定义：

struct {
    a string
    c string
    b bool
    d bool
}

结构体A - 大小为40，内存布局图：

-w333

对比，结构体B - 定义：

struct {
    a string
    b bool
    c string
    d bool
}

结构体B - 大小为48，内存布局图：

-w329

咱们发现，结构体的属性顺序不一样，占用的内存大小和布局是彻底不一样的。

那咱们所以约定：将相同类型的属性尽可能放置在一块儿。即，推荐结构体A中的定义顺序。

结构体中的嵌入

嵌入式类型（例如mutex）应位于结构体内的字段列表的顶部，而且必须有一个空行将嵌入式字段与常规字段分隔开。

Bad:

type Client struct {
    version int
    http.Client
}

Good:

type Client struct {
    http.Client

    version int
}

初始化结构体时必须指定字段名

必须在初始化结构体时指定字段名，不然相关工具和 Review 都不给过。若是不指定，会对代码重构形成不可预期的后果。

Bad:

k := User{"John", "Doe", true}

Good:

k := User{
    FirstName: "John",
    LastName: "Doe",
    Admin: true,
}
惟一例外：若是有3个或更少的字段，则能够在测试表中省略字段名 
tests := []struct{
}{
    op Operation
    want string
}{
    {Add, "add"},
    {Subtract, "subtract"},
}

缩小变量做用域

  • 若是有可能，尽可能缩小变量做用范围，除非它与减小嵌套的规则冲突

Bad:

err := ioutil.WriteFile(name, data, 0644)
if err != nil {
    return err
}

Good:

if err := ioutil.WriteFile(name, data, 0644); err != nil {
    return err
}
  • 若是须要在 if 以外使用函数调用的结果，则不该尝试缩小范围

Bad:

if data, err := ioutil.ReadFile(name); err == nil {
    err = cfg.Decode(data)
    if err != nil {
    return err
    }

    fmt.Println(cfg)
    return nil
} else {
    return err
}

Good:

data, err := ioutil.ReadFile(name)
if err != nil {
    return err
}

if err := cfg.Decode(data); err != nil {
    return err
}

fmt.Println(cfg)
return nil

Error 信息不该大写或标点符号结束

Bad:

fmt.Errorf("Something bad.")

Good:

fmt.Errorf("something bad")

Error 描述信息是须要被包裹或引用描述的，那么下面的代码将告诉咱们为什么不该如此：

log.Printf("Reading %s: %v", filename, err)

slice

nil 是一个有效长度为 0 的 slice
  • 零值切片可当即使用，无需调用make建立

Bad:

nums := []int{}
// or, nums := make([]int, 0)

if add1 {
    nums = append(nums, 1)
}

Good:

var nums []int

if add1 {
    nums = append(nums, 1)
}
  • 要检查切片是否为空，请始终使用 len(s) == 0，不要检查 nil

Bad:

func isEmpty(s []string) bool {
    return s == nil
}

Good:

func isEmpty(s []string) bool {
    return len(s) == 0
}
  • 对于须要序列化的切片，则必须使用make初始化

Bad:

var v []int
s, _ := json.Marshal(v)
println(string(s))
// output: null

Good:

v := make([]int, 0)
s, _ := json.Marshal(v)
println(string(s))
// output: []

参考资料

感谢您的阅读，以为内容不错，点个赞吧 😆

原文地址: https://shockerli.net/post/go-code-guide-style

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程