go-kratos/kratos

> An API-first Go framework for building HTTP and gRPC microservices from a single Protobuf definition.

GitHub repo · Official website · License: MIT

Overview

Kratos is a Go microservices framework that treats the Protobuf service definition as the source of truth: you write a .proto, and code generation produces both the HTTP and gRPC server/client stubs, error types, and OpenAPI docs from it¹. It originated from an internal framework at Bilibili and was open-sourced in 2019. As of 2026 it sits among the most-starred Go microservice frameworks (~25.8k stars, ~4.2k forks), actively maintained with commits landing through mid-2026.

The framework's defining stance is "small explicit core, everything else is contrib." The main repository ships only the primitives — a transport abstraction, a middleware chain, and interfaces for registry, config, logging, and encoding. Concrete integrations (Consul/etcd/Nacos registries, Apollo/Nacos config sources, OpenTelemetry, Kafka encodings) live in a separate go-kratos/contrib repository so the core dependency tree stays minimal. This is a deliberate reaction against monolithic frameworks that pull in a database driver and a service-discovery client whether you use them or not.

The tradeoff: Kratos is a framework, not a library, and it is opinionated about project structure. Its value is highest when you commit to the proto-first workflow, the kratos CLI scaffolding, and the standard project layout. Used against the grain — as a thin HTTP router, say — it offers little over the standard library, and you pay for the code-generation toolchain (protoc, plugins, go generate) that must be set up correctly before anything compiles.

Getting Started

go install github.com/go-kratos/kratos/cmd/kratos/v3@latest
kratos new helloworld
cd helloworld
go mod tidy
kratos run

A minimal service wires HTTP and gRPC transports into one application lifecycle:

package main

import (
	"github.com/go-kratos/kratos/v3"
	"github.com/go-kratos/kratos/v3/transport/grpc"
	"github.com/go-kratos/kratos/v3/transport/http"
)

func main() {
	httpSrv := http.NewServer(http.Address(":8000"))
	grpcSrv := grpc.NewServer(grpc.Address(":9000"))

	app := kratos.New(
		kratos.Name("helloworld"),
		kratos.Version("v1.0.0"),
		kratos.Server(httpSrv, grpcSrv),
	)
	if err := app.Run(); err != nil { // blocks; handles signals + graceful shutdown
		panic(err)
	}
}

The proto-driven flow adds handlers from a service definition — kratos proto add, then kratos proto server / kratos proto client generate the HTTP and gRPC glue, leaving you to implement the business methods.

Architecture / How It Works

The core abstraction is transport.Server — anything that can Start and Stop under the app lifecycle. kratos.New(...).Run() starts every registered server, registers the instance with the configured registry, and blocks until a termination signal triggers graceful shutdown. HTTP and gRPC are two implementations of the same interface, which is why one app can expose both from one process.

Proto-first codegen is the center of gravity. protoc plus Kratos's plugins (protoc-gen-go-http, protoc-gen-go-grpc, protoc-gen-go-errors, protoc-gen-openapi) turn a single service definition into typed HTTP routes, gRPC stubs, error constructors, and API docs. HTTP routing derives from google.api.http annotations, so a method is exposed on both protocols with consistent semantics.

Middleware is a func(Handler) Handler chain shared across transports — recovery, logging, tracing, metrics, validation, and auth are all middleware, applied uniformly to HTTP and gRPC. Because the chain is transport-agnostic, a metrics or tracing middleware written once instruments both protocols.

Errors are modeled as a Protobuf type carrying an HTTP-style code, a machine-readable reason string, and metadata. protoc-gen-go-errors generates typed helpers per reason enum, so a service returns v1.ErrorUserNotFound(...) and the transport layer maps it to the correct HTTP status or gRPC code automatically — one error model, two wire formats.

Registry, config, and encoding are interfaces in core with implementations in contrib. Service discovery (Registrar/Discovery), configuration (config.Source with live-reload watchers), and codecs are all pluggable. Logging in the v3 line is built on the standard library's log/slog, with OpenTelemetry bridges living in contrib rather than the core.

Dependency injection is not built in, but the standard project layout generated by kratos-layout uses Google's wire for compile-time DI, splitting a service into api, internal/service, internal/biz, internal/data, and internal/server layers².

Production Notes

The toolchain is the first hurdle. Nothing generates without a correct protoc plus the matching plugin versions on PATH. Version skew between protoc-gen-go, the gRPC plugin, and the Kratos plugins is the most common "it worked on my machine" failure. Pin plugin versions and run generation in CI so the committed generated code is reproducible; check generated files in rather than regenerating on every build.

Major-version rewrites are real migrations, not bumps. v1 → v2 was a full rewrite of the API surface, and v3 continues to make previously implicit behavior explicit and trims core dependencies. The README explicitly directs you to the v2-to-v3 migration guide before upgrading production services³ — do not treat a major bump as a drop-in. v3 also raises the minimum to Go 1.25.

Contrib versions drift from core. Because integrations live in a separate repository with independent tagging, a contrib module can lag behind a core release or pull a different transitive dependency version. Audit the go.mod of each contrib package you import; mismatched google.golang.org/grpc or OpenTelemetry versions between core and contrib surface as confusing build or runtime errors.

Graceful shutdown depends on registry cooperation. app.Run() deregisters on shutdown, but connection draining and load-balancer propagation delay mean in-flight requests can still hit a terminating instance. Configure readiness probes and a shutdown grace period on the orchestrator side; the framework's deregistration alone does not guarantee zero-downtime rollout.

Observability is opt-in. Tracing and metrics are middleware you add plus contrib exporters you wire — a fresh service has none by default. Budget setup time for the OpenTelemetry contrib packages rather than assuming instrumentation ships out of the box.

When to Use / When Not

Use when:

• You want one service definition to serve both HTTP (REST/JSON) and gRPC clients without maintaining two code paths.
• You are building a fleet of Go microservices and want a consistent layout, error model, and middleware story across all of them.
• You are comfortable committing to a proto-first workflow and the kratos CLI.
• You want a minimal core with integrations you add explicitly rather than a batteries-included monolith.

Avoid when:

• You need a plain HTTP API and don't want a codegen toolchain — a router like Gin or the standard library is lighter.
• Your team won't adopt Protobuf; most of Kratos's leverage evaporates without it.
• You want an all-in-one framework that bundles ORM, job queues, and admin scaffolding — go-zero or a fuller stack fits better.
• You need long-term API stability with rare breaking changes; Kratos has rewritten its surface across major versions.

Alternatives

• zeromicro/go-zero — batteries-included Go microservice framework with its own goctl codegen and built-in resilience patterns; use it when you want more bundled (caching, rate limiting) out of the box.
• go-kit/kit — a toolkit of composable packages rather than a framework; use it when you want to assemble your own architecture with no scaffolding opinions.
• micro/go-micro — pluggable RPC-centric microservice framework; use it when service discovery and pub/sub abstractions are the priority over proto-first HTTP+gRPC parity.
• gin-gonic/gin — a fast HTTP router, not a microservice framework; use it when you only need REST and no gRPC or codegen.
• grpc-ecosystem/grpc-gateway — generates a REST proxy in front of a gRPC service; use it when you already have gRPC and just need a JSON edge, without adopting a full framework.

History

References

1. ^ Kratos documentation — Getting Started. https://go-kratos.dev/docs/getting-started/start
2. ^ Kratos standard project layout (uses google/wire for DI). https://github.com/go-kratos/kratos-layout
3. ^ Kratos README and v2-to-v3 migration guide. https://github.com/go-kratos/kratos/blob/main/docs/migration/v2-to-v3.md

Tags

go, golang, microservices, grpc, http, protobuf, framework, api-first, cloud-native, code-generation, middleware