Kratos implements REST and gRPC as the transport protocols. We mainly follows the API Design Guide from Google.

You could define REST API and gRPC API in proto files and generate Go codes from these files.

Definition

You could define REST API and gRPC API with Protobuf IDL.

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.         // To define GET API, map name to HelloRequest
  18.         get: "/helloworld/{name}",
  19.         // You could also add some additional APIs
  20.         additional_bindings {
  21.             // To define POST API, map body to HelloRequest
  22.             post: "/v1/greeter/say_hello",
  23.             body: "*",
  24.         }
  25.     };
  26.   }
  27. }
  29. // The request message contains the user's name.
  30. message HelloRequest {
  31.   string name = 1;
  32. }
  34. // The response message contains the greetings
  35. message HelloReply {
  36.   string message = 1;
  37. }

Generation

  1. # To generate proto template
  2. kratos proto add api/helloworld/v1/greeter.proto
  3. # To generate client codes
  4. kratos proto client api/helloworld/v1/greeter.proto
  5. # To generate server codes
  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

Register API

HTTP API is http.Handler which generated by protoc-gen-go-http plugin, can be registered into 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 is gRPC Registrar which generated by protoc-gen-go-grpc plugin，can be registered into 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