17370845950

Go项目包结构应以职责清晰、边界明确、导入安全为核心，善用internal（隔离私有逻辑）、cmd（分离可执行入口）、pkg（提供稳定公共组件）三个目录，配合小写单一名词命名与单一职责原则。

Go项目包结构不是越深越好，而是要让职责清晰、边界明确、导入安全。核心是用好 internal、cmd 和 pkg 这三个关键目录，再配合小写命名与单一职责原则。

用 internal 隔离私有逻辑

所有不希望被外部项目直接 import 的业务代码，必须放在 internal/ 下。Go 编译器会强制检查：任何在 internal/ 外的模块都无法导入其子路径。

• internal/service 放核心业务流程，比如订单创建、库存扣减
• internal/repository 只负责数据读写，不包含业务判断
• internal/handler 仅做请求解析和响应包装，不写业务逻辑

用 cmd 分离可执行入口

每个二进制文件（如 API 服务、定时任务、CLI 工具）应有独立的 cmd/ 目录，里面只放 main.go。

• 避免把 main.go 放在项目根目录——那样会让整个 internal 逻辑无法被其他命令复用
• 不同命令可共享同一套 internal 逻辑，比如 cmd/api 和 cmd/cli 都调用 internal/service
• main 函数里只做初始化和启动，不写任何业务分支

用 pkg 提供可复用组件

pkg/ 是唯一允许被外部项目 import 的公共模块区，必须满足“稳定、无副作用、低耦合”。

• 命名用单个小写名词：pkg/httpx、pkg/uuid、pkg/validate
• 不依赖 internal 或 cmd，只引入标准库或第三方基础包
• 接口定义优先放在 pkg，实现放在 internal，方便 mock 和替换

包命名与组织细节

每个包名都是一个语义单元，不是目录路径的缩写。

• 全小写，不用下划线或驼峰：user ✅，user_service ❌，userService ❌
• 一个包只做一件事：比如 user 包处理用户实体和基础操作，userauth 单独处理登录鉴权
• 避免循环依赖：用接口解耦，service 定义接口，repository 实现它，反过来不能依赖

基本上就这些。结构不是一成不变的模板，而是随着业务演进而微调的协作契约。