该功能特性从 |
在开发项目的时候,往往需要先根据业务需求和场景设计API
接口,使用proto
或者golang struct
来设计API
的输入和输出,随后再创建与API
相对应的控制器实现,最后也有可能会提供SDK
(同为Golang
语言条件下)供内/外部服务调用。在开发过程中会遇到以下痛点:
API
中创建输入输出定义文件后还需要在控制器目录下创建对应的文件、创建对应的控制器初始化代码、从API
代码中反复拷贝各个输入输出结构名称,在这过程重复性的操作比较繁琐。API
有一定的命名约束外,控制器的创建和方法命名并没有约束,灵活度较高,API
的结构名称与控制器方法名称难以约束对应,当接口越来越多时会有一定维护成本。API
后,往往需要立即给内部或者外部调用,缺少便捷的SDK
生成,需要手动来维护这部分SDK
代码,那么对于调用端来说成本非常高。API
定义与控制器文件命名、控制器实现方法命名。API
定义与控制器代码之间的关联关系,便于快速定位API
实现。API
定义自动生成控制器接口、控制器初始化文件及代码、接口初始化代码。API
定义自动生成易于使用的HTTP SDK
代码。该功能可配置,默认关闭。File Watch
自动化生成模式:当某个API
结构定义文件发生变化时,自动增量化更新对应的控制器、SDK
代码。该命令的目的之一是规范化api
代码的编写,那么我们应该有一些重要的规范需要了解(否则生成不了代码哦):
api
层的接口定义文件路径需要满足/api/模块/版本/定义文件.go
,例如:/api/user/v1/user.go
、/api/user/v1/user_delete.go
、etc.API
的模块划分,我们可以将API
按照不同的业务属性进行拆分方便聚合维护。你也可以将模块认为是具体的业务资源。v1
/v2
..这样的形式来定义,用以API
兼容性的版本控制。当相同的API
出现兼容性更新时,需要通过不同版本号来区分。默认使用v1
来管理第一个版本。API
的输入输出定义文件,通常每个API
需要单独定义一个go
文件来独立维护。当然也支持将多个API
放到一个go
文件中统一维护。api
定义的结构体名称需要满足操作+Req
及操作+Res
的命名方式。例如:GetOneReq/GetOneRes
、GetListReq/GetListRes
、DeleteReq/DeleteRes
、etc.API
模块的操作名称,通常对应CURD
是:Create
、Update
、GetList/GetOne
、Delete
。以下是项目工程模板中的Hello
接口示例:
我们对一些常用的接口定义做了一些建议性的命名,供大家参考:
操作名称 | 建议命名 | 备注 |
---|---|---|
查询列表 | GetListReq/Res | 通常是从数据库中分页查询数据记录 |
查询详情 | GetOneReq/Res | 通常接口需要传递主键条件,从数据库中查询记录详情 |
创建资源 | CreateReq/Res | 通常是往数据表中插入一条或多条数据记录 |
修改资源 | UpdateReq/Res | 通常是按照一定条件修改数据表中的一条或多条数据记录 |
删除资源 | DeleteReq/Res | 通常是按照一定条件删除数据表中的一条或多条数据记录 |
该命令通过分析给定的api
接口定义目录下的代码,自动生成对应的控制器/SDK Go
代码文件。
如果是手动执行命令行,直接在项目根目录下执行 gf gen ctrl
即可,她将完整扫描api
接口定义目录,并生成对应代码。
$ gf gen ctrl -h USAGE gf gen ctrl [OPTION] OPTION -s, --srcFolder source folder path to be parsed. default: api -d, --dstFolder destination folder path storing automatically generated go files. default: internal/controller -w, --watchFile used in file watcher, it re-generates go files only if given file is under srcFolder -k, --sdkPath also generate SDK go files for api definitions to specified directory -v, --sdkStdVersion use standard version prefix for generated sdk request path -n, --sdkNoV1 do not add version suffix for interface module name if version is v1 -c, --clear auto delete generated and unimplemented controller go files if api definitions are missing -m, --merge generate all controller files into one go file by name of api definition source go file -h, --help more information about this command EXAMPLE gf gen ctrl |
如果使用框架推荐的项目工程脚手架,并且系统安装了 |
参数说明:
名称 | 必须 | 默认值 | 含义 |
---|---|---|---|
srcFolder | 否 | api | 指向api 接口定义文件目录地址 |
dstFolder | 否 | internal/controller | 指向生成的控制器文件存放目录 |
watchFile | 否 | 用在IDE的文件监控中,用于根据当文件发生变化时自动执行生成操作 | |
sdkPath | 否 | 如果需要生成HTTP SDK ,该参数用于指定生成的SDK代码目录存放路径 | |
sdkStdVersion | 否 | false | 生成的 |
sdkNoV1 | 否 | false | 生成的HTTP SDK 中,当接口为v1 版本时,接口模块名称是否不带V1 后缀。 |
| 否 | false | 是否删除controller 中与api 层定义不存在的控制器接口文件。 |
| 否 | false | 用以控制生成的 |
如果您是使用的GolandIDE
,那么可以使用我们提供的配置文件:watchers.xml 自动监听代码文件修改时自动生成接口文件。使用方式,如下图:
HTTP SDK
代码文件api
接口生成一个controller
文件而不是合并到一个controller
文件中当然,针对小型项目或者个人简单项目、一个api
模块只有几个接口的项目而言,管理的方式并不会成为什么问题,可以根据个人喜好维护代码文件即可。我们这里以较复杂的业务项目,或者企业级项目,在一个api
模块的接口比较多的场景来展开描述一下。
api
接口时,查找api
接口实现更加清晰,而不是在一个动则上千行的代码文件中查找。controller
文件在版本管理中容易出现文件冲突。一个api
接口对应一个controller
实现文件的维护方式能最大减少代码协作时的文件冲突概率,大部分开发者也不希望花费自己宝贵的时间一次又一次地解决文件冲突上。controller
层的代码有它自身的职责:controller
中实现接口逻辑,或者调用一个或多个service
接口、第三方服务接口来实现接口逻辑。注意事项,不能在service
层的接口中去实现api
接口逻辑,因为api
接口是与具体的业务场景绑定的,无法复用。💀大部分常见的错误是controller
直接把请求透传给service
接口来实现api
接口逻辑,造成了controller
看起来可有可无、service
层的实现越来越重且无法复用。💀controller
的代码也是比较复杂,分开维护能减少开发者心智负担、易于清晰维护api
接口实现逻辑。一些建议:
如果一个api
模块下的接口文件太多,建议将复杂的api
模块进一步划分为子模块。这样可以对复杂的api
模块进行解耦,也能通过多目录的方式来维护api
接口定义和controller
接口实现文件。目录结构会更清晰,更利于多人协作和版本管理。
看完以上关于对此的设计后,如果您仍然想使用单源码文件来管理所有接口,可以参考merge
参数。
api
模块生成对应的controller
模块中为何存在一个空的go
文件例如:
说明:
每个api
模块会生成一个空的该模块controller
下的go
文件,该文件只会生成一次,用户可以在里面填充必要的预定义代码内容,例如,该模块controller
内部使用的变量、常量、数据结构定义,或者包初始化init
方法定义等等。我们提倡好的代码管理习惯,模块下的预定义内容尽量统一维护到该模块下以模块名称命名的go
文件中(模块.go
),而不是分散到各个go
文件中,以便于更好地维护代码。
如果该controller
目前没有需要自定义填充的代码内容,那么保留该文件为空即可,为未来预留扩展能力。