golang-standards/project-layout

这是 Go 应用程序项目的基本布局。它不是核心 Go 开发团队定义的官方标准；然而，它是 Go 生态系统中一组常见的老项目和新项目的布局模式。其中一些模式比其他模式更受欢迎。它还具有许多小的增强，以及对任何足够大的实际应用程序通用的几个支持目录。 如果你尝试学习 Go，或者你正在为自己建立一个 PoC 或一个玩具项目，这个项目布局是没啥必要的。从一些非常简单的事情开始(一个 main.go 文件绰绰有余)。随着项目的增长，请记住保持代码结构良好非常重要，否则你最终会得到一个凌乱的代码，这其中就包含大量隐藏的依赖项和全局状态。当有更多的人参与这个项目时，你将需要更多的结构。这时候，介绍一种管理包/库的通用方法是很重要的。当你有一个开源项目时，或者当你知道其他项目从你的项目存储库中导入代码时，这时候拥有私有(又名 internal)包和代码就很重要。克隆存储库，保留你需要的内容，删除其他所有的内容!仅仅因为它在那里并不意味着你必须全部使用它。这些模式都没有在每个项目中使用。甚至 vendor 模式也不是通用的。 Go 1.14 终于可以投入生产了。除非你有特定的理由不使用它们，否则使用 。如果你使用，就无需担心 $GOPATH 以及项目放置的位置。存储库中的 go.mod 文件基本假定你的项目托管在 Github 上，但这不是要求。模块路径可以是任何地方，尽管第一个模块路径组件的名称中应该有一个点（当前版本的 Go 不再强制使用该模块，但如果使用稍旧的版本，如果没有 mod 文件构建失败的话 ，不要惊讶）。如果你想知道更多信息，请参阅 Issues 和 。 此项目布局是通用的，并且不会尝试强加一个特定的 Go 包结构。 这是社区的努力。 如果看到新的模式，或者认为一个现有的模式需要更新，请提一个 issue。 如果需要命名、格式和样式方面的帮助，请运行 和 。还要确保阅读这些 Go 代码风格的指导方针和建议: 参见 Go Project Layout 了解更多的背景信息。 更多关于包的命名和组织以及其他代码结构的建议: 本项目的主干。 每个应用程序的目录名应该与你想要的可执行文件的名称相匹配(例如，/cmd/myapp)。 不要在这个目录中放置太多代码。如果你认为代码可以导入并在其他项目中使用，那么它应该位于 /pkg 目录中。如果代码不是可重用的，或者你不希望其他人重用它，请将该代码放到 /internal 目录中。你会惊讶于别人会怎么做，所以要明确你的意图!

https://github.com/golang-standards/project-layout/blob/master/README_zh.md

目录概述

1. /cmd 本项目的主干。 每个应用程序的目录名应该与你想要的可执行文件的名称相匹配(例如，/cmd/myapp)。 不要在这个目录中放置太多代码。如果你认为代码可以导入并在其他项目中使用，那么它应该位于 /pkg 目录中。如果代码不是可重用的，或者你不希望其他人重用它，请将该代码放到 /internal 目录中。

2. /internal 私有应用程序和库代码。这是你不希望其他人在其应用程序或库中导入代码。请注意，这个布局模式是由 Go 编译器本身执行的。有关更多细节，请参阅Go 1.4 release notes。注意，你并不局限于顶级 internal 目录。在项目树的任何级别上都可以有多个内部目录。 你可以选择向 internal 包中添加一些额外的结构，以分隔共享和非共享的内部代码。这不是必需的(特别是对于较小的项目)，但是最好有有可视化的线索来显示预期的包的用途。你的实际应用程序代码可以放在 /internal/app 目录下(例如 /internal/app/myapp)，这些应用程序共享的代码可以放在 /internal/pkg 目录下(例如 /internal/pkg/myprivlib)。 因为我们习惯把相关的服务，比如账号服务，内部有 rpc、job、admin 等，相关的服务整合一起后，需要区分 app。单一的服务，可以去掉 /internal/myapp。

3. /pkg 外部应用程序可以使用的库代码(例如 /pkg/mypubliclib)。其他项目会导入这些库，所以在这里放东西之前要三思:-)注意，internal 目录是确保私有包不可导入的更好方法，因为它是由 Go 强制执行的。/pkg 目录仍然是一种很好的方式，可以显式地表示该目录中的代码对于其他人来说是安全使用的好方法。 /pkg 目录内，可以参考 go 标准库的组织方式，按照功能分类。/internla/pkg 一般用于项目内的 跨多个应用的公共共享代码，但其作用域仅在单个项目工程内。 由 Travis Jeffery 撰写的 I'll take pkg over internal 博客文章提供了 pkg 和 internal 目录的一个很好的概述，以及什么时候使用它们是有意义的。 当根目录包含大量非 Go 组件和目录时，这也是一种将 Go 代码分组到一个位置的方法，这使得运行各种 Go 工具变得更加容易组织。

Kit Project Layout - 基础库

kit 项目必须具备的特点:

1. 统一

2. 标准库方式布局

3. 高度抽象

4. 支持插件

Service Application Project Layout - 服务layout

1. /api API 协议定义目录，xxapi.proto protobuf 文件，以及生成的 go 文件。我们通常把 api 文档直接在 proto 文件中描述。

2. /configs 配置文件模板或默认配置。

3. /test 额外的外部测试应用程序和测试数据。你可以随时根据需求构造 /test 目录。对于较大的项目，有一个数据子目录是有意义的。例如，你可以使用 /test/data 或 /test/testdata (如果你需要忽略目录中的内容)。请注意，Go 还会忽略以“.”或“_”开头的目录或文件，因此在如何命名测试数据目录方面有更大的灵活性。

4. 不应该包含：/src 有些 Go 项目确实有一个 src 文件夹，但这通常发生在开发人员有 Java 背景，在那里它是一种常见的模式。不要将项目级别 src 目录与 Go 用于其工作空间的 src 目录。

Service Application Project

1. 多 app 的方式，app 目录内的每个微服务按照自己的全局唯一名称，比如 “account.service.vip” 来建立目录，如: account/vip/*。

2. 和 app 平级的目录 pkg 存放业务有关的公共库（非基础框架库）。如果应用不希望导出这些目录，可以放置到 myapp/internal/pkg 中。

1. interface: 对外的 BFF 服务，接受来自用户的请求，比如暴露了 HTTP/gRPC 接口。

2. service: 对内的微服务，仅接受来自内部其他服务或者网关的请求，比如暴露了gRPC 接口只对内服务。

3. admin：区别于 service，更多是面向运营测的服务，通常数据权限更高，隔离带来更好的代码级别安全。

4. job: 流式任务处理的服务，上游一般依赖 message broker。

5. task: 定时任务，类似 cronjob，部署到 task 托管平台中。

Service Application Project - v1

1. api: 放置 API 定义(protobuf)，以及对应的生成的 client 代码，基于 pb 生成的 swagger.json。

2. configs: 放服务所需要的配置文件，比如database.yaml、redis.yaml、application.yaml。

3. internal: 是为了避免有同业务下有人跨目录引用了内部的 model、dao 等内部 struct。

4. server: 放置 HTTP/gRPC 的路由代码，以及 DTO 转换的代码。

1. model: 放对应“存储层”的结构体，是对存储的一一隐射。

2. dao: 数据读写层，数据库和缓存全部在这层统一处理，包括 cache miss 处理。

3. service: 组合各种数据访问来构建业务逻辑。

4. server: 依赖 proto 定义的服务作为入参，提供快捷的启动服务全局方法。

5. api: 定义了 API proto 文件，和生成的 stub 代码，它生成的 interface，其实现者在 service 中。

Service Application Project - v2

1. internal: 是为了避免有同业务下有人跨目录引用了内部的 biz、data、service 等内部 struct。
1. biz: 业务逻辑的组装层，类似 DDD 的 domain 层，data 类似 DDD 的 repo，repo 接口在这里定义，使用依赖倒置的原则。
2. data: 业务数据访问，包含 cache、db 等封装，实现了 biz 的 repo 接口。我们可能会把 data 与 dao 混淆在一起，data 偏重业务的含义，它所要做的是将领域对象重新拿出来，我们去掉了 DDD 的 infra 层。
3. service: 实现了 api 定义的服务层，类似 DDD 的 application 层，处理 DTO 到 biz 领域实体的转换(DTO -> DO)，同时协同各类 biz 交互，但是不应处理复杂逻辑。

ent/ent

Simple, yet powerful entity framework for Go, that makes it easy to build and maintain applications with large data-models. Schema As Code - model any database schema as Go objects. Easily Traverse Any Graph - run queries, aggregations and traverse any graph structure easily.

https://github.com/facebook/ent

1. 失血模型
模型仅仅包含数据的定义和 getter/setter 方法，业务逻辑和应用逻辑都放到服务层中。这种类在 Java 中叫 POJO，在 .NET 中叫 POCO。

2. 贫血模型 贫血模型中包含了一些业务逻辑，但不包含依赖持久层的业务逻辑。这部分依赖于持久层的业务逻辑将会放到服务层中。可以看出，贫血模型中的领域对象是不依赖于持久层的。

3. 充血模型 充血模型中包含了所有的业务逻辑，包括依赖于持久层的业务逻辑。所以，使用充血模型的领域层是依赖于持久层，简单表示就是 UI层->服务层->领域层<->持久层。

4. 胀血模型
胀血模型就是把和业务逻辑不想关的其他应用逻辑（如授权、事务等）都放到领域模型中。我感觉胀血模型反而是另外一种的失血模型，因为服务层消失了，领域层干了服务层的事，到头来还是什么都没变。

Lifecycle

google/wire

Wire is a code generation tool that automates connecting components using dependency injection. Dependencies between components are represented in Wire as function parameters, encouraging explicit initialization instead of global variables. Because Wire operates without runtime state or reflection, code written to be used with Wire is useful even for hand-written initialization.

https://github.com/google/wire

wire

The Go Blog

Robert van Gent 9 October 2018 The Go team recently announced the open source project Go Cloud, with portable Cloud APIs and tools for open cloud development. This post goes into more detail about Wire, a dependency injection tool used in Go Cloud.

https://blog.golang.org/wire

使用说明

google/wire

Wire has two core concepts: providers and injectors. The primary mechanism in Wire is the provider: a function that can produce a value. These functions are ordinary Go code. Provider functions must be exported in order to be used from other packages, just like ordinary functions.

https://github.com/google/wire/blob/main/docs/guide.md

API 设计

gRPC

• 多语言：语言中立，支持多种语言。

• 轻量级、高性能：序列化支持 PB(Protocol Buffer)和 JSON，PB 是一种语言无关的高性能序列化框架。

• 可插拔

• IDL：基于文件定义服务，通过 proto3 工具生成指定语言的数据结构、服务端接口以及客户端 Stub。

• 设计理念

• 移动端：基于标准的 HTTP2 设计，支持双向流、消息头压缩、单 TCP 的多路复用、服务端推送等特性，这些特性使得 gRPC 在移动端设备上更加省电和节省网络流量。

• 服务而非对象、消息而非引用：促进微服务的系统间粗粒度消息交互设计理念。

• 负载无关的：不同的服务需要使用不同的消息类型和编码，例如 protocol buffers、JSON、XML和Thrift。

• 流: Streaming API。

• 阻塞式和非阻塞式：支持异步和同步处理在客户端和服务端间交互的消息序列。

• 元数据交换：常见的横切关注点，如认证或跟踪，依赖数据交换。

• 标准化状态码：客户端通常以有限的方式响应 API 调用返回的错误。

API Project

googleapis/googleapis

This repository contains the original interface definitions of public Google APIs that support both REST and gRPC protocols. Reading the original interface definitions can provide a better understanding of Google APIs and help you to utilize them more efficiently. You can also use these definitions with open source tools to generate client libraries, documentation, and other artifacts.

https://github.com/googleapis/googleapis

envoyproxy/data-plane-api

This tree hosts the configuration and APIs that drive Envoy. The APIs are also in some cases used by other proxy solutions that aim to interoperate with management systems and configuration generators that are built against this standard. Thus, we consider these a set of universal data plane APIs.

https://github.com/envoyproxy/data-plane-api

istio/api

This repository defines component-level APIs and common configuration formats for the Istio platform. These definitions are specified using the protobuf syntax. This repository depends only on the tools repository for tools used during build. This repository will not depend on any other repositories.

https://github.com/istio/api

• API 仓库，方便跨部门协作。

• 版本管理，基于 git 控制。

• 规范化检查，API lint。

• API design review，变更 diff。

• 权限管理，目录 OWNERS

API Project Layout

API Compatibility-兼容性说明

向后兼容(非破坏性)的修改

1. 给 API 服务定义添加 API 接口 从协议的角度来看，这始终是安全的。

2. 给请求消息添加字段 只要客户端在新版和旧版中对该字段的处理不保持一致，添加请求字段就是兼容的。

3. 给响应消息添加字段 在不改变其他响应字段的行为的前提下，非资源（例如，ListBooksResponse）的响应消息可以扩展而不必破坏客户端的兼容性。即使会引入冗余，先前在响应中填充的任何字段应继续使用相同的语义填充。

向后不兼容(破坏性)的修改

1. 删除或重命名服务，字段，方法或枚举值 从根本上说，如果客户端代码可以引用某些东西，那么删除或重命名它都是不兼容的变化，这时必须修改 major 版本号。

2. 修改字段的类型 即使新类型是传输格式兼容的，这也可能会导致客户端库生成的代码发生变化，因此必须增加major 版本号。 对于编译型静态语言来说，会容易引入编译错误。

3. 修改现有请求的可见行为 客户端通常依赖于 API 行为和语义，即使这样的行为没有被明确支持或记录。 因此，在大多数情况下，修改 API 数据的行为或语义将被消费者视为是破坏性的。如果行为没有加密隐藏，您应该假设用户已经发现它，并将依赖于它。

4. 给资源消息添加 读取/写入 字段

API Naming Conventions - API命名

API Primitive Fields - 0值

protocolbuffers/protobuf

You can't perform that action at this time. You signed in with another tab or window. You signed out in another tab or window. Reload to refresh your session. Reload to refresh your session.

https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/wrappers.proto

API Errors - 错误码

1. 使用一小组标准错误配合大量资源