CloudWeGo Study Group 是由 CloudWeGo 社区建议的学习小组，展开以 30 天为一期的源码解读和学习活动，协助新成员融入社区圈子，和社区 Committer 互动沟通，并学习上手 CloudWeGo 几大结构项目。现在 CSG 第四期—— CloudWeGo 事务实践事例解读现已圆满结束！

本期活动期间组织了 4 期直播共享，主题分别为：

  • Bookinfo——依据 CloudWeGo 重写 Istio 经典 demo
  • Open Payment Platform——依据 CloudWeGo 完结 API Gateway
  • EasyNote——CloudWeGo 生态入门
  • BookShop——从上手电商到上手CloudWeGo

本文为 CSG 第四期第二场直播中CloudWeGo Reviewer 李宜茗共享内容。

回放链接：meetings.feishu.cn/s/1iraydxgi…

一、嘉宾介绍

Easy Note——快速入门 CloudWeGo 生态

怎么快速入门 CloudWeGo 生态，biz-demo Easy Note 解读

本期共享的内容首要分为以下三个部分：

  1. 怎么入门 CloudWeGo 生态
  2. Hertz，Kitex，GORM 介绍
  3. Easy Note 解读

二、怎么入门 CloudWeGo 生态

Tip 01: 官方文档

“遇事不决先查文档”，获取信息最直接的方法便是查询官方文档。CloudWeGo 具有十分完善的中文文档以及英文文档，而且文档的更新和保护都十分及时。而且文档在 GitHub 上也有对应的库房，你假设发现了哪里有问题或许语法过错，都能够随时提交 GitHub issue 或许 PR 来协助进行修正。 在CloudWeGo 的官网，能够经过文档目录检查 CloudWeGo 现在开源的一切产品。以 Hertz 举例，“概览” 板块协助咱们快速了解 Hertz 是什么，一起 “快速开端” 板块能够让你快速入门 Hertz ，它会协助你以最快速、简略的方法去树立一个简易的 HTTP 服务。

Tip 02: Examples

假设官方文档还没有解决你的疑问，能够去检查对应的示例库房。例如 Hertz 和 Kitex，都有对应的示例库房 hertz-examples 和 kitex-examples。Examples 库房一般会包含产品各个首要特性的愈加细致的运用方法，为你供给一些愈加具体的运用示例参阅。

比方，经过检查 Hertz-examples 的 readme，能够看到关于 Hertz 常见的一些中间件，包含官网上列出的首要特性，都有对应的示例。假设你在检查一个特性的官方文档后仍觉得比较笼统，你就能够去 Examples 里边检查特性对应的示例，里边会供给愈加具体的运用的示例来协助你快速进行入门。Hertz-examples 也包含了一些常用结构组件和 Hertz 一起运用的 biz-demo，比方 hertz_jwt 是运用 Hertz 和 JWT 中间件的 demo，hertz_session 是运用 Hertz 和 Session，CSRF 中间件的 demo，这些 biz-demo 能够协助你快速上手 Hertz 和其他组件搭配运用的方法。 包含假设你觉得这些 biz-demo 还不够完善，有一些自己想增加的组件，你能够在 Hertz issues/486 下面谈论，就能够去为 hertz-examples 供给一些你自己的一些组件和 Hertz 结合的示例 demo。

Tip 03: 扩展库房

像 Hertz 和 Kitex ，都有分出一个专门的扩展库房去保护各自的组件。比方， Hertz 和 Kitex 都对常见的服务发现与注册中心进行了支撑，包含 nacos，etcd，consul 等等。一起， Hertz 也对常用的 Web 中间件进行了支撑，像 JWT，gzip，sessions 这些。而且大多数的扩展库房都会有附带运用示例，便利用户进行上手。所以假设你想要去运用一些常用的功用扩展，无妨先看看这些扩展库房，不需要你自己去进行开发了。 而且，大多数的扩展库房作者在写这些库房时分，都会单独分出一个叫 example 的文件夹，你能够去检查这些库房的 example 文件夹，去取得愈加细致的运用方法。比方 Hertz session 中间件，它的 example 文件夹下就包含了它怎么和 cookie 结合，以及和 redis 结合的简略示例，这也是一个比较高效获取信息的途径。

Tip 04: 关于发问

最终一个小 tips 是有关发问，比方平时咱们遇到一些技术问题，通常能够经过查询引擎，各大技术社区，比方，或一些产品的官网，GitHub 的前史 issue，包含现在十分火的 ChatGPT，这些都能够为咱们供给许多解决方案，而且咱们大多数常见问题都能够经过以上方法查询到解决方案。假设这些都解决不了，那么欢迎提 issue，这样一方面能够对问题进行记录，一起也能便利之后遇到相同问题的同学，最终也能够协助产品自身进一步地完善生长。提 issue 也是我十分推荐的一种解决问题的方法。

三、Hertz，Kitex，GORM 介绍

结构概述

  • Hertz 和 Kitex 都是由字节跳动开源的一款 HTTP 结构，它参阅了其他开源结构，像Gim、 Echo 的一些优势，而且结合了字节跳动内部的一些需求，具有高应用、高性能以及高拓宽性的特色。
  • Kitex 是字节开源的 Golang 微服务 RPC 结构，具有高性能，强可扩展的首要特色，支撑多协议而且拥有丰厚的开源扩展。
  • GORM 则是一个迭代 10 多年的十分十分强壮的 RM 结构，在字节内部现已进行了广泛运用，一起也是一种十分丰厚的开源拓宽。

Hertz – 架构规划

www.cloudwego.io/zh/docs/her…

能够看到这儿是 Hertz 简略的架构规划图。

Easy Note——快速入门 CloudWeGo 生态

Hertz 自带的 hz 的代码生成东西，能够协助咱们快速地生成脚手架代码，简化开发流程。包含 Hertz 也具有丰厚的协议支撑，比方 HTTP 1.1，HTTP 2 和 HTTP 3，其间 2 和 3 以扩展的方法存放于 hertz-contrib 库房下。包含 Hertz 也支撑切换底层的网络库，能够运用 CloudWeGo 开源的 netpoll 替代和 go 原生的网络库。你也能够去自己进行扩展，Hertz 供给了丰厚的扩展接口，便利你去完结自己的一些完结。

Kitex

www.cloudwego.io/zh/docs/kit…

Kitex 也是自带代码生成东西的 kitex。它能够帮咱们十分便利地生成一些脚手架代码，包含也支撑一些插件扩展，协助咱们简化开发流程，一起也支撑了十分多的音讯协议以及传输类型，以及各种音讯方法。它也能够运用 netpoll 以及 go 原生库去进行切换。

Easy Note——快速入门 CloudWeGo 生态

GORM

  • 全功用 ORM
  • 关联 (has one，has many，belongs to，many to many，多态，单表承继)
  • Create，Save，Update，Delete，Find 中钩子方法
  • 支撑 Preload、Joins 的预加载
  • 事务，嵌套事务，Save Point，Rollback To to Saved Point
  • Context、预编译模式、DryRun 模式
  • 批量插入，FindInBatches，Find/Create with Map，运用 SQL 表达式、Context Valuer 进行 CRUD
  • SQL 构建器，Upsert，锁，Optimizer/Index/Comment Hint，命名参数，子查询
  • 复合主键，索引，约束
  • Auto Migration
  • 自界说 Logger
  • 灵敏的可扩展插件 API：Database Resolver（多数据库，读写分离）、Prometheus…
  • 每个特性都经过了测试的重重检测
  • 开发者友爱

四、Easy Note 解读

技术架构

下图是Easy Note 技术栈，首要分为三层，分别运用 Hertz, Kitex 和 GORM 去编写。

Easy Note——快速入门 CloudWeGo 生态

  1. Hertz 担任处理用户恳求，处理担任客用户直接拜访的 HTTP 恳求，包含这儿也运用了 Hertz 的 4 个中间件 ，requestid 中间件、jwt 中间件、 pproof 以及 gzip 中间件。
  2. Kitex 首要运用了它的 etcd 的扩展作为服务注册与发现中心，而且也运用了一个 Kitex 的代码生成扩展，thrift-gen-validator 去对 RPC 恳求做校验。最终对数据库操作，运用了 GORM 结构，一起运用 MySQL 数据库作 RDBMS。一起也集成了 OpenTelemetry 以及 Jaeger 对链路进行追寻。
  3. 最终，用 Logrus 日志对 Hertz, Kitex 与 GORM 默许的日志进行替换，达成一致。

调用联系

下图则是 Easy Note 这个biz – demo 的服务调用联系图。 Easy Note 是一个微服务项目，首要分为三个微服务：demoapi、 demonote 以及 demouser。

Easy Note——快速入门 CloudWeGo 生态

其间 demoapi 是一个 HTTP 服务， demonote 和 demouser 是一个 RPC 服务，用户经过拜访经过 HTTP 拜访 demoapi 服务， demoapi 服务会经过 RPC 拜访 demouser 服务以及 demonote 服务。一起咱们 demonote 服务也会经过 RPC 恳求 demouser 服务，完结咱们的逻辑。

目录介绍

Easy Note——快速入门 CloudWeGo 生态

刚刚说到，Easy Note 是一个微服务项目，分为三个微服务。其间在 CMD 环节下就包含了三个微服务的首要代码。 API 便是咱们运用各自树立的 HTTP 服务，它为用户直接供给服务。

user 便是咱们方才提及到的 demouser 服务，它是运用 Kitex 和 GORM 去树立的一个 RPC 服务，还担任用户的创立、查询以及校验等功用。最终是 demonote 服务，它是咱们用 Kitex 和 GORM 树立的 RPC 服务，首要是担任笔记的增修改查功用。 dal 是数据库操作目录，里边包含了运用 GORM 去编写代码，对数据库表进行资源改查操作。 pack 则是咱们的数据包装文件夹，它会包装 RPC 呼应，这样的一些 RPC 呼应便利一致服务之间的沟通。 pkg 文件夹下， mw 目录则是咱们为 Kitex 界说的一些 RPC 中间件，包含 client 侧中间件，server 侧中间件以及 common 中间件。而 consts 类目录是包含了整个项目大局界说的常量。 errno 则是自界说的过错码，对整个过错的处理进行标准。 configs 是 SQL 脚本以及 OpenTelementry 的 Tracing 的装备。

开发流程

  1. 界说 IDL

首先榜首步，需要去界说服务的IDL。经过 thrift IDL 去界说这些服务的接口。比方咱们这儿能够用 API 注解去运用 Hertz 参数绑定与验证的功用，便利 Hertz 生成代码。一起，也能够去经过 API 注解， api.post、 api.get 一些注解去界说 HTTP 恳求方法与路由。这样 Hertz 会依据一些路由为咱们生成对应的脚手架代码。一起 Hertz 也会对一些路由进行分组，便利后面咱们对各个不同路由集成各自不同的中间件。

Easy Note——快速入门 CloudWeGo 生态

包含前面说到，咱们运用了 thrift-gen-validator 插件，让 Kitex 协助生成对应的代码以及 thrift-gen-validator。它能够协助对 RPC 恳求的结构体进行简略的校验。

  1. 树立数据库表

第二步，咱们需要去树立一个数据库表，能够经过 gorm.Model，快速地去规划数据库表的结构。包含运用 gorm.Model 今后， GORM 也会支像软删去这样的一些功用，十分便利。

Easy Note——快速入门 CloudWeGo 生态

一起，也能够运用在 docker-compose.yaml 中装备 volumes 特点将 SQL 脚本挂载到 MySQL 容器中，这样 MySQL 的官方镜像会在容器发动时分主动履行 /docker-entrypoint-initdb.d 这个文件夹下的 SQL 脚本，然后去完结数据库的初始化。在 pkg/config/sql 目录中，init.sql 包含了对数据库表的初始化代码。创立了 user 表和 note 表来存储用户信息以及笔记的信息。这样咱们在创立 MySQL 容器的时分，init.sql 就会主动履行，然后完结数据库表的初始化。

Easy Note——快速入门 CloudWeGo 生态

  1. 代码生成

第三步便是代码生成，咱们刚刚说到 Hertz 有 hz 东西， Kitex 有它的 kitex 东西，能够十分便利地帮咱们生成许多脚手架代码，然后简化开发流程。一起 CloudWeGo 最近也开源了一款新的产品 cwgo，它集成了 Hertz ， Kitex 以及 gorm-gen 这些代码生成东西，而且它供给了愈加丰厚的模板以及代码生成功用。

Easy Note——快速入门 CloudWeGo 生态

cwgo 项目链接：github.com/cloudwego/c…

能够拜访上方链接，去 GitHub 上看这个项目，这是一个 all-in-one 东西，结合了各个组件优势，十分的便利。而且它也支撑动态命令，简化用户的运用难度。

  1. demouser，demonote

接下来是 demouser 服务和 demonote 服务的开发流程，它们的开发流程十分的类似。

  • demouser

    • 利用 GORM 完结对用户的创立与查询
    • 完结用户创立，检查，查询的具体事务逻辑
    • 将服务注册进 etcd 以供其他服务调用

  • demonote

    • 利用 GORM 完结对笔记的增修改查
    • 经过 RPC 调用 demouser 服务获取用户信息
    • 完结笔记增修改查具体的事务逻辑
    • 将服务注册进 etcd 以供其他服务调用

  1. demoapi

最终，是demoapi服务的开发。

  • 运用 jwt，requestid，gzip，pprof 中间件
  • 完结用户注册登录功用
  • 经过 jwt 认证授权后的用户才能对笔记进行一系列操作
  • 经过 RPC 调用 demouser 和 demonote 服务完结事务逻辑
  • 回来呼应数据给前端。

代码细节

  1. 链路追寻

Hertz、 Kitex 与 GORM 都对 OpenTelemetry 扩展供给了支撑，供给 tracing 、metrics 以及 logging 的支撑。

Easy Note 项目中只运用了一个 Jaeger 进行事务上的链路追寻。一起咱们还能够经过 Gafana 面板进行观测。

Easy Note——快速入门 CloudWeGo 生态

在 Request ID 中间件里，咱们经过 trace ID 去替换掉默许的 Request ID，这样咱们就能够直接能够经过 HTTP 呼应头中的 X-Request-ID，获取到 trace ID。在 Jaeger 面板中能够对链路的信息进行查询。

  1. Kitex 中间件

前面说到，咱们界说了一个 server 端， client 端，以及 comment 中间件，而且它会以选项的模式去嵌入咱们的 Kitex。这儿咱们界说的中间件能够对 RPC 的调用信息以及其他的信息进行具体的输出。

Easy Note——快速入门 CloudWeGo 生态

  1. 过错码封装

咱们对过错码也进行了封装，能够预先在 thrift IDL 中界说过错码，这样 Kitex 会生成对应的代码，再去直接去运用就能够了。咱们能够去拟定一些过错类型与函数，能够去关于事务的异常进行转换，然后让过错处理一致化。

Easy Note——快速入门 CloudWeGo 生态

总结回忆

以上便是 Easy Note 的简略共享。

榜首部分咱们从 CloudWeGo 生态入门开端，谈到怎么去检查文档，以及 CloudWeGo 的一些扩展，最终咱们了解了一些怎么发问的 Tips。

第二部分去对 Hertz，Kitex 以及 GORM 这三个结构进简略的介绍。

最终咱们对 Easy Note 的架构、代码生成以及开发流程，从代码细节方面进行的解读，希望能够协助到我们对 Easy Note 以及 CloudWeGo 生态有一个更深的了解。

一起也十分欢迎我们为 Hertz，Kitex 以及 GORM 进行贡献代码，三者都是十分优异的开源项目。

  • github.com/cloudwego/h…

  • github.com/cloudwego/k…

  • github.com/go-gorm/gor…

  • kitex-contrib/obs-opentelemetry

  • hertz-contrib/obs-opentelemetry

  • kitex-contrib/xds

  • cloudwego/biz-demo:bookinfo

  • cloudwego/hertz-examples

  • cloudwego/kitex-examples

项目地址

  • GitHub：github.com/cloudwego

  • 官网：www.cloudwego.io

  • 【CSG 第四期】CloudWeGo 事务实践事例解读开端啦

活动链接：github.com/cloudwego/c…