Standard Go Project Layout 深度解析/pkg 目录的可见性契约、与 internal 的协作及使用时机【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout/pkg目录是 Standard Go Project Layout标准 Go 项目布局中用于存放允许被外部项目导入的公共库代码的约定位置。本文围绕 pkg/README.md 的完整论述展开讲清/pkg与/internal在可见性机制上的本质区别编译器强制约束 vs 约定信号给出该布局仓库明确的取舍标准——什么时候该用、什么时候不该用并结合本仓库的go.mod、占位目录结构还原外部项目导入pkg包时的真实 import 路径帮助你在自己的 Go 项目中正确划定公共 API 的边界。/pkg 是什么允许外部应用使用的库代码/pkg的定位在 pkg/README.md 中有明确定义它是可以被外部应用使用的库代码library code thats ok to use by external applications典型形态如/pkg/mypubliclib。本仓库为此提供了一个空占位目录 pkg/your_public_lib作为布局示意。这里有一个关键的工程含义原文用了一个带笑号的警告值得原样记住Other projects will import these libraries expecting them to work, so think twice before you put something here :-)也就是说一旦某个包进入/pkg它就事实上承担了公共 API 的职责其他项目会导入它并预期它会一直可用、行为稳定。因此放入/pkg之前必须三思——这个包是否真的准备被当作对外承诺来维护如果答案是不确定那么它更合适的位置是/internal。这一点与 cmd/README.md 中的建议是配套的应用目录/cmd里不要堆大量代码如果你认为这段代码可以被其他项目导入使用它应该放在/pkg如果代码不可复用或你不希望别人复用就放进/internal。/pkg 与 /internal一个信号与一条硬约束理解/pkg的最佳参照物是/internal因为二者共同构成了 Go 项目里公共/私有代码划分的完整图景。/internal是编译器强制的硬约束。把包放进任意层级的internal目录后Go 工具链会拒绝任何不共享公共祖先目录的外部项目导入它——这一机制自 Go 1.4 起由编译器本身执行详见 internal/README.md。你可以在项目树的任意层级放置多个internal目录不限于顶层。/pkg只是约定没有任何编译器层面的可见性控制。从 pkg/README.md 的表述看internal目录是确保私有包不可被导入的更好方式因为它由 Go 强制执行/pkg目录的价值在于显式地传达一个信息——这个目录里的代码是供他人安全使用的。用一句话概括两者的分工internal解决别人能不能导入能/不能由工具链裁定pkg解决我打算让别人导入什么意图声明。二者可以共存且互不冲突——本仓库的根布局中同时保留了 pkg/your_public_lib、internal/pkg/your_private_lib和 internal/app/your_app三类占位目录正好演示了这种分层。/internal内部还可以再细分internal/README.md实际的应用代码放/internal/app如/internal/app/myapp被这些应用共享的代码放/internal/pkg如/internal/pkg/myprivlib。这种app pkg的子结构不是必需的但对大项目提供了这个包打算给谁用的视觉线索。第二个用途把 Go 代码集中起来方便工具运行除可见性沟通外/pkg还有第二个独立价值出自 pkg/README.mdIts also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools.当仓库根目录塞满了非 Go 组件静态资源、部署模板、前端代码、构建脚本等时把所有 Go 代码收拢到pkg及internal、cmd下能让gofmt、go vet、staticcheck这类按目录树工作的 Go 工具更容易以正确范围运行。这一点在 GopherCon EU 2018 Best Practices for Industrial Programming、GopherCon 2018 Kat Zien 的演讲以及 GoLab 2018 Project layout patterns in Go 等社区讨论中被反复提及见 README.md 的引用段落。使用时机本仓库给出的三条决策准则/pkg并非普遍接受的模式——pkg/README.md 直言Its not a universally accepted pattern and for every popular repo that uses it you can find 10 that dont对每一个使用它的主流仓库你能找到 10 个不用的。因此仓库给出的是决策准则而非强制要求小项目不必用pkg/README.md如果应用项目很小多一层嵌套目录带来的价值有限就不需要/pkg——除非你确实想要。Think about it when its getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components)即当项目变大、根目录变得拥挤尤其有大量非 Go 组件时再引入。它主要服务于仓库同时被当库使用的场景。根 README.md 指出当项目是开源项目、或你知道其他项目会导入本仓库的代码时用internal划私有边界以及用pkg划公共边界才真正重要。保持意图显式Go 社区里别人会怎么导入你的代码是不可控变量Youll be surprised what others will do见 cmd/README.md所以pkg/internal的划分本质上是在用目录名代替代码注释把你的 API 意图写进文件树。import 路径与模块结构外部项目如何引用你的 pkg 包看本仓库的 go.modmodule github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME go 1.19模块路径是占位符实际使用时替换为你自己的仓库地址。据此可以推演出pkg包对外的完整 import 形态假设模块路径为github.com/myorg/myrepo则/pkg/mypubliclib对外暴露的导入路径就是import github.com/myorg/myrepo/pkg/mypubliclib对照之下pkg/your_public_lib、internal/pkg/your_private_lib、cmd/your_app这些以下划线开头的目录值得注意Go 工具会忽略以_或.开头的目录因此它们是纯布局示意不会被编译或产生可见的包你在真实项目中应把它们替换为真实的包名如mypubliclib。另外两点配套事实本仓库当前不包含任何.go文件Makefile 也仅有一行注释# note: call scripts from /scripts——它本身是布局骨架而非可构建应用克隆后保留你需要的部分、删掉其余即可根 README 原话Clone the repository, keep what you need and delete everything else!。辅助工具目录可以打破公共包对外的直觉根 README.md 说明/tools中的支持工具可以导入/pkg与/internal的代码因为工具随仓库内部使用不对外发布。pkg 目录的起源与生态中的代表项目起源早期的 Go 官方源码仓库曾用pkg目录存放其包编译产物曾存放在$GOPATH/pkg标准库源树中也存在pkg组织方式随后社区各类 Go 项目开始复制这一模式逐渐沉淀为一种布局惯例。Brad Fitzpatrick 的公开讨论为该模式的流行提供了背景。代表项目pkg/README.md 附有一份 90 项目的示例清单原文为链接列表此处仅保留项目名以供检索。其中使用/pkg布局的知名项目包括containerd、mobyDocker 引擎、kubernetes、helm、etcd、jaeger、grafana、influxdb、cockroachdb、istio、gvisor、syzkaller、argo-cd、argoproj/argo-workflows、dapr、cilium、k3s、prometheus 生态相邻项目如 loki、thanos、flux2、linkerd2、keda、kubevirt、kyverno、openfga、lazygit、pdfcpu、werf、sealer 等。从这份名单可以看到一个规律pkg布局高度集中在既是可部署系统、又对外提供可复用库的大型基础设施项目中——这与前文项目变大、根目录变拥挤时再考虑的准则相互印证。实践建议如何用 /pkg 划定公共 API 边界综合 pkg/README.md 与根 README.md 的论述落地时可按以下顺序操作先默认全部私有不确定是否公开的代码一律放入/internal可再分internal/app、internal/pkg利用编译器强制保证误导入在构建期就报错。把确定要对外承诺的包提升进/pkg提升即声明。提升前检查该包是否依赖了internal包——依赖私有实现的包无法安全公开需要先把实现下沉或抽象出公开接口。在/cmd下保持极薄的main应用入口只负责装配并调用pkg/internal中的代码cmd/README.md避免业务逻辑沉积在应用目录而难以复用。小项目克制使用单个main.gogo.mod足以起步根 README.md 的明确提醒只有当根目录组件混杂、仓库被外部项目导入时才引入pkg/internal分层。以文档与工具兜底/pkg没有编译器兜底公共 API 的稳定性需要靠版本策略、changelog 和staticcheck等工具根 README.md 推荐使用 gofmt 与 staticcheck 处理命名、格式与静态检查来维持。小结/pkg的价值不在于任何编译期机制而在于它把哪些代码是公共 API这一意图写进了目录树它是internal硬约束之外的软性契约层同时也是大型混合项目里集中 Go 代码、方便工具运行的组织手段。它不是官方标准、也不是普适最佳实践——本布局仓库的态度是当你明确希望其他项目导入你的代码、且项目规模大到根目录已经拥挤时它就是值得采用的惯例。【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Standard Go Project Layout 深度解析/pkg 目录的可见性契约、与 internal 的协作及使用时机【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout/pkg目录是 Standard Go Project Layout标准 Go 项目布局中用于存放允许被外部项目导入的公共库代码的约定位置。本文围绕 pkg/README.md 的完整论述展开讲清/pkg与/internal在可见性机制上的本质区别编译器强制约束 vs 约定信号给出该布局仓库明确的取舍标准——什么时候该用、什么时候不该用并结合本仓库的go.mod、占位目录结构还原外部项目导入pkg包时的真实 import 路径帮助你在自己的 Go 项目中正确划定公共 API 的边界。/pkg 是什么允许外部应用使用的库代码/pkg的定位在 pkg/README.md 中有明确定义它是可以被外部应用使用的库代码library code thats ok to use by external applications典型形态如/pkg/mypubliclib。本仓库为此提供了一个空占位目录 pkg/your_public_lib作为布局示意。这里有一个关键的工程含义原文用了一个带笑号的警告值得原样记住Other projects will import these libraries expecting them to work, so think twice before you put something here :-)也就是说一旦某个包进入/pkg它就事实上承担了公共 API 的职责其他项目会导入它并预期它会一直可用、行为稳定。因此放入/pkg之前必须三思——这个包是否真的准备被当作对外承诺来维护如果答案是不确定那么它更合适的位置是/internal。这一点与 cmd/README.md 中的建议是配套的应用目录/cmd里不要堆大量代码如果你认为这段代码可以被其他项目导入使用它应该放在/pkg如果代码不可复用或你不希望别人复用就放进/internal。/pkg 与 /internal一个信号与一条硬约束理解/pkg的最佳参照物是/internal因为二者共同构成了 Go 项目里公共/私有代码划分的完整图景。/internal是编译器强制的硬约束。把包放进任意层级的internal目录后Go 工具链会拒绝任何不共享公共祖先目录的外部项目导入它——这一机制自 Go 1.4 起由编译器本身执行详见 internal/README.md。你可以在项目树的任意层级放置多个internal目录不限于顶层。/pkg只是约定没有任何编译器层面的可见性控制。从 pkg/README.md 的表述看internal目录是确保私有包不可被导入的更好方式因为它由 Go 强制执行/pkg目录的价值在于显式地传达一个信息——这个目录里的代码是供他人安全使用的。用一句话概括两者的分工internal解决别人能不能导入能/不能由工具链裁定pkg解决我打算让别人导入什么意图声明。二者可以共存且互不冲突——本仓库的根布局中同时保留了 pkg/your_public_lib、internal/pkg/your_private_lib和 internal/app/your_app三类占位目录正好演示了这种分层。/internal内部还可以再细分internal/README.md实际的应用代码放/internal/app如/internal/app/myapp被这些应用共享的代码放/internal/pkg如/internal/pkg/myprivlib。这种app pkg的子结构不是必需的但对大项目提供了这个包打算给谁用的视觉线索。第二个用途把 Go 代码集中起来方便工具运行除可见性沟通外/pkg还有第二个独立价值出自 pkg/README.mdIts also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools.当仓库根目录塞满了非 Go 组件静态资源、部署模板、前端代码、构建脚本等时把所有 Go 代码收拢到pkg及internal、cmd下能让gofmt、go vet、staticcheck这类按目录树工作的 Go 工具更容易以正确范围运行。这一点在 GopherCon EU 2018 Best Practices for Industrial Programming、GopherCon 2018 Kat Zien 的演讲以及 GoLab 2018 Project layout patterns in Go 等社区讨论中被反复提及见 README.md 的引用段落。使用时机本仓库给出的三条决策准则/pkg并非普遍接受的模式——pkg/README.md 直言Its not a universally accepted pattern and for every popular repo that uses it you can find 10 that dont对每一个使用它的主流仓库你能找到 10 个不用的。因此仓库给出的是决策准则而非强制要求小项目不必用pkg/README.md如果应用项目很小多一层嵌套目录带来的价值有限就不需要/pkg——除非你确实想要。Think about it when its getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components)即当项目变大、根目录变得拥挤尤其有大量非 Go 组件时再引入。它主要服务于仓库同时被当库使用的场景。根 README.md 指出当项目是开源项目、或你知道其他项目会导入本仓库的代码时用internal划私有边界以及用pkg划公共边界才真正重要。保持意图显式Go 社区里别人会怎么导入你的代码是不可控变量Youll be surprised what others will do见 cmd/README.md所以pkg/internal的划分本质上是在用目录名代替代码注释把你的 API 意图写进文件树。import 路径与模块结构外部项目如何引用你的 pkg 包看本仓库的 go.modmodule github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME go 1.19模块路径是占位符实际使用时替换为你自己的仓库地址。据此可以推演出pkg包对外的完整 import 形态假设模块路径为github.com/myorg/myrepo则/pkg/mypubliclib对外暴露的导入路径就是import github.com/myorg/myrepo/pkg/mypubliclib对照之下pkg/your_public_lib、internal/pkg/your_private_lib、cmd/your_app这些以下划线开头的目录值得注意Go 工具会忽略以_或.开头的目录因此它们是纯布局示意不会被编译或产生可见的包你在真实项目中应把它们替换为真实的包名如mypubliclib。另外两点配套事实本仓库当前不包含任何.go文件Makefile 也仅有一行注释# note: call scripts from /scripts——它本身是布局骨架而非可构建应用克隆后保留你需要的部分、删掉其余即可根 README 原话Clone the repository, keep what you need and delete everything else!。辅助工具目录可以打破公共包对外的直觉根 README.md 说明/tools中的支持工具可以导入/pkg与/internal的代码因为工具随仓库内部使用不对外发布。pkg 目录的起源与生态中的代表项目起源早期的 Go 官方源码仓库曾用pkg目录存放其包编译产物曾存放在$GOPATH/pkg标准库源树中也存在pkg组织方式随后社区各类 Go 项目开始复制这一模式逐渐沉淀为一种布局惯例。Brad Fitzpatrick 的公开讨论为该模式的流行提供了背景。代表项目pkg/README.md 附有一份 90 项目的示例清单原文为链接列表此处仅保留项目名以供检索。其中使用/pkg布局的知名项目包括containerd、mobyDocker 引擎、kubernetes、helm、etcd、jaeger、grafana、influxdb、cockroachdb、istio、gvisor、syzkaller、argo-cd、argoproj/argo-workflows、dapr、cilium、k3s、prometheus 生态相邻项目如 loki、thanos、flux2、linkerd2、keda、kubevirt、kyverno、openfga、lazygit、pdfcpu、werf、sealer 等。从这份名单可以看到一个规律pkg布局高度集中在既是可部署系统、又对外提供可复用库的大型基础设施项目中——这与前文项目变大、根目录变拥挤时再考虑的准则相互印证。实践建议如何用 /pkg 划定公共 API 边界综合 pkg/README.md 与根 README.md 的论述落地时可按以下顺序操作先默认全部私有不确定是否公开的代码一律放入/internal可再分internal/app、internal/pkg利用编译器强制保证误导入在构建期就报错。把确定要对外承诺的包提升进/pkg提升即声明。提升前检查该包是否依赖了internal包——依赖私有实现的包无法安全公开需要先把实现下沉或抽象出公开接口。在/cmd下保持极薄的main应用入口只负责装配并调用pkg/internal中的代码cmd/README.md避免业务逻辑沉积在应用目录而难以复用。小项目克制使用单个main.gogo.mod足以起步根 README.md 的明确提醒只有当根目录组件混杂、仓库被外部项目导入时才引入pkg/internal分层。以文档与工具兜底/pkg没有编译器兜底公共 API 的稳定性需要靠版本策略、changelog 和staticcheck等工具根 README.md 推荐使用 gofmt 与 staticcheck 处理命名、格式与静态检查来维持。小结/pkg的价值不在于任何编译期机制而在于它把哪些代码是公共 API这一意图写进了目录树它是internal硬约束之外的软性契约层同时也是大型混合项目里集中 Go 代码、方便工具运行的组织手段。它不是官方标准、也不是普适最佳实践——本布局仓库的态度是当你明确希望其他项目导入你的代码、且项目规模大到根目录已经拥挤时它就是值得采用的惯例。【免费下载链接】project-layoutStandard Go Project Layout项目地址: https://gitcode.com/GitHub_Trending/pr/project-layout创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
