From c392528e112226d9617d60816c04f75c3a79ef40 Mon Sep 17 00:00:00 2001 From: yeqown Date: Fri, 12 Nov 2021 23:16:12 +0800 Subject: [PATCH] docs: replenish config/apollo and registry/discovery readme (#1625) * docs(config/apollo): replenish config/apollo readme * docs(registry/discovery): replenish registry/discovery readme * docs: complete docs of config/apollo and registry/discovery --- contrib/config/apollo/README.md | 104 +++++++++++++++++++++++++++ contrib/registry/discovery/README.md | 97 ++++++++++++++++++++++++- 2 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 contrib/config/apollo/README.md diff --git a/contrib/config/apollo/README.md b/contrib/config/apollo/README.md new file mode 100644 index 000000000..c07b67ec4 --- /dev/null +++ b/contrib/config/apollo/README.md @@ -0,0 +1,104 @@ +## Apollo config centry + +This module implements the `config.Source` interface in kratos based apollo config management center. + +[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/go-kratos/kratos/contrib/config/apollo/v2) + +### Quick start + +```go +import ( + "fmt" + "log" + + "github.com/go-kratos/kratos/contrib/config/apollo/v2" + "github.com/go-kratos/kratos/v2/config" +) + +func main() { + c := config.New( + config.WithSource( + apollo.NewSource( + apollo.WithAppID("kratos"), + apollo.WithCluster("dev"), + apollo.WithEndpoint("http://localhost:8080"), + apollo.WithNamespace("application,event.yaml,demo.json"), + apollo.WithEnableBackup(), + apollo.WithSecret("ad75b33c77ae4b9c9626d969c44f41ee"), + ), + ), + ) + var bc bootstrap + if err := c.Load(); err != nil { + panic(err) + } + + // use value and watch operations，help yourself. +} +``` + +### Options list + +> You get what you see. + +```go +// specify the app id +func WithAppID(appID string) Option +// specify the cluster of application +func WithCluster(cluster string) Option + +// enable backup or not, and where to back up them. +func WithBackupPath(backupPath string) Option +func WithDisableBackup() Option +func WithEnableBackup() Option + +// specify apollo endpoint, such as http://localhost:8080 +func WithEndpoint(endpoint string) Option + +// inject a logger to debug +func WithLogger(logger log.Logger) Option + +// namespaces to load, comma to separate. +func WithNamespace(name string) Option + +// secret is the apollo secret key to access application config. +func WithSecret(secret string) Option +``` + +### Notice + +apollo config center use `Namespace` to be part of the key. For example: + +***application.json*** + +```json +{ + "http": { + "address": ":8080", + "tls": { + "enable": false, + "cert_file": "", + "key_file": "" + } + } +} +``` + +you got them in kratos config instance maybe look like: + +```go +config := map[string]interface{}{ + // application be part of the key path. + "application": map[string]interface{}{ + "http": map[string]interface{}{ + "address": ":8080", + "tls": map[string]interface{}{ + "enable": false, + "cert_file": "", + "key_file": "" + } + } + } +} +_ = config +``` \ No newline at end of file diff --git a/contrib/registry/discovery/README.md b/contrib/registry/discovery/README.md index 48bd654f3..b220b6293 100644 --- a/contrib/registry/discovery/README.md +++ b/contrib/registry/discovery/README.md @@ -1,4 +1,97 @@ -# Discovery Registry +## Discovery Registry -## [discovery](https://github.com/bilibili/discovery) +This module implements a `registry.Registrar` and `registry.Discovery` interface in kratos based `bilibili/discovery`. + +[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/go-kratos/kratos/contrib/registry/discovery/v2) + +### Quick Start + +**_Register a service_** + +```go +import ( + "github.com/go-kratos/kratos/contrib/registry/discovery/v2" +) + +func main() { + logger := log.NewStdLogger(os.Stdout) + logger = log.With(logger, "service", "example.registry.discovery") + + // initialize a registry + r := discovery.New(&discovery.Config{ + Nodes: []string{"0.0.0.0:7171"}, + Env: "dev", + Region: "sh1", + Zone: "zone1", + Host: "hostname", + }, logger) + + // construct srv instance + // ... + + app := kratos.New( + kratos.Name("helloworld"), + kratos.Server( + httpSrv, + grpcSrv, + ), + kratos.Metadata(map[string]string{"color": "gray"}), + // use Registrar + kratos.Registrar(r), + ) + + if err := app.Run(); err != nil { + log.NewHelper(logger).Fatal(err) + } +} +``` + +**_Discover a service_** + +```go +import ( + "github.com/go-kratos/kratos/contrib/registry/discovery/v2" + "github.com/go-kratos/kratos/v2/transport/grpc" +) + +func main() { + // initialize a discovery + r := discovery.New(&discovery.Config{ + Nodes: []string{"0.0.0.0:7171"}, + Env: "dev", + Region: "sh1", + Zone: "zone1", + Host: "localhost", + }, nil) + + conn, err := grpc.DialInsecure( + context.Background(), + grpc.WithEndpoint("discovery:///appid"), + // use discovery + grpc.WithDiscovery(r), + ) + if err != nil { + log.Fatal(err) + } + defer conn.Close() + + // request and log +} +``` + +### Config explain + +```go +type Config struct { + Nodes []string // discovery nodes address + Region string // region of the service, sh + Zone string // zone of region, sh001 + Env string // env of service, dev, prod and etc + Host string // hostname of service +} +``` + +### References + +- [bilibili/discovery](https://github.com/bilibili/discovery)