Go项目结构与代码组织

Go项目遵循标准结构约定，利于团队协作和代码维护。

标准项目结构

基本布局

myproject/
├── cmd/                # 主程序入口
│   └── server/
│       └── main.go
├── internal/           # 内部代码（外部不可导入）
│   ├── handler/
│   ├── service/
│   └── model/
├── pkg/                # 公开代码（可被外部导入）
│   ├── utils/
│   └── common/
├── api/                # API协议定义
│   └ proto/
├── configs/            # 配置文件
├── docs/               # 文档
├── scripts/            # 脚本文件
├── test/               # 测试数据和辅助文件
├── go.mod
└── go.sum

目录详解

cmd目录

// 存放应用程序入口
// 每个子目录代表一个可执行程序

cmd/
├── server/          # 服务端程序
│   └── main.go
├── client/          # 客户端程序
│   └── main.go
├── cli/             # CLI工具
│   └── main.go

// main.go应简洁，主要调用内部包
package main

import "myproject/internal/server"

func main() {
    server.Run()
}

internal目录

// 私有代码，外部模块无法导入
// Go编译器强制限制

internal/
├── handler/        # HTTP处理器
├── service/        # 业务逻辑
├── repository/     # 数据访问
├── model/          # 数据模型
├── config/         # 配置加载

// 其他项目导入internal会编译错误
import "github.com/user/project/internal/xxx"
// 错误：use of internal package not allowed

internal保证代码私有，防止外部依赖内部实现。

pkg目录

// 可被外部导入的公开代码
// 如工具库、公共组件

pkg/
├── utils/          # 工具函数
├── logger/         # 日志组件
├── validator/      # 验证器
├── crypto/         # 加密工具

// 外部可导入
import "github.com/user/project/pkg/utils"

api目录

// API定义和协议文件

api/
├── proto/          # Protobuf定义
│   └ user.proto
├── openapi/        # OpenAPI/Swagger定义
│   └ swagger.yaml

// 与前端或其他服务共享

目录选择原则

简单项目结构

// 小项目可简化结构
simple-app/
├── main.go        # 主程序
├── handler.go     # 处理器
├── model.go       # 模型
├── go.mod
└── go.sum

// 无需过度结构化

命名规范

包命名

// 包名：简短、有意义、小写
package handler    // ✓
package http_handler  // ✗ 不用下划线
package httphandler  // ✓

// 不使用通用名
package utils      // ✗ 太通用
package util       // ✗ 太通用
package common     // ✗ 太通用

// 使用具体名
package httputil   // ✓
package stringutil // ✓

文件命名

// 文件名：小写、下划线分隔
handler.go         // ✓
user_handler.go    // ✓
userHandler.go     // ✗ 不用驼峰

// 测试文件
handler_test.go    // 单元测试
handler_integration_test.go // 集成测试

项目组织原则

单一职责

// 每个包职责清晰
internal/
├── user/           # 用户相关
│   ├── handler.go
│   ├── service.go
│   └── repository.go
├── order/          # 订单相关
│   ├── handler.go
│   ├── service.go

// 不混放无关代码

分层架构

// 推荐分层结构
// Handler → Service → Repository → Model

handler/     # HTTP层（接收请求）
service/     # 业务层（处理逻辑）
repository/  # 数据层（访问数据）
model/       # 模型层（数据定义）

项目结构示例

github.com/myorg/myapp/
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   ├── handler/
│   │   └── user.go
│   ├── service/
│   │   └── user.go
│   ├── repository/
│   │   └── user.go
│   └ model/
│   │   └ user.go
│   └ config/
│   │   └ config.go
├── pkg/
│   └ response/
│   │   └ response.go
├── api/
│   └ proto/
│       └ user.proto
├── configs/
│   └ config.yaml
├── go.mod
└── go.sum

要点总结

• cmd存放主程序入口
• internal存放私有代码，外部不可导入
• pkg存放公开代码，可被外部导入
• api存放协议定义和接口规范
• 包名简短、小写、有意义
• 文件名小写，用下划线分隔
• 遵循单一职责和分层架构
• 小项目可简化，避免过度设计
• 标准结构利于团队协作和维护