tRPC-Go 系统讲解 ：从 0 系统理解 tRPC-Go — 小白友好版

🎯 本文目标：让你从 0 系统理解 tRPC-Go——不是堆术语，而是把"它是什么"“为什么这么设计”“怎么工作”"怎么用"讲透。
📚 阅读门槛：会写最基础的 Go 代码即可（func、struct、import 看得懂）。
⏱️ 预计阅读时间：30 分钟系统读 + 1 小时动手实操。

📖 阅读路线图

第 1 章 · tRPC-Go 是什么？

1.1 一句话定义

tRPC-Go 是腾讯开源的 Go 语言微服务开发框架，让你用最少的代码写出高性能、可治理、跨协议的后端服务。

1.2 “tRPC” 这个词同时指三样东西（最容易混淆！）

💡 本文的"tRPC-Go"特指框架本身（第 2 项）。

1.3 类比：和你熟悉的东西对比一下

第 2 章 · 为什么需要 tRPC-Go？

2.1 没有框架，写一个微服务有多累？

假设你要写一个返回 “Hello, World” 的服务，完全不用框架：

结论：业务代码 5 行，框架代码 4000 行。这 4000 行就是 tRPC-Go 替你写好的。

2.2 tRPC-Go 帮你解决的 6 大问题

2.3 设计哲学：契约先行（Contract First）

一份 .proto，全栈通用。 前后端各自看契约写代码，不需要互相看代码。

第 3 章 · 核心概念六件套

理解 tRPC-Go，最重要的是这 6 个概念：

3.1 Service（服务）

// helloworld.proto 里的定义
service HelloWorldService {
  rpc Hello(HelloReq) returns (HelloRsp);
}

一个进程可以注册多个 Service，但生产实践建议一个进程只跑一个 Service。

3.2 RPC Method（远程方法）

.proto 里 rpc Hello(HelloReq) returns (HelloRsp); 这一行就是个方法。

4 种调用模式（tRPC-Go 都支持）：

💡 你 helloworld 里的 Hello 就是 Unary 模式。

3.3 Codec（编解码器）

做什么的？ 把 Go 的 struct ↔ 网络字节流互转。

性能对比：Protobuf 比 JSON 小 3-5 倍、快 5-10 倍。

3.4 Transport（网络传输）

做什么的？ 把字节流真正发出去。

💡 trpc_go.yaml 里 transport: tnet 这一行就是它。

3.5 Filter（过滤器）⭐⭐⭐

这是 tRPC 的灵魂概念——所有"非业务但通用"的逻辑都写在 Filter 里。

类比：Spring 的 Interceptor / Web 的 Middleware / 洋葱模型。

配置在 trpc_go.yaml 的 filter: 字段下：

server:
  filter:
    - simpledebuglog
    - recovery
    - trpc-robust

3.6 Plugin（插件）

做什么的？ 给框架"插上"额外能力，按需启用。

用法：在代码里匿名 import触发注册，在 yaml 里配置参数。

import (
    _ "git.code.oa.com/trpc-go/trpc-naming-polaris"   // 引入即生效
    _ "git.code.oa.com/trpc-go/trpc-metrics-runtime"
)

plugins:
  selector:
    polaris:
      # 北极星配置

第 4 章 · 一个请求的完整一生

理解了概念，我们追踪一次 RPC 调用从客户端到服务端再回来的完整旅程：

关键观察

对你（业务开发）而言：你只在 业务 Handler 里写代码，其他所有环节框架已经帮你做好了。

第 5 章 · 项目结构深度剖析

以你本地的 helloworld 项目为例：

helloworld/
├── 📝 helloworld.proto            ← 契约（你手写）
├── 📦 stub/                       ← 自动生成的桩代码
│   └── git.code.oa.com/examples/helloworld/
│       ├── helloworld.pb.go       ← 数据结构（自动生成）
│       ├── helloworld.trpc.go     ← RPC 桩（自动生成）
│       └── go.mod                 ← 桩独立成模块
├── 🚀 main.go                     ← 服务入口
├── 💼 hello_world_service.go      ← 业务实现 ⭐ 你改这里
├── 🧪 hello_world_service_test.go ← 测试
├── 📞 cmd/client/main.go          ← 客户端示例
├── ⚙️ trpc_go.yaml                ← 运行配置
├── 📋 go.mod / go.sum             ← Go 依赖
└── 📂 polaris/log/                ← 北极星运行时日志

5.1 三层架构心智模型

5.2 main.go 是黏合剂

func main() {
    // 1️⃣ 创建服务器（自动加载配置 + 初始化插件）
    s := trpc.NewServer()

    // 2️⃣ 实例化业务实现
    impl := &helloWorldServiceImpl{}

    // 3️⃣ 把业务实现注册到框架
    pb.RegisterHelloWorldServiceService(s, impl)

    // 4️⃣ 启动监听（阻塞）
    if err := s.Serve(); err != nil {
        log.Fatal(err)
    }
}

✨ main.go 不写业务，只做"黏合"。业务全在 hello_world_service.go。

5.3 trpc_go.yaml 配置全景

global:    # 🌍 环境/命名空间
  namespace: Development

server:    # 🖥️ 服务端配置
  app: yourAppName
  server: HelloWorldService
  filter: [recovery, simpledebuglog]   # 过滤器链
  service:                             # 提供哪些服务
    - name: helloworld.HelloWorldService
      ip: 127.0.0.1
      port: 8000
      protocol: trpc                   # 协议
      transport: tnet                  # 传输层
      timeout: 1000                    # 超时

client:    # 📞 客户端配置（调下游服务）
  service:
    - name: xxx.YyyService
      target: ip://127.0.0.1:9000

plugins:   # 🔌 插件配置
  log: ...
  selector: { polaris: ... }
  overload_control: ...

记住一个原则：代码定义"做什么"，yaml 决定"怎么做"。

第 6 章 · 插件与过滤器（深入篇）

6.1 为什么 tRPC-Go 用"匿名 import"加载插件？

import (
    _ "git.code.oa.com/trpc-go/trpc-naming-polaris"
)

_ 的含义：只触发包的 init() 函数，不调用包里的任何函数。

插件包内部：

// trpc-naming-polaris 包的源码（伪代码）
package polaris

func init() {
    plugin.Register("polaris", &polarisPlugin{})  // 自动注册
}

机制：

好处：零侵入扩展——添加新能力不用改框架代码，只需 import _ 一行。

6.2 自定义 Filter（实战代码）

写一个记录请求耗时的 Filter：

package mylogger

import (
    "context"
    "time"

    "git.code.oa.com/trpc-go/trpc-go/filter"
    "git.code.oa.com/trpc-go/trpc-go/log"
)

func init() {
    filter.Register("timing", ServerFilter(), nil)
}

func ServerFilter() filter.ServerFilter {
    return func(ctx context.Context, req interface{},
        next filter.ServerHandleFunc) (interface{}, error) {
        start := time.Now()

        // 调用业务逻辑
        rsp, err := next(ctx, req)

        // 后置处理
        log.Infof("耗时 %v ms", time.Since(start).Milliseconds())
        return rsp, err
    }
}

激活：在 trpc_go.yaml 加一行：

server:
  filter:
    - timing   # 👈 启用

6.3 框架内置插件清单（按需启用）

💎 核心： 想要什么能力 → 找对应插件 → import _ + yaml 配置。

第 7 章 · 服务治理三剑客

线上服务不是"能跑就行"，必须解决三大难题：

7.1 ⚔️ 第一剑：服务发现（Polaris 北极星）

没有服务发现的世界

问题：服务挂了/扩容/换 IP 了，客户端全部要改代码！

有了北极星

配置启用：

server:
  service:
    - name: yourapp.helloworld.HelloWorldService
      registry: polaris      # 👈 启动时自动注册

client:
  service:
    - name: xxx.YyyService
      target: polaris://xxx.YyyService   # 👈 通过北极星寻址

7.2 ⚔️ 第二剑：过载保护（trpc-robust）

传统限流 vs 自适应过载

核心算法（极简版）：

监测 goroutine 排队耗时
    ├─ 耗时 < 阈值 → 都放行
    └─ 耗时 > 阈值 → 拒绝低优先级请求

已经在你的 helloworld 配置里了！看 trpc_go.yaml 中的 overload_control.trpc-robust 那块。

7.3 ⚔️ 第三剑：可观测性

三大支柱

tRPC-Go 怎么用

一行 import 就接入：

import _ "git.code.oa.com/trpc-go/trpc-opentelemetry/oteltrpc"

第 8 章 · 开发实战清单

8.1 接口开发完整流程（5 步法）

Step 1：写 .proto

syntax = "proto3";
package trpc.test.helloworld;
option go_package = "git.woa.com/trpcprotocol/test/helloworld";

service Greeter {
  rpc SayHello(HelloRequest) returns (HelloReply);
}

message HelloRequest { string msg = 1; }
message HelloReply   { string msg = 1; }

Step 2：生成代码

trpc create -p helloworld.proto -o helloworld

Step 3：实现业务（你只需要改这一处）

func (s *greeterImpl) SayHello(
    ctx context.Context,
    req *pb.HelloRequest,
) (*pb.HelloReply, error) {
    // 👇 你的业务逻辑
    return &pb.HelloReply{
        Msg: "Hello, " + req.Msg,
    }, nil
}

Step 4：调整配置

server:
  app: test
  server: helloworld
  service:
    - name: trpc.test.helloworld.Greeter
      port: 8000

Step 5：编译运行

go build && ./helloworld

8.2 写客户端调用（3 行核心代码）

proxy := pb.NewGreeterClientProxy()
req := &pb.HelloRequest{Msg: "World"}
rsp, err := proxy.SayHello(ctx, req,
    client.WithTarget("ip://127.0.0.1:8000"))
// rsp.Msg == "Hello, World"

8.3 单元测试模板

func TestSayHello(t *testing.T) {
    s := &greeterImpl{}
    rsp, err := s.SayHello(
        context.Background(),
        &pb.HelloRequest{Msg: "test"},
    )
    assert.NoError(t, err)
    assert.Equal(t, "Hello, test", rsp.Msg)
}

8.4 常见业务场景速查

第 9 章 · 性能与生态

9.1 性能数据（参考值）

测试条件：Echo 服务、单实例、4 核 8G、本地网络。仅供方向性参考。

为什么快？

• ✅ tnet 高性能网络库（替代 Go net）
• ✅ Protobuf 二进制序列化
• ✅ 协程池复用
• ✅ 零拷贝优化

9.2 tRPC-Go 生态地图

第 10 章 · 小白常见误区

⚠️ 误区 1：把 tRPC 当成纯协议

❌ “tRPC 就是个协议，跟 Spring Boot 不是一个东西”
✅ tRPC = 协议 + 框架 + 工具，框架部分确实就是 Spring Boot 的对应物。

⚠️ 误区 2：到处改 stub 代码

❌ 觉得 stub 代码不够好，直接修改 helloworld.pb.go
✅ stub 代码自动生成，绝不手改——下次 trpc create -f 会被覆盖。

⚠️ 误区 3：业务逻辑写在 Filter 里

❌ 把数据库查询、业务计算放进 Filter
✅ Filter 只放通用横切逻辑（日志/鉴权/监控），业务一律放 service.go。

⚠️ 误区 4：硬编码 IP 部署

❌ 线上 yaml 写 ip: 127.0.0.1 或 ip: 10.1.2.3
✅ 容器环境用 nic: eth1 或 ${ip} 占位符 + registry: polaris 注册。

⚠️ 误区 5：以为 main.go 不能改

❌ “main.go 是生成的，我不能动”
✅ 可以改。需要全局初始化（如读 DB 连接）就在 trpc.NewServer() 之后写。

⚠️ 误区 6：配置完全靠 yaml

❌ 觉得只能配 yaml
✅ tRPC-Go 支持 代码 Option 覆盖 yaml，比如 client.WithTimeout(2 * time.Second)。

⚠️ 误区 7：分不清 client 和 server filter

server:
  filter: [...]   # 服务端过滤器：拦截"我收到的请求"
client:
  filter: [...]   # 客户端过滤器：拦截"我发出的请求"

两者是两个独立的过滤链。

⚠️ 误区 8：忽视 namespace

❌ 测试和生产共用 Development，导致测试请求打到生产
✅ 严格区分：Production（生产）/ Development（开发）。

⚠️ 误区 9：以为 tnet 万能

❌ 所有 service 都加 transport: tnet
✅ tnet 目前不支持 HTTP，HTTP 协议要去掉这一行。

⚠️ 误区 10：用 go install 装 trpc 工具

❌ go install trpc.tech/trpc-go/trpc-go-cmdline/v2/trpc@latest
✅ 实测各种问题（fbs 仓库 404、依赖错乱），直接下载二进制最稳：

wget https://mirrors.tencent.com/repository/generic/trpc-go-cmdline/...

🎯 总结：理解 tRPC-Go 的"一句话精髓"

一句话精髓：
tRPC-Go 让你只关心业务逻辑，把"网络/序列化/治理/可观测性"这些通用难题都通过配置 + 插件搞定。

📚 推荐学习路径

你已经完成的

• ✅ 环境搭建（环境搭建笔记）
• ✅ 第一个项目跑通（快速上手）
• ✅ 代码上传工蜂（工蜂笔记）

接下来建议

🛠️ 速查附录

A. 必背命令

trpc create -p xxx.proto              # 生成完整项目
trpc create -p xxx.proto --rpconly    # 只更新桩代码
trpc create -p xxx.proto -f           # 强制覆盖
go build && ./xxx                     # 编译运行
go run cmd/client/main.go             # 跑客户端
trpc-cli -func /xx.Service/Method \   # 命令行测接口
  -target ip://127.0.0.1:8000 \
  -body '{"msg":"hi"}'

B. 必背文件

C. 必背概念

📌 完结祝福

看到这里，你已经具备了理解和上手 tRPC-Go 的完整知识地图。

框架是工具，实战才能内化——现在就去给 hello_world_service.go 的 Hello 方法加点真业务，跑一下你的 cmd/client/main.go，亲手感受 RPC 的魔法 ✨

Happy coding! 🚀