本文介绍 go 语言中构建 rest api 时推荐的模块化目录结构，强调符合 go 语言哲学的简洁性、可测试性与可维护性，避免过度模仿 rails 等框架的 mvc 模式，提供清晰的分层设计与实用示例。
在 Go 生态中，REST API 项目的结构不应盲目套用 Ruby on Rails 的经典 MVC 分层（如 app/controllers/ + app/models/），而应遵循 Go 的核心原则：显式优于隐式、组合优于继承、小而专注的包。Go 编译为静态二进制文件，不支持运行时反射驱动的自动路由发现或约定式配置，因此“魔力越少，可控性越强”。
推荐结构（轻量级、生产就绪）
以下是一个经过验证的、适用于中小型 REST API 的典型布局：
myapi/ ├── cmd/ │ └── myapi/ # 主程序入口（main.go） ├── internal/ │ ├── handler/ # HTTP 处理器：绑定路由、解析请求、调用 service │ ├── service/ # 业务逻辑层：协调 domain 操作，处理用例（如 CreateOrder） │ ├── domain/ # 领域模型与接口：纯 Go 结构体 + 方法，不含框架依赖 │ └── storage/ # 数据访问层：DB/Cache 客户端封装，实现 domain.Repository 接口 ├── pkg/ # 可复用的通用工具包（如 logger, middleware, validator） ├── migrations/ # 数据库迁移脚本（如 Goose 或 golang-migrate） ├── go.mod └── README.md
✅ 关键设计思想： internal/ 下各子包职责单一、依赖单向（handler → service → domain → storage）； domain/ 包定义核心业务实体和接口（如 User, UserRepository），是整个应用的稳定内核； 所有外部依赖（HTTP 框架、数据库驱动）仅出现在最外层（handler 和 storage），便于单元测试（可通过 mock 实现零依赖测试）。
示例：用户注册 Handler 与 Service 协作
// internal/domain/user.go
type User struct {
ID int64 `json:"id"`
Email string `json:"email"`
}
type UserRepository interface {
Create(u *User) error
FindByEmail(email string) (*User, error)
}
// internal/service/user_service.go
type UserService struct {
repo domain.UserRepository
}
func NewUserService(repo domain.UserRepository) *UserService {
return &UserService{repo: repo}
}
func (s *UserService) Register(email string) (*domain.User, error) {
if email == "" {
return nil, errors.New("email required")
}
u := &domain.User{Email: email}
if err := s.repo.Create(u); err != nil {
return nil, fmt.Errorf("failed to create user: %w", err)
}
return u, nil
}
// internal/handler/user_handler.go
func (h *Handler) RegisterUser(w http.ResponseWriter, r *http.Request) {
var req struct{ Email string }
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "invalid JSON", http.StatusBadRequest)
return
}
user, err := h.userService.Register(req.Email)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"user_id": user.ID})
}路由配置：使用 Gorilla Mux（轻量可靠）
// cmd/myapi/main.go
func main() {
db := setupDB() // 初始化 DB 连接
repo := storage.NewUserRepo(db)
svc := service.NewUserService(repo)
handler := &handler.Handler{userService: svc}
r := mux.NewRouter()
r.HandleFunc("/users", handler.RegisterUser).Methods("POST")
log.Fatal(http.ListenAndServe(":8080", r))
}注意事项与避坑指南
- ❌ 避免将 models/ 直接暴露为顶层包（如 models.User），易导致循环依赖和框架污染；应置于 internal/domain/ 并通过接口抽象数据访问。
- ❌ 不要过早引入全栈框架（如 Revel）。它虽提供 Rails 式体验，但会牺牲 Go 的简洁性与可调试性，且社区活跃度与生态成熟度远不及标准库 + Gorilla/Chi 组合。
- ✅ 优先使用 net/http + gorilla/mux 或 chi：轻量、稳定、文档完善、中间件生态丰富。
- ✅ 所有 internal/ 包禁止被外部 module 导入，天然保障封装性（Go 1.4+ internal 机制强制约束）。
- ✅ 将配置、日志、错误处理等横切关注点统一抽离至 pkg/，确保业务代码专注领域逻辑。
总结而言，Go 的 REST 项目结构不是关于“有多少层”，而是关于“每一层是否清晰表达其契约”。从 domain 出发定义业务本质，再逐层向外适配技术细节——这种正向依赖、面向接口的设计，才是 Go 项目长期可演进、可测试、可协作的根本保障。
