pkg

README

Grafana plugin backend

Explanation of catalog structure

// Grafana plugin backend folder
├── pkg
    // all api proto files put here
    ├── api
        └── copilot  // your project name
            └── v1   // api version
                ├── api_http.pb.go  // generated api
                ├── api.pb.go       // generated api
                ├── api.proto       // !!IMPORTANT You need to define the API here, in protobuf format
                └── openapi.yaml    // generated openapi swagger
    // common packages
    ├── common
    // All the code of the service that is not exposed to the public, 
    // the usual business logic is underneath, use internal to avoid misreferences
    ├── internal
        ├── biz         // Assembly Layer for Business Logic
        ├── config      // The structure definition of the internally used config, generated using the proto format
        ├── data        // Business data access, including cache, db and other packages, the implementation of the biz repo interface
        ├── server      // http and grpc instance creation and configuration
        ├── service     // implements the service layer defined by the api (pkg/api/copilot/v1/api.proto)
        └── testdata
    // plugin 
    ├── plugin  
        ├── app.go   
        ├── wire_gen.go // Generated by command "wire"   
        └── wire.go     // Generate dependencies between server ,service, biz, data via Wire Dependency Injection
    ├── main.go  
    └── README.md
├── tool  
    // A plugin for protobuf that generates http api from protoc files.
    // go build -o <protoc-gen-go-http.exe> or <protoc-gen-go-http>
    // put file <protoc-gen-go-http> to environment variable of your develop env
    ├── protoc-gen-go-http 
        ├── go.mod
        ├── go.sum
        ├── http.go
        ├── httpTemplate.tpl
        ├── main.go
        ├── README.md
        ├── template.go  
        └── version.go  
├── Makefile // Use makefile to generate api, run test, build front end and backend, etc..
└── third_party  // third party proto files put here

Development specification

When designing an API, it is often necessary to define the structure of services and messages.Protobuf (Protocol Buffers) is an efficient binary data transfer format that can be used to define these structures. Here is a simple example showing how to design a simple API using Protoc.

First, you need to create a .proto file that defines your services and messages. For example, create a file called example.proto:

1. Design your api and put to the pkg///api.proto

Here's an example pkg/copilot/v1/api.proto

syntax = "proto3";

package mypackage;

service MyService {
    rpc MyMethod(MyRequest) returns (MyResponse) {
    option (google.api.http) = {
      post: "/copilot/security"
      body: "*"
    };
  }
}

message MyRequest {
    string field1 = 1;
    int32 field2 = 2;
}

message MyResponse {
    string result = 1;
}

Execute the following command in the project root directory

cd <project-root-dir>/pkg/api/copilot/v1 && protoc --proto_path=<project-root-dir>/pkg/api/copilot/v1 \
        --proto_path=$(ROOT_DIR)/third_party \
        --go_out=paths=source_relative:. \
        --go-http_out=paths=source_relative:. \
        --openapi_out=fq_schema_naming=true,default_response=false:. \
        <project-root-dir>/pkg/api/copilot/v1/api.proto

Some files will be generated: api_http.pb.go, api.pb.go, openapi.yaml

The above command has been implemented at MAKEFILE, you can execute command make api

2. Implementing your interface

当你通过上面步骤生成 api_http.pb.go, api.pb.go, openapi.yaml 后, 在 api_http.pb.go 文件中找到以下接口

type MyServiceHTTPServer interface {
	MyMethod(context.Context, *MyRequest) (*MyResponse, error)
}

pkg/internal/server pkg/internal/service pkg/internal/biz pkg/internal/data