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

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

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

本文为 CSG 第四期第二场直播中CloudWeGo Reviewer 王伟超共享内容。

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

一、嘉宾介绍

运用 Kitex 和 Hertz 进行付出敞开渠道的开发演示，运用 CloudWeGo 完成 API Gateway ，参阅最佳实践，力求简洁、明晰得展示作用。

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

1. 布景介绍
2. 架构规划
3. 工程实践
4. 总结

二、布景介绍

这期主题是关于 Open Payment Platform，即付出敞开渠道事务，基于 CloudWeGo 来完成 API Gateway。

今天的共享会分 4 个部分，

• 榜首部分是编写 biz-demo 的布景；
• 第二部分从全体架构上来讲是怎样规划的；
• 第三部分共享详细的实践过程；
• 第四部分对本次共享做的小结。

项目布景

首先，在做这个 biz-demo 之前我一向有个疑问。这个疑问是从上一年 3 月份开端，其时刚接触到 Kitex 不久，了解到 Kitex 有泛化调用的特性，可是并不是很清楚这个特性有什么用、用在什么场景。 别的，咱们都知道微服务一般不直接在公网露出，那么公网或许用户普通的 HTTP 恳求是怎样到 RPC 恳求的呢？这个处理链路其时不是很明晰。

于是，我在 Github 提了一个评论：“关于泛化调用及怎样从集群外拜访详细的某服务”，后来也是很快得到社区小伙伴的反馈和回答。不过其时对此认识不是特别深，后续也是带着这个问题一向在了解这方面的知识。

直到上一年的 9 月份，咱们社区的广明说到想基于泛化调用做一个 biz-demo，我觉得这是一个很好的尝试，想借助这次时机很好的了解该特性。一边学习一边做输出，这是很好的学习方式，所以就有了后续的这个 demo。

付出敞开渠道

付出敞开渠道通常是敞开给服务商或商户供给收款记账等能力的服务进口，常见于付出宝、微信、银联等第三方或第四方付出渠道商，特别是前几年发展起来的聚合付出方向。

我做这个 demo 也是由于曾经做过第四方的付出，有接过很多的付出 SDK，所以稍会略微了解它的事务场景特点，详细分析如下。

• 榜首，它对外露出的是 HTTP 接口，结合咱们社区已有的项目，能够用 Hertz 来做别的一个敞开渠道。
• 第二，需求有加签、验签的功能，正好能够用 Hertz 的 Middleware 去自界说它的加签验签逻辑。
• 第三，也是特别重要的一点，即事务场景、事务模块很明晰，比方商户、付出、对账相关的安全鸿沟很详细，也十分适合咱们做事务、做微服务的拆分。
• 最终，关注工程化，比方 ORM、分包、代码分层、错误一致界说及优雅处理。比方分包在之前或许会比较简略、随意，这次也想能更多借鉴社区或许业内略微能达成共识的规划。

三、架构规划

全体架构

首先从全体的视点去看这个项目，如图所示：

1、左边用户建议了 HTTP 恳求，POST 方法，指定特定的服务途径参数，传了某些事务参数到了网关；

2、网关会判断它是要去到哪一个 RPC 微服务，然后用传递过来的参数，由泛化调用客户端，向 RPC 服务建议恳求。

在此之前，发动 hert-gateway 时，还有一个前置处理：解析了一切的 IDL 文件，生成了 RPC 服务 -> 泛化调用客户端 的映射联系，后续每个 RPC 服务都运用各自的一个客户端建议泛化调用。

综上，hert-gateway 接纳的是 HTTP 恳求，该恳求的 handler 是解析参数建议了一个 RPC 恳求到后端服务。 从全体代码结构上，整个项目如下

• 首先是 cmd，它是一切的 RPC 服务的进口。多个使用也能够加不同的目录做区别，这儿的代码很少，首要做使用发动、装备初始化、命令参数解析、依靠办理、底层结构强相关的初始化工作等等。
• configs 该 demo 初始化环境时的一些装备，现在这儿其实很简略，它创建了一个数据库，便利发动 demo 刺进数据，直接去演示。
• hertz-gateway，一切的网关逻辑放在了这儿。
• idl 则是将一切的文件都放在此处。IDL 文件要强调的是，现在 Kitex 支撑的泛化调用只支撑 thrift 协议，之前也有小伙伴提出疑问能不能支撑 gRPC，在咱们社区内也接到了反馈，后续会进行考虑或许做相关规划。
• internal 是一切 RPC 微服务的事务逻辑。
• kitex_gen 是根据 IDL 生成的 Kitex 客户端代码。
• pkg 是一些公共代码。

hertz-gateway

咱们详细看下 hertz-gateway ，基本上把一切的逻辑都在 biz 目录中。

biz 目录下再分如下几个目录：

• errors：标准错误处理。
• handler：分发用户端恳求，建议泛化调用到 RPC 服务的要害逻辑。
• middleware：这儿演示了签名的 middleware。
• router 由咱们 hertz 结构主动生成的目录。
• types 存放自界说的数据，如 HTTP 呼应体。
• main.go 程序进口。

整齐架构

在看 RPC 服务之前。咱们有必要简略介绍下整齐架构

这儿咱们着重强调下整齐架构的中心的理念：图中红圈是依靠的笼统接口，圈里包含 usercase 和 Entities，这是整个事务的中心。 详细来说的三个要点：

1. 独立于结构：体系的架构不应该与详细结构强绑定。
2. 可被测试：单测不能依靠外部存储或许环境，单测必须能在本地，只依靠自己的代码来快速运转。
3. 独立于数据库：不要写出强依靠你的存储组件的体系，底层的存储或许跟着事务增长而不再运用。

别的， 还有一句时间应该记住的话：“依靠笼统接口，不应该依靠详细完成“。这也是为什么依靠要显现地去注入，而不应该在你的事务逻辑中忽然 New 出一个目标的原因。

Payment Server

目录如下：

• makefile 放置了快速运转服务和开发时的常用命令。
• entity 即事务实体。
• usecase 中心的事务代码都会在这儿去做，其依靠的笼统接口会放在这儿界说。
• infrastructure，包含 ORM 和仓储层的详细完成。

四、工程实践

在介绍了整个架构规划、分包、工程理念之后，来看详细的实践过程。

• 榜首步，笼统事务和界说 IDL。
• 第二步，创建一个微服务模块（Payment Server）
• 第三步，微服务工程目录。
• 第四步，网关和敞开能力。
• 第五步，标准和细节调整。

笼统事务

刚刚也有说到，现在泛化调用只支撑 thrift 协议。这儿的 payment.thrift 以其间的一个接口为简略的演示：Unifypay 一致付出的接口，界说了它的入参和呼应体。

其间咱们看到 api.post / api.param 这些都是泛化调用时需求解析用到的注解，在官方文档也有更多详细的阐明。

完成微服务

usecase

刚刚界说 IDL，现在去完善事务逻辑。比方在这儿的场景，咱们依靠笼统接口，刺进订单记录，能够如下去做。

/internal/payment/usecase/service.go

interface

/internal/payment/usecase/interface.go

entity

下图是咱们界说的事务实体，这也是咱们的中心代码之一。

/internal/payment/entity/order.go

infrastructure

咱们用 ent 作为 ORM，一个刺进数据的代码如下：

/internal/payment/infrastructure/repository/order_sql.go

相关表规划放在单独的 ent 目录下

/internal/payment/infrastructure/ent/schema/order.go

网关

解析 IDL 并生成泛化调用客户端

网关的中心逻辑之一是：在服务发动时，怎样解析 IDL，怎样生成方法调用的客户端，怎样放在路由组里边。这一段代码体现的这些过程，咱们简略地介绍一下。

/hertz-gateway/router.go

• 第 3 行，界说一个路由组，它运用了网关签名的 middleware。
• 第 4 行，指定要遍历的 IDL 目录。
• 第 9 行，指定 RPC 服务的注册中心。
• 第 14 行，开端遍历解析 IDL。
• 第 17 行，解析详细的IDL，生成一个协议内容供给者。
• 第 22 行，结构 HTTP 类型的泛化调用策略。
• 到 26 行， 生成泛化调用的客户端，后续咱们便能够据此建议调用。

建议泛化调用

/hertz-gateway/biz/handler/gateway.go

这儿是咱们在接纳到用户恳求后，路由了 /gateway/:svc 的 handler，处理如下：

• 第 13 行，svc 参数告知咱们要恳求到的 RPC 服务名。
• 第 14 行，SvcMap 是咱们在发动服务时构建好的服务与泛化调用的客户端的映射联系。
• 从 16 – 19 行，构建泛化调用的恳求参数。
• 第 21 行，建议一个泛化调用并拿到呼应接口。

作用演示

1. 详见回放视频（“01:04:15”处）：meetings.feishu.cn/s/1iraydxgi…
2. 也可参阅 readme 过程进行操作：github.com/cloudwego/b…

暂时无法在飞书文档外展示此内容

五、总结

关于项目

榜首，该 demo 运用了 CloudWeGo 两个首要的项目 Kitex 和 Hertz。

第二，两个特性，泛化调用和整齐架构的中心理念。整齐架构简略易落地，对于大部分的事务笼统仍是有指导意义的。

最终，演示理念，简洁和明晰。

关于工程化

CloudWeGo 最近新开源 cwgo ，是 Open Payment Platform 后续的一个优化点，结合更多生态内项目做演示更有意义。

cwgo 能够自界说工程化的模板，也欢迎更多人来奉献。工程模板或许工程化目录，能够用 DDD，或许用新的一些理念做划分，欢迎我们一起来评论。

关于社区

最终共享一下我对社区的感触，我认为是自在、敞开、互相成果。

互相成果，当你参与一个开源社区，让更多人用到、看到你奉献的代码和文档，不仅是帮助了别人，更是成果了自己，有一种自豪感和荣誉感。一起也帮助社区壮大和健康成长，这是双赢的作用。

很多人不知道怎样来奉献，其实奉献也包含很多种。文档，是很适合上手入门的，demo 也是其间一种，其他还包含单元测试和布道。很多人特别想去做特性和缺点的开发，能够经过前几步，了解社区运作、开源协作方式，特别是经过这些途径了解现有项目，都是能够按部就班而来的。

在社区有一句话：做开源，把时间拉长，三年五年投入一件事。积沙成塔，积水成渊。

参阅

最终是以上内容的重要参阅

• 泛化调用 www.cloudwego.io/zh/docs/kit…
• Proposal：工程化模板或标准化的评论 github.com/cloudwego/k…
• Clean Architecture – The Dependency Rule codecoach.co.nz/clean-archi…

---

项目地址

• GitHub：github.com/cloudwego

• 官网：www.cloudwego.io

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

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