设计理念

本篇文档阐述Kratos的设计理念，介绍Kratos项目的整体情况和主要组件。

设计哲学

Kratos是一个Go语言实现的微服务框架，说得更准确一点，它更类似于一个使用Go构建微服务的工具箱，开发者可以按照自己的习惯选用或定制其中的组件，来打造自己的微服务。也正是由于这样的原因，Kratos并不绑定于特定的基础设施，不限定于某种注册中心，或数据库ORM等，所以您可以十分轻松地将任意库集成进项目里，与Kratos共同运作。

围绕这样的核心设计理念，我们设计了如下的项目生态：

• kratos Kratos框架核心，主要包含了基础的CLI工具，内置的HTTP/gRPC接口生成和服务生命周期管理，提供链路追踪、配置文件、日志、服务发现、监控等组件能力和相关接口定义。
• contrib 基于上述核心定义的基础接口，对配置文件、日志、服务发现、监控等服务进行具体实现所形成的一系列插件，可以直接使用它们，也可以参考它们的代码，做您需要的服务的适配，从而集成进kratos项目中来。
• aegis 我们将服务可用性相关的算法：如限流、熔断等算法放在了这个独立的项目里，几乎没有外部依赖，它更不依赖Kratos，您可以在直接在任意项目中使用。您也可以轻松将它集成到Kratos中使用，提高服务的可用性。
• layout 我们设计的一个默认的项目模板，它包含一个参考了DDD和简洁架构设计的项目结构、Makefile脚本和Dockerfile文件。但这个项目模板不是必需的，您可以任意修改它，或使用自己设计的项目结构，Kratos依然可以正常工作。框架本身不对项目结构做任何假设和限制，您可以按照自己的想法来使用，具有很强的可定制性。
• gateway 这个是我们刚刚起步，用Go开发的API Gateway，后续您可以使用它来作为您Kratos微服务的网关，用于微服务API的治理，项目正在施工中，欢迎关注。

仓库、文档和社区

• GitHub仓库：https://github.com/go-kratos
• 文档：https://go-kratos.dev/
• 微信群：go-kratos 官方微信群
• Discord：go-kratos

为什么v2完全重新设计

以前关注过 kratos 项目的可能知道，Kratos的v1版本已经开源了很久，也是个较为完善的框架。那么为什么不直接基于v1继续迭代，而是要推倒重来，推出完全重新设计的v2呢？

经验源自踩坑。

在业务不断迭代、项目不断膨胀的情况下，我们发现，过去的框架和项目结构设计，导致代码变更成本逐渐升高，而没有进行合理的抽象，导致更难进行模块的测试，也更难对第三方基础库进行适配和迁移，这在一定程度上拉低了生产力。

因此，我们参考了大量的DDD和Clean Architecture等业界先进设计理念，重新设计了微服务的项目结构，并且这个结构随着我们的后续研究，会进一步进行迭代，让它成为微服务项目结构的最佳实践。

没错，新版本的是从kratos-layout开始的。也许刚接触这个项目结构时会觉得不适应，但随着项目迭代，代码复杂度的提高，这个定义良好的结构，将使项目保持优秀的代码可读性、可测试性，以及令人满意的开发效率和可维护性。

更重要的一点是，这一次我们想面向社区来设计和开发这个框架。让更多的开发者能够使用我们的框架来提高生产力，同时参与到我们的项目中来。

所以我们把整个框架设计成为一个插座，我们希望整个框架轻量，插件化，可定制。对于几乎每一个微服务相关的功能模块，我们都设计了标准化接口，对于第三方库设计为插件，这样就能迅速把任意基础设施集成到使用Kratos的项目里，因此，无论您的公司使用何种基础设施，有何种规范，您都可以轻松将Kratos定制成与您的开发、生产环境相匹配的样子。

不破不立，v2是一次从内到外的彻底革新，我们无法在旧版本上修修补补，而是选择重新设计和开发新版本。而目前v2版本也已经在很多生产环境使用，我们也将持续迭代和完善这个框架，同时也更欢迎各位开发者参与进来，一起让它变得更好。

数据库/缓存/消息队列/

正如前文提到的，Kratos框架不限制您使用任何第三方库来进行项目开发，因此您可以根据喜好来选择库进行集成。我们也会逐步针对更多被广泛使用的第三方库开发插件。

这里给出一些被广泛使用的库供参考：

数据库：

• database/sql 官方库
• gorm
• ent

缓存：

• go-redis
• redigo
• gomemcache

消息队列：

• sarama kafka客户端
• kafka-go

其它更多的优秀go库，可以在awesome-go这个仓库中找找。

CLI工具

kratos命令目前主要用于从模板创建项目，维护依赖包版本等。具体请参考文档

Protobuf定义API

Kratos使用Protobuf进行API定义。Protobuf是由Google开发的一种语言中立的数据序列化协议。它有结构定义清晰、可扩展性好、体积小、性能优秀等特点，在众多公司和项目被广泛使用。

在使用Kratos的项目中，您将使用如下的IDL进行您的接口定义，并且通过protoc工具生成相应的.pb.go文件，其中包含根据定义生成的服务端和客户端代码。随后您就可以在自己的项目内部注册服务端代码使用，或引用客户端代码进行远程调用。

Kratos默认仅生成gRPC接口的代码，如果需要生成HTTP代码，请在proto文件中使用option (google.api.http)来添加HTTP部分的定义后再进行生成。默认情况下，HTTP接口将使用JSON作为序列化格式，如果想使用其它序列化格式（form，XML等），请参考文档序列化进行相应的配置即可。

syntax = "proto3";

package helloworld.v1;

import "google/api/annotations.proto";

option go_package = "github.com/go-kratos/kratos-layout/api/helloworld/v1;v1";

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply)  {
        option (google.api.http) = {
            get: "/helloworld/{name}"
        };
    }
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

需要注意，虽然Protobuf定义的API的可靠性更强，但字段结构灵活性相对JSON要弱一些，因此如果您有诸如文件上传接口，或者某些无法对应到proto的JSON结构需要使用，我们还提供了“逃生门”，在我们的Protobuf体系之外定义这些接口，实现为普通的http.Handler并且挂载到路由上，或者用struct来定义您的字段。可以参考我们的upload例子进行实现。

元信息传递

服务之间的API调用，如果有某些元信息需要传递过去，而不是写在payload消息中，可以使用Metadata包进行字段设置和提取，具体细节参考元信息传递文档

错误处理

Kratos的errors模块提供了error的封装。框架也预定义了一系列标准错误供使用。

错误处理这一块的设计也经过了很久的讨论才定下来，主要设计理念如下：

1. code 语义近似HTTP的Status Code（例如客户端传参数错误用400）同时也作为大类错误，在HTTP接口中的HTTP Code会使用它，好处是网关层可以根据这个code触发相应策略（重试、限流、熔断等）。
2. reason 业务的具体错误码，为可读的字符串，能够表明，在同一个服务中应该唯一。
3. message 用户可读的信息，可以在客户端（App、浏览器等）进行相应的展示给用户看。
4. metadata 为一些附加信息，可以作为补充信息使用。

在API返回的错误信息中，以HTTP接口为例，消息结构大概是长这个样子的：

{
    // 错误码，跟 http-status 一致，并且在 grpc 中可以转换成 grpc-status
    "code": 500,
    // 错误原因，定义为业务判定错误码
    "reason": "USER_NOT_FOUND",
    // 错误信息，为用户可读的信息，可作为用户提示内容
    "message": "invalid argument error",
    // 错误元信息，为错误添加附加可扩展信息
    "metadata": {"some-key": "some-value"}
}

在Kratos中您可以使用proto文件定义您的业务错误，并通过工具生成对应的处理逻辑和方法。（如使用layout中提供的make errors指令。）

错误定义：

syntax = "proto3";

package api.blog.v1;
import "errors/errors.proto";

option go_package = "github.com/go-kratos/examples/blog/api/v1;v1";

enum ErrorReason {
  // 设置缺省错误码
  option (errors.default_code) = 500;
  
  // 为某个枚举单独设置错误码
  USER_NOT_FOUND = 0 [(errors.code) = 404];
  CONTENT_MISSING = 1 [(errors.code) = 400];;
}

错误创建：

// 通过 errors.New() 响应错误
errors.New(500, "USER_NAME_EMPTY", "user name is empty")

// 通过 proto 生成的代码响应错误，并且包名应替换为自己生成代码后的 package name
api.ErrorUserNotFound("user %s not found", "kratos")

// 传递metadata
err := errors.New(500, "USER_NAME_EMPTY", "user name is empty")
err = err.WithMetadata(map[string]string{
    "foo": "bar",
})

错误断言：

err := wrong()

// 通过 errors.Is() 断言
if errors.Is(err,errors.BadRequest("USER_NAME_EMPTY","")) {
  // do something
}

// 通过判断 *Error.Reason 和 *Error.Code
e := errors.FromError(err)
if  e.Reason == "USER_NAME_EMPTY" && e.Code == 500 {
  // do something
}

// 通过 proto 生成的代码断言错误，并且包名应替换为自己生成代码后的 package name
if api.IsUserNotFound(err) {
  // do something
}

配置文件

Kratos提供了统一的接口，支持配置文件的加载和变更订阅。

通过实现Source 和 Watcher即可实现任意配置源（本地或远程）的配置文件加载和变更订阅。

已经实现了下列插件：

• file 本地文件加载，Kratos内置
• apollo
• etcd
• kubernetes
• nacos

服务注册&服务发现

Kratos定义了统一的注册接口，通过实现Registrar和Discovery，您可以很轻松地将Kratos接入到您的注册中心中。

您也可以直接使用我们已经实现好的插件：

• consul
• discovery
• etcd
• kubernetes
• nacos
• zookeeper

日志

Kratos的日志模块由两部分组成：

1. Logger：底层日志接口，用于快速适配各种日志库到框架中来，仅提供一个最简单的Log方法。
2. Helper：高级日志接口，提供了一系列带有日志等级和格式化方法的帮助函数，通常业务逻辑中建议使用这个，能够简化日志代码。

我们已经实现好的插件用于适配目前一些日志库，您也可以参考它们的代码来实现自己需要的日志库的适配：

• std 标准输出，Kratos内置
• fluent
• zap

监控

监控告警方面，您可以通过实现metrics相关接口将服务的统计数据上报给监控平台。

也可以直接使用我们已经实现好的插件：

• datadog
• prometheus

链路追踪

Kratos使用OpenTelemetry作为分布式链路追踪所使用的标准，您可以通过对client和server配置tracing来将服务接入到链路追踪平台（如jaeger等），从而对服务的接口调用关系，耗时，错误等进行追踪。

负载均衡

Kratos内置了若干种负载均衡算法，如Weighted round robin（默认）、P2C，Random等，您可以通过在client初始化时配置来使用他们。

限流熔断

Kratos提供了限流ratelimit和熔断circuitbreaker中间件，用于微服务出现异常故障时自动对流量进行限制，提升服务的健壮性，避免雪崩。这两个中间件使用的算法，也可以在我们的可用性算法仓库aegis中找到，独立于Kratos直接使用。

中间件

您可以通过Kratos的middleware机制，统一微服务接口的某些共同逻辑。上面提到的功能插件，您可以通过实现Middleware编写Kratos能够使用的中间件。

同时在仓库的middleware目录下，我们也提供了一系列中间件供您使用。

插件

除了上述提到的插件外，我们还提供了一些其它插件，完整的插件列表请参考文档社区插件

示例代码

如果您看过文档后，对某些功能的使用仍有疑惑，或者是希望寻找一些用Kratos写项目的灵感，在examples仓库的目录下我们提供了很多代码供参考。

您也可以通过文档中的示例代码清单页面来查阅有哪些示例。