核心目录结构

相关源文件

• README.md
• README_it.md
• README_ua.md

本文档概述了标准 Go 项目布局中最重要的一些目录。这些核心目录构成了结构良好的 Go 应用程序的骨干，确保了关注点分离得当以及不同组件之间清晰的可见性边界。

有关特定核心目录的更详细信息，请参阅

• 命令目录 (/cmd)
• 内部目录 (/internal)
• 包目录 (/pkg)

有关其他支持目录的信息，请参阅接口目录和支持目录。

核心目录概览

标准 Go 项目布局定义了三个核心目录，它们构成了推荐结构的基础。

1. /cmd - 包含应用程序入口点（main 包）
2. /internal - 包含不应被外部项目导入的私有应用程序代码
3. /pkg - 包含可以被外部项目安全导入的公共库代码

这三个目录根据代码的预期用途和可见性，为不同类型的代码创建了清晰的组织边界。

核心目录结构可视化

来源：README.md58-88

代码可见性和导入边界

核心目录结构的一个关键方面是它如何为代码库的不同部分建立清晰的导入边界。

来源：README.md58-89

/cmd 目录

/cmd 目录包含您项目的主要应用程序。/cmd 中的每个子目录对应一个您想要构建的可执行文件。

主要特性

• 每个子目录的名称应与可执行文件的名称匹配（例如，/cmd/myapp）
• 包含最少的代码，通常只有一个小的 main 函数
• 导入并调用 /internal 和 /pkg 目录中的代码
• 应用程序特定的逻辑不应放在此处

示例结构

/cmd
  /myapp
    main.go
  /cli
    main.go

来源：README.md58-68

/internal 目录

/internal 目录包含不应被其他项目导入的私有应用程序和库代码。这种私有性由 Go 编译器本身强制执行。

主要特性

• 包含特定于您的应用程序的代码，不用于其他地方的重用
• Go 编译器阻止外部代码导入 internal 目录下的包
• 可以在项目树的任何级别拥有多个 internal 目录
• 可以结构化为 /internal/app 用于应用程序特定代码，/internal/pkg 用于共享的私有库

示例结构

/internal
  /app
    /myapp
      app.go
      handler.go
  /pkg
    /database
      db.go
    /config
      config.go

来源：README.md70-76

/pkg 目录

/pkg 目录包含可供外部应用程序安全使用的库代码。这是您明确希望提供给其他项目导入的代码。

主要特性

• 包含可重用的、面向公众的库
• 应保持稳定且文档齐全，因为其他人将依赖它
• 向用户表明代码 intended for public consumption
• 当您的根目录包含许多非 Go 组件时很有用
• 可选，但对于大型项目或提供库供他人使用时很有用

示例结构

/pkg
  /api
    client.go
  /utils
    helpers.go

来源：README.md78-88

核心目录之间的导入流程

三个核心目录以特定方式相互作用，创建清晰的依赖流程。

来源：README.md58-89

核心目录的典型模式

目录	主要目的	导入约束	何时使用
/cmd	应用程序入口点	可以从 /internal 和 /pkg 导入	当您需要可执行文件时
/internal	私有应用程序代码	不能被外部项目导入	用于应用程序特定的代码
/pkg	公共库代码	可以被任何项目导入	用于可重用的公共库

来源：README.md58-89

最佳实践

何时使用每个目录

• /cmd: 用于主要的应用程序入口点、命令行工具或多个可执行文件
• /internal: 用于应用程序特定的代码、私有实用程序和实现细节
• /pkg: 用于 intended for import by other projects、稳定库和公共 API 的代码

项目规模考虑

对于较小的项目

• 您可能不需要所有三个目录
• 从简单的结构开始，根据需要进行扩展
• 对于非常小的应用程序，根目录中的单个 main.go 可能就足够了
• 当您需要组织私有代码时，添加 /internal
• 当提供供外部使用的代码时，添加 /pkg

来源：README.md30-32 README.md58-89

结论

/cmd、/internal 和 /pkg 的核心目录结构提供了一个组织 Go 代码的基础，这种组织方式能够清晰地传达意图、强制执行适当的代码可见性并促进良好的关注点分离。虽然这并非 Go 团队定义的官方标准，但这种结构已成为 Go 生态系统中的一种常见模式，为 Go 应用程序提供了一个坚实的起点。

这种结构有意设计为灵活的——请根据您的具体需求和项目要求进行调整。请记住，并非所有项目都需要这三个核心目录，尤其是较小的项目。