Go 项目文件命名规范是什么？(命名项目规范目录下划线)「hgo项目文件夹名与项目名不一致」

计算机科学中只有两件难事：缓存失效和命名。
—— 菲尔·卡尔顿（Phil Karlton）。

在编程世界中，选择正确的命名约定是打开可读和可维护代码大门的重要途径。
在使用 Go 语言开发大型项目时，文件命名是构建清晰项目结构的关键一环，一个合理的文件命名规范不仅能提高开发效率，还能降低团队协作中的沟通成本。

在这篇博文中，我们将深入探讨 Go 中命名的最佳实践。

在探讨 Go 文件命名规范之前，我们有必要先来了解下 Go 项目中的目录和包的命名规范是什么。

关于 Go 目录命名规范，在网上搜索相关资料，基本能找到如下两条共识：

项目本身也是一个目录，所以项目名也遵循这两条规范。

其实我们可以借鉴流行的 Go 项目，参考这些优秀的项目是如何对目录进行命名的。
比如 Kubernetes 项目就非常具有参考价值。

如下是 Kubernetes 项目 /cmd 目录部分截图：

K8s /cmd

可以发现，Kubernetes 项目目录名都采用全小写单词，并且必要时可以使用中划线分隔。

不过，值得注意的是，有些目录名并没有使用中划线进行分隔，而是直接将多个单词连在了一起。
所以何时使用中划线是一个选择问题，而不是固定的强制规范。

我们再看下 Kubernetes 项目 /pkg 目录部分截图：

K8s /pkg

可以发现，/pkg 目录下所有目录名都没有使用中划线分隔。
有意思的是，甚至 kubeapiserver 也连在了一起，回看上面 /cmd 目录中的写法是 kube-apiserver。
看来 Kubernetes 项目不同目录有着各自的命名规范。

针对这点，我的理解是：/cmd/kube-apiserver，作为项目中组件的入口文件目录，使用中划线分隔可以起到见名知意的效果；而 /pkg/kubeapiserver 作为包路径不使用中划线分隔，是为了方便包的导入。

如下列举几个目录名正反示例。

正确示例：

cmdinternalpkgtaskkube-schedulerkube-controller-manager

反向示例：

CMDkubeSchedulerKubeSchedulerkube_scheduler

不过凡事总有特例，我之前写过一篇文章《如何设计一个优秀的 Go Web 项目目录结构》，里面介绍了一个 Go 项目的标准布局。
其中包含一个外部辅助工具目录 third_party，用来存放 fork 的代码和其他第三方工具。
这里 third_party 就采用了下划线命名，这种算是约定俗成的命名，就无需刻意遵循目录命名规范了。

另外，关于项目本身的的命名，其实还有一些额外的规范：

如下列举几个项目名正反示例。

正确示例：

useruserapiredis-gokubernetes

反向示例：

user_apiProductAIInfraAiInfra

以下是我个人的一些建议：

接下来，我们再一起探究下 Go 项目中包名的命名规范是什么。

幸运的是，对于包名，Go 官方博客给出了参考建议，也是最为权威的规范。

在 Package names 这篇 Go 官方博文中，给出了几条好的包命名原则：

Go Team 成员 David Crawshaw 在 2014 Google I/O talk 中也对包命名规范给出了建议：

同目录名规范一样，包名也存在例外的情况：

如下列举几个包名正反示例。

正确示例：

controllerstringsettabwriter

反例：

MyUtilutiltime // 与标准库重名tabWriterTabWritertab_writer文件名

前文分别介绍了 Go 项目中目录名和包名的命名规范，现在终于可以探讨 Go 文件的命名规范了，这也是本文的重头戏。

不过，对于 Go 文件的命名规范，即没有 Go 团队的官方博客作为参考，也没有著名的 Gopher 站出来分享 Go 文件到底改如何命名。

这是一个少有人特意提及的规范项，不过我在 Go 项目的 GitHub 仓库中找到了一条讨论这个问题的 issue doc: filename conventions。

虽然不少人参与了讨论，但遗憾的是，这个问题现在仍然没有定论。
不过，这也正是此问题值得探讨的原因，也是本文的意义所在。

其实遇到规范相关问题，我们最先想到的，应该就是参考 Go 源码本身。
很不巧，针对 Go 文件的命名规范问题，Go 源码做的也不够好。

正如 doc: filename conventions 问题 issue 提问者列举的几个 Go 文件名示例中，存在很大差异：

这就比较有意思了 。

在 issue 中点赞最多的是 peterbourgon 的评论:

There is a de facto standard for Go source file names: all lowercase with underscore separation when necessary, i.e. snake case. (The exceptions are exceptions.) I'd appreciate having it as a documented standard, too, to answer questions like @carnott-snap notes, especially among junior Gophers. In my opinion it needn't be so formal as entering Effective Go, a short new section on CodeReviewComments is more than sufficient.

这个回答的核心是：all lowercase with underscore separation when necessary, i.e. snake case. (The exceptions are exceptions.) 。

即大家达成了三点共识：

前面两条好理解，例外情况都有哪些？我总结大概有如下几种：

虽然很多人达成了上面三点共识，但其实文件命名和目录命名规范一样，存在“灰色地带” —— 必要时用下划线分隔。

到底何时是必要的时候？

这也是最不统一的一点规范，我发现很多人推荐，在名称出现多个单词时采用下划线分隔。
例如 task_status.go、web_shell.go。

但还有一小部分人，更推崇不采用下划线的命名方式，例如 taskstatus.go、webshell.go。

而我个人的偏好则更倾向于后者。
如果单词数量为 2 个，我会倾向于不使用下划线分隔，例如 taskstatus.go；如果单词数量为 3～4 个，则倾向于使用下划线分隔，例如 import_known_versions.go、default_storage_factory_builder.go。

但最好的方案，仍然是尽量用简短有意义的单个单词或缩写作为文件名。

NOTE: 我倾向于不使用下划线分隔的几点理由：

与包名对齐。

kubernetes 也经常这么干。

你看，testdata 就没有使用下划线分隔 。

... 想到了再说 :)。

如下列举几个文件名正反示例。

正确示例：

router.gomiddleware.gowebshell.go

反面示例：

routers.go // 复数fooBar.goService.go总结

计算机科学中只有两件难事：缓存失效和命名。
本文探讨的是后者。

Go 语言虽然是后起之秀，但在项目布局、命名规范等的确没有一个统一的标准。
不过社区还是给出了一些共识性建议：

希望本文能对你有所启发。

延伸阅读