CloudWeGo 入门指南

前言

CloudWeGo 是字节跳动基础架构服务框架团队开源的一组云原生中间件项目，目标是帮助开发者快速构建高性能、高扩展性、高可靠的微服务系统。它不是一个单独的框架，而是一套围绕服务通信、服务治理、网络通信、序列化、AI 应用开发等场景展开的生态。

如果你是第一次接触 CloudWeGo，可以先把它理解为下面这几类工具的组合：

写 HTTP 服务：优先看 Hertz。
写 Go RPC 微服务：优先看 Kitex。
写 Rust RPC 或 HTTP 服务：优先看 Volo。
写 Go 语言 AI 应用或 Agent：优先看 Eino。

本文会按照“先跑起来，再理解生态，再逐步深入”的方式梳理 CloudWeGo 的入门路径。文章内容参考 CloudWeGo 官方中文文档，如需查看最新细节，建议以官方文档为准。

CloudWeGo 生态概览

CloudWeGo 的核心项目很多，初学时不建议一口气全学。可以先从业务入口层和服务通信层开始。

项目	语言	主要定位	适合什么时候学
Kitex	Go	高性能 RPC 框架	需要服务间调用、IDL 代码生成、服务治理时
Hertz	Go	高性能 HTTP 框架	需要写 Web API、网关、BFF、HTTP 服务时
Volo	Rust	Rust RPC/HTTP 框架	团队使用 Rust，追求安全性与性能时
Eino	Go	AI 应用开发框架	需要搭建 LLM 应用、Agent、工具调用、工作流时
Netpoll	Go	网络库	需要了解底层网络性能优化时
Sonic	Go	JSON 库	需要高性能 JSON 序列化与反序列化时

从工程实践看，最典型的 CloudWeGo 微服务架构是：

  graph LR
A(浏览器或客户端) --> B(Hertz HTTP API)
B --> C(Kitex RPC Client)
C --> D(Kitex RPC Server)
D --> E(数据库或缓存)
B --> F(认证、限流、日志中间件)
D --> G(服务注册、服务发现、链路追踪)

Hertz 负责接住外部 HTTP 请求，Kitex 负责内部服务之间的 RPC 调用。等这条主线跑通之后，再去补服务发现、负载均衡、超时、重试、熔断、链路追踪、日志和指标，就会比较自然。

学习前需要准备什么

如果先学习 Hertz 和 Kitex，需要准备 Go 开发环境。

安装 Go，并确保 go version 能正常输出。
确认已经开启 Go Modules。Go 1.15 之后默认开启。
确认 GOPATH 正常，并把 $GOPATH/bin 加入 PATH。
国内环境可以设置 Go 代理：

1	go env -w GOPROXY=https://goproxy.cn

根据官方文档，Hertz 推荐 Go 版本不低于 1.19。Kitex 文档建议使用较新的 Go 版本，并保证对最新三个正式版本的兼容性。对于初学者来说，直接安装当前稳定版 Go 最省心。

如果要学习 Volo，需要准备 Rust 环境。官方文档中 Volo CLI 要求 Rust 版本不低于 1.80.0。

第一站：用 Hertz 写一个 HTTP 服务

Hertz 是 CloudWeGo 的 Go HTTP 框架，适合用来写 Web API、网关服务、BFF 服务等。它的入门体验和常见 Go Web 框架比较接近：创建 server，注册路由，启动服务。

创建项目

1 2	mkdir hertz_demo cd hertz_demo

新建 main.go：

package main

import (
	"context"

	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/cloudwego/hertz/pkg/common/utils"
	"github.com/cloudwego/hertz/pkg/protocol/consts"
)

func main() {
	h := server.Default()

	h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
		c.JSON(consts.StatusOK, utils.H{"message": "pong"})
	})

	h.Spin()
}

初始化 Go Module 并拉取依赖：

1 2	go mod init hertz_demo go mod tidy

运行服务：

go run .

另开一个终端测试接口：

1	curl http://127.0.0.1:8888/ping

如果看到下面的输出，说明 Hertz 服务已经跑起来了：

1	{"message":"pong"}

什么时候使用 hz

hz 是 Hertz 提供的代码生成工具。写简单 Demo 时可以手写 main.go，但到了真实项目，建议用 IDL 和 hz 生成项目骨架。

安装命令：

1	go install github.com/cloudwego/hertz/cmd/hz@latest

常见用法有两类：

hz new：生成一个新的 Hertz 项目。
hz update：IDL 发生变化后，更新已有项目代码。

Hertz 支持通过 Thrift 或 Protobuf IDL 生成 HTTP 项目。这样做的好处是接口定义会更稳定，前后端、服务端、网关之间可以围绕 IDL 协作，减少“文档和代码不一致”的问题。

第二站：用 Kitex 写一个 RPC 服务

Kitex 是 CloudWeGo 的 Go RPC 框架，适合做服务之间的高性能通信。和 HTTP 框架不同，RPC 更强调“服务接口定义”和“客户端/服务端代码生成”。

学习 Kitex 时，建议先建立一个基本认知：IDL 是服务契约，Kitex 根据 IDL 生成框架代码，我们只需要补业务逻辑。

安装 kitex 工具

1	go install github.com/cloudwego/kitex/tool/cmd/kitex@latest

安装后可以检查版本：

1	kitex --version

如果提示找不到命令，通常是 $GOPATH/bin 没有加入 PATH。

直接运行官方示例

对于初学者，最快的方式是先把官方示例跑起来。

1
2
3

git clone https://github.com/cloudwego/kitex-examples.git
cd kitex-examples/hello
go run .

服务端启动后，另开一个终端运行客户端：

1	go run ./client

客户端能够持续输出响应日志，就说明已经完成一次 RPC 调用。

Kitex 的基本开发流程

真实项目中，Kitex 的开发流程大致是：

定义 Thrift 或 Protobuf IDL。
使用 kitex 命令生成服务端和客户端代码。
在 handler 中补业务逻辑。
在调用方使用生成的 client 发起 RPC 请求。
接入服务注册、服务发现、超时、重试、熔断、日志、链路追踪等治理能力。

一个极简 Thrift IDL 可以长这样：

namespace go api

struct Request {
    1: string message
}

struct Response {
    1: string message
}

service Hello {
    Response echo(1: Request req)
}

根据 IDL 生成代码时，可以使用类似下面的命令：

1	kitex -module your_module_name -service hello hello.thrift

生成后，业务开发者重点关注 handler 的实现，而不是手写 RPC 通信细节。这也是 Kitex 这类框架的核心价值：把通信、编解码、客户端、服务端骨架和治理能力沉到框架里。

Hertz 和 Kitex 怎么组合

一个常见的入门练习是：用 Hertz 暴露 HTTP 接口，再在 Handler 中调用 Kitex Client。

整体流程如下：

  sequenceDiagram
participant U as 用户
participant H as Hertz API
participant C as Kitex Client
participant S as Kitex Server
participant DB as 数据库
U->>H: GET /users/1
H->>C: 调用 GetUser RPC
C->>S: 发送 RPC 请求
S->>DB: 查询数据
DB-->>S: 返回数据
S-->>C: 返回 RPC 响应
C-->>H: 返回业务结果
H-->>U: 返回 JSON

这条链路跑通后，就可以逐步补上工程能力：

在 Hertz 侧加认证、跨域、访问日志、参数绑定和校验。
在 Kitex 侧加服务注册发现、负载均衡、超时、重试和熔断。
在全链路加 trace、metrics、结构化日志。
用统一 IDL 管理接口契约。

如果你正在学习微服务，建议不要一开始就把所有治理能力都接上。先写一个能跑的 HTTP + RPC Demo，再逐个引入能力，理解会扎实很多。

第三站：认识 Volo

Volo 是 CloudWeGo 的 Rust 服务框架，面向 RPC 和 HTTP 场景。它适合已经有 Rust 基础，或者团队计划用 Rust 写高性能服务的情况。

安装 Volo CLI：

1	cargo install volo-cli

查看命令：

volo help

生成一个 RPC 项目时，可以先写 IDL，再执行：

1	volo init volo-rpc-example idl/rpc_example.thrift

生成一个 HTTP 项目时，可以执行：

1	volo http init volo-http-example

对于 Go 技术栈的同学，Volo 可以先作为了解项；对于 Rust 技术栈的同学，它就是 CloudWeGo 生态里最值得优先看的服务框架。

第四站：认识 Eino

Eino 是 CloudWeGo 生态中的 Go AI 应用开发框架，适合用来搭建 LLM 应用、Agent、工具调用、Graph/Workflow 编排等。

如果你之前写过普通后端服务，可以把 Eino 理解为 AI 应用层的工程化框架。它关注的不只是“调用一次模型”，而是把模型、消息、工具、记忆、中间件、回调、Trace、Graph、Agent Runner 等能力组织成可维护的应用结构。

官方 Quickstart 推荐从示例仓库开始：

1 2	git clone https://github.com/cloudwego/eino-examples.git cd eino-examples/quickstart/chatwitheino

准备模型配置，以 OpenAI 为例：

1 2	export OPENAI_API_KEY="..." export OPENAI_MODEL="gpt-4.1-mini"

运行最小 Console 示例：

1	go run ./cmd/ch01 -- "用一句话解释 Eino 的 Component 设计解决了什么问题？"

运行 Web 形态：

go run .

如果你只是想学传统微服务，可以先跳过 Eino；如果你想把 Go 后端和 AI Agent 结合起来，Eino 值得单独拿一条学习线。

初学者学习路线

下面是一条比较稳的 7 天入门路线。

第 1 天：理解 CloudWeGo 生态

目标不是记住所有项目，而是搞清楚每个项目解决什么问题。

CloudWeGo 是中间件集合，不是单个框架。
Hertz 解决 HTTP 服务问题。
Kitex 解决 Go RPC 服务问题。
Volo 面向 Rust 服务开发。
Eino 面向 Go AI 应用开发。

第 2 天：跑通 Hertz

完成 /ping 示例，并尝试新增一个接口：

1
2
3

h.GET("/hello", func(ctx context.Context, c *app.RequestContext) {
	c.JSON(consts.StatusOK, utils.H{"message": "hello cloudwego"})
})

重点理解：

server.Default() 创建服务实例。
h.GET 注册路由。
RequestContext 负责请求与响应。
h.Spin() 启动服务。

第 3 天：跑通 Kitex

克隆并运行 kitex-examples/hello。重点理解：

什么是 IDL。
服务端代码和客户端代码分别在哪里。
handler 里写的是什么。
client 是如何发起 RPC 调用的。

第 4 天：自己改一次 IDL

在示例 IDL 中新增一个方法，然后重新生成代码，补全 handler，再从 client 调用新方法。

这一天最重要，因为你会真正理解“契约变更 -> 代码生成 -> 业务实现 -> 客户端调用”的完整链路。

第 5 天：把 Hertz 和 Kitex 串起来

写一个 Hertz 接口，在接口内部调用 Kitex Client。

这一步完成后，你就拥有了一个最小微服务架构：

外部用户访问 HTTP 接口。
HTTP 服务转成内部 RPC 请求。
RPC 服务处理业务并返回结果。

第 6 天：补服务治理基础

重点看这些能力：

超时控制：避免一个慢请求拖垮整条链路。
请求重试：处理临时失败，但要注意幂等性。
熔断与限流：保护服务。
服务注册与发现：让服务实例可以动态上下线。
日志、指标、链路追踪：让问题可定位。

第 7 天：按方向分叉

如果你做 Go 微服务：继续深入 Kitex 和 Hertz。

如果你做 Rust 服务：开始看 Volo。

如果你做 AI 应用：开始看 Eino 的 ChatModel、Tool、Agent、Graph、Workflow。

常见问题

1. CloudWeGo 和 Gin、gRPC 是什么关系？

Hertz 可以理解为 Go HTTP 框架，和 Gin、Echo 这类框架处在相近位置，但 Hertz 更强调高性能、可扩展和企业级治理生态。

Kitex 是 RPC 框架，可以支持 Thrift、Protobuf 等 IDL，也能与 gRPC 相关协议场景结合。和直接使用 gRPC 相比，Kitex 更强调 CloudWeGo 生态里的代码生成、服务治理、扩展点和性能优化。

2. 初学者应该先学 Hertz 还是 Kitex？

如果你没有 RPC 经验，建议先学 Hertz。HTTP 更直观，能很快看到请求和响应。

如果你已经写过 Go Web 服务，建议直接学 Kitex。RPC、IDL、代码生成和服务治理才是 CloudWeGo 微服务体系的重点。

3. 一定要用 IDL 吗？

如果只是写一个简单 HTTP Demo，不一定需要。
如果是团队协作或微服务项目，强烈建议用 IDL。IDL 能让接口变成稳定契约，减少口头约定和手写代码带来的混乱。

4. 什么时候需要服务注册发现？

单机 Demo 可以直连地址。只要服务开始多实例部署、动态扩缩容、容器化部署，就应该考虑服务注册发现。CloudWeGo 生态中有 Etcd、Consul、Nacos、Zookeeper、Polaris 等扩展可选。

5. 为什么代码生成后还有 TODO？

代码生成工具只负责生成框架骨架，不会替你写业务逻辑。handler 里的 TODO 就是你需要补充业务规则的地方。

入门建议

学习 CloudWeGo 时，最容易踩的坑是“一上来就看治理能力”。超时、重试、熔断、限流、服务发现都很重要，但它们应该建立在你已经理解 HTTP、RPC、IDL、Client、Server 的基础上。

比较推荐的顺序是：

用 Hertz 写出第一个 HTTP 接口。
用 Kitex 跑通第一个 RPC 调用。
修改 IDL 并重新生成代码。
把 Hertz 和 Kitex 串成一条链路。
再逐步补齐服务治理和可观测性。

如果这五步都跑通了，再看 CloudWeGo 的高级文档就不会觉得散了。你会发现它不是一堆孤立的框架，而是一套围绕企业级微服务落地构建的工具链。