From 300b124e4233659c094780d3415a61819a22cddd Mon Sep 17 00:00:00 2001 From: Kevin Wan Date: Tue, 12 Jul 2022 23:16:40 +0800 Subject: [PATCH] docs: update goctl readme (#2136) --- tools/goctl/{goctl.md => readme-cn.md} | 59 +++------ tools/goctl/readme.md | 172 +++++++++++++++++++++++++ 2 files changed, 190 insertions(+), 41 deletions(-) rename tools/goctl/{goctl.md => readme-cn.md} (81%) create mode 100644 tools/goctl/readme.md diff --git a/tools/goctl/goctl.md b/tools/goctl/readme-cn.md similarity index 81% rename from tools/goctl/goctl.md rename to tools/goctl/readme-cn.md index e4178079..261a7caa 100644 --- a/tools/goctl/goctl.md +++ b/tools/goctl/readme-cn.md @@ -1,12 +1,14 @@ -# goctl使用 +# goctl -## goctl用途 +[English](readme.md) | 简体中文 + +## goctl 用途 * 定义api请求 * 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter) * 生成MySQL CURD 详情见[goctl model模块](model/sql) -## goctl使用说明 +## goctl 使用说明 ### goctl 参数说明 @@ -21,50 +23,41 @@ #### API 语法说明 ```golang - -info( - title: doc title - desc: > - doc description first part, - doc description second part< - version: 1.0 -) - type int userType -type user struct { +type user { name string `json:"user"` // 用户姓名 } -type student struct { +type student { name string `json:"name"` // 学生姓名 } -type teacher struct { +type teacher { } type ( - address struct { + address { city string `json:"city"` // 城市 } - innerType struct { + innerType { image string `json:"image"` } - createRequest struct { + createRequest { innerType name string `form:"name"` age int `form:"age,optional"` address []address `json:"address,optional"` } - getRequest struct { + getRequest { name string `path:"name"` age int `form:"age,optional"` } - getResponse struct { + getResponse { code int `json:"code"` desc string `json:"desc,omitempty"` address address `json:"address"` @@ -73,13 +66,6 @@ type ( ) service user-api { - @doc( - summary: user title - desc: > - user description first part, - user description second part, - user description second line - ) @server( handler: GetUserHandler group: user @@ -98,31 +84,22 @@ service user-api { group: profile ) service user-api { - @doc(summary: user title) - @server( - handler: GetProfileHandler - ) + @handler GetProfileHandler get /api/profile/:name(getRequest) returns(getResponse) - @server( - handler: CreateProfileHandler - ) + @handler CreateProfileHandler post /api/profile/create(createRequest) } service user-api { - @doc(summary: desc in one line) - @server( - handler: PingHandler - ) + @handler PingHandler head /api/ping() } ``` -1. info部分：描述了api基本信息，比如Auth，api是哪个用途。 -2. type部分：type类型声明和golang语法兼容。 +1. type部分：type类型声明和golang语法兼容。 3. service部分：service代表一组服务，一个服务可以由多组名称相同的service组成，可以针对每一组service配置group属性来指定service生成所在子目录。 - service里面包含api路由，比如上面第一组service的第一个路由，doc用来描述此路由的用途，GetProfileHandler表示处理这个路由的handler， + service里面包含api路由，比如上面第一组service的第一个路由，GetProfileHandler表示处理这个路由的handler， `get /api/profile/:name(getRequest) returns(getResponse)` 中get代表api的请求方式（get/post/put/delete）, `/api/profile/:name` 描述了路由path，`:name`通过 请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。 diff --git a/tools/goctl/readme.md b/tools/goctl/readme.md new file mode 100644 index 00000000..89aa7820 --- /dev/null +++ b/tools/goctl/readme.md @@ -0,0 +1,172 @@ +# goctl + +English | [简体中文](readme-cn.md) + +## goctl introduction + +* Define api requests +* Automatically generate golang (backend), java (iOS & Android), typescript (web & desktop app), dart (flutter) based on the defined api +* Generate MySQL CRUD, check [goctl model](model/sql) for details + +## goctl usage instructions + +### goctl parameter description + + `goctl api [go/java/ts] [-api user/user.api] [-dir ./src]` + + > api followed by the target language, now supports go/java/typescript + > + > -api the path to the api file + > + > -dir the target dir to generate in + +#### API syntax description + +```golang +type int userType + +type user { + name string `json:"user"` // user name +} + +type student { + name string `json:"name"` // student's name +} + +type teacher { +} + +type ( + address { + city string `json:"city"` // city + } + + innerType { + image string `json:"image"` + } + + createRequest { + innerType + name string `form:"name"` + age int `form:"age,optional"` + address []address `json:"address,optional"` + } + + getRequest { + name string `path:"name"` + age int `form:"age,optional"` + } + + getResponse { + code int `json:"code"` + desc string `json:"desc,omitempty"` + address address `json:"address"` + service int `json:"service"` + } +) + +service user-api { + @server( + handler: GetUserHandler + group: user + ) + get /api/user/:name(getRequest) returns(getResponse) + + @server( + handler: CreateUserHandler + group: user + ) + post /api/users/create(createRequest) +} + +@server( + jwt: Auth + group: profile +) +service user-api { + @handler GetProfileHandler + get /api/profile/:name(getRequest) returns(getResponse) + + @handler CreateProfileHandler + post /api/profile/create(createRequest) +} + +service user-api { + @handler PingHandler + head /api/ping() +} +``` + +1. type part: type declaration. +3. service part: service represents a set of services, a service can be composed of multiple groups of service with the same name, you can configure the group attribute for each group of service to specify the subdirectory where the service is generated. + service contains api routes, such as the first route of the first group of service above, GetProfileHandler indicates the handler that handles this route. + `get /api/profile/:name(getRequest) returns(getResponse)` where get represents the request method of the api (get/post/put/delete), `/api/profile/:name` describes the route path, `:name` is assigned by the + The request getRequest assigns a value to the property inside, and getResponse is the returned structure. + +#### api vscode plugin + +Developers can search for the api plugin for goctl in vscode and goland, which provides api syntax highlighting, syntax detection and formatting related functions. + + 1. support syntax highlighting and type navigation. + 2. syntax detection, formatting api will automatically detect where the api is written wrong, using vscode default formatting shortcut (option+command+F) or custom ones can be used. + 3. formatting (option+command+F), similar to code formatting, unified style support. + +#### Generate golang code based on the defined api file + + The command is as follows. + ```goctl api go -api user/user.api -dir user``` + +```Plain Text +. +├── 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 +``` + + +The generated code can be run directly, there are a few things that need to be changed. + +* Add some resources that need to be passed to logic in `servicecontext.go`, such as mysql, redis, rpc, etc. +* Add the code to handle the business logic in the handlers and logic of the defined get/post/put/delete requests + +#### Generate java code based on the defined api file + +```Plain Text +goctl api java -api user/user.api -dir . /src +``` + +#### Generate typescript code from the defined api file + +```Plain Text +goctl api ts -api user/user.api -dir . /src -webapi *** +``` + +ts needs to specify the directory where the webapi is located + +#### Generate Dart code based on the defined api file + +```Plain Text +goctl api dart -api user/user.api -dir . /src +``` \ No newline at end of file