API 与用户的通信协议，通常是 REST API 和 RPC API 作为传输层协议，而 Kratos 主要参考 Google API 指南，实现了对应通信协议支持，并且遵守了 gRPC API 使用 HTTP 映射功能进行 JSON/HTTP 的支持。

也就是通过定义 proto 即可使用 REST API 和 RPC API，通过类似 Google API 的仓库方式进行 API Schema 的管理。

定义接口

通过 Protobuf IDL 定义对应的 REST API 和 gRPC API：

api/helloworld/v1/greeter.proto

  1. syntax = "proto3";
  3. package helloworld.v1;
  5. import "google/api/annotations.proto";
  7. option go_package = "github.com/go-kratos/service-layout/api/helloworld/v1;v1";
  8. option java_multiple_files = true;
  9. option java_package = "dev.kratos.api.helloworld.v1";
  10. option java_outer_classname = "HelloWorldProtoV1";
  12. // The greeting service definition.
  13. service Greeter {
  14.   // Sends a greeting
  15.   rpc SayHello (HelloRequest) returns (HelloReply)  {
  16.     option (google.api.http) = {
  17.         // 定义一个 GET 接口，并且把 name 映射到 HelloRequest
  18.         get: "/helloworld/{name}",
  19.         // 可以添加附加接口
  20.         additional_bindings {
  21.             // 定义一个 POST 接口，并且把 body 映射到 HelloRequest
  22.             post: "/v1/greeter/say_hello",
  23.             body: "*",
  24.         }
  25.     };
  26.   }
  27. }
  29. // The request message containing the user's name.
  30. message HelloRequest {
  31.   string name = 1;
  32. }
  34. // The response message containing the greetings
  35. message HelloReply {
  36.   string message = 1;
  37. }

生成接口

  1. # 生成 proto 模板
  2. kratos proto add api/helloworld/v1/greeter.proto
  3. # 生成 client 源码
  4. kratos proto client api/helloworld/v1/greeter.proto
  5. # 生成 server 源码
  6. kratos proto server api/helloworld/v1/greeter.proto -t internal/service
  1. client:
  2. |____api
  3. | |____helloworld
  4. | | |____v1
  5. | | | |____greeter.pb.go
  6. | | | |____greeter.proto
  7. | | | |____greeter_http.pb.go
  8. | | | |____greeter_grpc.pb.go
  10. server:
  11. | |____service
  12. | | |____greeter.go

注册接口

HTTP API 是通过 protoc-gen-go-http 插件进行生成 http.Handler，然后可以注册到 HTTPServer 中：

  1. import "github.com/go-kratos/kratos/v2/transport/http"
  3. greeter := &GreeterService{}
  4. srv := http.NewServer(http.Address(":8000"))
  5. srv.HandlePrefix("/", v1.NewGreeterHandler(greeter))

gRPC API 是通过 protoc-gen-go-grpc 插件进行生成 gRPC Registrar，然后可以注册到 GRPCServer 中；

  1. import "github.com/go-kratos/kratos/v2/transport/grpc"
  3. greeter := &GreeterService{}
  4. srv := grpc.NewServer(grpc.Address(":9000"))
  5. v1.RegisterGreeterServer(srv, greeter)

References