go 语言项目规范

命名规范

包

• 包名必须和目录名一致，尽量采取有意义、简短的包名，不要和标准库冲突。
• 包名全部小写，没有大写或下划线，使用多级目录来划分层级。
• 项目名可以通过中划线来连接多个单词。
• 包名以及包所在的目录名，不要使用复数，比如 net/utl 而不是 net/urls。
• 不要用 common、util、shared 或者 lib 这类宽泛的、无意义的包名。
• 包名要简单明了，例如 net、time、log。

函数

函数名采用驼峰式，首字母根据访问控制决定使用大写或小写。

文件

文件名要简短有意义，应小写并使用下划线分割单词。

结构体

• 采用驼峰命名方式，首字母根据访问控制决定使用大写或小写，例如 MixedCaps 或者 mixedCaps。
• 结构体名不应该是动词，应该是名词，比如 Node、NodeSpec。
• 避免使用 Data、Info 这类无意义的结构体名。
• 结构体的声明和初始化应采用多行：

  // User 多行声明
  type User struct {
      Name  string
      Email string
  }
  
  // 多行初始化
  u := User{
      UserName: "colin",
      Email:    "colin404@foxmail.com",
  }
  

接口

基本和结构体命名规则保持一致：

• 单个函数的接口名以 “er”作为后缀（例如 Reader，Writer），有时候可能导致蹩脚的英文，但是没关系。
• 两个函数的接口名以两个函数名命名，例如 ReadWriter。
• 三个以上函数的接口名，类似于结构体名。

变量

• 变量名必须遵循驼峰式，首字母根据访问控制决定使用大写或小写。
• 在相对简单（对象数量少、针对性强）的环境中，可以将一些名称由完整单词简写为单个字母，比如：user 可简写为 u；userID 可简写 uid。
• 对于私有特有名词为首个单词则使用小写（如 apiClient）。其他特有名词都应当使用该名词原有的写法，如 APIClient、repoID、UserID。
• 若变量类型为 bool 类型，则名称应以 Has，Is，Can 或 Allow 开头。
• 局部变量应当尽可能短小，比如使用 buf 指代 buffer，使用 i 指代 index。

常量

常量名必须遵循驼峰式，首字母根据访问控制决定使用大写或小写

Error

Error 类型应该写成 FooError 的形式，比如 type ExitError struct {}
Error 变量写成 ErrFoo 的形式，比如 var ErrFormat = errors.New("unknown format")

---

注释规范

---

日志规范

• 打印日志

  • 在分支语句处打印。可判断出代码走了哪个分支，有助于判断请求的下一跳，继而继续排查问题。
  • 写操作必须打印。写操作最可能引起比较严重的业务故障，写操作打印日志可在出问题时找到关键信息。
  • 在循环中打印要慎重。如果循环次数过多会导致打印大量日志，严重拖累代码的性能，建议在循环中记录要点，在循环外面总结打印。
  • 在错误产生的最原始位置打印。对于嵌套 Error，可在 Error 产生的最初位置打印 Error 日志，上层如果不需要添加必要的信息，可直接返回下层 Error（减少重复的日志打印）。

• 日志级别

  • Debug：在开发测试阶段打印最详尽的信息（比如整个 HTTP 请求/响应的 Body）有助于 Debug，由于可能会严重拖慢性能，在上线时必须禁用。
  • Info：记录有助于运营分析的有用信息，目标是满足需求但不至于日志量太大、频度过高。
  • Warn：提示程序异常，一般是业务层面上不符合预期但不影响继续运行，或暂时影响但后续会恢复的情况。
  • Error：提示程序出错（大部分），比如请求失败、创建资源失败等。需要记录以避免日后排障过程中被忽略。
  • Panic：实际开发中很少用，通常只在需要错误堆栈，或不希望发生严重错误导致程序退出而采用 defer 处理错误时使用。
  • Fatal：实际开发中很少用，此时问题相当严重，导致整个程序无法运行。

• 日志内容

  • 避免输出敏感信息，例如密码、密钥等。
  • 为方便调试，通常在 Debug 级别记录临时日志，可以特殊字符开头，比如 log.Debugf("XXXXXXXXXXXX-1:Input key was: %s", setKeyName)。完成调试后可查找 XXXXXXXXXXXX 字符串找到临时日志，commit 前删除。
  • 以小写字母开头，以 . 结尾，比如 log.Info("update user function called.")。
  • 为了提高性能，尽可能明确类型，例如使用 log.Warnf("init datastore: %s", err.Error()) 而非 log.Warnf("init datastore: %v", err) 。
  • 最好包含两个信息。请求 ID（每次请求的唯一 ID可放在请求的通用日志字段中，便于过滤出某次请求）以及用户和行为（标识谁做了什么）。
  • 避免将普通日志记录在错误级别上。

• 日志内容

  • 避免输出敏感信息，例如密码、密钥等。
  • 为方便调试，通常在 Debug 级别记录临时日志，可以特殊字符开头，比如 log.Debugf("XXXXXXXXXXXX-1:Input key was: %s", setKeyName)。完成调试后可查找 XXXXXXXXXXXX 字符串找到临时日志，commit 前删除。
  • 以小写字母开头，以 . 结尾，比如 log.Info("update user function called.") 。
  • 为了提高性能，尽可能明确类型，例如使用 log.Warnf("init datastore: %s", err.Error()) 而非 log.Warnf("init datastore: %v", err)。
  • 最好包含两个信息。请求 ID（每次请求的唯一 ID可放在请求的通用日志字段中，便于过滤出某次请求）以及用户和行为（标识谁做了什么）。
  • 避免将普通日志记录在错误级别上。

• 实践

  • 开发调试、现网故障排障时，根据排障的过程优化日志打印。
  • 避免打印无用日志，也不要遗漏关键信息，目标是仅凭借关键日志就能定位到问题。
  • 总是将记录在本地文件，与日志平台解耦（确保中间出错时仍能记录日志）。
  • 应用可能包含多个服务，一个服务包含多个实例，应集中化日志存储处理。
  • 结构化日志记录，即添加默认通用字段到每行日志，方便日志查询和分析。包括：时间(精确到微秒)，文件名-函数-行号，日志级别。如果是错误，还需要把调用栈打出来。
  • 日志可分布在不同的组件、机器上，使用 RequestID 串联请求日志可提高排障效率。
  • 支持动态开关 Debug 日志，可避免为排查问题调整日志级别时重启服务。

版本规范

一般使用 语义化版本规范（SemVer，Semantic Versioning），即 主版本号.次版本号.修订号（X.Y.Z，其中 X、Y 和 Z 为非负的整数，且禁止在数字前方补零）。

• 主版本号（MAJOR）：不兼容的 API 修改。
  • 必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须归零。
  • 主版本号为零（0.y.z）的软件处于开发初始阶段，由于一切都可能随时被改变，不应该被视为稳定版。1.0.0 被界定为第一个稳定版本，之后的所有版本号更新都基于该版本修改。
• 次版本号（MINOR）：向下兼容的功能性新增及修改。一般偶数为稳定版本，奇数为开发版本。在任何公共 API 功能被标记为弃用时也必须递增，当有改进时也可以递增。其中可以包括修订级别的改变。每当次版本号递增时，修订号必须归零。
• 修订号（PATCH）：向下兼容的问题修正，即 bug 修复。

项目目录结构规范

---

git commit 规范

TODO

---

Git Flow

TODO

---

其他可参考的文章：

1、https://mp.weixin.qq.com/s/ZiWTxLAhw-aJxHQBUG_9YA
2、Go 语言实践：编写可维护的程序的建议