Kratos

https://go-kratos.dev/zh-cn/docs/
Admin
Kratos is a lightweight Go microservices framework that provides comprehensive tools and libraries...
Tokens:38,348
Snippets:474
Trust Score:7.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Creating and Starting a New HTTP Server

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

Example of initializing a new Kratos application with an HTTP server.

```go
hs := http.NewServer()
app := kratos.New(
  kratos.Name("kratos"),
  kratos.Version("v1.0.0"),
  kratos.Server(hs),
)
```

--------------------------------

### Install proto-gen-validate

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/validate

Install the proto-gen-validate tool using go install. If issues arise, consider cloning the repository and building manually.

```go
go install github.com/envoyproxy/protoc-gen-validate@latest
```

--------------------------------

### Install Kratos CLI

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

Use 'go install' to install the Kratos CLI tool. Ensure your Go environment is configured correctly.

```bash
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
```

--------------------------------

### Defining HTTP Server Routes with GET Method

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

This example demonstrates how to create a new HTTP server router and define a GET route for a specific path, associating it with a handler function.

```go
r := s.Route("/v1")
r.GET("/helloworld/{name}", _Greeter_SayHello0_HTTP_Handler(srv))

```

--------------------------------

### Install Wire Tool

Source: https://go-kratos.dev/zh-cn/docs/guide/wire

Installs the Wire command-line tool and imports it into your project.

```bash
go get -u github.com/google/wire
go install github.com/google/wire/cmd/wire
```

--------------------------------

### Prometheus Metrics Setup (kratos >= 2.8.0)

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/metrics

Initializes Prometheus exporter and MeterProvider for OpenTelemetry metrics. This setup is required for kratos v2.8.0 and later.

```go
import (
    "github.com/go-kratos/kratos/v2/middleware/metrics"
    "go.opentelemetry.io/otel/exporters/prometheus"
    "go.opentelemetry.io/otel/metric"
    sdkmetric "go.opentelemetry.io/otel/sdk/metric"
)


// Detailed reference https://github.com/go-kratos/examples/tree/main/metrics
func init() {
    exporter, err := prometheus.New()
    if err != nil {
        panic(err)
    }
    provider := sdkmetric.NewMeterProvider(sdkmetric.WithReader(exporter))
    meter := provider.Meter(Name)


    _metricRequests, err = metrics.DefaultRequestsCounter(meter, metrics.DefaultServerRequestsCounterName)
    if err != nil {
        panic(err)
    }


    _metricSeconds, err = metrics.DefaultSecondsHistogram(meter, metrics.DefaultServerSecondsHistogramName)
    if err != nil {
        panic(err)
    }
}
```

--------------------------------

### Example Configuration Merging (File 1)

Source: https://go-kratos.dev/zh-cn/docs/component/config

Represents the first configuration file used in an example demonstrating Kratos's configuration merging capabilities. Keys at the root level should be unique to avoid overwrites.

```yaml
# 文件1
foo:
  baz: "2"
  biu: "example"
hello:
  a: b
```

--------------------------------

### Install protoc-gen-openapi Plugin

Source: https://go-kratos.dev/zh-cn/docs/guide/openapi

Install the protoc-gen-openapi plugin globally using go install. This is a prerequisite for generating OpenAPI files.

```bash
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest

```

--------------------------------

### Full API Service Definition Example

Source: https://go-kratos.dev/zh-cn/docs/guide/api-protobuf

A complete example of a Protobuf file defining a service, messages, and options, including multi-language specific package names.

```protobuf
syntax = "proto3";


package kratos.demo.v1;


// 多语言特定包名，用于源代码引用
option go_package = "github.com/go-kratos/kratos/demo/v1;v1";   // ';' 后面的 <version> 是为了生成对应代码
option java_multiple_files = true;
option java_package = "com.github.kratos.demo.v1";
option objc_class_prefix = "KratosDemoV1";


// 描述该服务的信息
service Greeter {
  // 描述该方法的功能
  rpc SayHello (HelloRequest) returns (HelloReply);
}
// Hello请求参数
message HelloRequest {
  // 用户名字
  string name = 1;
}
// Hello返回结果
message HelloReply {
  // 结果信息
  string message = 1;
}
```

--------------------------------

### Kratos Application Initialization with Wire

Source: https://go-kratos.dev/zh-cn/docs/guide/wire

Defines the Kratos application entry point and the wire.go file for dependency injection setup.

```go
// 应用程序入口
cmd
-main.go
-wire.go
-wire_gen.go


// main.go 创建 kratos 应用生命周期管理
func newApp(logger log.Logger, hs *http.Server, gs *grpc.Server, greeter *service.GreeterService) *kratos.App {
    pb.RegisterGreeterServer(gs, greeter)
    pb.RegisterGreeterHTTPServer(hs, greeter)
    return kratos.New(
        kratos.Name(Name),
        kratos.Version(Version),
        kratos.Logger(logger),
        kratos.Server(
            hs,
            gs,
        ),
    )
}


// wire.go 初始化模块
func initApp(*conf.Server, *conf.Data, log.Logger) (*kratos.App, error) {
    // 构建所有模块中的 ProviderSet，用于生成 wire_gen.go 自动依赖注入文件
    panic(wire.Build(server.ProviderSet, data.ProviderSet, biz.ProviderSet, service.ProviderSet, newApp))
}
```

--------------------------------

### Example Configuration Merging (File 2)

Source: https://go-kratos.dev/zh-cn/docs/component/config

Represents the second configuration file used in an example demonstrating Kratos's configuration merging capabilities. Keys at the root level should be unique to avoid overwrites.

```yaml
# 文件2
foo:
  bar: 3
  baz: aaaa
hey:
  good: bad
  qux: quux
```

--------------------------------

### Initializing Helper with Fluentd Logger

Source: https://go-kratos.dev/zh-cn/docs/component/log

Example of initializing a Helper with a custom logger, specifically a Fluentd logger.

```go
import "github.com/go-kratos/kratos/contrib/log/fluent/v2"


logger, err := fluent.NewLogger("unix:///var/run/fluent/fluent.sock")
if err != nil {
    return
}
h := log.NewHelper(logger)
```

--------------------------------

### Provider Function Examples

Source: https://go-kratos.dev/zh-cn/docs/guide/wire

Examples of provider functions that can be used with Wire. These functions initialize components and can depend on other providers.

```go
// 提供一个配置文件（也可能是配置文件）
func NewConfig() *conf.Data {...}


// 提供数据组件，依赖了数据配置（初始化 Database、Cache 等）
func NewData(c *conf.Data) (*Data, error) {...}


// 提供持久化组件，依赖数据组件（实现 CURD 持久化层）
func NewUserRepo(d *data.Data) (*UserRepo, error) {...}
```

--------------------------------

### Run the Kratos Application

Source: https://go-kratos.dev/zh-cn/docs/getting-started/start

Starts the Kratos application. The output shows the configuration loading and the ports the gRPC and HTTP servers are listening on.

```bash
# Run the project
kratos run

# Output
INFO msg=config loaded: config.yaml format: yaml # Default load configs/config.yaml configuration file
INFO msg=[gRPC] server listening on: [::]:9000 # gRPC service listening on port 9000
INFO msg=[HTTP] server listening on: [::]:8000 # HTTP service listening on port 8000
```

--------------------------------

### Service Discovery (gRPC) with etcd

Source: https://go-kratos.dev/zh-cn/docs/component/registry

Example of creating an etcd discoverer and configuring a gRPC client to use it for service discovery.

```go
import (
    "github.com/go-kratos/kratos/contrib/registry/etcd/v2"
    clientv3 "go.etcd.io/etcd/client/v3"
)


// new etcd client
client, err := clientv3.New(clientv3.Config{
    Endpoints: []string{"127.0.0.1:2379"},
})
if err != nil {
    panic(err)
}
// new dis with etcd client
dis := etcd.New(client)


endpoint := "discovery:///provider"
conn, err := grpc.Dial(context.Background(), grpc.WithEndpoint(endpoint), grpc.WithDiscovery(dis))
if err != nil {
    panic(err)
}

```

--------------------------------

### Register gRPC Server with Kratos

Source: https://go-kratos.dev/zh-cn/docs/component/transport/grpc

Example of how to create a new gRPC server and register it with a Kratos application instance.

```go
gs := grpc.NewServer()
app := kratos.New(
    kratos.Name("kratos"),
    kratos.Version("v1.0.0"),
    kratos.Server(gs),
)
```

--------------------------------

### Example gRPC Client with JWT

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/auth

A simple example demonstrating a gRPC client connecting to a different service (port 9001) with matching JWT keys and algorithms.

```go
con, _ := grpc.DialInsecure(
    context.Background(),
    grpc.WithEndpoint("dns:///127.0.0.1:9001"), // 本地的9001服务
    grpc.WithMiddleware(
        jwt.Client(func(token *jwtv4.Token) (interface{}, error) {
            return []byte(serviceTestKey), nil
        }),
    ),
)

```

--------------------------------

### Release Notes Generation Example

Source: https://go-kratos.dev/zh-cn/docs/community/contribution

An example of generated release notes, categorized into New Features and Others, based on commit messages.

```markdown
### New Features
- feat(cmd): add kratos changelog command (#1140)
- feat(examples): add  benchmark example (#1134)
- feat: add int/int32/Stringer support when get atomicValue (#1130)
### Others
- add form encoding (#1138)
- upgrade otel to v1 rc1 (#1132)
- http stop should use ctx (#1131)

```

--------------------------------

### Project Directory Structure

Source: https://go-kratos.dev/zh-cn/docs/guide/api-protobuf

Example of how to structure Protobuf definitions within a project, with API definitions under the 'api' directory.

```text
kratos-demo：
|____api // 服务API定义
| |____kratos
| | |____demo
| | | |____v1
| | | | |____demo.proto
```

--------------------------------

### Service Discovery (gRPC) with Consul

Source: https://go-kratos.dev/zh-cn/docs/component/registry

Example of creating a Consul discoverer and configuring a gRPC client to use it for service discovery.

```go
import (
    "context"


    consul "github.com/go-kratos/kratos/contrib/registry/consul/v2"
    "github.com/go-kratos/kratos/v2/transport/grpc"
    "github.com/hashicorp/consul/api"
)


// new consul client
client, err := api.NewClient(api.DefaultConfig())
if err != nil {
    panic(err)
}
// new dis with consul client
dis := consul.New(client)


endpoint := "discovery:///provider"
conn, err := grpc.Dial(context.Background(), grpc.WithEndpoint(endpoint), grpc.WithDiscovery(dis))
if err != nil {
    panic(err)
}

```

--------------------------------

### Proto File Definition

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

This is an example of a proto file defining a service and its messages. It includes package declarations and options for Go and Java.

```proto
syntax = "proto3";


package api.helloworld.v1;


option go_package = "helloworld/api/helloworld/v1;v1";
option java_multiple_files = true;
option java_package = "api.helloworld.v1";


service Demo {
    rpc CreateDemo (CreateDemoRequest) returns (CreateDemoReply);
    rpc UpdateDemo (UpdateDemoRequest) returns (UpdateDemoReply);
    rpc DeleteDemo (DeleteDemoRequest) returns (DeleteDemoReply);
    rpc GetDemo (GetDemoRequest) returns (GetDemoReply);
    rpc ListDemo (ListDemoRequest) returns (ListDemoReply);
}


message CreateDemoRequest {}
message CreateDemoReply {}


message UpdateDemoRequest {}
message UpdateDemoReply {}


message DeleteDemoRequest {}
message DeleteDemoReply {}


message GetDemoRequest {}
message GetDemoReply {}


message ListDemoRequest {}
message ListDemoReply {}
```

--------------------------------

### Install Ent CLI Tool

Source: https://go-kratos.dev/zh-cn/docs/guide/ent

Installs the latest version of the Ent command-line interface tool.

```bash
go install entgo.io/ent/cmd/ent@latest
```

--------------------------------

### Install Protoc-gen-go-errors Tool

Source: https://go-kratos.dev/zh-cn/docs/component/errors

Installs the protoc-gen-go-errors tool, which is necessary for generating error helper code from proto definitions.

```bash
# If protoc-gen-go is not installed on the computer, install it first
# go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-errors/v2@latest
```

--------------------------------

### Basic Helper Logging

Source: https://go-kratos.dev/zh-cn/docs/component/log

Use the Helper interface for simplified logging in business logic. This example shows basic Info and Errorf calls.

```go
helper.Info("hello")
helper.Errorf("hello %s", "eric")
```

--------------------------------

### Prometheus Metrics Setup (kratos < 2.8.0)

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/metrics

Defines Prometheus Histogram and Counter for server requests duration and count. Ensure these are registered.

```go
// 详见 https://github.com/go-kratos/examples/tree/main/metrics


_metricSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
    Namespace: "server",
    Subsystem: "requests",
    Name:      "duration_sec",
    Help:      "server requests duratio(sec).",
    Buckets:   []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.250, 0.5, 1},
}, []string{"kind", "operation"})


_metricRequests = prometheus.NewCounterVec(prometheus.CounterOpts{
    Namespace: "client",
    Subsystem: "requests",
    Name:      "code_total",
    Help:      "The total number of processed requests",
}, []string{"kind", "operation", "code", "reason"})


prometheus.MustRegister(_metricSeconds, _metricRequests)
```

--------------------------------

### Full Commit Message Example

Source: https://go-kratos.dev/zh-cn/docs/community/contribution

A comprehensive commit message example demonstrating the use of type, scope, description, body, and footer, including breaking changes and issue references.

```markdown
fix(log): [BREAKING-CHANGE] unable to meet the requirement of log Library


Explain the reason, purpose, realization method, etc.


Close #777
Doc change on doc/#111
BREAKING CHANGE:
  Breaks log.info api, log.log should be used instead

```

--------------------------------

### gRPC Operation Path Construction Example

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/overview

Illustrates how gRPC operation paths are constructed, which is essential for middleware matching. The format is '/PackageName.ServiceName/MethodName'.

```proto
syntax = "proto3";


package helloworld;


import "google/api/annotations.proto";


option go_package = "github.com/go-kratos/examples/helloworld/helloworld";


// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply)  {
        option (google.api.http) = {
            get: "/helloworld/{name}",
        };
  }
}
// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}


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

--------------------------------

### Generate Code and Wire Dependencies

Source: https://go-kratos.dev/zh-cn/docs/getting-started/start

Installs the Wire tool and generates necessary code, including proto sources and Wire configurations, for your project.

```bash
# Install dependencies
go get github.com/google/wire/cmd/wire@latest
# Generate all proto sources, wire, etc.
go generate ./...
```

--------------------------------

### Register Service Instance with etcd

Source: https://go-kratos.dev/zh-cn/docs/component/registry

Example of creating an etcd registrar and injecting it into a Kratos application for automatic service registration and deregistration.

```go
import (
    "github.com/go-kratos/kratos/contrib/registry/etcd/v2"
    clientv3 "go.etcd.io/etcd/client/v3"
)


// new etcd client
client, err := clientv3.New(clientv3.Config{
    Endpoints: []string{"127.0.0.1:2379"},
})
if err != nil {
    panic(err)
}
// new reg with etcd client
reg := etcd.New(client)


app := kratos.New(
    // service-name
    kratos.Name(Name),
    kratos.Version(Version),
    kratos.Metadata(map[string]string{}),
    kratos.Logger(logger),
    kratos.Server(
        hs,
        gs,
    ),
    // with registrar
    kratos.Registrar(reg),
)
```

--------------------------------

### Generated Accessors Example

Source: https://go-kratos.dev/zh-cn/docs/guide/api-protobuf

Illustrates how Protobuf field names translate to accessor methods in C++ and Java.

```text
C++:
  const string& song_name() { ... }
  void set_song_name(const string& x) { ... }


Java:
  public String getSongName() { ... }
  public Builder setSongName(String v) { ... }
```

--------------------------------

### Register Service Instance with Consul

Source: https://go-kratos.dev/zh-cn/docs/component/registry

Example of creating a Consul registrar and injecting it into a Kratos application for automatic service registration and deregistration.

```go
import (
    consul "github.com/go-kratos/kratos/contrib/registry/consul/v2"
    "github.com/hashicorp/consul/api"
)


// new consul client
client, err := api.NewClient(api.DefaultConfig())
if err != nil {
    panic(err)
}
// new reg with consul client
reg := consul.New(client)


app := kratos.New(
    // service-name
    kratos.Name(Name),
    kratos.Version(Version),
    kratos.Metadata(map[string]string{}),
    kratos.Logger(logger),
    kratos.Server(
        hs,
        gs,
    ),
    // with registrar
    kratos.Registrar(reg),
)
```

--------------------------------

### Monorepo Directory Structure

Source: https://go-kratos.dev/zh-cn/docs/guide/api-protobuf

Example of structuring Protobuf definitions in a monorepo, including API definitions, annotations, and third-party references.

```text
kratos-apis:
|____api // 服务API定义
| |____kratos
| | |____demo
| | | |____v1
| | | | |____demo.proto
|____annotations // 注解定义options
|____third_party // 第三方引用
```

--------------------------------

### JSON Codec Implementation

Source: https://go-kratos.dev/zh-cn/docs/component/encoding

Example implementation of the Codec interface for JSON encoding and decoding, handling both standard JSON and protobuf messages.

```go
package json


import (
    "encoding/json"
    "reflect"

    "github.com/go-kratos/kratos/v2/encoding"
    "google.golang.org/protobuf/encoding/protojson"
    "google.golang.org/protobuf/proto"
)


// Name is the name registered for the json codec.
const Name = "json"

var (
    // MarshalOptions is a configurable JSON format marshaller.
    MarshalOptions = protojson.MarshalOptions{
        EmitUnpopulated: true,
    }
    // UnmarshalOptions is a configurable JSON format parser.
    UnmarshalOptions = protojson.UnmarshalOptions{
        DiscardUnknown: true,
    }
)

func init() {
    encoding.RegisterCodec(codec{})
}

// codec is a Codec implementation with json.
type codec struct{}

func (codec) Marshal(v interface{}) ([]byte, error) {
    switch m := v.(type) {
    case json.Marshaler:
        return m.MarshalJSON()
    case proto.Message:
        return MarshalOptions.Marshal(m)
    default:
        return json.Marshal(m)
    }
}

func (codec) Unmarshal(data []byte, v interface{}) error {
    switch m := v.(type) {
    case json.Unmarshaler:
        return m.UnmarshalJSON(data)
    case proto.Message:
        return UnmarshalOptions.Unmarshal(data, m)
    default:
        rv := reflect.ValueOf(v)
        for rv := rv; rv.Kind() == reflect.Ptr; {
            if rv.IsNil() {
                rv.Set(reflect.New(rv.Type().Elem()))
            }
            rv = rv.Elem()
        }
        if m, ok := reflect.Indirect(rv).Interface().(proto.Message); ok {
            return UnmarshalOptions.Unmarshal(data, m)
        }
        return json.Unmarshal(data, m)
    }
}

func (codec) Name() string {
    return Name
}
```

--------------------------------

### Server Interface for Service Lifecycle Management

Source: https://go-kratos.dev/zh-cn/docs/component/transport/overview

Defines the Start and Stop methods for managing the service lifecycle. Used for controlling the server's operational state.

```go
type Server interface {
    Start(context.Context) error
    Stop(context.Context) error
}
```

--------------------------------

### Configure Log Filtering

Source: https://go-kratos.dev/zh-cn/docs/component/log

Use filters to mask sensitive information or control log output based on level, keys, values, or custom functions. This example demonstrates setting up filters for log level, key masking, value masking, and a custom filter function.

```go
h := NewHelper(
    NewFilter(logger,
        // 等级过滤
        FilterLevel(log.LevelError),


        // 按key遮蔽
        FilterKey("username"),


        // 按value遮蔽
        FilterValue("hello"),


        // 自定义过滤函数
        FilterFunc(
            func (level Level, keyvals ...interface{}) bool {
                if level == LevelWarn {
                    return true
                }
                for i := 0; i < len(keyvals); i++ {
                    if keyvals[i] == "password" {
                        keyvals[i+1] = fuzzyStr
                    }
                }
                return false
            }
        ),
    ),
)


h.Log(log.LevelDebug, "msg", "test debug")
h.Info("hello")
h.Infow("password", "123456")
h.Infow("username", "kratos")
h.Warn("warn log")

```

--------------------------------

### Configure Global Logger with Zap

Source: https://go-kratos.dev/zh-cn/docs/component/log

Set a custom global logger using the Zap logging library. This example shows how to configure Zap with a JSON encoder, file output, and then set it as the global Kratos logger.

```go
// 使用zap日志设置全局logger


import (
    "os"


    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"


    kratoszap "github.com/go-kratos/kratos/contrib/log/zap/v2"
    "github.com/go-kratos/kratos/v2/log"
)


f, err := os.OpenFile("test.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
    return
}
writeSyncer := zapcore.AddSync(f)


encoder := zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig())
core := zapcore.NewCore(encoder, writeSyncer, zapcore.DebugLevel)
z := zap.New(core)


logger := kratoszap.NewLogger(z)
log.SetLogger(logger)


// 打印日志
log.Info("info")
log.Debug("debug")

```

--------------------------------

### gRPC Server Tracing Integration

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/logging

Integrates tracing with a gRPC server using the tracing middleware. This example shows how to set up a tracer provider and apply it to the gRPC server options.

```go
exporter, err := stdouttrace.New(stdouttrace.WithWriter(ioutil.Discard))
if err != nil {
    fmt.Printf("creating stdout exporter: %v", err)
    panic(err)
}
tp := tracesdk.NewTracerProvider(
    tracesdk.WithBatcher(exporter),
    tracesdk.WithResource(resource.NewSchemaless(
        semconv.ServiceNameKey.String(Name)),
    ))
var opts = []grpc.ServerOption{
        grpc.Middleware(
            tracing.Server(tracing.WithTracerProvider(tp)),
        ),
    }
srv := grpc.NewServer(opts...)

```

--------------------------------

### Configure JSON MarshalOptions for HTTP Responses (Proto Names and Omit Empty)

Source: https://go-kratos.dev/zh-cn/docs/intro/faq

Customize JSON marshaling for HTTP responses in Kratos by setting protojson.MarshalOptions. This example configures to use proto names and emit unpopulated fields.

```go
import (
  "github.com/go-kratos/kratos/v2/encoding/json"
  "google.golang.org/protobuf/encoding/protojson"
)

func init() {
 flag.StringVar(&flagconf, "conf", "../../configs", "config path, eg: -conf config.yaml")
 //增加这段代码
 json.MarshalOptions = protojson.MarshalOptions{
  EmitUnpopulated: true, //默认值不忽略
  UseProtoNames:   true, //使用proto name返回http字段
 }
}

```

--------------------------------

### Define REST and gRPC API with Protobuf

Source: https://go-kratos.dev/zh-cn/docs/component/api

Define your service, requests, and responses using Protobuf syntax. Use google.api.http annotations to map RPC methods to HTTP GET and POST requests, specifying path parameters and request bodies.

```proto
syntax = "proto3";


package helloworld.v1;


import "google/api/annotations.proto";


option go_package = "github.com/go-kratos/service-layout/api/helloworld/v1;v1";
option java_multiple_files = true;
option java_package = "dev.kratos.api.helloworld.v1";
option java_outer_classname = "HelloWorldProtoV1";


// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply)  {
    option (google.api.http) = {
        // 定义一个 GET 接口，并且把 name 映射到 HelloRequest
        get: "/helloworld/{name}",
        // 可以添加附加接口
        additional_bindings {
            // 定义一个 POST 接口，并且把 body 映射到 HelloRequest
            post: "/v1/greeter/say_hello",
            body: "*",
        }
    };
  }
}


// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}


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

```

--------------------------------

### Create New Kratos Project

Source: https://go-kratos.dev/zh-cn/docs/intro/layout

Use this command to initialize a new project based on the kratos-layout structure.

```bash
kratos new <project-name>
```

--------------------------------

### Initializing Helper with DefaultLogger

Source: https://go-kratos.dev/zh-cn/docs/component/log

Creating a Helper instance using the default logger, which logs to standard output.

```go
import "github.com/go-kratos/kratos/v2/log"


h := NewHelper(log.DefaultLogger)
```

--------------------------------

### Commit Message Type Examples

Source: https://go-kratos.dev/zh-cn/docs/community/contribution

Examples of commit types used in Kratos, such as 'fix', 'feat', 'deps', 'break', 'docs', 'refactor', 'style', 'test', 'chore', and 'ci'.

```markdown
fix: The log debug level should be -1

```

--------------------------------

### Using Kratos Middleware with HTTP Server

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

Illustrates how to apply Kratos middleware to the HTTP server during its creation.

```go
hs := http.NewServer(
    http.Address(":8000"),
    http.Middleware(
        logging.Server(),
    ),
)
```

--------------------------------

### SayHello API

Source: https://go-kratos.dev/zh-cn/docs/component/api

Defines a 'SayHello' RPC method with HTTP GET and POST bindings. The GET method maps the 'name' path parameter to the request, while the POST method maps the request body.

```APIDOC
## GET /helloworld/{name}

### Description
Sends a greeting using the provided name.

### Method
GET

### Endpoint
/helloworld/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name to greet.

### Response
#### Success Response (200)
- **message** (string) - The greeting message.

### Request Example
```json
{
  "name": "Kratos"
}
```

### Response Example
```json
{
  "message": "Hello Kratos"
}

## POST /v1/greeter/say_hello

### Description
Sends a greeting using the provided request body.

### Method
POST

### Endpoint
/v1/greeter/say_hello

### Parameters
#### Request Body
- **name** (string) - Required - The name to greet.

### Request Example
```json
{
  "name": "Kratos"
}
```

### Response
#### Success Response (200)
- **message** (string) - The greeting message.

### Response Example
```json
{
  "message": "Hello Kratos"
}

```

--------------------------------

### Loading Environment Variables with Prefix

Source: https://go-kratos.dev/zh-cn/docs/component/config

Initializes configuration to load from environment variables, optionally with a prefix (e.g., 'KRATOS_'). It can be combined with other sources like file sources.

```go
c := config.New(
    config.WithSource(
        // 添加前缀为 KRATOS_ 的环境变量，不需要的话也可以设为空字符串
        env.NewSource("KRATOS_"),
        // 添加配置文件
        file.NewSource(path),
    ))


// 加载配置源：
if err := c.Load(); err != nil {
    log.Fatal(err)
}


// 获取环境变量 KRATOS_PORT 的值，这里用去掉前缀的名称进行读取
port, err := c.Value("PORT").String()
```

--------------------------------

### Get Codec

Source: https://go-kratos.dev/zh-cn/docs/component/encoding

Retrieves a registered Codec by its name. Ensure the codec is registered before calling this.

```go
jsonCodec := encoding.GetCodec("json")
```

--------------------------------

### Create HTTP Client with Service Discovery

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

Configures an HTTP client to use service discovery. The 'discovery://' scheme indicates a service name, and a service discovery registry 'r' must be provided.

```go
conn, err := http.NewClient(
    context.Background(),
    http.WithEndpoint("discovery:///helloworld"),
    http.WithDiscovery(r),
)
```

--------------------------------

### Commit Message with Scope and Attention

Source: https://go-kratos.dev/zh-cn/docs/community/contribution

An example of a commit message that includes a scope and indicates a breaking change.

```markdown
refactor!(transport/http): replacement underlying implementation

```

--------------------------------

### Proto Validation Rule for Required Message

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/validate

Example of marking a nested message field as required using proto-gen-validate.

```proto
// 参数为必填项
Info info = 11 [(validate.rules).message.required = true];
message Info {
    string address = 1;
}
```

--------------------------------

### Listener Configuration for HTTP Server

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

Demonstrates the configuration option for providing a custom net.Listener to the Kratos HTTP server.

```go
// Listener with server lis
func Listener(lis net.Listener) ServerOption {
    return func(s *Server) {
        s.lis = lis
    }
}
```

--------------------------------

### Loading Configuration from Local File

Source: https://go-kratos.dev/zh-cn/docs/component/config

Initializes a Kratos configuration instance to load settings from a local file or directory. Ensure the path points to your configuration file (e.g., config.yaml).

```go
import (
    "github.com/go-kratos/kratos/v2/config"
    "github.com/go-kratos/kratos/v2/config/file"
)


path := "configs/config.yaml"
c := config.New(
    config.WithSource(
        file.NewSource(path),
    ),
)
```

--------------------------------

### Initialize Ent Client with SQLite3

Source: https://go-kratos.dev/zh-cn/docs/guide/ent

Opens a new Ent client connection using SQLite3 in memory mode and creates the database schema.

```go
package main


import (
    "context"
    "log"

    "<project>/ent"

    _ "github.com/mattn/go-sqlite3"
)


func main() {
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()
    // Run the auto migration tool.
    if err := client.Schema.Create(context.Background()); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }
}
```

--------------------------------

### gRPC Server Recovery Middleware Usage

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/recovery

Example of applying the Recovery middleware to a gRPC server with custom logger and handler.

```go
var opts = []grpc.ServerOption{
    grpc.Middleware(
        recovery.Recovery(
            recovery.WithLogger(log.DefaultLogger),
            recovery.WithHandler(func(ctx context.Context, req, err interface{}) error {
                // do someting
                return nil
            }),
        ),
    ),
}
srv := grpc.NewServer(opts...)
```

--------------------------------

### Create a New Kratos Project

Source: https://go-kratos.dev/zh-cn/docs/getting-started/start

Use the Kratos CLI to scaffold a new project. You can specify a remote repository for the project template if needed.

```bash
# Use the default template to create a project
kratos new helloworld

# If fetching fails in a domestic environment, specify the source with -r
kratos new helloworld -r https://gitee.com/go-kratos/kratos-layout.git

# Enter the project directory
cd helloworld

# Pull project dependencies
go mod download
```

--------------------------------

### HTTP Server Recovery Middleware Usage

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/recovery

Example of applying the Recovery middleware to an HTTP server with custom logger and handler.

```go
var opts = []http.ServerOption{
    http.Middleware(
        recovery.Recovery(
      recovery.WithLogger(log.DefaultLogger),
            recovery.WithHandler(func(ctx context.Context, req, err interface{}) error {
                    // do someting
                    return nil
            }),
    ),
    ),
}
srv := http.NewServer(opts...)
```

--------------------------------

### Generated Go Service Implementation

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

This is a sample Go service implementation generated from a proto file. It includes basic CRUD operations for a 'Demo' resource.

```go
package service


import (
    "context"


    pb "helloworld/api/helloworld"
)


type DemoService struct {
    pb.UnimplementedDemoServer
}


func NewDemoService() *DemoService {
    return &DemoService{}
}


func (s *DemoService) CreateDemo(ctx context.Context, req *pb.CreateDemoRequest) (*pb.CreateDemoReply, error) {
    return &pb.CreateDemoReply{}, nil
}
func (s *DemoService) UpdateDemo(ctx context.Context, req *pb.UpdateDemoRequest) (*pb.UpdateDemoReply, error) {
    return &pb.UpdateDemoReply{}, nil
}
func (s *DemoService) DeleteDemo(ctx context.Context, req *pb.DeleteDemoRequest) (*pb.DeleteDemoReply, error) {
    return &pb.DeleteDemoReply{}, nil
}
func (s *DemoService) GetDemo(ctx context.Context, req *pb.GetDemoRequest) (*pb.GetDemoReply, error) {
    return &pb.GetDemoReply{}, nil
}
func (s *DemoService) ListDemo(ctx context.Context, req *pb.ListDemoRequest) (*pb.ListDemoReply, error) {
    return &pb.ListDemoReply{}, nil
}
```

--------------------------------

### Generate Proto Code

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

Generate Go code from proto files using either the 'make api' command or the 'kratos proto client' command. The generated files include .pb.go, _grpc.pb.go, and optionally _http.pb.go.

```bash
# 可以直接通过 make 命令生成
make api


# 或使用 kratos cli 进行生成
kratos proto client api/helloworld/v1/demo.proto
```

--------------------------------

### Use Kratos Middleware in gRPC Server

Source: https://go-kratos.dev/zh-cn/docs/component/transport/grpc

Demonstrates how to apply Kratos middleware, such as logging, to a gRPC server during its creation.

```go
grpcSrv := grpc.NewServer(
    grpc.Address(":9000"),
    grpc.Middleware(
        logging.Server(),
    ),
)
```

--------------------------------

### Basic Helper Log Messages

Source: https://go-kratos.dev/zh-cn/docs/component/log

Demonstrates logging messages at different levels using the Helper interface without formatting.

```go
h.Debug("Are you OK?")
h.Info("42 is the answer to life, the universe, and everything")
h.Warn("We are under attack!")
h.Error("Houston, we have a problem.")
h.Fatal("So Long, and Thanks for All the Fish.")
```

--------------------------------

### Loading Configuration from Consul

Source: https://go-kratos.dev/zh-cn/docs/component/config

Initializes a Kratos configuration instance to load settings from Consul. This requires a Consul client and specifies a path within Consul where configuration files are stored.

```go
import (
    "github.com/go-kratos/kratos/contrib/config/consul/v2"
    "github.com/hashicorp/consul/api"
)


consulClient, err := api.NewClient(&api.Config{
  Address: "127.0.0.1:8500",
})
if err != nil {
  panic(err)
}
cs, err := consul.New(consulClient, consul.WithPath("app/cart/configs/"))
if err != nil {
  panic(err)
}
c := config.New(config.WithSource(cs))
```

--------------------------------

### Basic User Schema Definition

Source: https://go-kratos.dev/zh-cn/docs/guide/ent

Defines the basic User schema with no fields or edges. This is a starting point generated by 'ent new'.

```go
// <project>/ent/schema/user.go

package schema


import "entgo.io/ent"


// User holds the schema definition for the User entity.
type User struct {
    ent.Schema
}


// Fields of the User.
func (User) Fields() []ent.Field {
    return nil
}


// Edges of the User.
func (User) Edges() []ent.Edge {
    return nil
}
```

--------------------------------

### Create HTTP Client Connection

Source: https://go-kratos.dev/zh-cn/docs/component/transport/http

Establishes a basic HTTP client connection to a specified endpoint. Ensure the endpoint is correctly formatted.

```go
conn, err := http.NewClient(
    context.Background(),
    http.WithEndpoint("127.0.0.1:8000"),
)
```

--------------------------------

### StdLogger to Console and File

Source: https://go-kratos.dev/zh-cn/docs/component/log

Demonstrates using StdLogger to output logs to both standard output and a file.

```go
// 输出到控制台
l := log.DefaultLogger
l.Log(log.LevelInfo, "stdout_key", "stdout_value")


// 输出到 ./test.log 文件
f, err := os.OpenFile("test.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
    return
}
l = log.NewStdLogger(f)
l.Log(log.LevelInfo, "file_key", "file_value")
```

--------------------------------

### Proto Validation Rules for Boolean Types

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/validate

Examples of enforcing specific boolean values (true or false) using the 'const' rule in proto-gen-validate.

```proto
// 参数必须为 true
bool state = 5 [(validate.rules).bool.const = true];
// 参数必须为 false
bool state = 5 [(validate.rules).bool.const = false];
```

--------------------------------

### Create New Kratos Project

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

Use the 'kratos new' command to generate a new project template. This command initializes a standard Kratos project structure.

```bash
kratos new helloworld
```

--------------------------------

### Proto Validation Rules for Numeric Types

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/validate

Examples of defining validation rules for integer and float types in proto files using proto-gen-validate.

```proto
// 参数必须大于 0
int64 id = 1 [(validate.rules).int64 = {gt: 0}];
// 参数必须在 0 到 120 之间
int32 age = 2 [(validate.rules).int32 = {gt:0, lte: 120}];
// 参数是 1 或 2 或 3
uint32 code = 3 [(validate.rules).uint32 = {in: [1,2,3]}];
// 参数不能是 0 或 99.99
float score = 1 [(validate.rules).float = {not_in: [0, 99.99]}];
```

--------------------------------

### Initialize Logger with Global Values in Main

Source: https://go-kratos.dev/zh-cn/docs/component/log

Initialize a logger instance in the application's entry point (cmd/server/main.go) and inject global values like service ID, name, version, and trace IDs. This logger is then typically injected into other parts of the application.

```go
logger := log.With(log.NewStdLogger(os.Stdout),
    "ts", log.DefaultTimestamp,
    "caller", log.DefaultCaller,
    "service.id", id,
    "service.name", Name,
    "service.version", Version,
    "trace_id", tracing.TraceID(),
    "span_id", tracing.SpanID(),
)

```

--------------------------------

### Enable Go Modules

Source: https://go-kratos.dev/zh-cn/docs/getting-started/start

Ensures that Go modules are enabled for dependency management. This is a recommended setting for Go projects.

```bash
go env -w GO111MODULE=on
```

--------------------------------

### Test HTTP Endpoints

Source: https://go-kratos.dev/zh-cn/docs/getting-started/start

Demonstrates how to test the application's HTTP endpoints using curl. Includes examples for a successful response and an error response.

```bash
curl 'http://127.0.0.1:8000/helloworld/kratos'
# Output:
{
  "message": "Hello kratos"
}


curl 'http://127.0.0.1:8000/helloworld/error'
# Output
{
    "code": 404,
    "reason": "USER_NOT_FOUND",
    "message": "user not found: error",
    "metadata": {}
}
```

--------------------------------

### Run Kratos Project

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

Executes the Kratos project. If multiple projects exist in subdirectories, a selection menu will appear.

```bash
kratos run
```

--------------------------------

### Add Validate Command to Makefile

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/validate

Integrate the proto validation generation command into a Makefile for easier execution. This example assumes API_PROTO_FILES is defined elsewhere.

```makefile
.PHONY: validate
# generate validate proto
validate:
    protoc --proto_path=. \
           --proto_path=./third_party \
           --go_out=paths=source_relative:. \
           --validate_out=paths=source_relative,lang=go:. \
           $(API_PROTO_FILES)
```

--------------------------------

### JSON Deserialization Example

Source: https://go-kratos.dev/zh-cn/docs/component/encoding

Deserializes a JSON byte slice into a user struct using the registered JSON Codec. The struct must be addressable (a pointer).

```go
// 直接使用内置 Codec 时需要 import _ "github.com/go-kratos/kratos/v2/encoding/json"
jsonCodec := encoding.GetCodec("json")
type user struct {
    Name string
    Age string
    state bool
}
u := &user{}
jsonCodec.Unmarshal([]byte(`{"Name":"kratos","Age":"2"}`), &u)
fmt.Println(*u)
// 输出：&{kratos 2 false}
```

--------------------------------

### Watching for Configuration Changes

Source: https://go-kratos.dev/zh-cn/docs/component/config

Sets up a watch on a specific configuration key to execute a callback function when the value changes. This enables hot reloading of configurations.

```go
if err := c.Watch("service.name", func(key string, value config.Value) {
  fmt.Printf("config changed: %s = %v\n", key, value)
  // 在这里写回调的逻辑
}); err != nil {
  log.Error(err)
}
```

--------------------------------

### Generated Error Helper Code

Source: https://go-kratos.dev/zh-cn/docs/component/errors

Example of Go code generated from proto definitions, providing helper functions to check and create specific errors.

```go
package helloworld


import (
    fmt "fmt"
    errors "github.com/go-kratos/kratos/v2/errors"
)


// This is a compile-time assertion to ensure that this generated file
// is compatible with the kratos package it is being compiled against.
const _ = errors.SupportPackageIsVersion1


func IsUserNotFound(err error) bool {
    if err == nil {
        return false
    }
    e := errors.FromError(err)
    return e.Reason == ErrorReason_USER_NOT_FOUND.String() && e.Code == 404
}


func ErrorUserNotFound(format string, args ...interface{}) *errors.Error {
    return errors.New(404, ErrorReason_USER_NOT_FOUND.String(), fmt.Sprintf(format, args...))
}


func IsContentMissing(err error) bool {
    if err == nil {
        return false
    }
    e := errors.FromError(err)
    return e.Reason == ErrorReason_CONTENT_MISSING.String() && e.Code == 400
}


func ErrorContentMissing(format string, args ...interface{}) *errors.Error {
    return errors.New(400, ErrorReason_CONTENT_MISSING.String(), fmt.Sprintf(format, args...))
}
```

--------------------------------

### Add Proto File

Source: https://go-kratos.dev/zh-cn/docs/getting-started/usage

Use the 'kratos proto add' command to add a new proto file to your API directory. The command expects the path to the proto file.

```bash
kratos proto add api/helloworld/v1/demo.proto
```

--------------------------------

### Getting a Specific Configuration Value

Source: https://go-kratos.dev/zh-cn/docs/component/config

Retrieves a single configuration value by its key path (e.g., 'service.name'). Supports type assertion like .String().

```go
name, err := c.Value("service.name").String()
if err != nil {
  panic(err)
}
fmt.Printf("service: %s", name)
```

--------------------------------

### Configure GoLand for Protobuf

Source: https://go-kratos.dev/zh-cn/docs/intro/faq

Instructions for adding third_party directory to Protobuf custom include paths in GoLand to resolve IDE errors for imported proto files.

```text
GoLand
GoLand(新)
VSCode
```

--------------------------------

### JSON Serialization Example

Source: https://go-kratos.dev/zh-cn/docs/component/encoding

Serializes a user struct to JSON bytes using the registered JSON Codec. Note that unexported fields like 'state' are omitted by default.

```go
// 直接使用内置 Codec 时需要 import _ "github.com/go-kratos/kratos/v2/encoding/json"
jsonCodec := encoding.GetCodec("json")
type user struct {
    Name string
    Age string
    state bool
}
u := &user{
    Name:  "kratos",
    Age:   "2",
    state: false,
}
bytes, _ := jsonCodec.Marshal(u)
fmt.Println(string(bytes))
// 输出：{"Name":"kratos","Age":"2"}
```

--------------------------------

### Responding with Errors using errors.New

Source: https://go-kratos.dev/zh-cn/docs/component/errors

Demonstrates how to create and return errors directly using the `errors.New` function from the Kratos errors package.

```go
// Respond with errors using errors.New()
errors.New(500, "USER_NAME_EMPTY", "user name is empty")
```

--------------------------------

### Retrieve User Information from Context

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/auth

Get user claims from the request context after JWT authentication on the server. Requires type assertion to access specific user data.

```go
func FromContext(ctx context.Context) (token jwt.Claims, ok bool) {

```

--------------------------------

### Dockerfile for Minimal Go Application Image

Source: https://go-kratos.dev/zh-cn/docs/devops/docker

This multi-stage Dockerfile builds a minimal container image for a Go application. It uses a builder stage with Go to compile the application and then copies the binary to a slim Debian base image.

```dockerfile
FROM golang:1.19 AS builder


COPY . /src
WORKDIR /src


RUN GOPROXY=https://goproxy.cn make build


FROM debian:stable-slim


RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates  \
        netbase \
        && rm -rf /var/lib/apt/lists/ \
        && apt-get autoremove -y && apt-get autoclean -y


COPY --from=builder /src/bin /app


WORKDIR /app


EXPOSE 8000
EXPOSE 9000
VOLUME /data/conf


CMD ["./server", "-conf", "/data/conf"]

```

--------------------------------

### Get Metadata Field Value from Server Context

Source: https://go-kratos.dev/zh-cn/docs/component/metadata

Retrieve a specific metadata field's value from the server context. This is useful for accessing information passed from the client.

```go
if md, ok := metadata.FromServerContext(ctx); ok {
    extra = md.Get("x-md-global-extra")
}
```

--------------------------------

### HTTP Client Selector Usage

Source: https://go-kratos.dev/zh-cn/docs/component/selector

Demonstrates how to configure an HTTP client with a custom node filter and a default weighted round robin selector. Ensure the necessary selector and filter packages are imported.

```go
import    "github.com/go-kratos/kratos/v2/selector/wrr"
import    "github.com/go-kratos/kratos/v2/selector/filter"


// 创建路由 Filter：筛选版本号为"2.0.0"的实例
filter :=  filter.Version("2.0.0")
// 创建 P2C 负载均衡算法 Selector，并将路由 Filter 注入
selector.SetGlobalSelector(wrr.NewBuilder())

hConn, err := http.NewClient(
  context.Background(),
  http.WithEndpoint("discovery:///helloworld"),
  http.WithDiscovery(r),
  http.WithNodeFilter(filter)
)
```

--------------------------------

### Configure Tracer Provider Option

Source: https://go-kratos.dev/zh-cn/docs/component/middleware/tracing

Use `WithTracerProvider` to set the trace provider. It accepts a `trace.TracerProvider` as an argument.

```go
func WithTracerProvider(provider trace.TracerProvider) Option {
    return func(opts *options) {
        opts.TracerProvider = provider
    }
}
```
Tokens:
Raw