提示
该功能特性从 v2.5
版本开始提供。该命令目前仅支持 HTTP
接口开发, GRPC
部分请参考 gen pb
命令。未来会考虑 HTTP
及 GRPC
统一使用该命令生成控制器及 SDK
源代码。
基本介绍
解决痛点
在开发项目的时候,往往需要先根据业务需求和场景设计 API
接口,使用 proto
或者 golang struct
来设计 API
的输入和输出,随后再创建与 API
相对应的控制器实现,最后也有可能会提供 SDK
(同为 Golang
语言条件下)供内/外部服务调用。在开发过程中会遇到以下痛点:
- 重复性的代码工作较繁琐。在
API
中创建输入输出定义文件后还需要在控制器目录下创建对应的文件、创建对应的控制器初始化代码、从API
代码中反复拷贝各个输入输出结构名称,在这过程重复性的操作比较繁琐。 - API与控制器之间的关联没有可靠规范约束。除了
API
有一定的命名约束外,控制器的创建和方法命名并没有约束,灵活度较高,API
的结构名称与控制器方法名称难以约束对应,当接口越来越多时会有一定维护成本。 - 团队开发多人协作时代码文件冲突概率大。多人开发协作都往一个文件执行变更时,出现文件冲突的概率就会变大,团队协作开发中处理这种文件冲突的精力开销毫无意义。
- 缺少API的HTTP SDK自动生成工具。当开发完
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
接口示例: