文章目录
- 1.目录细则表
- 2.目录使用说明及典型内容
- 2.例 K8S 源码目录编排
1.目录细则表
常见 Go 项目目录的作用、典型内容、文件类型和使用场景~
| 目录名 | 作用/用途 | 常见文件类型 | 使用场景及详细说明 | 典型内容举例 |
|---|---|---|---|---|
cmd/ | 存放可执行文件的入口点，通常为项目主程序入口或工具的 main.go 文件。 | main.go, 配置文件（如 .yaml） | 每个子目录下对应一个独立的可执行程序。适合构建多个 CLI 工具或服务器。 | cmd/app/main.go：应用主入口，调用业务逻辑、启动服务等。 |
pkg/ | 公共库代码，复用性强，可以被项目内外导入。 | .go 文件，库代码 | 用于编写高复用度的库，供其他模块或项目使用。这个目录代表项目对外暴露的 API。 | pkg/utils/：常用工具函数库，如字符串处理、时间格式化等。 |
internal/ | 项目内部使用的私有库代码，外部项目无法导入，保持封装性和安全性。 | .go 文件，私有库代码 | 用于实现内部逻辑，防止外部依赖，确保模块内部实现的可维护性。 | internal/auth/：用户认证相关的内部逻辑，不暴露给外部模块。 |
api/ | 定义与实现 API 相关的接口文件，如 gRPC、RESTful 接口、Swagger 定义等。 | .proto, .json, .yaml | 用于存放接口定义文件、协议文件或自动生成的代码，特别是面向服务或微服务架构。 | api/v1/service.proto：gRPC 服务定义，包含消息结构和服务方法。 |
configs/ | 配置文件目录，项目启动时加载的静态配置，如数据库连接、日志配置等。 | .yaml, .json, .toml, .env | 存放不同环境的配置文件，供开发、测试和生产环境使用。 | configs/app.yaml：应用程序的配置文件，包含端口、环境变量等。 |
scripts/ | 自动化脚本目录，通常用于构建、测试、部署等任务。 | .sh, .bat, .ps1, .py | 自动化操作脚本，简化常见任务如构建、CI/CD 流程等。 | scripts/deploy.sh：部署脚本，用于在服务器上自动化部署项目。 |
test/ | 集成测试或端到端测试的目录，测试多个组件的集成效果。 | _test.go, 配置文件 | 对外部依赖或多模块的功能进行整体测试。通常用于验证项目的整体功能是否正确。 | test/integration_test.go：集成测试，验证多个服务或模块间的交互。 |
vendor/ | 存放项目的本地依赖库，主要在不使用 Go Modules 时用于本地化第三方依赖。 | 第三方库代码 | 当无法依赖外部的包管理系统时，将第三方库存放于此，确保项目的依赖可控性。 | vendor/github.com/some-library/：本地化的外部依赖库代码。 |
docs/ | 项目文档目录，存放用户指南、开发文档、设计文档、架构图等。 | .md, .pdf, .html | 帮助开发者或用户理解项目的结构和使用方法，通常包括项目的使用手册和设计文档。 | docs/architecture.md：项目的架构设计文档，解释模块如何协同工作。 |
build/ | 存放构建相关的文件和输出结果，如二进制文件、Dockerfile 等。 | 构建脚本，配置文件，二进制文件 | 项目构建输出目录，用于存放编译好的文件，或用于 CI/CD 的配置文件。 | build/Dockerfile：Docker 镜像的构建文件，用于创建容器化的应用程序。 |
assets/ | 存放静态资源文件，如图片、CSS、JavaScript、HTML 模板等。 | .html, .css, .js, 图片文件 | 用于 Web 项目，存放静态文件或资源，前后端分离项目的前端资源通常放在此目录。 | assets/index.html：前端 HTML 模板，供后端渲染和返回给浏览器使用。 |
bin/ | 存放编译后的二进制可执行文件。 | 编译好的二进制文件 | 项目编译后的输出，供开发者直接执行，通常会包含生成的命令行工具或服务器程序。 | bin/app：项目编译后的可执行文件，包含了整个应用的逻辑。 |
examples/ | 提供项目的示例代码，演示如何使用库或接口，帮助用户快速上手。 | 示例代码，文档 | 向用户展示如何使用项目的 API 或库，通常是简化版的代码片段或完整示例。 | examples/demo.go：项目使用示例，展示如何使用库进行开发。 |
third_party/ | 存放第三方工具或依赖库的自定义版本，便于项目集成。 | 第三方库或工具 | 项目自定义版本的外部依赖或工具，通常是未通过标准包管理工具获得的第三方代码。 | third_party/custom-library/：自定义版本的第三方库或工具。 |
web/ | 存放 Web 项目相关的前端文件，如 HTML 模板、静态资源等。 | .html, .css, .js, 图片文件 | Web 应用的前端资源目录，供后端渲染或静态文件服务器使用。 | web/index.html：Web 项目的首页文件，供浏览器直接访问。 |
tmp/ | 临时文件目录，存放运行时或临时生成的文件。 | 临时文件 | 在项目运行过程中产生的临时文件，不需要永久保存，可以被定期清理。 | tmp/cache/：运行时生成的缓存文件，通常会在程序结束时删除。 |
log/ | 存放项目运行时生成的日志文件。 | .log 文件 | 用于记录项目运行过程中的日志信息，帮助开发者调试和监控系统状态。 | log/app.log：项目的运行日志文件，记录请求和错误等信息。 |
2.目录使用说明及典型内容
cmd/：适合存放项目的可执行文件的入口点，尤其是当一个项目有多个 CLI 工具或服务器时，可以为每个工具创建独立的子目录。pkg/：这个目录常用来放置公共库代码，设计成可以被其他项目或库导入复用，尽量避免直接将业务逻辑暴露在pkg/中。internal/：存放项目的内部实现，外部项目无法导入它。适合存放核心业务逻辑和实现细节，保证这些逻辑的封装性和独立性。api/：用于存放 API 的定义文件，如 gRPC 的.proto文件或 REST API 的 Swagger 定义文件。适合大型微服务架构或接口设计。configs/：可以存放各类环境的配置文件，例如开发、测试、生产等，并且通过环境变量动态切换配置。scripts/：自动化运维脚本，通常用于构建、部署、运行项目时的自动化任务。test/：区别于单元测试，这里用于存放集成测试、端到端测试或性能测试，确保项目的多个组件在真实环境中可以正常运行。vendor/：尽管 Go modules 已经广泛使用，但当需要强制将依赖库内置时，可以使用vendor/。docs/：存放开发者文档、API 文档等，帮助新加入的开发者或用户更好地理解项目。build/：存放构建相关的文件，特别是 CI/CD 配置文件或构建输出，通常与项目的构建过程相关联。assets/：Web 项目必备的目录，用于存放静态资源如 HTML、CSS、JS 等前端文件。bin/：存放项目编译后的二进制文件，供直接部署或分发使用。examples/：向用户展示项目的使用方法，提供代码示例帮助用户快速上手。third_party/：集成第三方库或工具时，如果需要做定制修改或扩展，可以将它们放在此目录下。web/：存放 Web 项目的静态文件，适合前后端分离的项目。tmp/：临时文件目录，存放短期生成的中间文件或缓存，通常会在任务结束时清理。log/：存放日志文件，帮助监控项目运行状态和排查错误。
2.例 K8S 源码目录编排
