Skip to main content
Version: v0.5

代码规约

在这部分,你将会了解 Karpor 项目中所有类型的代码规约。不必一次把这些规则全部了解,确保你在编写代码前阅读对应的部分就可以了。

Go 代码规约

  • Go 代码评审评论

  • 高效的 Go

  • 了解并且避免 Go 地雷

  • 为你的代码编写注释.

    • Go's 注释规约
    • 如果代码评阅者询问你代码为什么要这么实现,这可能说明你应当为你的代码编写注释。
  • 命令行标志应该用双连接号 --,而不是下划线

  • 接口

    • 根据 RFC3986,URL 是大小写敏感的。Karpor 使用“短横线命名(kebab-case)”作为 URL。
      • 例如:POST /rest-api/v1/resource-group-rule
  • 命名

    • 为接口选择名称时请考虑包名称,避免冗余。

      • 例如: storage.Interface 优于 storage.StorageInterface
    • 不要在包名称中使用大写字符、下划线和破折号。

    • 选择包名称时,请考虑父目录名称。

      • 所有 pkg/manager/cluster/foo.go 应该命名为 package cluster 而不是 package clustermanager
      • 除非有充分理由,package foo 行应该与 .go 文件所在目录的名称相同。
      • 为了避免歧义,导入包时可以指定别名。
    • 锁应该被称为 lock,并且永远不应该被嵌入(总是以 lock sync.Mutex 的形式明确声明)。当存在多个锁时,应该遵循 Go 的命名约定给每个锁一个 buts 的名称 - stateLockmapLock 等。

Bash 或脚本规约

  • Shell 样式指南
  • 确保构建、发布、测试和集群管理脚本可以在 macOS 上运行

目录和文件规约

  • 避免软件包无序扩展。为新的包找到合适的子目录。

    • 没有更合适放置位置的新包应该放在 pkg/util 下的子目录。
  • 避免使用通用包。使用名为 util 的包让人疑惑。相反地,应当根据你期望的功能推导出包名 例如,处理等待操作的使用功能位于 wait 包中,包括类似 Poll 这样的功能,所以完整名称是 wait.Poll

  • 所有的文件名都应该是小写

  • Go 源码文件名和目录名中使用 _,而不是 -

    • 包目录名通常应当尽量避免使用分隔符(当包目录名含多个单词时,它们通常应该被放在嵌套的子目录)
  • 文档的文件名和目录名中应该使用 -,而不是 _

  • 用于说明系统特性的示例应该位于 /docs/user-guide/docs/admin, 取决于它是主要面向部署应用的用户还是集群管理员。实际的应用示例应位于 /example

  • 第三方代码

    • 普通的第三方依赖 Go 代码 由 go modules 管理

    • 其他的第三方代码应该放在 /third_party 目录下

      • fork 的第三方 Go 代码放在 /third_party/forked 目录下
      • fork 的golang stdlib 代码放在 /third_party/forked/golang 目录下
    • 第三方代码必须包含许可证

    • 这也包括修改过的第三方代码和引用

Linting 和格式化

为了确保 Go 代码库之间的一致性,我们要求所有代码通过多个 linter 检查。

要运行所有的 linter,请使用 lint 作为 Makefile 目标:

make lint

该命令将清理代码并进行一些 lint 检查。检查结束后请记得检查所有变更。