go-kratos/kratos · 上手攻略

• 仓库：go-kratos/kratos
• 链接：https://github.com/go-kratos/kratos
• 分类：Go 微服务框架 · 云原生
• 作者：Jay
• 更新：2026-07-14

这是什么

Kratos 是 Go 语言的微服务框架，专为云原生时代设计。它提供了一套轻量、显式（explicit）的 API，涵盖传输层、中间件、服务注册发现、配置、日志、编解码和代码生成等环节，让开发者专注于业务逻辑而非基础设施搭建。

v3 是当前主要版本（README 标注需 Go 1.25+），相比 v2 大幅精简了核心依赖，并将原来隐式的行为显式化，详见官方 v2 → v3 迁移指南。

核心特性一览：

• API First：用 Protobuf 定义接口，自动生成 HTTP/gRPC 代码
• 统一传输层：同一服务同时暴露 HTTP 和 gRPC，无需两套实现
• 可组合中间件：恢复、日志、验证、追踪、指标、认证等开箱即用，可按需替换
• 插件化组件：注册中心、配置源、编解码器均支持插拔
• 标准日志：基于标准库 log/slog，contrib 包提供 OpenTelemetry 扩展
• 一站式代码生成：Kratos CLI 全流程覆盖项目创建、Proto 生成、Wire 依赖注入、OpenAPI 文档

解决什么问题

在 Go 生态里，从零搭建微服务门槛不低：要选 HTTP 框架、比选 gRPC 库、设计项目结构、串联依赖注入、配置追踪/指标……Kratos 的目标是把这些最佳实践打包成统一方案，让团队从第一天起就站在同一个规范上。

它的设计思路深受 go-kit、go-micro、google/go-cloud、go-zero 和 beego 影响，取各家之长并统一了 API 风格。

快速安装

前置依赖

⚠️ 国内用户注意：若遇到网络问题，建议提前配置 GOPROXY： bash go env -w GOPROXY=https://goproxy.cn,direct

安装 Kratos CLI 并升级

go install github.com/go-kratos/kratos/cmd/kratos/v3@latest
kratos upgrade   # 升级到最新版本

核心用法

1. 创建项目（脚手架）

kratos new helloworld
cd helloworld
go mod download

这会从 GitHub 拉取 kratos-layout 模板，生成一套完整项目结构。

⚠️ 若拉取失败，可手动 git clone 模板后本地创建项目： bash git clone https://github.com/go-kratos/kratos-layout.git helloworld cd helloworld go mod edit -module github.com/your-org/your-service

2. 生成依赖注入代码（Wire）

go get github.com/google/wire/cmd/wire@latest
go generate ./...

3. 运行服务

kratos run
# 访问 http://localhost:8000/helloworld/kratos
# 期望返回: { "message": "Hello kratos" }

4. 定义新的 Proto API

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

5. 标准项目结构（来自 kratos-layout）

api/              # Protobuf API 定义及生成的 Go 代码
cmd/              # 应用入口
configs/          # 本地配置文件（YAML）
internal/
  server/         # HTTP/gRPC Server 的构造逻辑
  service/        # 传输层面的服务方法（暴露给 HTTP/gRPC）
  biz/            # 业务用例、实体、错误定义、仓库接口
  data/           # 仓库的具体实现（数据库、外部服务等）
third_party/      # Protobuf 依赖
openapi.yaml     # 生成的 OpenAPI 文档

6. 手动编写服务入口（不依赖脚手架时）

package main

import (
    "log"

    "github.com/go-kratos/kratos/v3"
    "github.com/go-kratos/kratos/v3/transport/grpc"
    "github.com/go-kratos/kratos/v3/transport/http"
    pb "github.com/your-org/your-service/api/helloworld/v1"
)

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

    // 注册服务实现
    // v1.RegisterGreeterServer(grpcSrv, &greeterServer{})
    // v1.RegisterGreeterHTTPServer(httpSrv, &greeterServer{})

    app := kratos.New(
        kratos.Name("kratos-app"),
        kratos.Version("v1.0.0"),
        kratos.Server(httpSrv, grpcSrv),
    )

    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

7. 代码生成命令速查

典型适用场景

• 中大型微服务项目：需要统一项目结构、强制分层（service/biz/data）的团队
• API First 开发：先定义 Protobuf，再用自动生成代码，减少手写 REST 或 gRPC 样板
• 需要同时暴露 HTTP 和 gRPC：移动端用 HTTP，前端/内部服务用 gRPC，同一实现双端支持
• 需要强依赖注入治理：Wire 强制声明式注入，适合大型项目的依赖管理
• 云原生部署：自带 Docker 支持，config.yaml 与 Kubernetes 配置天然对齐

坑与注意

1. Go 版本要求高：v3 要求 Go ≥ 1.25，线上项目升级前务必确认版本。（v2 要求 Go ≥ 1.16）

2. v2 → v3 迁移成本：v3 做了不少 breaking change，已有项目迁移前必读官方迁移文档，不要直接 kratos upgrade。

3. protoc 必须安装：没有 protoc，代码生成会静默失败。Linux/macOS 下推荐 brew install protobuf，或从 releases 下载对应平台的二进制。

4. layout 模板依赖 GitHub：在国内网络环境下 kratos new 可能超时，建议提前配置代理或手动 clone kratos-layout。

5. Wire 生成失败：若 go generate ./... 报错，先确认 wire 工具链已安装且 $GOPATH/bin 或 $GOBIN 在 PATH 中。

6. contrib 包版本同步：Kratos 核心与各 contrib 包的版本需对应，混用可能导致运行时 panic。推荐在 go.mod 中锁定具体版本。

7. 生产环境不要裸用 layout：layout 里的 in-memory 存储只是示例，生产需替换为真实数据库（建议搭配 gorm、ent 或 sqlx）。

与同类对比

一句话推荐：如果你团队使用 Go、需要规范的分层架构、同时对外提供 HTTP 和 gRPC 接口，Kratos 是目前最完整的开箱即用方案；如果只是做轻量 HTTP API，直接用 Gin 更简单。

一句话推荐结论

Kratos 是 Go 生态里把微服务工程化做到极致的框架——Protobuf 定义一切、CLI 生成一切、分层约束一切，适合追求规范与效率平衡的中大型团队。