From f52e790001b641f8500b02e0aa1751c00a0a55c7 Mon Sep 17 00:00:00 2001 From: kevin Date: Sat, 8 Aug 2020 13:40:11 +0800 Subject: [PATCH] update readme --- doc/goctl.md | 30 ++++++++--------- readme.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 109 insertions(+), 16 deletions(-) diff --git a/doc/goctl.md b/doc/goctl.md index e9c602d6..b8eea01a 100644 --- a/doc/goctl.md +++ b/doc/goctl.md @@ -10,13 +10,13 @@ #### goctl参数说明 `goctl api [go/java/ts] [-api user/user.api] [-dir ./src]` - + > api 后面接生成的语言，现支持go/java/typescript - + > -api 自定义api所在路径 - + > -dir 自定义生成目录 - + #### 保持goctl总是最新版 第一次运行会在~/.goctl里增加下面两行： @@ -51,7 +51,7 @@ type teacher struct { type ( address struct { - city string `json:"city"` // 城市 + city string `json:"city"` } innerType struct { @@ -60,8 +60,8 @@ type ( createRequest struct { innerType - name string `form:"name"` // niha - age int `form:"age,optional"` // nihaod + name string `form:"name"` + age int `form:"age,optional"` address []address `json:"address,optional"` } @@ -174,7 +174,7 @@ service user-api { ``` 生成的代码可以直接跑，有几个地方需要改： - + * 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等 * 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码 @@ -183,9 +183,9 @@ service user-api { #### 根据定义好的api文件生成typescript代码 `goctl api ts -api user/user.api -dir ./src -webapi ***` - - ts需要指定webapi所在目录 + ts需要指定webapi所在目录 + #### 根据定义好的api文件生成Dart代码 `goctl api dart -api user/user.api -dir ./src` @@ -209,22 +209,22 @@ type User struct { 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 [示例目录，可自己指定，强制覆盖更新] diff --git a/readme.md b/readme.md index 51c1e75a..76af03fe 100644 --- a/readme.md +++ b/readme.md @@ -61,4 +61,97 @@ go-zero是一个集成了各种工程实践的包含web和rpc框架，有如下 ## 5. go-zero近期开发计划 * 自动生成API mock server，便于客户端开发 -* 自动生成服务端功能测试 \ No newline at end of file +* 自动生成服务端功能测试 + +## 6. Installation + +1. 在项目目录下通过如下命令安装： + + ```shell + go get -u github.com/tal-tech/go-zero + ``` + +2. 代码里导入go-zero + + ```go + import "github.com/tal-tech/go-zero" + ``` + +## 7. Quick Start + +1. 编译goctl工具 + + ```shell + go build tools/goctl/goctl.go + ``` + + 把goctl放到$PATH的目录下，确保goctl可执行 + +2. 定义API文件，比如greet.api，可以在vs code里安装`goctl`插件，支持api语法 + + ```go + type Request struct { + Name string `path:"name"` + } + + type Response struct { + Message string `json:"message"` + } + + service greet-api { + @server( + handler: GreetHandler + ) + get /greet/from/:name(Request) returns (Response); + } + ``` + + 也可以通过goctl生成api模本文件，命令如下： + + ```shell + goctl api -o greet.api + ``` + +3. 生成go服务端代码 + + ```shell + goctl api go -api greet.api -dir greet + ``` + + 生成的文件结构如下： + + ``` + . + ├── greet + │   ├── etc + │   │   └── greet-api.json + │   ├── greet.go + │   └── internal + │   ├── config + │   │   └── config.go + │   ├── handler + │   │   ├── greethandler.go + │   │   └── routes.go + │   ├── logic + │   │   └── greetlogic.go + │   ├── svc + │   │   └── servicecontext.go + │   └── types + │   └── types.go + └── greet.api + + 8 directories, 9 files + ``` + + 生成的代码可以直接运行： + + ```shell + cd greet + go run greet.go -f etc/greet-api.json + ``` + + * 可以在servicecontext.go里面传递依赖给logic，比如mysql, redis等 + * 在api定义的get/post/put/delete等请求对应的logic里增加业务处理逻辑 + + 可以根据api文件生成前端需要的Java, TypeScript, Dart, JavaScript代码。 +