快速开始

cwgo 是 CloudWeGo All in one 代码生成工具，整合了各个组件的优势，提高开发者提体验。

准备 Golang 开发环境

  1. 如果您之前未搭建 Golang 开发环境， 可以参考 Golang 安装
  2. 推荐使用最新版本的 Golang，我们保证最新两个正式版本的兼容性(现在 >= v1.18)。
  3. 确保打开 go mod 支持 (Golang >= 1.15时，默认开启)
  4. cwgo 暂时没有针对 Windows 做支持，如果本地开发环境是 Windows 建议使用 WSL2

在完成环境准备后，接下来将帮助你快速上手 cwgo。

安装 cwgo 工具

$ go install github.com/cloudwego/cwgo@latest

用 go 命令来安装是最简单的，你也可以选择自己从源码构建和安装。要查看 cwgo 的安装位置，可以用：

$ go list -f {{.Target}} github.com/cloudwego/cwgo

要使用 thrift 或 protobuf 的 IDL 生成代码，需要安装相应的编译器：thriftgo 或 protoc。

thriftgo 安装：

$ GO111MODULE=on go install github.com/cloudwego/thriftgo@latest

protoc 安装

# brew 安装
$ brew install protobuf 


# 官方镜像安装，以 macos 为例
$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.4/protoc-3.19.4-osx-x86_64.zip
$ unzip protoc-3.19.4-osx-x86_64.zip
$ cp bin/protoc /usr/local/bin/protoc
# 确保 include/google 放入 /usr/local/include下
$ cp -r include/google /usr/local/include/google

首先，我们需要安装使用本示例所需要的命令行代码生成工具：

  1. 确保 GOPATH 环境变量已经被正确地定义（例如 export GOPATH=~/go）并且将$GOPATH/bin添加到 PATH 环境变量之中（例如 export PATH=$GOPATH/bin:$PATH）；请勿将 GOPATH 设置为当前用户没有读写权限的目录
  2. 安装 cwgo：go install github.com/cloudwego/cwgo@latest
  3. 安装 thriftgo：go install github.com/cloudwego/thriftgo@latest

安装成功后，执行 cwgo --version 和 thriftgo --version 应该能够看到具体版本号的输出（版本号有差异，以 x.x.x 示例）：

$ cwgo --version
vx.x.x

$ thriftgo --version
vx.x.x

$ protoc --version
libprotoc x.x.x

确定代码放置位置

  1. 若将代码放置于 $GOPATH/src 下，需在 $GOPATH/src 下创建额外目录，进入该目录后再获取代码：
$ mkdir -p $(go env GOPATH)/src/github.com/cloudwego
$ cd $(go env GOPATH)/src/github.com/cloudwego
  1. 若将代码放置于 GOPATH 之外，可直接获取

注意事项

cwgo 底层使用 kitex、hz、gen 工具，所以其相应的工具规范也需要遵守，如 kitex 的注意事项和 hz 的注意事项。

使用

cwgo 的具体使用请参考命令行工具

下面以 thrift 为例

  1. 首先创建一个目录
$ mkdir -p $GOPATH/src/local/cwgo_test
$ cd $GOPATH/src/local/cwgo_test
  1. 创建一个 idl 目录
$ mkdir idl
  1. 编写 idl/hello.thrift 文件
# idl/hello.thrift
namespace go hello.example

struct HelloReq {
    1: string Name (api.query="name"); // 添加 api 注解为方便进行参数绑定
}

struct HelloResp {
    1: string RespBody;
}

service HelloService {
    HelloResp HelloMethod(1: HelloReq request) (api.get="/hello");
}
  1. 生成项目 layout

静态命令行

$ cwgo server -service=a.b.c -type HTTP  -idl=idl/hello.thrift

动态命令行

动态命令行

  1. 编译运行
$ go mod tidy && go mod verify
$ sh build.sh && sh output/bootstrap.sh
  1. 发起调用
$ curl http://127.0.0.1:8080/ping
pong

恭喜你！至此你成功编写了一个 Cwgo 的服务端，并完成了一次调用！


最后修改 July 13, 2023 : docs: update code example in kitex-generic call (#711) (f80b346)