Quick start

Detailed examples referencehere

Install protoc plugins

Install as needed, the commands for the framework to auto-generate code can be found incmd/directory

## Generate .pb.go files
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
## Generate _grpc.pb.go files, gRPC server and client
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
## Generate _amqp.pb.go files, RabbitMQ server and client
go install github.com/asjard/asjard/cmd/protoc-gen-go-amqp@latest
## Generate _asynq.pb.go files, Asynq server and client
go install github.com/asjard/asjard/cmd/protoc-gen-go-asynq@latest
## Generate _rest.pb.go files, HTTP server
go install github.com/asjard/asjard/cmd/protoc-gen-go-rest@latest
## Generate _rest_gw.pb.go files, HTTP protocol to gRPC protocol
go install github.com/asjard/asjard/cmd/protoc-gen-go-rest2grpc-gw@latest
## Generate _validate.pb.go files, parameter validation
go install github.com/asjard/asjard/cmd/protoc-gen-go-validate@latest
## Generate enum.pb.ts files, TypeScript enum generation
go install github.com/asjard/asjard/cmd/protoc-gen-ts-enum@latest
## Generate umi.pb.ts files, Umi request generation
go install github.com/asjard/asjard/cmd/protoc-gen-ts-umi@latest
## Generate pb.ts files, TypeScript type definitions
go install github.com/asjard/asjard/cmd/protoc-gen-ts@latest

Define protobuf file

syntax = "proto3";

package api.v1.example.docs;

option go_package = "protos-repo/example/api/v1/sample";

import "github.com/asjard/protobuf/http.proto";
import "github.com/asjard/protobuf/validate.proto";

service Sample {
  rpc SayHello(HelloRequest) returns (HelloReply) {
    option (asjard.api.http) = {
      get : "/helloworld/{name}"
    };
    option (asjard.api.http) = {
      get : '/hello'
    };
  }
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1 [ (asjard.api.validate).rules = "required,max=20" ];
}

// The response message containing the greetings
message HelloReply { string message = 1; }

Generate Go code from the proto file

protoc --go_out=. --go-grpc_out=. --go-rest_out=. -I${GOPATH}/src -I. sample.proto

Add a new service

package main

import (
	"context"

	pb "github.com/asjard/asjard/_examples/protos-repo/example/api/v1/sample"
	"github.com/asjard/asjard/pkg/server/grpc"
	"github.com/asjard/asjard/pkg/server/rest"
	"github.com/asjard/asjard"
)

type SampleAPI struct {
	pb.UnimplementedSampleServer
}

func NewSampleAPI() *SampleAPI {
	return &SampleAPI{}
}

func (api *SampleAPI) Start() error                       { return nil }
func (api *SampleAPI) Stop()                              {}

// GRPC service
func (api *SampleAPI) GrpcServiceDesc() *grpc.ServiceDesc { return &pb.Sample_ServiceDesc }

// HTTP service
func (api *SampleAPI) RestServiceDesc() *rest.ServiceDesc { return &pb.SampleRestServiceDesc }

func (api *SampleAPI) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
	return &pb.HelloReply{
		Message: "hello " + in.Name,
	}, nil
}

func main() {
	server := asjard.New()
	if err := server.AddHandler(NewSampleAPI(), grpc.Protocol, rest.Protocol); err != nil {
		log.Fatal(err)
	}
	log.Fatal(server.Start())
}

Add configuration file

asjard.service.instance.systemCode: 100
asjard.service.instance.name: svc-example-api
asjard:
  servers:
    grpc:
      enabled: true
      addresses:
        listen: 0.0.0.0:9${asjard.service.instance.systemCode}
    rest:
      enabled: true
      addresses:
        listen: 0.0.0.0:8${asjard.service.instance.systemCode}

Start the service

ASJARD_CONF_DIR="$(PWD)/conf"  go run ./main.go

After successful start you will see information similar to the following:

                                       App:      example
                                       Env:      local
    _   ___    _  _   ___ ___          Region:   default
   /_\ / __|_ | |/_\ | _ \   \          Az:       default
  / _ \\__ \ || / _ \|   / |) |
 /_/ \_\___/\__/_/ \_\_|_\___/ 0.8.8
                                       ID:       91183721-3157-4798-be2b-ce087b958f41
                                       Name:     svc-example-api
                                       Version:  1.0.0
                                       Servers:  grpc://0.0.0.0:9100;rest://0.0.0.0:8100
                                       ConfDir:  ./conf

Test

Success

curl -s  -X GET 'http://localhost:8100/api/v1/docs/samples/helloworld/john'|python3 -m json.tool
## Or
curl -s  -X GET 'http://localhost:8100/api/v1/docs/samples/hello?name=john'|python3 -m json.tool

You will get a result similar to the following

{
  "code": 0,
  "err_code": 0,
  "status": 200,
  "system": 0,
  "success": true,
  "message": "",
  "prompt": "",
  "doc": "",
  "request_id": "1d2e0f7e7668f86d9def719777ebb78f",
  "request_method": "/api.v1.example.docs.Sample/SayHello",
  "data": {
    "@type": "type.googleapis.com/api.v1.example.docs.HelloReply",
    "message": "hello john"
  }
}

Failure

curl -s  -X GET 'http://localhost:8100/api/v1/docs/samples/helloworld'|python3 -m json.tool

You will get a result similar to the following

{
  "code": 1004045,
  "err_code": 5,
  "status": 404,
  "system": 100,
  "success": false,
  "message": "page not found",
  "prompt": "",
  "doc": "",
  "request_id": "9e4e8910729daa5f54225388dd2bfd47",
  "request_method": "/asjard.api.ErrorHandler/NotFound",
  "data": null
}

The above examples can be viewed ingithub.com/asjard/asjard/_examples/svc-example/apis/api/v1/sample.goandgithub.com/asjard/asjard/_examples/protos-repo/examples/api/v1/sample.protorespectively

With the above example you have started the simplest service that includes HTTP and gRPC. Later I will enable various features for you via configuration, such asCORS,OpenAPI,parameter validation,tracingand other features