设计理念

本篇文档阐述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的治理,项目正在施工中,欢迎关注。

仓库、文档和社区

为什么v2完全重新设计

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

经验源自踩坑。

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

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

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

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

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

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

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

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

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

数据库:

缓存:

消息队列:

其它更多的优秀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等),请参考文档序列化进行相应的配置即可。

  1. syntax = "proto3";
  2. package helloworld.v1;
  3. import "google/api/annotations.proto";
  4. option go_package = "github.com/go-kratos/kratos-layout/api/helloworld/v1;v1";
  5. // The greeting service definition.
  6. service Greeter {
  7. // Sends a greeting
  8. rpc SayHello (HelloRequest) returns (HelloReply) {
  9. option (google.api.http) = {
  10. get: "/helloworld/{name}"
  11. };
  12. }
  13. }
  14. // The request message containing the user's name.
  15. message HelloRequest {
  16. string name = 1;
  17. }
  18. // The response message containing the greetings
  19. message HelloReply {
  20. string message = 1;
  21. }

需要注意,虽然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接口为例,消息结构大概是长这个样子的:

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

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

错误定义:

  1. syntax = "proto3";
  2. package api.blog.v1;
  3. import "errors/errors.proto";
  4. option go_package = "github.com/go-kratos/examples/blog/api/v1;v1";
  5. enum ErrorReason {
  6. // 设置缺省错误码
  7. option (errors.default_code) = 500;
  8. // 为某个枚举单独设置错误码
  9. USER_NOT_FOUND = 0 [(errors.code) = 404];
  10. CONTENT_MISSING = 1 [(errors.code) = 400];;
  11. }

错误创建:

  1. // 通过 errors.New() 响应错误
  2. errors.New(500, "USER_NAME_EMPTY", "user name is empty")
  3. // 通过 proto 生成的代码响应错误,并且包名应替换为自己生成代码后的 package name
  4. api.ErrorUserNotFound("user %s not found", "kratos")
  5. // 传递metadata
  6. err := errors.New(500, "USER_NAME_EMPTY", "user name is empty")
  7. err = err.WithMetadata(map[string]string{
  8. "foo": "bar",
  9. })

错误断言:

  1. err := wrong()
  2. // 通过 errors.Is() 断言
  3. if errors.Is(err,errors.BadRequest("USER_NAME_EMPTY","")) {
  4. // do something
  5. }
  6. // 通过判断 *Error.Reason 和 *Error.Code
  7. e := errors.FromError(err)
  8. if e.Reason == "USER_NAME_EMPTY" && e.Code == 500 {
  9. // do something
  10. }
  11. // 通过 proto 生成的代码断言错误,并且包名应替换为自己生成代码后的 package name
  12. if api.IsUserNotFound(err) {
  13. // do something
  14. })

配置文件

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

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

已经实现了下列插件:

服务注册&服务发现

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

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

日志

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

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

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

监控

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

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

链路追踪

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仓库的目录下我们提供了很多代码供参考。

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