You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
paopao-ce/docs/proposal/006-关于paopao-ce的结构设计.md

5.9 KiB

编号 作者 发表时间 变更时间 版本 状态
006 北野 2022-11-23 2022-01-01 v1.0 提议

关于paopao-ce的结构设计

本文档主要讨论paopao-ce目前的代码结构简要清晰的描述一个API请求接受解析->逻辑处理->结果响应的大概路径帮助开发人员快速了解paopao-ce代码基的基本面更好的融入paopao-ce的开发中做出PR贡献。

两种服务 - RESTful API服务 与 gRPC服务

paopao-ce提供RESTful API与gRPC两种类型子服务并且拥有单实例多服务运行的机制。RESTful API服务基于gin引擎实现,使用go-mir脚手架辅助工具集实现RESTFul API从接口定义到代码自动生成的便捷开发体验。 gRPC服务使用buf自动化辅助工具对gRPC服务从 *.proto DSL服务接口定义到接口代码自动生成的全流程管理。

结构说明

paopao-ce采用清晰的分层结构设计主要包括 接入层、业务逻辑层、数据逻辑层、数据存储

  • 接入层
    RESTful API服务的接入层由 gin引擎 与 go-mir生成的 Binding/Render 代码共同组成。当一个HTTP Request被http server接受后通过gin的路由机制,由相应的go-mir生成的Binding将请求解析后传入 业务逻辑层中相对应的 子服务Servants 完成业务处理后获得结果,go-mir生成的Render把结果渲染后生成对应的 HTTP Response发送出去以完成一个HTTP请求。
    gRPC服务的接入层由其对应的gRPC服务器引擎组成当一个RPC请求过来后先把请求解码解析后传入 业务逻辑层中相对应的 子服务Servers 完成业务处理后获得结果,将处理结果编码后生成对应的 HTTP Response发送出去就完成了一个RPC请求的完整流程。
  • 业务逻辑层
    RESTful API服务的业务逻辑层是由go-mir依据接口定义自动生成的Servants服务接口组成开发人员需要实现这些接口以提供相应的业务逻辑。gRPC也是一样的业务逻辑需要通过实现gRPC依据proto DSL定义接口自动生成的服务接口来提供相应业务处理服务。
  • 数据逻辑层
    paopao-ce将所有与数据存储相关的服务都统一定义成接口包括SQL服务、缓存服务、OBS服务、Search服务然后根据具体的部署环境选择适配的相应存储服务实现。比如OBS服务定义了统一的操作对象存储的服务接口然后提供阿里云、腾讯云、华为云、MinIO、S3、Localoss等的服务适配实现这样就可以根据不同的部署环境切换使用不同的对象存储服务实现。
  • 数据存储
    数据存储包括 SQL存储(MySQL/PostgreSQL/Sqlite3)、Cache、OBS、Search Engine(Zinc/Meilisearch)等paopao-ce本身不关心具体的数据存储是如何部署的一般是通过对应的标准方式连接部署实例以获取相应存储服务。

paopao-ce代码目录的说明

tree -L 2
.
|-- auto
|   |-- api
|   `-- rpc
|-- internal
|   |-- conf
|   |-- core
|   |-- dao
|   |-- ims
|   |-- migration
|   |-- model
|   |-- obs
|   |-- servants
|   `-- service
|-- main.go
|-- mirc
|-- proto
|-- release
`-- web
  • 根目录的mirc包含RESTful API的go-mir服务接口定义文件, auto/api目录包含go-mir自动生成的服务接口代码;
  • 目录proto包含gRPC的proto服务接口定义文件自动生成的服务接口代码包含在auto/rpc目录中;
  • 业务逻辑层的代码都包含在internal/servants目录包括RESTful服务以及gRPC服务的业务逻辑处理代码都包含在这个目录中
  • internal/core包含所有数据逻辑层的服务接口定义,相应的数据逻辑层服务接口实现代码都包含在internal/dao目录中;
  • 一些大的功能模块统一放置于internal目录中,以降低代码目录深度;比如数据库迁移功能模块migration的代码包含在internal/migration目录、 消息推送功能模块ims -> internal/ims, 简单本地OBS功能obs -> internal/obs 等;
  • internal/service目录包含paopao-ce所有子服务(WebAdminBotSpaceXMobile ...)的初始化逻辑代码;
  • internal/conf目录包含全局配置相关的逻辑代码;

疑问

  1. 为什么要引入go-mir?
    工欲善其事,必先利其器。为了RESTFul API的后端开发体验可以媲美gRPC本人特意打造go-mir v3版本来满足需求。go-mir是一套使用golang自身语言生态实现的RESTFul API从接口定义到代码自动生成的脚手架辅助工具集便捷的实现快速后端开发体验颇有 “程咬金的三板斧,简单抡着就完事” 的韵味。而从go-mir的官方文档参考也可以看出其生成的代码也确实就将一个HTTP的请求/响应简单分成 请求绑定->业务逻辑->结果渲染三个步骤去完成生成的代码结构简单清晰与gRPC的生成代码有点类似。
  2. 为什么要兼容RESTful服务与gRPC服务
    RESTful服务与gRPC服务各自有擅长的场景在合适的场景使用最适合的技术去做相应的适配这是paopao-ce秉持的代码开发原则之一。

更新记录

v0.0(2022-11-23) - 北野

  • 初始文档, 先占个位置

v0.1(2022-12-23) - 北野

  • 添加部分内容

v1.0(2023-01-01) - 北野

  • 添加部分内容