本文介绍 go 语言中构建 restful api 时推荐的模块化、可维护、符合 go 习惯的项目目录结构，涵盖 models、handlers、routes 等核心包的组织方式，并结合 gorilla/mux 实践示例，避免过度框架化，兼顾简洁性与扩展性。
在 Go 生态中，REST API 项目的结构不应盲目套用 Rails 或 Spring 等传统 MVC 框架的分层模式（如严格分离 controllers、views、helpers），而应遵循 Go 的设计哲学：显式优于隐式、组合优于继承、小而专注的包。由于 Go 是静态编译型语言，且无运行时反射驱动的自动路由发现机制，强行模仿 Rails 的“约定优于配置”反而会导致代码耦合度高、依赖难追踪、测试不直观。
推荐的标准目录结构
以下是一个生产就绪、易于演进的典型结构（基于 cmd/internal/pkg 分层规范）：
myapi/ ├── cmd/ │ └── myapi/ # 主程序入口（main.go） ├── internal/ │ ├── handlers/ # HTTP 处理逻辑（替代传统 "controllers"） │ │ └── user_handler.go │ ├── models/ # 数据模型与业务实体（含数据库映射） │ │ └── user.go │ ├── services/ # 业务逻辑封装（协调 models + 外部依赖） │ │ └── user_service.go │ └── storage/ # 数据访问层（如 SQL、Redis 客户端封装） │ └── pgstore.go ├── pkg/ │ └── middleware/ # 可复用中间件（auth、logging、recovery） ├── routes/ │ └── router.go # 路由注册中心（清晰聚合所有 endpoint） ├── go.mod └── README.md
✅ 关键原则说明： internal/ 下的包仅限本项目使用，禁止外部导入，保障封装性； handlers 不包含业务逻辑，只负责解析请求、调用 services、构造响应； services 是真正的业务中枢，解耦 handler 与 storage，便于单元测试； storage 抽象数据源细节，支持未来无缝切换 PostgreSQL → SQLite → Mock。
示例：用户管理 API 快速实现
以 /users 列表接口为例，展示各层协作：
// internal/models/user.go
package models
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}// internal/services/user_service.go
package services
import (
"myapi/internal/models"
"myapi/internal/storage"
)
type UserService struct {
store storage.UserStorer
}
func NewUserService(store storage.UserStorer) *UserService {
return &UserService{store: store}
}
func (s *UserService) ListUsers() ([]models.User, error) {
return s.store.FindAll()
}// routes/router.go
package routes
import (
"github.com/gorilla/mux"
"myapi/internal/handlers"
)
func NewRouter(userHandler *handlers.UserHandler) *mux.Router {
r := mux.NewRouter()
r.HandleFunc("/users", userHandler.List).Methods("GET")
return r
}// cmd/myapi/main.go
package main
import (
"log"
"net/http"
"myapi/internal/handlers"
"myapi/internal/services"
"myapi/internal/storage"
"myapi/routes"
)
func main() {
db := storage.NewPostgresDB("postgres://...")
userService := services.NewUserService(db)
userHandler := handlers.NewUserHandler(userService)
r := routes.NewRouter(userHandler)
log.Println("Starting server on :8080")
log.Fatal(http.ListenAndServe(":8080", r))
}注意事项与避坑指南
- ❌ 避免将 handler 直接操作 database/sql 或硬编码 SQL —— 这违反关注点分离，导致 handler 难以测试；
- ❌ 不要为每个 model 创建独立的 package（如 usermodel, ordermodel），小项目中统一放 internal/models/ 更清晰；
- ✅ 使用 pkg/ 存放真正跨项目复用的通用组件（如 JWT 工具、HTTP 客户端封装），而非业务逻辑；
- ✅ 路由定义集中于 routes/ 包，便于审计权限、添加中间件或生成 OpenAPI 文档；
- ? 当项目规模扩大时，可按领域（Domain-Driven Design）拆分子模块（如 internal/user/, internal/order/），每个域内含自己的 models/services/handlers。
Go 的力量在于其克制与清晰。一个良好的 REST 项目结构，不是追求“看起来像 Rails”，而是让新人能 5 分钟看懂数据流向，让 CI 能精准运行某一层的单元测试，让重构时只需修改两个包而非全局搜索 Controller。从 internal/handlers 开始，用组合代替继承，用接口定义契约——这才是地道的 Go 方式。
