From d58f22e1d1c9a59d0bbfe03090a4eea0d5d1931e Mon Sep 17 00:00:00 2001 From: kevin Date: Mon, 27 Jul 2020 22:40:32 +0800 Subject: [PATCH] add goctl doc --- doc/goctl.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 doc/goctl.md diff --git a/doc/goctl.md b/doc/goctl.md new file mode 100644 index 00000000..e9c602d6 --- /dev/null +++ b/doc/goctl.md @@ -0,0 +1,265 @@ +# goctl使用说明 + +## goctl用途 +* 定义api请求 +* 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter) +* 生成MySQL CURD (https://goctl.xiaoheiban.cn) +* 生成MongoDB CURD (https://goctl.xiaoheiban.cn) + +## goctl使用说明 +#### goctl参数说明 + + `goctl api [go/java/ts] [-api user/user.api] [-dir ./src]` + + > api 后面接生成的语言，现支持go/java/typescript + + > -api 自定义api所在路径 + + > -dir 自定义生成目录 + +#### 保持goctl总是最新版 + + 第一次运行会在~/.goctl里增加下面两行： + + ``` + url = http://47.97.184.41:7777/ + ``` + +#### API 语法说明 + +``` +info( + title: doc title + desc: > + doc description first part, + doc description second part< + version: 1.0 +) + +type int userType + +type user struct { + name string `json:"user"` // 用户姓名 +} + +type student struct { + name string `json:"name"` // 学生姓名 +} + +type teacher struct { +} + +type ( + address struct { + city string `json:"city"` // 城市 + } + + innerType struct { + image string `json:"image"` + } + + createRequest struct { + innerType + name string `form:"name"` // niha + age int `form:"age,optional"` // nihaod + address []address `json:"address,optional"` + } + + getRequest struct { + name string `path:"name"` + age int `form:"age,optional"` + } + + getResponse struct { + code int `json:"code"` + desc string `json:"desc,omitempty"` + address address `json:"address"` + service int `json:"service"` + } +) + +service user-api { + @doc( + summary: user title + desc: > + user description first part, + user description second part, + user description second line + ) + @server( + handler: GetUserHandler + folder: user + ) + get /api/user/:name(getRequest) returns(getResponse) + + @server( + handler: CreateUserHandler + folder: user + ) + post /api/users/create(createRequest) +} + +@server( + jwt: Auth + folder: profile +) +service user-api { + @doc(summary: user title) + @server( + handler: GetProfileHandler + ) + get /api/profile/:name(getRequest) returns(getResponse) + + @server( + handler: CreateProfileHandler + ) + post /api/profile/create(createRequest) +} + +service user-api { + @doc(summary: desc in one line) + @server( + handler: PingHandler + ) + head /api/ping() +} +``` +1. info部分：描述了api基本信息，比如Auth，api是哪个用途。 +2. type部分：type类型声明和golang语法兼容。 +3. service部分：service代表一组服务，一个服务可以由多组名称相同的service组成，可以针对每一组service配置jwt和auth认证，另外通过folder属性可以指定service生成所在子目录。 + service里面包含api路由，比如上面第一组service的第一个路由，doc用来描述此路由的用途，GetProfileHandler表示处理这个路由的handler， + `get /api/profile/:name(getRequest) returns(getResponse)` 中get代表api的请求方式（get/post/put/delete）, `/api/profile/:name` 描述了路由path，`:name`通过 + 请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。 + +#### api vscode插件 +开发者可以在vscode中搜索goctl的api插件，它提供了api语法高亮，语法检测和格式化相关功能。 + + 1. 支持语法高亮和类型导航。 + 2. 语法检测，格式化api会自动检测api编写错误地方，用vscode默认的格式化快捷键(option+command+F)或者自定义的也可以。 + 3. 格式化(option+command+F)，类似代码格式化，统一样式支持。 + +#### 根据定义好的api文件生成golang代码 + + 命令如下： + `goctl api go -api user/user.api -dir user` + + ``` + + . + ├── internal + │   ├── config + │   │   └── config.go + │   ├── handler + │   │   ├── pinghandler.go + │   │   ├── profile + │   │   │   ├── createprofilehandler.go + │   │   │   └── getprofilehandler.go + │   │   ├── routes.go + │   │   └── user + │   │   ├── createuserhandler.go + │   │   └── getuserhandler.go + │   ├── logic + │   │   ├── pinglogic.go + │   │   ├── profile + │   │   │   ├── createprofilelogic.go + │   │   │   └── getprofilelogic.go + │   │   └── user + │   │   ├── createuserlogic.go + │   │   └── getuserlogic.go + │   ├── svc + │   │   └── servicecontext.go + │   └── types + │   └── types.go + └── user.go + + ``` + 生成的代码可以直接跑，有几个地方需要改： + + * 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等 + * 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码 + +#### 根据定义好的api文件生成java代码 + `goctl api java -api user/user.api -dir ./src` + +#### 根据定义好的api文件生成typescript代码 + `goctl api ts -api user/user.api -dir ./src -webapi ***` + + ts需要指定webapi所在目录 + +#### 根据定义好的api文件生成Dart代码 + `goctl api dart -api user/user.api -dir ./src` + +## 根据定义好的简单go文件生成mongo代码文件(仅限golang使用) + `goctl model mongo -src {{yourDir}}/xiao/service/xhb/user/model/usermodel.go -cache yes` + + -src需要提供简单的usermodel.go文件，里面只需要提供一个结构体即可 + -cache 控制是否需要缓存 yes=需要 no=不需要 + src 示例代码如下 + ``` +package model + +type User struct { + Name string `o:"find,get,set" c:"姓名"` + Age int `o:"find,get,set" c:"年纪"` + School string `c:"学校"` +} + ``` + 结构体中不需要提供Id,CreateTime,UpdateTime三个字段，会自动生成 + 结构体中每个tag有两个可选标签 c 和 o + c是改字段的注释 + o是改字段需要生产的操作函数 可以取得get,find,set 分别表示生成返回单个对象的查询方法，返回多个对象的查询方法，设置该字段方法 + 生成的目标文件会覆盖该简单go文件 + +## goctl rpc生成 + + 命令 `goctl rpc proto -proto ${proto} -service ${serviceName} -project ${projectName} -dir ${directory} -shared ${shared}` + 如： `goctl rpc proto -proto test.proto -service test -project xjy -dir .` + + 参数说明： + + - ${proto}: proto文件 + - ${serviceName}: rpc服务名称 + - ${projectName}: 所属项目，如xjy,xhb,crm,hera，具体查看help，主要为了根据不同项目服务往redis注册key，可选 + - ${directory}: 输出目录 + - ${shared}: shared文件生成目录，可选，默认为${pwd}/shared + + 生成目录结构示例： + + ``` go + . + ├── shared [示例目录，可自己指定，强制覆盖更新] + │   └── contentservicemodel.go + ├── test + │   ├── etc + │   │   └── test.json + │   ├── internal + │   │   ├── config + │   │   │   └── config.go + │   │   ├── handler [强制覆盖更新] + │   │   │   ├── changeavatarhandler.go + │   │   │   ├── changebirthdayhandler.go + │   │   │   ├── changenamehandler.go + │   │   │   ├── changepasswordhandler.go + │   │   │   ├── changeuserinfohandler.go + │   │   │   ├── getuserinfohandler.go + │   │   │   ├── loginhandler.go + │   │   │   ├── logouthandler.go + │   │   │   └── testhandler.go + │   │   ├── logic + │   │   │   ├── changeavatarlogic.go + │   │   │   ├── changebirthdaylogic.go + │   │   │   ├── changenamelogic.go + │   │   │   ├── changepasswordlogic.go + │   │   │   ├── changeuserinfologic.go + │   │   │   ├── getuserinfologic.go + │   │   │   ├── loginlogic.go + │   │   │   └── logoutlogic.go + │   │   └── svc + │   │   └── servicecontext.go + │   ├── pb + │   │   └── test.pb.go + │   └── test.go [强制覆盖更新] + └── test.proto + ``` + - 注意 ：目前rpc目录生成的proto文件暂不支持import外部proto文件 +* 如有不理解的地方，随时问Kim/Kevin \ No newline at end of file