github.com/erda-project/erda-infra@v1.0.10-0.20240327085753-f3a249292aeb/README.md (about)

     1  # Erda Infra
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/erda-project/erda-infra.svg)](https://pkg.go.dev/github.com/erda-project/erda-infra)
     4  [![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
     5  [![codecov](https://codecov.io/gh/erda-project/erda-infra/branch/develop/graph/badge.svg?token=SVROJLY8UK)](https://codecov.io/gh/erda-project/erda-infra)
     6  
     7  Translations: [English](README.md) | [简体中文](README_zh.md)
     8  
     9  Erda Infra is a lightweight microservices framework implements by golang, which offers many useful modules and tools to help you quickly build a module-driven application.
    10  
    11  Many Go projects are built using Erda Infra including:
    12  * [Erda](https://github.com/erda-project/erda)
    13  
    14  ## Features
    15  * modular design to drive the implementation of the application system, and each module is pluggable.
    16  * each module is configurable, supports setting defaults、reading from files (YAML, HCL,、JSON、TOML、.env file)、environment、flags.
    17  * manage the lifecycle of the module, includes initialization, startup, and shutdown.
    18  * manage dependencies between modules.
    19  * support Dependency Injection between modules.
    20  * offers many commonly modules that can be used directly.
    21  * support define APIs and models in protobuf file to expose both gRPC and HTTP APIs.
    22  * offers tools to help you quickly build a module.
    23  * etc.
    24  
    25  ## Concept
    26  * Service, represents a function.
    27  * Provider, service provider, equivalent to module, provide some services. It can also depend on other services, witch provide by other provider.
    28  * ProviderDefine, describe a provider, includes provider's name, constructor function of provider, services, etc. Register it by *servicehub.RegisterProvider* function.
    29  * Hub, is a container for all providers, and manage the life cycle of all loaded providers.
    30  
    31  A configuration is used to determine whether all registered Providers are loaded, and the Hub initializes, starts, and closes the loaded Providers.
    32  
    33  ![servicehub](./docs/servicehub.jpg)
    34  
    35  ## Define Provider
    36  Define a provider by implementing the *servicehub.ProviderDefine* interface, and register it through the *servicehub.RegisterProvider* function.
    37  
    38  But, it is simpler to describe a provider through *servicehub.Spec* and register it through the *servicehub.Register* function.
    39  
    40  [Examples](./base/servicehub/examples)
    41  
    42  ## Quick Start
    43  ### Create a Provider
    44  **Step 1**, Create a Provider
    45  ```sh
    46  ➜ gohub init -o helloworld
    47  Input Service Provider Name: helloworld
    48  ➜ tree helloworld
    49  helloworld
    50  ├── provider.go
    51  └── provider_test.go
    52  ```
    53  
    54  **Step 2**, Create *main.go*
    55  ```go
    56  package main
    57  
    58  import (
    59  	"github.com/erda-project/erda-infra/base/servicehub"
    60  	_ "./helloworld" // your package import path
    61  )
    62  
    63  func main() {
    64  	servicehub.Run(&servicehub.RunOptions{
    65  		Content: `
    66  helloworld:
    67  `,
    68  	})
    69  }
    70  ```
    71  
    72  **Step 3**, Run
    73  ```sh
    74  ➜ go run main.go
    75  INFO[2021-04-13 13:17:36.416] message: hi                                   module=helloworld
    76  INFO[2021-04-13 13:17:36.416] provider helloworld initialized              
    77  INFO[2021-04-13 13:17:36.416] signals to quit: [hangup interrupt terminated quit] 
    78  INFO[2021-04-13 13:17:36.426] provider helloworld running ...              
    79  INFO[2021-04-13 13:17:39.429] do something...                               module=helloworld
    80  ```
    81  [Hello World](./examples/example) \( [helloworld/](./examples/example/helloworld) | [main.go](./examples/example/main.go) \)
    82  
    83  ### Create HTTP/gRPC Service
    84  These services can be called either remote or local Provider.
    85  
    86  **Step 1**, Define the protocol, in the *.proto files, includes Message and Interface.
    87  ```protobuf
    88  syntax = "proto3";
    89  
    90  package erda.infra.example;
    91  import "google/api/annotations.proto";
    92  option go_package = "github.com/erda-project/erda-infra/examples/service/protocol/pb";
    93  
    94  // the greeting service definition.
    95  service GreeterService {
    96    // say hello
    97    rpc SayHello (HelloRequest) returns (HelloResponse)  {
    98      option (google.api.http) = {
    99        get: "/api/greeter/{name}",
   100      };
   101    }
   102  }
   103  
   104  message HelloRequest {
   105    string name = 1;
   106  }
   107  
   108  message HelloResponse {
   109    bool success = 1;
   110    string data = 2;
   111  }
   112  ```
   113  
   114  **Step 2**, build protocol to codes 
   115  ```sh
   116  ➜ gohub protoc protocol *.proto 
   117  ➜ tree 
   118  .
   119  ├── client
   120  │   ├── client.go
   121  │   └── provider.go
   122  ├── greeter.proto
   123  └── pb
   124      ├── greeter.form.pb.go
   125      ├── greeter.http.pb.go
   126      ├── greeter.pb.go
   127      ├── greeter_grpc.pb.go
   128      └── register.services.pb.go
   129  ```
   130  
   131  **Step 3**, implement the interface
   132  ```sh
   133  ➜ gohub protoc imp *.proto --imp_out=../server/helloworld
   134  ➜ tree ../server/helloworld
   135  ../server/helloworld
   136  ├── greeter.service.go
   137  ├── greeter.service_test.go
   138  └── provider.go
   139  ```
   140  
   141  **Step 4**, Create *main.go* and run it
   142  
   143  *main.go*
   144  ```
   145  package main
   146  
   147  import (
   148  	"os"
   149  
   150  	"github.com/erda-project/erda-infra/base/servicehub"
   151  
   152  	// import all providers
   153  	_ "github.com/erda-project/erda-infra/examples/service/server/helloworld"
   154  	_ "github.com/erda-project/erda-infra/providers"
   155  )
   156  
   157  func main() {
   158  	hub := servicehub.New()
   159  	hub.Run("server", "server.yaml", os.Args...)
   160  }
   161  ```
   162  
   163  *server.yaml*
   164  ```yaml
   165  # optional
   166  http-server:
   167      addr: ":8080"
   168  grpc-server:
   169      addr: ":7070"
   170  service-register:
   171  # expose services and interface
   172  erda.infra.example:
   173  ```
   174  
   175  [Service](./examples/service) \( [Protocol](./examples/service/protocol) | [Implementation](./examples/service/server/helloworld) | [Server](./examples/service/server) | [Caller](./examples/service/caller) | [Client](./examples/service/client)  \)
   176  
   177  ## Useful Providers
   178  Many available providers have been packaged in this project, it can be found in the [providers/](./providers) directory.
   179  
   180  Under each module, there is an examples directory, which contains examples of the use of the module.
   181  
   182  * elasticsearch, provide elasticsearch client APIs, and it easy to write batch data.
   183  * etcd, provide etcd client APIs.
   184  * etcd-mutex, distributed lock implemented by etcd.
   185  * grpcserver, start a grpc server.
   186  * grpcclient, provide gRPC client, and manage client's connection.
   187  * health, provide health check API, and can register some health check function into this provider.
   188  * httpserver, provide an HTTP server, support any form of handle function, interceptor, parameter binding, parameter verification, etc.
   189  * i18n, provide internationalization support, manage i18n files, support templates.
   190  * kafka, provide kafka sdk, and easy to produce and consume messages.
   191  * kubernetes, provide kubernetes client APIs.
   192  * mysql, provide mysql client APIs.
   193  * pprof, expose pprof HTTP APIs By httpserver.
   194  * redis, provide redis client APIs.
   195  * zk-master-election, provide interface about master-slave election, it is implemented by zookeeper.
   196  * zookeeper, provide zookeeper client.
   197  * cassandra, provide cassandra APIs, and easy to write batch data
   198  * serviceregister, use it to register services to expose gRPC and HTTP APIs.
   199  
   200  # Tools
   201  *gohub* is a CLI tool, which to help you quickly build a Provider. It can be installed as follows:
   202  ```sh
   203  go get -u github.com/erda-project/erda-infra/tools/gohub
   204  ```
   205  
   206  You can also use *gohub* through a Docker container.
   207  ```sh
   208  ➜ docker run --rm -ti -v $(pwd):/go \
   209      registry.cn-hangzhou.aliyuncs.com/dice/erda-tools:1.0 gohub                                                                
   210  Usage:
   211    gohub [flags]
   212    gohub [command]
   213  
   214  Available Commands:
   215    help        Help about any command
   216    init        Initialize a provider with name
   217    pkgpath     Print the absolute path of go package
   218    protoc      ProtoBuf compiler tools
   219    tools       Tools
   220    version     Print the version number
   221  
   222  Flags:
   223    -h, --help   help for gohub
   224  
   225  Use "gohub [command] --help" for more information about a command.
   226  ```
   227  
   228  ## License
   229  Erda Infra is under the Apache 2.0 license. See the [LICENSE](/LICENSE) file for details.