go项目目录结构无唯一标准但有硬性约束：包路径必须与文件系统路径严格一致，main包不可被导入，internal包禁止外部引用；go.mod须置于模块根目录，禁用src嵌套，包名须与目录名一致，测试文件须与被测代码同目录同包。
Go 项目目录结构没有“唯一标准”，但有明确的约束边界：包路径必须与文件系统路径严格一致，main 包不能被其他包导入，internal 下的包无法被外部模块引用——违反任一条件，编译或运行时就会报错。
go.mod 所在目录就是模块根，别再套 src 目录
很多从 Java 或 Python 转过来的开发者习惯在项目里建 src/，然后把所有 Go 文件塞进去。这会导致：go build 找不到 main 包、go test 不执行任何测试、gopls 报“no packages found”、CI 流水线依赖解析失败。
正确做法是让 go.mod 直接放在项目根目录下，所有源码（包括 main.go）平铺或按功能组织在子目录中：
-
cmd/myapp/main.go→ package main，生成可执行文件myapp -
internal/handler/user.go→ package handler，仅本项目可用 -
pkg/util/stringutil.go→ package util，可被其他项目import - 测试文件必须和被测文件同目录、同包名，如
internal/handler/user_test.go
internal 和 pkg 的权限差异直接影响依赖安全
internal 不是命名约定，而是 Go 编译器硬编码的访问控制机制。只要路径中包含 /internal/，外部模块调用 go build 或 go list 时会直接拒绝导入，哪怕你 push 到 GitHub 也没用。
pkg 则相反：它不带任何语言级保护，只是团队协作的语义提示。如果你把数据库连接池封装在 pkg/db 里并导出，外部项目就能 import "yourdomain.com/pkg/db" —— 这意味着它得有完整文档、向后兼容保证、独立单元测试。
常见误用：
- 把业务核心逻辑（如订单状态机）放在
pkg/order→ 外部项目误引入，导致耦合升级 - 把通用工具函数（如时间格式化）放在
internal/util→ 同一组织内其他项目重复实现 - 在
internal下建internal/api再暴露给前端 → 实际上应通过api/目录放 OpenAPI 定义，而非 Go 包
包名 ≠ 目录名，但不一致会引发维护灾难
Go 允许你在 foo/bar/ 目录下写 package baz，语法上合法，但后果严重：
-
go list ./...会把该目录识别为baz包，而其他地方import "yourmod/foo/bar"却找不到 - IDE（如 VS Code + gopls）频繁刷新失败，跳转定义失效
- 新人看到
import "yourmod/foo/bar"，却在foo/bar/baz.go里看到package qux，第一反应是“代码坏了”
所以务必让包声明与目录名完全一致：
internal/user<br>├── user.go // package user<br>├── repository.go // package user<br>└── service.go // package user
如果某类逻辑确实需要跨多个目录复用（比如错误类型），就单独提成一个包，例如 pkg/errors，而不是在每个 internal/* 下都复制粘贴 err.go。
测试文件必须和源码共存，且不能跨包调用未导出符号
Go 的测试机制设计得很直接：测试文件（*_test.go）和被测文件在同一目录、同一 package，才能访问小写字母开头的函数和变量。这是有意为之的封装边界。
典型错误：
- 把所有测试集中到
test/目录下 →go test ./test找不到被测包，或者被迫写package main_test，结果无法访问main包内部函数 - 在
internal/user/service_test.go中 import"yourmod/internal/user/repository"并调用其私有方法 → 编译失败，因为service_test.go属于user包，不能跨包访问repository的未导出符号 - 为绕过限制，在
repository包里加func TestHelper() {}导出测试辅助函数 → 破坏封装，污染生产包 API
正确解法只有两个：要么把测试逻辑写在同包内（利用可访问性），要么用接口抽象 + 依赖注入，让 service 接收 repository.Interface，测试时传 mock。
最易被忽略的一点：Go Modules 的 replace 指令能覆盖本地路径，但不会绕过 internal 的导入检查。也就是说，即使你用 replace github.com/x/y => ./local/y，只要 local/y 里有 import "yourmod/internal/z"，构建仍会失败——这个限制发生在编译器解析阶段，不是 go mod 能干预的层级。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
