当前适用的Go驱动的RPC代码生成工具。
- 100% Go语言
- 使用Go接口描述服务(包括结构体、方法、注释等)
- 生成服务器和客户端代码
- 可直接用于生产的模板(或复制并修改)
谁在使用Oto?
模板
这些模板已经在生产环境中使用。
- 有一些官方Oto模板
- Pace CLI工具是使用开源CLI模板生成的
学习
教程
安装项目:
go install github.com/pacedotdev/oto@latest
创建项目文件夹,并用Go接口编写服务定义:
// definitions/definitons.go
package definitions
// GreeterService 用于生成友好的问候语。
type GreeterService interface {
// Greet 生成一个问候语。
Greet(GreetRequest) GreetResponse
}
// GreetRequest 是GreeterService.Greet的请求对象。
type GreetRequest struct {
// Name 是要问候的人。
// example: "Mat Ryer"
Name string
}
// GreetResponse 是包含个人问候语的响应对象。
type GreetResponse struct {
// Greeting 是生成的问候语。
// example: "Hello Mat Ryer"
Greeting string
}
从otohttp下载模板
mkdir templates \
&& wget https://raw.githubusercontent.com/pacedotdev/oto/master/otohttp/templates/server.go.plush -q -O ./templates/server.go.plush \
&& wget https://raw.githubusercontent.com/pacedotdev/oto/master/otohttp/templates/client.js.plush -q -O ./templates/client.js.plush
使用oto
工具生成客户端和服务器:
mkdir generated
oto -template ./templates/server.go.plush \
-out ./generated/oto.gen.go \
-ignore Ignorer \
-pkg generated \
./definitions
gofmt -w ./generated/oto.gen.go ./generated/oto.gen.go
oto -template ./templates/client.js.plush \
-out ./generated/oto.gen.js \
-ignore Ignorer \
./definitions
- 运行
oto -help
获取这些标志的更多信息
用Go实现服务:
// greeter_service.go
package main
// GreeterService 用于生成友好的问候语。
type GreeterService struct{}
// Greet 生成一个问候语。
func (GreeterService) Greet(ctx context.Context, r GreetRequest) (*GreetResponse, error) {
resp := &GreetResponse{
Greeting: "Hello " + r.Name,
}
return resp, nil
}
使用生成的Go代码编写一个暴露服务器的main.go
:
// main.go
package main
func main() {
g := GreeterService{}
server := otohttp.NewServer()
server.Basepath = "/oto/"
generated.RegisterGreeterService(server, g)
http.Handle(server.Basepath, server)
log.Fatal(http.ListenAndServe(":8080", nil))
}
otohttp.Server
执行自己的路由,因此有一个Basepath
字段,你应该在路由处理程序时使用它。
使用生成的客户端在JavaScript中访问服务:
import { GreeterService } from "oto.gen.js";
const greeterService = new GreeterService();
greeterService
.greet({
name: "Mat",
})
.then((response) => alert(response.greeting))
.catch((e) => alert(e));
使用json
标签控制前端面向的名称
你可以使用json
标签控制JSON和前端代码中字段的名称:
// Thing 做某事。
type Thing struct {
SomeField string `json:"some_field"
}
SomeField
字段在json和前端代码中将显示为some_field
- 名称必须是有效的JavaScript字段名
指定额外的模板数据
你可以通过-params
标志为模板提供字符串:
oto \
-template ./templates/server.go.plush \
-out ./oto.gen.go \
-params "key1:value1,key2:value2" \
./path/to/definition
在模板中,你可以使用<%= params["key1"] %>
访问这些字符串。
注释元数据
可以在注释中为服务、方法、对象和字段包含额外的元数据。
// Thing 做某事。
// field: "value"
type Thing struct {
//...
}
Metadata["field"]
的值将是字符串value
。
- 值必须是有效的JSON(对于字符串,使用引号)
示例得到官方支持,但所有数据都可以通过Metadata
映射字段访问。
示例
要为字段提供示例值,你可以在注释中使用example:
前缀行。
// GreetRequest 是GreeterService.Greet的请求对象。
type GreetRequest struct {
// Name 是要问候的人。
// example: "Mat Ryer"
Name string
}
- 示例必须是有效的JSON
示例被提取并通过Field.Example
字段提供。
Open API
要处理Open API规范,你可能会发现这个命令很有用:
oto -template ./otohttp/templates/openapi.yaml.plush -out openapi.yaml -v -ignore Ignorer ./parser/testdata/services/pleasantries
贡献
特别感谢:
- @mgutz - 提供结构体标签支持
- @sethcenterbar - 提供注释元数据支持