mirror of
https://github.com/go-kratos/kratos.git
synced 2025-03-17 21:07:54 +02:00
add blademaster-pb.md (#91)
This commit is contained in:
Felix Hao
GitHub
parent
596e80c3f3
commit
60766fc104
@ -0,0 +1,76 @@
|
||||
# 介绍
|
||||
|
||||
基于proto文件可以快速生成`bm`框架对应的代码，提前需要准备以下工作：
|
||||
|
||||
* 安装`kratos tool protoc`工具，请看[kratos工具](kratos-tool.md)
|
||||
* 编写`proto`文件，示例可参考[kratos-demon内proto文件](https://github.com/bilibili/kratos-demo/blob/master/api/api.proto)
|
||||
|
||||
### kratos工具说明
|
||||
|
||||
`kratos tool protoc`工具可以生成`warden` `bm` `swagger`对应的代码和文档，想要单独生成`bm`代码只需加上`--bm`如：
|
||||
|
||||
```shell
|
||||
# generate BM HTTP
|
||||
kratos tool protoc --bm api.proto
|
||||
```
|
||||
|
||||
### proto文件说明
|
||||
|
||||
请注意想要生成`bm`代码，需要特别在`proto`的`service`内指定`google.api.http`配置，如下：
|
||||
|
||||
```go
|
||||
service Demo {
|
||||
rpc SayHello (HelloReq) returns (.google.protobuf.Empty);
|
||||
rpc SayHelloURL(HelloReq) returns (HelloResp) {
|
||||
option (google.api.http) = { // 该配置指定SayHelloURL方法对应的url
|
||||
get:"/kratos-demo/say_hello" // 指定url和请求方式为GET
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
# 使用
|
||||
|
||||
建议在项目`api`目录下编写`proto`文件及生成对应的代码，可参考[kratos-demo内的api目录](https://github.com/bilibili/kratos-demo/tree/master/api)。
|
||||
|
||||
执行命令后生成的`api.bm.go`代码，注意其中的`type DemoBMServer interface`和`RegisterDemoBMServer`，其中：
|
||||
|
||||
* `DemoBMServer`接口，包含`proto`文件内配置了`google.api.http`选项的所有方法
|
||||
* `RegisterDemoBMServer`方法提供注册`DemoBMServer`接口的实现对象，和`bm`的`Engine`用于注册路由
|
||||
* `DemoBMServer`接口的实现，一般为`internal/service`内的业务逻辑代码，需要实现`DemoBMServer`接口
|
||||
|
||||
使用`RegisterDemoBMServer`示例代码请参考[kratos-demo内的http](https://github.com/bilibili/kratos-demo/blob/master/internal/server/http/server.go)内的如下代码：
|
||||
|
||||
```go
|
||||
engine = bm.DefaultServer(hc.Server)
|
||||
pb.RegisterDemoBMServer(engine, svc)
|
||||
initRouter(engine)
|
||||
```
|
||||
|
||||
`internal/service`内的`Service`结构实现了`DemoBMServer`接口可参考[kratos-demo内的service](https://github.com/bilibili/kratos-demo/blob/master/internal/service/service.go)内的如下代码：
|
||||
|
||||
```go
|
||||
// SayHelloURL bm demo func.
|
||||
func (s *Service) SayHelloURL(ctx context.Context, req *pb.HelloReq) (reply *pb.HelloResp, err error) {
|
||||
reply = &pb.HelloResp{
|
||||
Content: "hello " + req.Name,
|
||||
}
|
||||
fmt.Printf("hello url %s", req.Name)
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
# 文档
|
||||
|
||||
基于同一份`proto`文件还可以生成对应的`swagger`文档，运行命令如下：
|
||||
|
||||
```shell
|
||||
# generate swagger
|
||||
kratos tool protoc --swagger api.proto
|
||||
```
|
||||
|
||||
该命令将生成对应的`swagger.json`文件，可用于`swagger`工具通过WEBUI的方式打开使用，可运行命令如下：
|
||||
|
||||
```shell
|
||||
kratos tool swagger serve api/api.swagger.json
|
||||
```
|
||||
@ -61,7 +61,8 @@ kratos new kratos-demo -o YourName -d YourPath
|
||||
kratos new kratos-demo -o YourName -d YourPath --proto
|
||||
```
|
||||
|
||||
> 特别注意，如果不是MacOS系统，需要自己进行手动安装protoc，用于生成的示例项目`api`目录下的`proto`文件并不会自动生成对应的`.pb.go`和`.bm.go`文件。
|
||||
> 特别注意，如果不是MacOS系统，需要自己进行手动安装protoc，用于生成的示例项目`api`目录下的`proto`文件并不会自动生成对应的`.pb.go`和`.bm.go`文件。
|
||||
|
||||
> 也可以参考以下说明进行生成：[protoc说明](protoc.md)
|
||||
|
||||
# kratos build & run
|
||||
@ -72,7 +73,7 @@ kratos new kratos-demo -o YourName -d YourPath --proto
|
||||
|
||||
`kratos tool`是基于proto生成http&grpc代码，生成缓存回源代码，生成memcache执行代码，生成swagger文档等工具集，先看下的执行效果：
|
||||
|
||||
```shell
|
||||
```
|
||||
kratos tool
|
||||
|
||||
swagger(已安装): swagger api文档 Author(goswagger.io) [2019/05/05]
|
||||
@ -85,26 +86,28 @@ kratos(已安装): Kratos工具集本体 Author(kratos) [2019/04/02]
|
||||
|
||||
详细文档： https://github.com/bilibili/kratos/blob/master/doc/wiki-cn/kratos-tool.md
|
||||
```
|
||||
|
||||
> 小小说明：如未安装工具，第一次运行也可自动安装，不需要特别执行install
|
||||
|
||||
目前已经集成的工具有：
|
||||
|
||||
* kratos 为本体工具，只用于安装更新使用；
|
||||
* protoc 用于快速生成gRPC、HTTP、Swagger文件，该命令Windows，Linux用户需要手动安装 protobuf 工具。
|
||||
* swagger 用于显示自动生成的HTTP API接口文档，通过 `kratos tool swagger serve api/api.swagger.json` 可以查看文档。
|
||||
|
||||
### kratos tool protoc
|
||||
|
||||
```
|
||||
// generate all
|
||||
```shell
|
||||
# generate all
|
||||
kratos tool protoc api.proto
|
||||
// generate gRPC
|
||||
# generate gRPC
|
||||
kratos tool protoc --grpc api.proto
|
||||
// generate BM HTTP
|
||||
# generate BM HTTP
|
||||
kratos tool protoc --bm api.proto
|
||||
// generate swagger
|
||||
# generate swagger
|
||||
kratos tool protoc --swagger api.proto
|
||||
```
|
||||
执行对应生成 `api.pb.go/api.bm.go/api.swagger.json` 源文档。
|
||||
执行对应生成 `api.pb.go/api.bm.go/api.swagger.json` 源文档。
|
||||
|
||||
> 该工具在Windows/Linux下运行，需提前安装好 protobuf 工具
|
||||
|
||||
@ -114,22 +117,24 @@ kratos tool protoc --swagger api.proto
|
||||
export $KRATOS_HOME = kratos路径
|
||||
export $KRATOS_DEMO = 项目路径
|
||||
|
||||
// 生成：api.pb.go
|
||||
# 生成：api.pb.go
|
||||
protoc -I$GOPATH/src:$KRATOS_HOME/tool/protobuf/pkg/extensions:$KRATOS_DEMO/api --gogofast_out=plugins=grpc:$KRATOS_DEMO/api $KRATOS_DEMO/api/api.proto
|
||||
|
||||
// 生成：api.bm.go
|
||||
# 生成：api.bm.go
|
||||
protoc -I$GOPATH/src:$KRATOS_HOME/tool/protobuf/pkg/extensions:$KRATOS_DEMO/api --bm_out=$KRATOS_DEMO/api $KRATOS_DEMO/api/api.proto
|
||||
|
||||
// 生成：api.swagger.json
|
||||
# 生成：api.swagger.json
|
||||
protoc -I$GOPATH/src:$KRATOS_HOME/tool/protobuf/pkg/extensions:$KRATOS_DEMO/api --bswagger_out=$KRATOS_DEMO/api $KRATOS_DEMO/api/api.proto
|
||||
```
|
||||
|
||||
大家也可以参考该命令进行`proto`生成，也可以参考[protobuf](https://github.com/google/protobuf)官方参数。
|
||||
大家也可以参考该命令进行`proto`生成，也可以参考[protobuf](https://github.com/google/protobuf)官方参数。
|
||||
|
||||
### kratos tool swagger
|
||||
|
||||
kratos tool swagger
|
||||
```shell
|
||||
kratos tool swagger serve api/api.swagger.json
|
||||
```
|
||||
|
||||
执行命令后，浏览器会自动打开swagger文档地址。
|
||||
同时也可以查看更多的 [go-swagger](https://github.com/go-swagger/go-swagger) 官方参数进行使用。
|
||||
|
||||
|
||||
@ -51,7 +51,7 @@ var (
|
||||
_tplTypeGomod: "/go.mod",
|
||||
_tplTypeMain: "/cmd/main.go",
|
||||
_tplTypeDao: "/internal/dao/dao.go",
|
||||
_tplTypeHTTPServer: "/internal/server/http/http.go",
|
||||
_tplTypeHTTPServer: "/internal/server/http/server.go",
|
||||
_tplTypeService: "/internal/service/service.go",
|
||||
_tplTypeModel: "/internal/model/model.go",
|
||||
// init config
|
||||
|
||||
@ -91,7 +91,7 @@ func (t *bm) generateFileHeader(file *descriptor.FileDescriptorProto, pkgName st
|
||||
// doc for the first file
|
||||
t.P("/*")
|
||||
t.P("Package ", t.GenPkgName, " is a generated blademaster stub package.")
|
||||
t.P("This code was generated with kratos/tool/bmgen/protoc-gen-bm ", generator.Version, ".")
|
||||
t.P("This code was generated with kratos/tool/protobuf/protoc-gen-bm ", generator.Version, ".")
|
||||
t.P()
|
||||
comment, err := t.Reg.FileComments(file)
|
||||
if err == nil && comment.Leading != "" {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user