搭建 golang 项目的目录介绍及其用途对比表

news2024/11/27 2:38:55

文章目录

- - 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/：存放日志文件，帮助监控项目运行状态和排查错误。