Why Kratos Is the Go Microservice Framework You Need: Protobuf, DI, and OpenTelemetry Explained

Overview of Kratos

Kratos (github.com/go-kratos/kratos) is a lightweight Go microservice framework that aims to provide a complete development experience, integrating surrounding tools so that service governance becomes transparent and developers can focus on business delivery. It emphasizes high extensibility, componentization, engineering discipline, and standardization, making the repository a valuable learning resource for microservice best practices.

Protobuf Ecosystem

All API definitions, gRPC services, HTTP services, request validation, error definitions, Swagger JSON, and service templates are built on Protobuf IDL. The following helloworld.proto example demonstrates a service definition, HTTP mapping, Swagger description, field validation, and custom error enums.

syntax = "proto3";
package helloworld;
import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "validate/validate.proto";
import "errors/errors.proto";

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

// The greeting service definition.
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/helloworld/{name}",
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      description: "这是SayHello接口";
    };
  }
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1 [(validate.rules).string = {min_len: 1, max_len: 16}];
}

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

enum ErrorReason {
  option (errors.default_code) = 500;
  USER_NOT_FOUND = 0 [(errors.code) = 404];
  CONTENT_MISSING = 1 [(errors.code) = 400];
}

Running kratos proto client api/helloworld/ helloworld.proto generates client code, illustrating the productivity boost that Protobuf‑driven code generation brings.

Openness – Extensible Transport Layer

The server transport interface defines Start(), Stop(), and Endpoint(). Implementing these methods allows new protocols to be added without touching the application layer, which only manages configuration, lifecycle, and loading order.

The App layer remains agnostic to the underlying protocol implementation.

Logging Architecture

Kratos defines a minimal Logger interface with a log level and key/value pairs. Extensibility is achieved via a Valuer callback that can inject timestamps, caller stack, trace IDs, etc., at log time.

Usage involves wrapping the original logger with With, which creates a new logger holding the additional key/value pairs and evaluates the Valuer when Log is called.

Tracing Integration

Kratos adopts the CNCF OpenTelemetry project, supporting OpenTracing and W3C Trace Context. It can seamlessly integrate with Zipkin, Jaeger, or custom propagators, and the tracer provider can be swapped via otel.SetTracerProvider() to accommodate different back‑ends.

Engineering Practices – Functional Options

Kratos configures components using functional options, avoiding mutable structs and distinguishing zero values from unset fields. The ClientOption pattern stores configuration in an unexported struct, applied via variadic arguments in NewClient.

Unexported options struct prevents external mutation.

Default values are set once; omitted options leave defaults untouched.

Required parameters are explicit, optional ones are passed variadically.

Unified Error Model

Kratos provides a structured error type with fields Code, Reason, Message, and Metadata. It implements GRPCStatus() for automatic conversion to google.rpc.Status and the standard errors.Is interface for reliable error comparison.

Dependency Injection

Kratos recommends compile‑time DI with Google Wire. Providers expose constructors; an injector assembles them into the final service graph, generating readable initialization code.

type RedisSource struct {
    redisCli *redis.Client
}
func NewRedisSource(db *redis.Client) *RedisSource { return &RedisSource{redisCli: db} }
func NewRedis(cfg *redis.Options) *redis.Client { return redis.NewClient(cfg) }
var ProviderSet = wire.NewSet(NewRedis, NewRedisSource)

// +build wireinject
func initService(cfg *redis.Options) *service.Service {
    panic(wire.Build(redisSource.ProviderSet, wire.Bind(new(data.DataSource), new(*redisSource.RedisSource)), service.NewService))
}

// Generated code (wireinject disabled)
func initService(cfg *redis.Options) *service.Service {
    client := redis.NewRedis(cfg)
    redisSource := redisSource.NewRedisSource(client)
    return service.NewService(redisSource)
}

Package Organization

Kratos follows clear, single‑responsibility packages:

/cmd : installable CLI tools.

/api : public interface definitions.

/errors : unified error handling.

/config : multi‑source configuration with atomic hot‑reload.

/internal : non‑public or unstable APIs.

/transport : abstraction of HTTP/gRPC transports.

/middleware : adapters between transport and service.

/third_party : external dependencies.

This package‑by‑function layout promotes readability, testability, and low coupling.