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 的名称 - stateLock，mapLock 等。

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 检查。检查结束后请记得检查所有变更。