go-kratos/kratos v3: A Protobuf-First Go Microservice Framework

The Problem Kratos Targets: Glue Code Between HTTP, gRPC and Protobuf

In a plain Go microservice, the tedious part is rarely the business logic. It is the wiring: one server for REST clients, another for internal gRPC callers, duplicated request structs on each side, a registry client, a config loader, and a logging setup that has to be threaded through every handler. Kratos exists to collapse that wiring into small, explicit APIs covering transport, middleware, registry, configuration, logging, encoding and code generation, as the README puts it. The intended audience is a team that has already decided on Protobuf as the contract format and wants the generator to produce both the HTTP and gRPC surfaces from one file. A single-service CRUD app with three endpoints is not the target. Neither is a team that wants an opinionated platform to hand them a running cluster. Kratos is a library and a CLI, and the README positions it as lightweight rather than batteries-included.

How the Transport Layer Unifies HTTP and gRPC in One Process

The usage example in the README is the clearest statement of the architecture. You construct an HTTP server with http.NewServer(http.Address(":8000")) and a gRPC server with grpc.NewServer(grpc.Address(":9000")), then hand both to kratos.New via kratos.Server(httpSrv, grpcSrv), along with kratos.Name and kratos.Version. Calling app.Run() starts the pair under one application lifecycle. That is the core data flow: one process, one lifecycle, two listeners, and a shared middleware chain that both transports draw from. Because the servers are constructed with functional options rather than a config struct, the wiring stays visible in main. The cost of that design is verbosity. Every option is a call, and there is no config file that magically assembles the server graph for you. The benefit is that when a service misbehaves, the startup path is a short function you can read top to bottom rather than a framework-managed container. Metadata, errors, validation and OpenAPI handling are described in the README as consistent across the two transports, which is the payoff for keeping them in one application object.

Getting a Service Running: The CLI Commands and Toolchain Requirements

The README lists three prerequisites before anything else: Go 1.25 or later, protoc, and protoc-gen-go. The CLI itself is installed with go install github.com/go-kratos/kratos/cmd/kratos/v3@latest followed by kratos upgrade. From there the shortest path to a running service is kratos new helloworld, cd helloworld, go mod tidy, kratos run, after which the README says the service answers at http://localhost:8000/helloworld/kratos. The fuller flow shows what the generator is actually for: kratos proto add api/helloworld/helloworld.proto creates the contract, kratos proto client generates the client side, kratos proto server api/helloworld/helloworld.proto -t internal/service scaffolds the server implementation into internal/service, go generate ./... runs the remaining generation, and kratos run starts it. The layout is not arbitrary; the README points to a separate kratos-layout repository as the canonical project structure, so the generated directories are a convention you are expected to keep rather than a starting point you immediately discard. Note the Go 1.25 floor. Teams on older toolchains will be blocked at installation, not at compile time, which is at least an early and unambiguous failure.

The v3 Dependency Trim and What It Costs Existing Services

The README devotes a short section to migration and says plainly that v3 reduces core dependencies and makes previously implicit behavior explicit, directing readers to docs/migration/v2-to-v3.md before upgrading production services. That phrasing is the whole story available here, and it is worth taking at face value. Reducing core dependencies means the framework no longer pulls in things you may have been relying on transitively. Making implicit behavior explicit means code that worked because a default was applied for you may now need that choice written out. There is a logging example in the same release: the README states logging is based on the standard library log/slog, with OpenTelemetry extensions living in contrib packages rather than the core. A service that previously got tracing hooks from the core module will need to add the contrib package. The release dates support a slow, deliberate cadence: v2.9.1 in September 2025, v2.9.2 in December 2025, and v3.0.0 in June 2026. That is roughly a major version per year of accumulated change, which is manageable, but the v3 jump is not a drop-in version bump.

Where Kratos Is the Wrong Tool

The contrib ecosystem is the framework's main structural limitation. Registries, config stores, middleware, encodings and observability integrations live outside the core repository, which keeps the core small but means the quality and maintenance of any given integration depends on that separate package, not on the framework release. If your registry or config backend has no contrib package, you are writing an adapter against the pluggable interfaces yourself. The second limitation is the Protobuf requirement. The entire workflow is API-first: kratos proto add, kratos proto client, kratos proto server. A team that wants to write Go handlers first and derive an API description later will spend its time fighting the generator rather than using it. Third, Kratos does not solve deployment. There is no sidecar, no control plane, no traffic policy engine in the material here. It gives you a well-structured binary, and everything about how that binary is scheduled, routed and secured is left to whatever platform you already run. If you were hoping the framework would supply that, it will not.

How Kratos Differs from go-zero and go-kit

The README's acknowledgments name go-kit/kit, go-micro, google/go-cloud, go-zero and beego as design influences, so the comparison is fair game. The closest functional overlap is go-zero, which also generates Go microservice scaffolding from a definition file. The difference in approach is the contract language. Kratos centers on Protobuf, which means the same .proto produces gRPC stubs and HTTP bindings, and the generated artifacts are standard Protobuf output that other tooling can consume. go-zero centers on its own .api DSL, which is more compact for HTTP-only services but is not a cross-language contract format. If your services are consumed by non-Go clients or you want one schema to drive gRPC, HTTP and documentation, Kratos's choice matters. go-kit sits at the opposite end: it is a collection of Go packages for building services, with no code generator and no prescribed layout, so you assemble the transport and middleware stack by hand. Kratos trades some of that freedom for a generator and a canonical project layout. Neither is strictly better; they fail in different ways. go-kit gives you nothing you did not ask for and nothing you forgot to ask for. Kratos gives you a working skeleton, and you inherit its conventions.

Maintenance, Licensing and What to Verify Before Adopting

Kratos is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive license with no copyleft obligation on your own code, but the contrib packages are separate modules and each carries its own license, so the MIT label on the core repository does not automatically extend to every integration you pull in. Check each contrib package you depend on individually. On maintenance cost, the material shows an active repository with a documented contribution guide, a security contact at go-kratos@googlegroups.com with private handling before disclosure, and development targets of make test and make lint. The upgrade cost is the part to budget for. The v3 release notes point to a migration guide rather than describing the changes inline, and the README explicitly warns to review it before upgrading production services. A practical first step is to run kratos new helloworld in a scratch directory, compare the generated internal/service and api layout against your own, and count how many files the generator would own. That tells you more about migration effort than any changelog summary will.

Editorial conclusion

Adopt Kratos if your team already treats .proto files as the source of truth and you want one process serving both HTTP and gRPC without hand-writing the glue. Skip it if you are building a single small HTTP service or you need a full service mesh sidecar model, since Kratos is a library-level toolkit, not a platform. Before committing, read docs/migration/v2-to-v3.md, confirm your Go toolchain is 1.25 or later, and run the generated layout end to end with kratos new helloworld so you can see how much of your current wiring the generator would replace.

Official sources

1. go-kratos/kratos on GitHub
2. License: MIT
3. Project website
4. README
5. Releases