06 | 目录结构设计：如何组织一个可维护、可扩展的代码目录？

孔令飞



该思维导图由 AI 生成，仅供参考

你好，我是孔令飞。今天我们来聊聊如何设计代码的目录结构。
目录结构是一个项目的门面。很多时候，根据目录结构就能看出开发者对这门语言的掌握程度。所以，在我看来，遵循一个好的目录规范，把代码目录设计得可维护、可扩展，甚至比文档规范、Commit 规范来得更加重要。
那具体怎么组织一个好的代码目录呢？在今天这一讲，我会从 2 个维度来解答这个问题。
首先，我会介绍组织目录的一些基本原则，这些原则可以指导你去组织一个好的代码目录。然后，我会向你介绍一些具体的、优秀的目录结构。你可以通过学习它们，提炼总结出你自己的目录结构设计方法，或者你也可以直接用它们作为你的目录结构规范，也就是说结构即规范。
如何规范目录？想设计好一个目录结构，我们首先要知道一个好的目录长什么样，也就是目录规范中包含哪些内容。
目录规范，通常是指我们的项目由哪些目录组成，每个目录下存放什么文件、实现什么功能，以及各个目录间的依赖关系是什么等。在我看来，一个好的目录结构至少要满足以下几个要求。
命名清晰：目录命名要清晰、简洁，不要太长，也不要太短，目录名要能清晰地表达出该目录实现的功能，并且目录名最好用单数。一方面是因为单数足以说明这个目录的功能，另一方面可以统一规范，避免单复混用的情况。
功能明确：一个目录所要实现的功能应该是明确的、并且在整个项目目录中具有很高的辨识度。也就是说，当需要新增一个功能时，我们能够非常清楚地知道把这个功能放在哪个目录下。
全面性：目录结构应该尽可能全面地包含研发过程中需要的功能，例如文档、脚本、源码管理、API 实现、工具、第三方包、测试、编译产物等。
可观测性：项目规模一定是从小到大的，所以一个好的目录结构应该能够在项目变大时，仍然保持之前的目录结构。
可扩展性：每个目录下存放了同类的功能，在项目变大时，这些目录应该可以存放更多同类功能。举个例子，有如下目录结构：

公开

同步至部落

取消

完成

0/2000

荧光笔

直线

曲线

笔记

复制

AI

深入了解
翻译
英语
中文简体
中文繁体
法语
德语
日语
韩语
俄语
西班牙语
阿拉伯语
解释
总结

本文详细介绍了如何设计一个可维护、可扩展的代码目录结构，并在Go应用中的具体应用。作者强调了目录结构在项目中的重要性，并提出了组织目录的基本原则，包括命名清晰、功能明确、全面性、可观测性和可扩展性。文章介绍了两种具体的目录结构：平铺式目录结构和结构化目录结构，并提供了具体的目录结构示例，并对每个目录和文件的作用进行了解释。内容涵盖了Go应用的前后端代码存放、私有应用和库代码存放、可被外部应用使用的代码库存放、项目依赖、测试相关的文件存放、应用部署相关的文件存放、项目管理相关的文件存放等方面。总的来说，本文通过介绍目录规范和具体的目录结构，为读者提供了设计代码目录结构的指导和实践方法。文章内容详实，适合读者快速了解并应用于实际项目中。

仅可试看部分内容，如需阅读全部内容，请付费购买文章所属专栏
《Go 语言项目开发实战》，新⼈⾸单¥68

立即购买

登录后留言

全部留言(40)

最新
精选

helloworld
目录不是推荐统一使用单数吗，为什么文中还写成configs、deployments等复数形式呢
作者回复: 这个问题问的好，其实也可以不加s。项目中加s主要是为了跟project-layout项目对齐。
2021-06-14
5
14
Geek_c3e438
老师好，受益匪浅！ 1. /api/下放api接口定义文件如果是gRPC, pb文件一般放在/api/目录下那相关的请求响应的定义是不是一般也放在/api/目录下？ 2. 另外很多项目都有这样的文件夹： /service /server /client 等，大多也是请求响应的场景，一般是个什么作用，和要怎么区分目录结构？ 3. 一些定时任务呢？ 4. 不建议使用/src/，那一些utils, common呢？
作者回复: 1. 建议放在这个目录下：github.com/marmotedu/api 理由：这个目录可以存放相同项目，不同应用的api定义文件，将api定义文件放在项目维度，有利于api定义共享，避免多个项目重复定义api接口，导致后期变更，维护复杂。可以参考下iam的存放位置。 2. service：里面按功能模块，存放业务逻辑代码 server：存放启动服务的初始化和启动代码，例如：server := NewServer(), server.Init(), server.Start(), server.Stop() client：这个可以命名为类似xxctl这类目录名，指向更具体，例如iamctl，存放在cmd/iamctl目录下 3. 定时任务是个daemon，可以放在cmd目录下。另外定时任务一般来说可以抽象成一个公共服务，放在类似github.com/marmotedu这类目录下 4.utils, common这类目录不建议用，在Go项目中，每个包名字应该唯一、功能单一、明确。这类目录存放了很杂的功能，后期维护、查找都很麻烦。如果有类似time类的处理，可以存放在pkg/util/time包中。
2021-06-07
4
13
h
老师好，我在做go web后台管理系统相关的项目，用的gin框架，因为类似于那种MVC模型，所以会有model(orm)，router，middleware等目录，这种在web应用里面建议使用吗？还是说也建议按照你这种目录来划分
作者回复: 不建议，这种是按层来划分的目录结构。在go语言中容易出现循环调用，也不符合go的设计哲学。go的包是按功能划分的一个功能模块，所以在go中建议也按功能划分，可以最大程度的复用代码，减少循环调用的概率。
2021-06-09
5
9
h
可能我说的这些router，model，controller等目录是使用其他语言留下来的习惯吧，如果放在您这个目录结构，路由 orm相关的代码应该放在那个目录下呢？
作者回复: 放在internal/apiserver/store/mysql目录下
2021-06-09
2
8
yandongxiao
总结： 1. Go 项目的目录结构分为两类：平铺式目录结构和结构化目录结构； 2. 结构化目录分为三大类：应用目录、项目管理目录、文档目录。应用目录又可分为开发阶段、测试阶段、部署阶段对应的目录；开发阶段分为前端目录和后端目录。 3. 前端目录：/web，后端目录：/cmd, /internal, /pkg, /vendor, /third_party；测试阶段: /test；部署阶段：/build, /configs, /deploy, /init 4. 文档目录: README.md, /api, /docs, /CHANGELOG, /examples 5. 项目管理：/Makfile, /scripts, /tools, /githooks
作者回复: 66666
2021-11-21
2
7
王副会长
老师，我是小白，有些地方不太懂。比如/cmd目录下面是放组件的核心代码吗，那到底是放哪些呢，逻辑不是拆分为/internal和/pkg了吗，那/cmd下到底是放啥？还有/internal中如何拆分轻量级和复杂的服务，哪些放api层下，哪些放service层里
作者回复: /cmd目录下存放的是main函数入口，/cmd目录下的main文件中，通过简单几行代码，将业务逻辑的具体实现转到internal目录下。这样做主要的好处是，可以方便开发者找到应用入口位置。
2021-10-31

3
Geek_d308cd
老师好，关于不建议把类型定义放在model这点，如果它被多个模块依赖，应该放在哪呢
作者回复: 引入其所在的包，
2021-06-28

3
王少侠
数据库操作都在store/mysql，那SQL语句组装是在service还是在store组装呢？
作者回复: store中存放一些接口定义。 sql语句的组装放在service中
2021-06-17

3
Cheng
文件夹命名没有规范吗？如： 1. 需不需要加 s 2. 要不要使用缩写，如controller 变 ctl 3. 文件夹名称的单词直接要不要加分隔符，已经加什么分隔符，目前看到: 有些不加分隔符，加-或_ 4. 文件夹名称大小写问题，看到有些使用大写开头和小写开头
作者回复: 1. 文件夹一般不建议加s 2. 这种缩写根据需要自己选择，controller不建议缩写。因为ctl你根本不知道啥意思，缩写前提是看目录名就知道啥意思。 3. 文件夹单词之间需要加分隔符，具体加什么分隔符还是要分情况。如果是组件名目录可以用-，其它可以选择_，其实这里没有标准答案，可以根据需要需要自己选择，并形成规范即可。 4. 建议全小写
2021-06-14

3
olym
老师好，/internal/apiserver/store/mysq 这里存放的查询方法查到数据之后，数据的strcut定义应该要放在哪个目录比较合适？
作者回复: 可以放这里：github.com/marmotedu/api/apiserver/v1 放这里的好处是：不同项目都可以共用
2021-06-11
2
3

收起评论