Golang中的文件夹组织结构（来自smartbytelabs.com）
当我们谈论Go语言（或者说任何编程语言）中的文件夹结构时，我们指的是如何在项目中组织文件和目录。这种组织方式就像一张路线图，帮助开发人员维护、浏览和扩展项目，通过清晰地划分不同的部分，如关注点、模块和功能。遵循Go语言中的一些常见约定惯例不仅使阅读和协作变得更加容易，也为长期维护项目奠定了基础。
为什么文件夹结构这么重要？
有几个重要原因，拥有一个井井有条的文件夹结构真的很重要。
- 层次分离： 它保持项目的不同部分——如业务逻辑、数据访问和API处理——在各自的文件夹中。这样，开发人员可以专注于特定领域，而不会感到不知所措或困惑。
- 更好的组织： 通过整洁地整理代码及其依赖项，大型项目变得更容易导航。
- 可重用性： 好的结构使你可以创建可以在项目不同部分使用的组件或包，从而节省时间和精力。
- 更易维护： 当每个人都遵循一致的文件夹设置时，查找和更新代码会变得简单得多。这有助于更好地管理项目的长期维护。
- 模块化： 有效的文件夹结构鼓励模块化设计，使在项目增长时添加新功能变得更加容易。
简单来说，智能文件夹使你的开发流程更顺畅，并有助于你的项目茁壮成长。
Go语言中的常见文件夹布局以下是一些在 Golang 项目中常用的文件夹组织
1. 扁平文件夹结构，也称为扁平文件结构:扁平文件夹结构是一种组织方法，其中所有文件都直接存储在根目录下，没有深层次的嵌套或多个子目录。这种简单的结构使其容易导航和管理，对于小型或简单的项目来说尤其如此。
项目目录/
├── main.go # 应用入口
├── handler.go # HTTP 处理函数
├── service.go # 业务逻辑
├── repository.go # 数据库访问层
├── config.go # 配置
├── utils.go # 工具方法
├── go.mod # go.mod 文件
└── go.sum # go.sum 文件- 小型项目：适合低复杂度的项目，允许开发人员在几个文件中管理所有功能。
- 原型和MVP：非常适合快速构建原型或最小可行产品（MVP，Minimum Viable Product），无需组织文件即可进行快速迭代。
- 命令行工具：适合只需要少量支持文件的这样的小型命令行应用程序，使执行和测试变得简单直接。
- 学习和实验：对于初学者学习新编程语言或框架非常有益，因为它简化了文件组织的复杂性。
在分层结构中，应用程序被组织成不同的层次，比如控制器、服务、数据存储和模型。每一层都有其特定的功能，从而使代码更容易维护。
项目
├── cmd # 命令相关的文件
│ └── app # 应用入口
│ └── main.go # 主程序
├── internal # 内部代码库
│ ├── handlers # HTTP 处理程序
│ │ └── user_handler.go # 用户特定处理程序
│ ├── services # 业务逻辑（服务层）
│ │ └── user_service.go # 用户特定服务
│ ├── repositories # 数据访问（仓储层）
│ │ └── user_repo.go # 用户特定仓储
│ └── models # 数据模型（实体）
│ └── user.go # 用户模型
├── pkg # 公用工具包
├── configs # 配置文件
├── go.mod # Go 模块定义
└── go.sum # Go 模块校验文件使用情况如下:
- 中等规模的项目： 适合需要功能和层次明确分离的应用。
- 职责分离： 促进这种清晰的架构，在这种架构中，处理器（Handler）只负责处理请求，将业务逻辑交给服务，数据访问交给数据存储库。
- 单元测试： 每一层都可以独立进行单元测试，确保更改不影响其他层，从而提高系统的可维护性。
在领域驱动设计（DDD）中，应用程序被细分到不同的领域或有边界的上下文中，每个领域有自己的模型、仓储和服务，这样可以将逻辑隔离，使代码保持领域特定性，从而促进更好的组织和清晰性。
项目
├── cmd # 命令相关的文件
│ └── app # 应用程序入口点
│ └── main.go # 主应用逻辑
├── internal # 内部库
│ ├── user # 域 'user'
│ │ ├── handler.go # 用户处理器
│ │ ├── service.go # 用户服务
│ │ ├── repository.go # 用户仓库
│ │ └── user.go # 用户模型
│ └── product # 域 'product'
│ ├── handler.go # 产品处理器
│ ├── service.go # 产品服务
│ └── repository.go # 产品仓库
├── pkg # 公用包
├── configs # 配置文件
├── go.mod # Go 模块文件
└── go.sum # Go 模块校验文件应用场景:
- 复杂的项目: 最适合具有多个业务领域的应用程序，确保每个领域可以独立发展而不影响其他领域。
- 解耦和扩展性: 当需要隔离应用程序的不同部分以实现扩展性和可维护性时非常有用。
- 促进模块化设计: 每个领域都可以单独管理和开发，使团队可以专注于特定领域而不会产生冲突。
这种架构将应用分层组织，各层之间有明确的依赖关系。这种结构确保核心业务逻辑不受数据库、框架、用户界面等外部系统的影响。
项目
├── cmd/ # 命令相关的文件
│ └── app/ # 应用入口
│ └── main.go # 主应用逻辑
├── internal # 内部代码库
│ ├── delivery/ # 外部层（HTTP 处理程序、gRPC 等）
│ │ └── http/ # HTTP 分发
│ │ └── user_handler.go # 用户专用的 HTTP 处理程序
│ ├── usecases/ # 用例（业务逻辑层）
│ │ └── user_service.go # 用户专用的服务逻辑
│ ├── repository/ # 仓库（数据访问、外部服务）
│ │ └── user_repo.go # 用户专用的数据访问
│ └── entities/ # 实体（核心模型、领域对象）
│ └── user.go # 用户实体
├── pkg/ # 公共工具包
├── configs/ # 配置
├── go.mod # Go 模块文件
└── go.sum # Go 模块校验文件重要原则:
- 核心实体：领域模型: 领域模型是架构的核心，确保业务逻辑是主要关注对象。
- 用例: 封装特定于应用的业务规则，定义实体间的交互模式。
- 交付层：接口层: 管理通过各种接口（如API、CLI、gRPC）的外部交互。
- 仓储层: 处理数据访问，允许与数据库及第三方服务交互，而不与业务逻辑绑定。
应用场景:
- 大型可扩展项目: 适用于随着时间的推移进行扩展和适应，而不会影响核心功能的应用。
- 独立测试: 易于独立测试核心逻辑，无需依赖于框架、数据库或任何其他外部服务，从而提高可维护性和灵活性。
一个模块化结构将应用程序划分为松散耦合、自包含的模块，每个模块有自己的代码库。这样设计使得每个模块能够专注于特定功能或业务单元，从而提升可重用性和可扩展性。
project/
├── user_module/ # 用户模块
│ ├── handler/ # 处理用户相关请求的程序
│ ├── service/ # 用户操作的业务处理
│ ├── repository/ # 访问用户数据的数据层
│ ├── user.go # 用户模型定义
│ ├── go.mod # 用户模块 Go 模块定义
│ └── go.sum # 用户模块校验文件
├── product_module/ # 产品模块
│ ├── handler/ # 处理产品相关请求的程序
│ ├── service/ # 产品操作的业务处理
│ ├── repository/ # 访问产品数据的数据层
│ ├── product.go # 产品模型定义
│ ├── go.mod # 产品模块 Go 模块定义
│ └── go.sum # 产品模块校验文件
├── api_gateway/ # API 网关，管理不同服务
│ ├── main.go # API 网关的主入口点
│ ├── go.mod # API 网关 Go 模块定义
│ └── go.sum # API 网关校验文件
└── configs/ # 共享配置文件应用场景:
- 微服务： 适用于构建在微服务架构上的应用，不同团队可以独立开发各自的模块。
- 解耦和可扩展性： 鼓励明确地分离关注点，使得每个模块可以独立开发、测试和部署。
- 独立依赖管理： 每个模块可以有自己的
go.mod文件，便于独立管理依赖，减少模块间的冲突。
在基于功能的文件夹结构中，应用程序的每个功能都被视为一个独立的单元。与该功能相关的所有代码，包括处理器（handlers）、服务、仓库（repositories）等，都位于该功能目录下。这样做增强了功能内的内聚性，并促进了封装特定功能的逻辑。
项目/
├── cmd/
│ └── app/
│ └── main.go # 主应用逻辑
├── internal/
│ ├── user/ # 用户模块
│ │ ├── handler/ # 用户相关的HTTP处理器
│ │ ├── service/ # 用户相关的业务逻辑
│ │ ├── repository/ # 用户相关的数据访问
│ │ └── user.go # 用户模型
│ ├── product/ # 产品模块
│ │ ├── handler/ # 产品相关的HTTP处理器
│ │ ├── service/ # 产品相关的业务逻辑
│ │ ├── repository/ # 产品相关的数据访问
│ │ └── product.go # 产品模型
│ ├── order/ # 订单模块
│ │ ├── handler/ # 订单相关的HTTP处理器
│ │ ├── service/ # 订单相关的业务逻辑
│ │ ├── repository/ # 订单相关的数据访问
│ │ └── order.go # 订单模型
├── pkg/ # 公用工具包
│ └── logger.go # 日志工具
├── configs/ # 配置文件
├── go.mod # Go模块定义
└── go.sum # Go模块校验文件特色:
- 封装: 每个功能封装了自己的逻辑、模型和层次，最小化不必要的依赖关系。
- 可扩展性: 结构能够随着新功能的添加轻松扩展，只需创建新的功能目录即可。
- 专注于业务需求: 由于组织围绕功能展开，因此与业务需求紧密契合，使开发团队更加直观理解。
- 高内聚性: 每个功能的相关代码都集中在一起，使得特定功能的代码库更容易维护和扩展。
使用案例:
- 大规模应用: 最适合用于由多个独立功能组成的应用，例如用户管理、产品目录管理或订单处理，这些功能可以逻辑上独立。
- 功能型团队: 特别适用于围绕功能所有权组织的团队，每个团队全程负责一个功能，增强协作并明确责任。
六边形架构模式，通常称为端口和适配器，是一种强调将核心业务逻辑与外部依赖分离的架构模式。在这种架构中，核心通过端口（也就是接口）与外部世界交互，而外部系统，比如数据库和Web框架，则作为适配器来实现这些接口。
项目/
├── cmd/
│ └── app/
│ └── main.go # 应用程序主逻辑
├── internal/
│ ├── core/ # 核心业务逻辑（实体和用例）
│ │ ├── user/ # 用户功能
│ │ │ ├── entity.go # 用户实体（领域对象）
│ │ │ └── usecase.go # 业务逻辑（用例）
│ │ └── product/ # 同样结构
│ │ └── ... # 产品相关的文件
│ ├── adapters/ # 外部系统接口适配器
│ │ ├── database/ # 数据库适配器（数据库仓库）
│ │ │ └── user_repo.go # 用户仓库实现
│ │ ├── api/ # API适配器（HTTP处理程序）
│ │ │ └── user_handler.go # 用户特定的HTTP处理程序
│ │ └── messaging/ # 消息系统（如Kafka）
│ │ └── user_event.go # 用户事件处理
│ └── ports/ # 端口（接口）
│ ├── user_repository.go # 用户仓库接口定义
│ ├── user_service.go # 用户服务接口
│ └── ... # 其他端口接口
├── pkg/ # 公用库
├── configs/ # 配置文件夹
├── go.mod # Go模块配置文件
└── go.sum # Go模块校验和文件特点:
- 核心独立性: 核心业务逻辑与框架、数据库和API等外部组件独立运行，这种独立性增强了系统的可维护性和灵活性。
- 端口（接口）: 端口定义了核心业务逻辑如何与外部系统交互，确保核心组件和适配器之间有明确的合同。
- 适配器: 适配器（比如数据库适配器、API适配器和消息适配器）可以轻松替换，而不会影响核心逻辑。这样可以便于测试和重构，因为核心可以在没有外部依赖的情况下独立测试。
例子：
- 解耦的业务逻辑：适用于需要将业务逻辑与外部系统（如数据库、API或UI框架）解耦的应用程序，确保系统的灵活性和适应性。
- 外部系统可能变化的项目：特别适用于需要灵活性的项目，让应用程序在不修改核心逻辑的情况下适应变化。
一个单代码库（monorepo）是指存放多个服务或库的单一代码库。这种结构在大型组织中很常见，让不同项目能独立开发和部署，但仍共享一个统一的代码库。
项目/
├── services/
│ ├── user-service/
│ │ ├── cmd/
│ │ │ └── main.go # 用户服务的主逻辑
│ │ ├── internal/ # 用户服务内部代码库
│ │ │ ├── handler/ # 用户特定的HTTP处理器
│ │ │ ├── service/ # 用户特定的业务处理逻辑
│ │ │ ├── repository/ # 用户特定的数据访问层
│ │ │ └── models/ # 用户模型
│ │ ├── go.mod # 用户服务Go模块定义
│ │ └── go.sum # 用户服务Go模块校验和文件
│ └── product-service/ # 商品服务
│ ├── cmd/ # 商品服务的命令
│ ├── internal/ # 商品服务的内部代码
│ └── go.mod # 商品服务Go模块定义
├── libs/ # 多个服务共享的库
│ ├── logging/ # 日志库
│ ├── authentication/ # 认证库
│ └── utils/ # 实用工具
├── go.mod # 顶层的Go模块定义
└── go.sum # 顶层的Go模块校验和文件特点:
- 多个服务: 每个服务（例如
user-service，product-service）各自独立且自包含，但它们都在同一个仓库里。 - 共享库: 常用的工具和库（如日志记录和认证）可以组织在
libs/目录下，以便在不同服务中重用。 - 共享模块: 项目可以有一个顶层
go.mod文件用于单代码库，或者每个服务都有自己的go.mod文件，这取决于所需的模块化需求。 - 代码共享和一致性: 鼓励在多个服务间共享代码并保持一致性，减少重复并确保标准化。
应用场景:
- 大型组织: 适合大型组织，多个团队各自负责独立的服务，同时需要共享库和统一的实践。
- 微服务架构: 特别适合处理微服务架构或多服务系统的场景，因为它简化了单一仓库内的协作和协调。
在CQRS（一种命令查询职责隔离的架构）中，命令和查询操作被组织成单独的模型。命令负责改变状态（例如，创建或更新数据），而查询则专注于读取数据。这种结构有助于在处理请求时分离职责。
项目/
├── cmd/
│ └── app/
│ └── main.go # 主程序逻辑
├── internal/ # 内部模块
│ ├── commands/ # 命令（变更状态）
│ │ ├── create_user.go # 创建用户的命令
│ │ ├── update_user.go # 更新用户的命令
│ │ └── delete_user.go # 删除用户的命令
│ ├── queries/ # 查询（读取）
│ │ └── get_user.go # 获取用户数据查询
│ ├── repositories/ # 数据仓库
│ │ └── user_repo.go # 用户仓库
│ ├── models/ # 领域模型
│ │ └── user.go # 用户领域模型
│ └── services/ # 业务处理逻辑
│ └── user_service.go # 用户业务逻辑
├── configs/ # 配置文件
├── go.mod # Go 模块
└── go.sum # Go 校验和文件以下是一些特点:
- 职责分离: 命令和查询各自独立，这样可以简化代码库的扩展和维护。
- 可扩展架构: 这种结构特别适合需要分别优化读写操作的应用程序，非常适合大规模系统。
- 解耦: 明确区分命令和查询的处理逻辑，使这两种操作更容易管理。
示例:
- 读写分离的需求: 最适合需要分别管理读取和写入操作的应用程序，特别是在事件驱动架构或高性能应用中。
- 事件溯源和一致性: 对于需要事件溯源或有复杂数据一致性要求的系统来说非常有用，可以更清楚地跟踪状态变更。
洋葱式架构通过将代码组织成围绕核心的同心圆（或层）来强调分离关注点。最内层是业务逻辑和领域模型的所在地，而外层则是外部依赖的所在，比如框架、用户界面和数据库。
项目根目录/
├── cmd/
│ └── your-app/
│ └── main.go # 应用入口
├── internal/
│ ├── 领域/
│ │ ├── entity.go # 领域实体
│ │ └── service.go # 领域服务
│ ├── 应用/
│ │ ├── usecase.go # 与领域交互的用例
│ └── 基础设施/
│ ├── 持久化/
│ │ ├── repository.go # 仓库
│ ├── api/
│ │ └── handler.go # HTTP处理程序
│ └── ... # 其他基础设施（消息代理等）
├── pkg/
│ └── 共享/
│ └── 共享代码/ # 项目中的共享代码（辅助函数、工具等）
├── 配置/
│ └── config.yaml
└── go.mod # Go模块文件特色
- 分层式架构: 架构以同心圆形式构建，最内层是核心领域，而外层则是应用接口和基础设施。
- 依赖倒转: 核心领域逻辑与外部框架和技术保持独立，促进了维护和测试的便利性。
- 关注点分离: 每层都有其特定的职责，有助于隔离变化并减少负面影响。
- 专注于业务逻辑: 核心业务逻辑位于中心位置，使得应用程序可以演化而不影响外部的依赖项。
- 可测试性: 由于核心逻辑与基础设施相互独立，更容易为领域和应用层编写单元测试，从而提高测试效率。
应用场景:
- 复杂的业务领域: 适合具有复杂业务规则且需要职责分明的应用程序。
- 长期项目: 适合那些预计会随时间发展的项目，让开发人员可以轻松适应业务需求的变化，而无需大幅重写代码。
- 职责分明的团队: 当不同团队分别负责应用程序的不同层次（如业务逻辑与基础设施）时，表现优秀。
常见的结构适用于更简单项目或场景，在这种情况下，更侧重于开发速度和易于理解，而非严格的架构指导原则。虽然它提供了灵活性，但长期来看可能导致代码维护难度增加。
项目/
├── cmd/ # 该项目的主要应用
│ └── myapp/ # myapp 目录
│ └── main.go # 应用入口点
├── internal/ # 私有应用和库代码
│ ├── app/ # 应用特定代码
│ │ └── myapp/ # 专用于 myapp 的应用代码
│ │ ├── handler.go # HTTP 处理程序
│ │ └── service.go # 业务处理
│ ├── pkg/ # 共享内部代码（内部库）
│ │ └── myprivlib/ # 内部使用的共享库
│ ├── domain/ # 领域模型和服务
│ │ ├── entity.go # 领域模型
│ │ └── service.go # 领域服务
│ └── infrastructure/ # 外部基础设施代码
│ ├── persistence/ # 数据库交互
│ │ └── repository.go # 数据库交互
│ ├── api/ # Web API 层
│ │ └── handler.go # API 处理
│ └── messaging/ # 消息系统（例如 Kafka）
│ └── producer.go # 消息生成器
├── pkg/ # 外部使用的库代码
│ └── mypubliclib/ # 供外部使用的公共库代码
├── vendor/ # 应用程序依赖
├── api/ # OpenAPI/Swagger 规范、JSON 模式文件
│ └── api_spec.yaml # API 规范文件
├── web/ # Web 应用组件
│ ├── static/ # 静态资源（CSS、JS）
│ └── templates/ # 服务器端模板
├── configs/ # 配置文件
│ └── config.yaml # 默认配置
├── init/ # 系统初始化
│ └── myapp.service # systemd 服务文件
├── scripts/ # 构建、安装、分析脚本
│ ├── build.sh # 构建脚本
│ └── install.sh # 安装脚本
├── build/ # 打包和 CI 配置
│ ├── package/ # 打包配置（Docker、AMI 等）
│ └── ci/ # 持续集成配置（Travis、CircleCI）
├── deployments/ # 部署配置和模板
│ └── kubernetes/ # Kubernetes 部署
├── test/ # 测试数据集
│ └── data/ # 测试数据
├── docs/ # 设计和用户文档
│ └── architecture.md # 项目架构文档
├── tools/ # 辅助工具
│ └── mytool/ # 示例工具
├── examples/ # 应用程序和库的示例
│ └── example_usage.go # 公共库代码的示例使用
├── third_party/ # 工具和实用程序
├── githooks/ # Git 钩子
├── assets/ # 其他资源（图像、徽标）
├── website/ # 项目网站数据
│ └── index.html # 项目首页
├── go.mod # Go 模块文件
└── go.sum # Go 模块依赖文件特色:
- 简洁性： 一种简洁明了的结构，能够组织代码而不引入过度复杂性。
- 单一抽象层： 常见结构可能不像洋葱架构或干净架构那样强制严格的分层，从而导致较少的抽象层次。
- 最小化依赖管理： 较少的依赖管理负担使得新人更容易理解项目结构。
- 灵活的代码组织： 开发人员可以根据项目需求而非严格的架构指南来组织代码，从而允许更具创意的解决方案。
使用案例:
- 小型到中等项目： 适用于较小的应用程序或项目，其中复杂的职责分离可能过于繁琐。
- 快速原型制作： 用于快速迭代想法，无需为严格的架构框架付出额外的努力。
- 单人开发项目： 适合单个开发者，他们更喜欢简单、不太结构化的开发环境来构建应用程序。
- 学习和实验： 适合初学者学习 Go 或那些尝试新想法的人，它允许自由探索，无需过多考虑架构设计。
选择合适的文件夹组织对于项目来说至关重要，这取决于多个因素，包括应用程序的规模和复杂性、团队合作以及未来的维护。理想的结构应符合你的特定需求和偏好，确保它能够促进开发并优化代码的整体组织。
通常从满足当前需求的更简单结构开始是有好处的。随着项目的发展或需求变化，你可以重写以应对新挑战，同时保持代码的清晰和可管理性。
参考资料
随时随地看视频
