本文介绍go语言构建rest api时简洁、可维护、符合go生态惯例的项目目录结构，强调面向包的设计思想，避免过度模仿rails等框架的mvc分层，结合标准库与轻量路由工具（如net/http + gorilla/mux）实现清晰职责分离。
在Go语言中，良好的项目结构并非追求“框架式”的严格分层（如controllers/、views/、helpers/），而是围绕领域职责和编译单元（package） 进行组织——每个包应具备高内聚、低耦合、单一职责，并能被独立测试与复用。以下是一个经过生产验证、兼顾可扩展性与Go惯用法的REST API基础结构：
myapi/ ├── cmd/ │ └── myapi/ # 主程序入口（仅含main.go） ├── internal/ │ ├── handler/ # HTTP处理器：封装业务逻辑调用，处理请求/响应 │ ├── service/ # 业务服务层：定义核心用例（Use Cases），协调领域对象 │ ├── repository/ # 数据访问层：抽象数据操作（如UserRepo），具体实现可位于internal/db/ │ └── model/ # 领域模型：纯Go结构体（如User, Order），不含业务逻辑 ├── pkg/ │ └── middleware/ # 可复用中间件（如JWT验证、日志、CORS） ├── db/ # 数据库迁移、连接池初始化（如migrate、sqlx配置） ├── api/ # OpenAPI/Swagger定义（可选，便于文档与客户端生成） ├── go.mod └── main.go
✅ 关键设计原则说明：
- cmd/ 下仅保留启动逻辑，确保main包极简，便于多二进制构建（如同时提供API服务与CLI工具）；
- internal/ 包含所有业务专属代码，其子包按功能而非MVC角色划分（例如handler不叫controller，因Go中无“控制器”抽象概念）；
- model 中的结构体应为POGO（Plain Old Go Object），避免嵌入json标签或数据库驱动相关字段（这些应在handler或repository中转换）；
- 路由注册建议集中于cmd/myapi/main.go或internal/handler/router.go中，使用 gorilla/mux 或 chi 等轻量路由器，示例：
// internal/handler/router.go
func NewRouter(h *Handler) *mux.Router {
r := mux.NewRouter()
r.Use(loggingMiddleware, recoveryMiddleware)
// 用户相关路由
userRouter := r.PathPrefix("/api/v1/users").Subrouter()
userRouter.HandleFunc("", h.CreateUser).Methods("POST")
userRouter.HandleFunc("/{id}", h.GetUser).Methods("GET")
userRouter.HandleFunc("/{id}", h.UpdateUser).Methods("PUT")
return r
}⚠️ 注意事项：
- 避免在model中直接使用gorm.Model或sqlx.DB等外部依赖，保持领域模型纯净；
- 不要为“一致性”而强行拆分过细的包（如internal/handler/user/, internal/handler/product/），除非规模显著增长且职责明确隔离；
- 若项目演进为大型系统，可引入领域驱动设计（DDD）分层（domain/application/infrastructure），但切忌过早抽象；
- 框架选择上，优先使用标准库 net/http + 社区成熟中间件（如 gorilla/mux, chi, sirupsen/logrus），而非全栈框架（如Revel）——后者易带来学习成本与灵活性折损。
总结而言，Go项目的结构本质是服务于可维护性与团队协作，而非遵循教条。从一个清晰的internal/handler + internal/service + internal/repository三层开始，随着业务复杂度自然演进，比一开始就套用Rails式结构更符合Go的哲学：“Less is more. Clear is better.”
立即学习“go语言免费学习笔记（深入）”；
