01
开发背景与功能概览
此外,组件各自的工具缺少一个全局视角,如果我们想开发一个完整的微服务项目的话,那么工具的代码生成就会涉及到若干个子命令和 flags,配合的复杂度较高,且在不断引入更多新能力后,复杂度将进一步提升。用户学习门槛会不断提高,削弱了用户的使用体验效果。
cwgo 就是围绕以上背景进行开发的,cwgo 是 CloudWeGo 社区提供的用于生成代码的一个命令行工具,它整合了包含了 hz、kitex 在内的各个组件的优势,覆盖了用户所需要的各类代码生成的需求,比如服务端/客户端生成代码,数据库生成代码等等,所以说 cwgo 是 CloudWeGo 社区提供的 All in One 的代码生成工具。cwgo 可以给用户提供全面的、完备的、易用的研发体验。
目前 cwgo 支持 thrift 和 protobuf 的 IDL 生成,支持 server 端和 client 端的代码生成,同时也支持 mysql 和mongodb 等 crud 的代码生成。cwgo 工具并不直接生成代码,而是构造好模板后调用相应工具的生成函数。比如server,client 命令,http 类型使用 hz 进行生成,rpc 类型使用 kitex 生成,mysql 代码通过 gorm/gen 生成,mongodb代码有些不同,它是通过 thriftgo/protoc 解析 IDL 后通过构建抽象语法树然后生成的代码。所以相对应工具的注意事项也需要遵守, 如生成 rpc 代码时 kitex 的注意事项和生成 http 代码时 hz 的注意事项。
02
服务端/客户端代码生成
cwgo 工具通过整合 hz/kitex 工具,从而支持使用 IDL (thrift/protobuf) 生成 Server/Client 端的代码,极大简化了项目开发的过程,提升了用户的体验。
在开发一个微服务项目时,只需通过执行三个命令,即可生成一个微服务项目所需要的桩代码。
cwgo server --type RPC
cwgo client --type RPC
cwgo server --type HTTP
cwgo 的服务端和客户端调用代码生成的功能主要是通过解析命令行参数然后透传给 hz/kitex 工具进行实现的,如果想使用 hz/kitex 的一些进阶参数有两种方式:一种是通过 pass 参数来把额外参数传递给 hz 或是 kitex,另一种是 cwgo 支持回退功能,允许回退为 kitex 或是 hz,对于用户存量的 Kitex/Hertz 项目,工具需要保持兼容。回退后,命令行工具表现将与 kitex 或 hz 保持一致,区别就是在前面加上了cwgo fallback。
cwgo server --type HTTP --pass "-handler_dir ./handler"
cwgo fallback hz new -module cwgo -idl hello.thrift
HTTP 项目目录如下:
cwgo 支持从本地或 git 中读取模板。其中 git 支持 https 或 ssh 的形式,通过 -template 指定模板路径,-branch 指定模板分支(默认为主分支)。cwgo 除了支持 go template 默认模板函数外,还集成了 sprig 模板扩展函数,进一步满足了用户需要高度定制模板的需求。
03
数据库代码生成
cwgo 的数据库代码生成能力包括两部分:
1. doc 命令生成 mongodb crud 代码
2. model 命令生成关系型数据库 sql 代码
其中,model 命令依赖 gorm/gen 工具生成代码,doc 命令基于 IDL 的注解以及 IDL 代码生成工具的插件机制生成代码。目前,IDL 支持 thrift 和 protobuf,底层使用的 IDL 代码生成工具为 thriftgo 和 protoc。
cwgo 集成了 gorm/gen 用于帮助用户生成 model 代码以及基础的 crud 代码,用户无需再自行封装繁琐的 crud 代码,极大的提高了用户的开发效率。用法示例如下:
cwgo model --db_type mysql --dsn "gorm:gorm@tcp(localhost:9910)/gorm?charset=utf8&parseTime=True&loc=Local"
doc 命令支持基于 IDL (thrift protobuf) 的注解以及 IDL 代码生成工具的插件机制来生成 mongodb 的 crud 代码,用户可以通过命令参数指定 idl 路径、代码生成的位置,若有其他需求,也可以将参数透传给底层的代码生成工具 thriftgo 或 protoc。
以 thrift 为例介绍 doc 命令的实践,在 thrift 文件中,struct 对应 mongodb 中的集合,用户除定义好结构体外,还需定义注解,有两种注解:字段注解和结构体注解。其中字段注解用于指明字段对应的 mongodb go tag,结构体注解由四部分组成:工具解析所用 token、函数名、入参、返回值。token 的编写需遵循工具的规则,例如,首单词为 Insert 表示插入数据,首单词为 Find 表示查询数据,函数名为生成的 crud 代码中对应的函数名,入参和返回值也需遵循工具的规则,通常与对应的 token 有关。
在如下给出了一个用户结构体,在结构体注解中给出了四个 token,代表增删改查四种操作,然后通过 cwgo doc 命令生成对应代码。
生成的代码结构如下所示,包含三部分内容:
user_repo.go:函数接口文件
user_repo_mongo.go:接口实现及具体 crud 代码
user.go:thriftgo 生成的桩代码,包含对应的结构体
其中,biz/doc/dao下的代码是 mongodb 的 crud 相关代码,这部分由 cwgo 借助 thriftgo 插件机制生成,biz/doc/model 下生成的是 idl 对应的桩代码,由 thriftgo 工具生成,这里面包含了 mongodb 集合对应的 go 结构体代码。
生成的部分代码产物如下所示:
此外,cwgo doc 提供了一个兜底处理:在现有生成代码不满足用户需求时使用基础 mongo 代码,可以为用户省去开发和测试 mongodb 公共库的时间。
04
未来展望
cwgo 项目地址:
https://github.com/cloudwego/cwgocwgo 项目文档:
https://www.cloudwego.io/zh/docs/cwgo/overview/