本文解析 go 语言中应用程序（application）与可复用包（package/library）在目录结构设计上的本质区别，阐明 gopath 时代与现代 go modules 下的实践演进，并提供清晰、符合工程规范的结构建议。
本文解析 go 语言中应用程序（application）与可复用包（package/library）在目录结构设计上的本质区别，阐明 gopath 时代与现代 go modules 下的实践演进，并提供清晰、符合工程规范的结构建议。
Go 语言的项目结构并非由语法强制约束，而是由工具链、发布意图和工程可维护性共同塑造。关键在于区分两类项目目标：可执行的应用程序（application） 与 供他人导入的可复用包（library/package）。
应用 vs 包：结构逻辑的根本差异
-
应用程序（如 myapp）：核心是单一入口（main.go），职责是组合多个内部包完成业务逻辑。其目录结构应服务于团队协作与功能分层，常见模式包括：
myproject/ ├── cmd/ # 主程序入口（如 ./cmd/myapp/main.go） ├── internal/ # 仅本项目使用的私有包（不可被外部 import） │ ├── handler/ │ ├── service/ │ └── repository/ ├── pkg/ # 可被外部引用的公共包（如有需要） ├── model/ # 数据模型定义（通常属 internal 或 pkg） ├── go.mod # Go Modules 根文件（现代标准） └── main.go # （或置于 cmd/ 下）
所有子目录对应独立 Go 包（如 myproject/internal/handler），包名与目录名一致，且同一目录下所有 .go 文件必须声明相同 package 名。
-
可复用包（如 sqlx）：目标是作为第三方依赖被 import 使用，因此需扁平化、无冗余路径——根目录即包根，import "github.com/jmoiron/sqlx" 直接映射到仓库根。添加多余嵌套（如 src/github.com/jmoiron/sqlx/sqlx/）反而破坏 Go 的导入语义。
立即学习“go语言免费学习笔记（深入）”；
关于依赖管理：告别 GOPATH/src 手动组织
你最初采用的 src/example.co/my_app/ 结构，源于早期 GOPATH 模式（go get 自动下载至 $GOPATH/src）。但自 Go 1.11 引入 Modules 后，推荐彻底弃用 GOPATH 依赖管理：
✅ 正确做法（Go 1.11+）：
myproject/ ├── go.mod # 运行 `go mod init example.co/myproject` ├── go.sum ├── cmd/ │ └── myapp/ │ └── main.go # package main ├── internal/ │ ├── model/ │ │ └── user.go # package model │ └── service/ │ └── processor.go # package service └── vendor/ # （可选）运行 `go mod vendor` 生成
go.mod 自动生成依赖声明：
module example.co/myproject
go 1.21
require (
github.com/jmoiron/sqlx v1.3.5
)导入时直接使用模块路径：
// cmd/myapp/main.go
package main
import (
"example.co/myproject/internal/service"
"github.com/jmoiron/sqlx"
)
func main() {
db := sqlx.Connect(...) // 使用第三方包
svc := service.New(...) // 使用本地包
}重要注意事项
- ❌ 避免手动维护 src/ 目录树：go get 已废弃，go mod 自动处理依赖位置。
- ❌ 不要将自己项目硬塞进 $GOPATH/src：Modules 模式下，项目可位于任意路径，只需包含 go.mod。
- ✅ internal/ 是 Go 官方支持的封装机制：internal/xxx 下的包仅允许被同一模块内代码导入，天然实现访问控制。
- ✅ vendor/ 非必需：仅当需锁定精确依赖版本或离线构建时，执行 go mod vendor。
总结而言，结构选择不是风格偏好，而是工程意图的体现：应用重组织、包重简洁；Modules 时代，以 go.mod 为枢纽，目录即包，路径即导入路径——回归 Go “少即是多”的设计哲学。
