合理的 golang web 项目目录结构应根据项目规模选择基础或模块化布局。1. 基础结构适用于中小型项目，包含 cmd（程序入口）、internal（业务逻辑分 handler、service、model）、config（配置管理）、pkg（公共组件）等目录。2. 模块化结构适合大型项目，通过 api（接口定义）、repository（数据访问）、service（业务逻辑）、handler（请求处理）实现分层解耦，提升可维护性。3. 设计建议包括避免 package 名重复、合理使用 internal（项目专用代码）与 pkg（可复用库）、集中管理配置并通过结构体加载、将中间件统一抽离至 middleware 目录并提供注册函数。此外可参考 go-kit、k8s 等优秀开源项目的组织方式，灵活适配项目实际需求。
在 Golang Web 项目中，合理的目录结构不仅能提升项目的可维护性，还能让新成员更容易上手。Go 社区虽然没有官方的强制标准，但经过多年的实践和总结，已经形成了一些被广泛接受的组织方式。下面介绍几种常见的布局方式以及模块划分建议，供你在构建项目时参考。
基础目录结构推荐：简洁清晰
对于中小型项目，一个基础但清晰的目录结构通常包括以下几个部分：
project/ ├── cmd/ │ └── app/ │ └── main.go ├── internal/ │ ├── handler/ │ ├── service/ │ ├── model/ │ └── middleware/ ├── config/ ├── pkg/ ├── go.mod └── README.md
-
cmd/app/main.go是程序入口，负责初始化配置、启动服务等。 -
internal/下存放业务逻辑相关代码，按职责划分为 handler（处理请求）、service（业务逻辑）、model（数据模型）等。 -
config/放置配置文件解析相关的代码或实际的配置文件。 -
pkg/用于存放通用工具函数或封装好的库，供多个项目复用。 - 这种结构简单明了，适合刚起步的项目或者功能相对集中的服务。
模块化结构：适用于大型项目
当项目逐渐变大，依赖关系复杂之后，就需要考虑更清晰的模块划分。可以引入接口抽象、分层设计，甚至使用 Go Modules 来管理子模块。
立即学习“go语言免费学习笔记（深入）”；
例如：
project/ ├── cmd/ │ └── app/ │ └── main.go ├── internal/ │ ├── api/ │ │ ├── v1/ │ │ └── handler.go │ ├── service/ │ │ ├── user_service.go │ │ └── order_service.go │ ├── repository/ │ │ └── user_repo.go │ ├── model/ │ └── middleware/ ├── config/ ├── pkg/ ├── go.mod └── README.md
这种结构强调了分层解耦：
-
api/v1/表示不同版本的 API 接口定义。 -
repository/负责与数据库交互，屏蔽底层实现细节。 -
service/处理具体的业务逻辑，调用 repository 获取数据。 -
handler/只负责接收请求并调用 service，不包含复杂逻辑。
这样做的好处是，当某一层需要更换实现时（比如从 MySQL 切换到 MongoDB），只需修改 repository 层，其他层几乎不需要改动。
目录结构设计的几个实用建议
1. 避免 package 名重复
Go 的包管理机制要求同一个目录下的所有 .go 文件属于同一个 package，因此要注意 package 名不要冲突。例如，在 internal/handler 中，package 应该统一为 handler。
2. 合理使用 internal 和 pkg
-
internal/用于当前项目专用的代码，外部无法导入。 -
pkg/用于公共组件，可以被其他项目引用。
如果你开发的是内部服务，可以多用 internal；如果是开源组件或公司内多个项目共享的代码，放在 pkg 更合适。
3. 配置集中管理
配置建议统一通过结构体加载，并提供默认值。可以使用 viper 或原生 flag + JSON/YAML 配合环境变量来实现。
例如：
type Config struct {
Port int `yaml:"port"`
DB struct {
DSN string `yaml:"dsn"`
} `yaml:"db"`
}4. 中间件单独抽离
如果项目中使用了很多自定义中间件（如日志、认证、限流等），建议统一放在 middleware/ 目录下，并提供注册函数，方便统一管理。
小技巧：参考社区优秀项目
如果你还在纠结目录结构，不妨看看一些成熟的开源项目是如何组织的：
这些项目虽然复杂度不同，但都体现了清晰的分层思想和良好的模块划分方式，值得借鉴。
基本上就这些。目录结构不是一成不变的，关键是要符合当前项目的实际情况。小项目不必一开始就追求“高大上”，大项目则要提前规划好扩展性和维护成本。
