写Go代码的第一步往往不是写逻辑，而是把项目骨架搭对。不少新手在学完语法后兴致勃勃地建了一堆文件夹，等真正引入依赖、拆分包的时候才发现目录层级混乱，循环引用频发，最后不得不推倒重来。其实Go社区经过多年沉淀，已经形成了一套约定俗成的项目布局规范，理解了这套规范背后的设计意图，初始化一个新项目只需要几分钟。
一、使用go mod初始化项目
从Go 1.11引入module机制开始，GOPATH模式的地位就逐渐弱化了。现在的标准做法是在任意目录下创建项目文件夹，然后执行go mod init命令生成go.mod文件。这个文件是整个项目的身份标识，记录了module名称、Go版本以及所有第三方依赖。
module名称建议使用仓库的完整路径，比如你的代码托管在GitHub上，就用github.com/你的用户名/项目名这样的形式。这样做的好处是别人拉取你的代码后可以直接编译，同时这个名称也是包导入路径的前缀，直接决定了import语句怎么写。
mkdir myapp && cd myapp go mod init github.com/yourname/myapp
执行完成后目录下会出现一个go.mod文件，内容大致如下。后续通过go get添加依赖时，依赖列表和版本号会自动写入这个文件。值得一提的是，Go 1.16之后go get只负责添加依赖，构建动作交给了go build，初次使用新版本的人容易在这里踩坑。
module github.com/yourname/myapp go 1.21
二、主流的目录布局与各目录职责
Go官方并没有强制规定目录结构，但社区参考了kubernetes、docker等大型开源项目的做法，总结出一份被广泛认可的标准布局。下面是一个典型的中型项目结构，每个目录的职责都值得单独说明。
myapp/ ├── cmd/ │ └── server/ │ └── main.go ├── internal/ │ ├── service/ │ ├── repository/ │ └── config/ ├── pkg/ │ └── utils/ ├── api/ ├── configs/ ├── scripts/ ├── web/ ├── go.mod └── go.sum
cmd目录存放程序的入口。每个子目录对应一个可执行程序，目录名就是编译产物的名字。比如cmd/server对应服务端程序，cmd/cli对应命令行工具。main.go里只做两件事：解析配置和调用internal里的业务逻辑启动程序，不要在main.go里堆积业务代码。
internal目录是Go编译器提供的一个特殊机制，放在这里的包只能被当前module下的代码引用，外部项目无法import。这个限制是语言层面强制的，不是约定。所以核心业务逻辑、数据库访问层、内部封装的工具都应该放在这里，能有效避免被外部项目误依赖。
pkg目录与internal相反，存放的是确定要暴露给外部使用的公共库。如果一个项目是内部项目，没有任何对外复用的需求，可以不建这个目录，全部放进internal即可。盲目地把所有包塞进pkg是新手常见的误解。
其余目录按用途划分：api存放protobuf文件或OpenAPI接口定义，configs存放配置模板文件，scripts存放构建部署脚本，web存放前端静态资源。
三、分层设计与避免循环引用
目录建好后，更关键的问题是包之间的依赖方向。推荐采用自上而下的单向依赖：cmd依赖service，service依赖repository，repository依赖具体的数据库驱动。依赖只能向下，不能向上，同层之间尽量不互相引用。这种分层可以最大化利用internal的隔离特性，也符合六边形架构、整洁架构的核心思想。
循环引用是Go项目中最令人头疼的问题，因为Go编译器严格禁止包之间形成环。假设service包需要用到utils里的函数，同时utils又反过来引用了service中的类型，编译就会直接失败。解决思路通常有两种：把共享的类型下沉到更底层的包，或者通过接口在调用方定义依赖，让被依赖方反过来实现接口，也就是常说的依赖倒置。
下面用一个简单的例子演示分层调用。配置加载、业务逻辑、入口分离，各自可独立测试：
package main
import (
"fmt"
"github.com/yourname/myapp/internal/config"
"github.com/yourname/myapp/internal/service"
)
func main() {
cfg, err := config.Load("configs/app.yaml")
if err != nil {
panic(err)
}
svc := service.New(cfg)
fmt.Println(svc.Run())
}编译时进入cmd/server目录执行go build，或者直接在项目根目录执行go build ./cmd/server，生成的二进制文件即可独立部署。为了方便日常工作，建议在项目根目录放一个Makefile，把build、test、lint等命令固化下来，团队成员一条命令就能完成构建。
四、小项目要不要遵守这套结构
上述结构对于几百行的小工具来说确实偏重。如果你的项目只是一个脚本或单一二进制程序，完全可以在根目录放一个main.go，配合go.mod就够用了，没必要为了结构而结构。Go的设计哲学一直强调简单直接，目录结构服务于项目复杂度，而不是反过来。
一个实用的判断标准是：当你发现单文件超过五百行，或者开始有第二个可执行入口、出现需要隔离的内部逻辑时，就应该引入cmd和internal目录了。早期的扁平结构随时可以平滑迁移到标准布局，因为module路径没有变化，import语句只需批量调整前缀。总之，先跑起来，再逐步演进，这本身也是Go社区推崇的工程节奏。
Golang项目结构Go moduleGo项目初始化修改时间：2026-09-06 02:52:34