go-kratos/kratos: a Go microservices framework built around Protobuf code generation

The problem Kratos solves: one interface definition, two transports

A Go service that speaks both HTTP and gRPC usually ends up with two hand-written layers that drift apart. Kratos attacks that directly. The README describes it as a lightweight Go framework for cloud-native microservices that provides small, explicit APIs for transport, middleware, registry, configuration, logging, encoding, and code generation, so applications can focus on business logic. The operative phrase is API-first development with Protobuf and generated HTTP/gRPC code. You write a .proto file, run the CLI, and get both server stubs and client code from the same source of truth.

The audience is narrower than the tagline suggests. This is for teams that already treat Protobuf as an interface contract, that run protoc in their build, and that expect a service to expose gRPC to internal callers and HTTP to browsers or third parties. If your team writes handlers by hand and has no schema compiler in its pipeline, the framework's central workflow is not for you, and the generated-code step becomes overhead rather than leverage. Kratos is also opinionated about structure: the project layout lives in a separate repository, kratos-layout, not in the core module.

How Kratos is put together: a thin core plus a contrib ecosystem

The repository layout is the clearest statement of the design. Top-level directories map to concerns: transport/, middleware/, registry/, selector/, config/, encoding/, errors/, log/, metadata/, and cmd/. There is no single monolithic package that owns the request path. Each concern is a package with an interface, and the core ships a small number of implementations.

The dependency list in go.mod confirms how thin the core is. Direct requirements are fsnotify, go-playground/form, google/uuid, gorilla/mux, gorilla/websocket, golang.org/x/sync, the genproto API and RPC packages, grpc, protobuf, and yaml.v3. Registries, config stores, and observability integrations that would otherwise drag in vendor SDKs are pushed to contrib/ instead. That is a deliberate trade: the core stays small, but a real service pulls in contrib modules for whatever registry or config backend it uses, so the effective dependency surface is larger than go.mod suggests.

The app entry point is small enough to read in one screen. The README's example constructs an HTTP server on :8000 and a gRPC server on :9000, then hands both to kratos.New with a name and version, and calls app.Run. Servers are values passed to the application, not globals registered by import side effects. That makes the wiring visible in main, which is the point of the explicit-APIs claim.

Logging is worth calling out because it signals the v3 direction: the README says logging is based on the standard-library log/slog, with OpenTelemetry extensions in contrib packages. That means the framework does not impose a logging facade of its own, but it also means anything you need beyond slog comes from contrib or from your own code.

Installing the Kratos CLI and running a first service

The README lists three requirements: Go 1.25 or later, protoc, and protoc-gen-go. The go.mod file pins go 1.25.0, so the version floor is real rather than advisory. Install the CLI with go install, then let it update itself:

go install github.com/go-kratos/kratos/cmd/kratos/v3@latest
kratos upgrade

The module path carries the v3 major version, which matters if you are copying commands from older tutorials. After the install, scaffold a service and run it:

kratos new helloworld
cd helloworld
go mod tidy
kratos run

According to the README, the service starts and you can visit http://localhost:8000/helloworld/kratos to see a response. That URL is the first thing to check, because a failure there usually means the generated code was not regenerated after a change, not that the framework failed to start.

For the fuller loop, the README gives the sequence that adds a proto file, generates the client and server code, and regenerates everything through go generate:

kratos proto add api/helloworld/helloworld.proto
kratos proto client api/helloworld/helloworld.proto
kratos proto server api/helloworld/helloworld.proto -t internal/service
go generate ./...
kratos run

Note the division of labour: kratos proto client produces the transport-level client and server bindings, kratos proto server writes a service implementation into internal/service, and go generate ./... runs whatever generators the project has configured. If you skip go generate, the new proto definitions will not be reflected in the running binary. The Makefile shows the same generators built directly from source, which is the route to take if you want to pin versions rather than install @latest.

Where Kratos gets in the way

The code-generation step is the main cost, and it is not optional in practice. Every interface change means editing a .proto file, rerunning the client and server generators, and rerunning go generate. Teams that treat generated files as something to commit will notice the churn in review; teams that generate in CI need protoc, protoc-gen-go, and the Kratos plugins available in the build image. The README lists protoc and protoc-gen-go as requirements but does not document how to pin the Kratos-specific generators, so version drift between a developer's machine and CI is a real failure mode.

The v3 release is the second constraint. The README states plainly that v3 reduces core dependencies and makes previously implicit behavior explicit, and directs readers to the v2 to v3 migration guide before upgrading production services. That wording is a warning, not boilerplate: code that relied on implicit behaviour in v2 needs review. If you are on v2.9.x, the upgrade is a project, not a version bump. The README does not document a rollback path for the migration.

The third limitation is ecosystem shape. Because registry, config, and encoding implementations live in contrib, the quality and maintenance of those modules is separate from the core. The README points to a contrib ecosystem for optional integrations but does not enumerate which backends are supported or how current each one is. Before designing around a specific registry or config store, check that the contrib module exists and is being updated.

Finally, Kratos is the wrong tool if you are building a single HTTP service with no gRPC requirement and no Protobuf schema. You would carry the generator toolchain for no benefit.

Kratos compared with go-zero, which the project itself cites

The README's acknowledgments list go-zero among the projects that influenced Kratos design, which makes it the honest comparison. The difference is where the interface definition lives. Kratos puts Protobuf at the centre: the .proto file is the contract, and HTTP and gRPC bindings are generated from it. go-zero's API definition is its own .api DSL, and code generation flows from that file, with Protobuf available for gRPC paths rather than as the single source for everything.

The practical consequence is portability. A Kratos service's contract is a standard Protobuf file that other languages and other gRPC tooling can consume without knowing anything about Kratos. An .api file is specific to go-zero's toolchain. If your organization has non-Go consumers, or you want the option of generating clients in another language later, the Protobuf-first route keeps that door open.

The trade runs the other way too. go-zero's DSL is tuned to its own generation pipeline, so the file and the generated code stay close together. Kratos spreads the workflow across kratos proto add, kratos proto client, kratos proto server, and go generate, which is more moving parts to keep in sync. The README's own sequence shows four commands before kratos run. That is the price of staying inside the standard Protobuf ecosystem.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-08-19, about a month before this writing. The most recent release is v3.0.0, dated 2026-06-26, following v2.9.2 in December 2025 and v2.9.1 in September 2025. The v2 line received patch releases across roughly fifteen months, and v3 arrived as a major version with a documented migration guide rather than as a silent change.

That pattern tells you what to budget. Major versions here are not cosmetic: the README frames v3 as a reduction of core dependencies and a move toward explicit behaviour, which means the upgrade touches wiring. The migration guide at docs/migration/v2-to-v3.md is the document to read before planning the work, and the fact that it exists in the repository rather than only on the website is a good sign for anyone who wants to review it offline.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT is permissive: it allows use, modification, and redistribution, including in proprietary products, provided the copyright notice and permission notice are retained. That is a summary of the licence text, not legal advice; if your organization has a policy on attribution notices in distributed binaries, have someone read the LICENSE file rather than this paragraph.

One maintenance detail worth checking before you adopt: the README points to a separate kratos-layout repository for the project layout and a separate examples repository. Those are distinct projects with their own release cadence, so the health of the core module does not automatically tell you the scaffold is current.

Editorial conclusion

Adopt go-kratos/kratos if your team already writes Protobuf interfaces and wants HTTP and gRPC served from one definition, and if you are willing to run protoc and the generated-code workflow in CI. Do not adopt it if you want a framework that works without a schema compiler, or if you are on a Go release older than 1.25. Before committing, verify two things yourself: that the v2 to v3 migration guide covers every component you depend on, and that each registry, config store and encoding you need exists in the contrib ecosystem rather than only in core.

Frequently asked questions

Official sources

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