
# 从零写一个真正的 tRPC-Go 项目：图书管理系统全流程实战

> 本文面向 **刚接触 tRPC-Go 的同学**：proto 不是写给文档看的，它是真正的"代码生成器入口"。
> 我们会用 `trpc create` 把一份 `library.proto` 变成一个能跑、能测、能压、能上线的微服务。
> 全文用到的代码都已经在本地跑通，关键文件结构、命令、输出都按真实结果给出。

---
![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-10730009/574b797d2ee323fea02602987bfd68e7.png)

## 一、为什么很多人写出来的"tRPC 项目"其实不是 tRPC 项目？

我第一次写图书管理系统时，掉进了一个非常典型的坑：

- 项目目录看起来很像 tRPC：有 `proto/`、有 `service/`、有 `handler/`；
- 然而启动入口是 `http.ListenAndServe(":8080", router)`；
- proto 文件只是被当成"接口文档"摆着，**没有人去 `trpc create`**；
- 客户端调用是 `curl -XPOST http://localhost:8080/...`。

这种项目本质上是一个 **手写的 HTTP 服务**，没有用到 tRPC-Go 的任何能力：
没有 stub、没有 filter 链、没有 yaml 驱动、没有名字服务、没有协议头里的错误码。

真正的 tRPC-Go 项目长什么样？一句话：

> **proto 文件是契约，`trpc create` 是发动机，业务代码只负责"填空"。**

下文的实战项目正是按这条主线来的。

---

## 二、项目最终结构一览

```text
trpc/library/
├── library.proto                  ← 服务契约（手写）
├── trpc_go.yaml                   ← 框架配置（端口/插件/日志/过载保护）
├── go.mod                         ← module = github.com/zhubo/library
│
├── main.go                        ← trpc.NewServer() 启动入口
├── library_service.go             ← 业务实现（借/还/CRUD/校验）
├── library_service_test.go        ← 单元测试
│
├── internal/
│   └── repository/
│       └── book_repo.go           ← 内存仓储 + ISBN 唯一性
│
├── cmd/client/
│   └── main.go                    ← 端到端演示客户端
│
└── stub/                          ← ★ trpc create 自动生成，禁止手改
    └── git.code.oa.com/examples/library/
        ├── library.pb.go          ← message 序列化代码
        ├── library.trpc.go        ← service stub（Server/Client 双端代理）
        └── library_mock.go        ← gomock 自动生成的 mock
```

只有 4 个文件需要你亲手写：`library.proto`、`main.go`、`library_service.go`、`book_repo.go`。
其他全是 **生成 + 配置**。

---

## 三、第 0 步：环境准备

```bash
# Go 版本 >= 1.20
go version

# 安装 trpc 命令行（一次性）
go install trpc.group/trpc-go/trpc-cmdline/trpc@latest

trpc version
```

`trpc create` 命令在后续生成 stub 时会被反复使用，确保它已经在 `$PATH` 里。

---

## 四、第 1 步：写契约 —— `library.proto`

tRPC-Go 是 **契约先行** 的框架。先定义"图书管理系统对外暴露什么 RPC"，再去实现它。

```proto
syntax = "proto3";

package library;

option go_package = "git.code.oa.com/examples/library";

// LibraryService 管理一家小型图书馆的目录
service LibraryService {
  rpc ListBooks   (ListBooksReq)   returns (ListBooksRsp);
  rpc GetBook     (GetBookReq)     returns (Book);
  rpc CreateBook  (CreateBookReq)  returns (Book);
  rpc UpdateBook  (UpdateBookReq)  returns (Book);
  rpc DeleteBook  (DeleteBookReq)  returns (DeleteBookRsp);
  rpc BorrowBook  (BorrowBookReq)  returns (Book);
  rpc ReturnBook  (ReturnBookReq)  returns (Book);
}

message Book {
  int64  id         = 1;
  string title      = 2;
  string author     = 3;
  string isbn       = 4;
  int32  stock      = 5;  // 在馆数量
  int32  borrowed   = 6;  // 已借数量
  int64  created_at = 7;
  int64  updated_at = 8;
}

message ListBooksReq {}
message ListBooksRsp { repeated Book books = 1; }

message GetBookReq    { int64 id = 1; }
message CreateBookReq { string title = 1; string author = 2; string isbn = 3; int32 stock = 4; }
message UpdateBookReq { int64 id = 1; string title = 2; string author = 3; string isbn = 4; int32 stock = 5; }
message DeleteBookReq { int64 id = 1; }
message DeleteBookRsp { bool  ok = 1; }
message BorrowBookReq { int64 id = 1; }
message ReturnBookReq { int64 id = 1; }
```

两点经验：

1. **`option go_package` 一定要写**，它决定生成代码的 import 路径。
2. **请求和响应一律用 `message`**，不要用 `repeated string` 之类的标量返回值，后续要扩字段才不会破坏兼容性。

---

## 五、第 2 步：用 `trpc create` 生成项目骨架

在 proto 所在目录执行：

```bash
trpc create \
  -p library.proto \
  -o library \
  --mod github.com/zhubo/library
```

执行完成后你会得到：

- `main.go`：tRPC 服务启动入口；
- `library_service.go`：每个 RPC 方法的空实现；
- `trpc_go.yaml`：框架配置文件；
- `stub/git.code.oa.com/examples/library/`：序列化代码 + Server/Client 代理（**禁止手改**）。

> 这一刻你已经拥有一个可启动的 tRPC-Go 服务，所有 RPC 都返回 `UNIMPLEMENTED`，
> 接下来要做的事，就是把这些方法填上业务逻辑。

---

## 六、第 3 步：搭好"分层依赖" —— 仓储层先行

按 DDD 的分层思路，业务代码 **不应该直接持有 `map`**。
我们先写一个仓储接口，业务代码只面向接口编程，未来切换到 MySQL 也无需动业务。

`internal/repository/book_repo.go` 关键节选：

```go
// Sentinel errors，调用方用 errors.Is 判断
var (
    ErrNotFound      = errors.New("book not found")
    ErrISBNDuplicate = errors.New("isbn already exists")
)

// 仓储接口：业务层只依赖它
type BookRepository interface {
    List() ([]*pb.Book, error)
    Get(id int64) (*pb.Book, error)
    Create(b *pb.Book) (*pb.Book, error)
    Update(b *pb.Book) (*pb.Book, error)
    Delete(id int64) error
}
```

内存实现做了三件正经事：

- `sync.RWMutex` 保证并发读写安全；
- `Create / Update` 都做 **ISBN 唯一性校验**；
- `List / Get` 返回的是 **副本**，避免外部 mutate 污染存储。

```go
func (r *memoryBookRepo) Create(b *pb.Book) (*pb.Book, error) {
    r.mu.Lock()
    defer r.mu.Unlock()
    if b.Isbn != "" {
        for _, existing := range r.books {
            if existing.Isbn == b.Isbn {
                return nil, ErrISBNDuplicate
            }
        }
    }
    r.nextID++
    b.Id = r.nextID
    if b.CreatedAt == 0 {
        b.CreatedAt = time.Now().Unix()
    }
    b.UpdatedAt = b.CreatedAt
    stored := *b
    r.books[b.Id] = &stored
    return b, nil
}
```

> 这种"接口在 internal、实现可替换"的写法，本质和 tRPC 的 **数据库插件机制** 是同构思想：
> 框架代码不变，把"驱动"交给配置或依赖注入决定。

---

## 七、第 4 步：业务实现 —— `library_service.go`

`trpc create` 给的是空方法，我们要把每个方法补上"参数校验 → 调仓储 → 错误映射"三步。

### 7.1 自定义业务错误码

```go
const (
    codeInvalidArgument = 10001
    codeNotFound        = 10002
    codeConflict        = 10003
)
```

> tRPC-Go 框架保留了 0~10000 的错误码（连接、超时、序列化等），
> 业务码用 10000 以上，避免冲突。返回时统一通过 `errs.New(code, msg)`，
> 它会被框架塞进协议头，客户端收到的是带 code 的结构化错误，**比 HTTP 状态码细粒度得多**。

### 7.2 业务结构体

```go
type libraryServiceImpl struct {
    pb.UnimplementedLibraryService          // 嵌入官方默认实现，兼容性兜底
    repo repository.BookRepository           // 依赖倒置
}

func newLibraryServiceImpl(repo repository.BookRepository) *libraryServiceImpl {
    return &libraryServiceImpl{repo: repo}
}
```

### 7.3 借阅逻辑：库存计数的事务边界

借/还是这个项目最核心的两条规则：

```go
func (s *libraryServiceImpl) BorrowBook(
    ctx context.Context, req *pb.BorrowBookReq,
) (*pb.Book, error) {
    if req.Id <= 0 {
        return nil, errs.New(codeInvalidArgument, "id must be positive")
    }
    current, err := s.repo.Get(req.Id)
    if err != nil {
        return nil, mapRepoError(ctx, err)
    }
    if current.Stock <= 0 {
        return nil, errs.New(codeConflict, "book is out of stock")
    }
    current.Stock--
    current.Borrowed++
    return s.repo.Update(current)
}
```

要点：

- **永远不允许借空**：`Stock <= 0` 直接 `codeConflict`；
- **`Update` 才是唯一持久化点**：避免局部更新导致计数器漂移；
- **`UpdateBook` 不允许动 `Borrowed`**：借/还才能改它，普通 update 只能改 title/stock 等元信息。

### 7.4 删除保护

```go
if current.Borrowed > 0 {
    return nil, errs.New(codeConflict, "cannot delete: copies are still borrowed")
}
```

> 真实业务里删除一本仍有外借记录的书，会让借阅记录变成"孤儿数据"。
> 这条规则在领域里叫 **聚合不变性**（aggregate invariant），
> 哪怕只有 3 行代码，也必须放在服务层而不是仓储层。

### 7.5 错误映射集中收口

```go
func mapRepoError(ctx context.Context, err error) error {
    switch {
    case errors.Is(err, repository.ErrNotFound):
        return errs.New(codeNotFound, "book not found")
    case errors.Is(err, repository.ErrISBNDuplicate):
        return errs.New(codeConflict, "isbn already exists")
    default:
        log.ErrorContextf(ctx, "repository error: %v", err)
        return errs.New(errs.RetServerSystemErr, err.Error())
    }
}
```

> 所有 RPC 都走这一个函数，保证 **同样的底层错误返回同样的业务码**。
> 这是接口可观测性的基础，远比 `if err != nil { return err }` 满天飞强。

---

## 八、第 5 步：把业务装进 tRPC-Go 服务器

`main.go` 才 30 行，但每行都是关键：

```go
func main() {
    s := trpc.NewServer()                       // ① 读取 trpc_go.yaml，初始化 filter 链

    repo := repository.NewMemoryBookRepo()      // ② 构造仓储（未来可换 MySQL）
    impl := newLibraryServiceImpl(repo)         // ③ 注入业务

    pb.RegisterLibraryServiceService(s, impl)   // ④ 把实现挂到 stub 上
    if err := s.Serve(); err != nil {           // ⑤ 阻塞监听
        log.Fatal(err)
    }
}
```

注意 `pb.RegisterLibraryServiceService` 这个函数不是我们写的，而是 `trpc create` 从 proto 里"反射"出来的。
**这就是 stub 的价值**：你写 `service` 块、它替你生成注册函数和客户端代理，从此再也不用手撸 router。

---

## 九、第 6 步：调试客户端 —— 端到端演示脚本

`cmd/client/main.go` 用 stub 自带的 `ClientProxy` 把整个生命周期跑了一遍：

```go
proxy := pb.NewLibraryServiceClientProxy(
    client.WithTarget("ip://127.0.0.1:8000"),
    client.WithProtocol("trpc"),
)
ctx := trpc.BackgroundContext()

created, _ := proxy.CreateBook(ctx, &pb.CreateBookReq{
    Title: "Domain-Driven Design", Author: "Eric Evans",
    Isbn: "978-0321125217", Stock: 2,
})
borrowed, _ := proxy.BorrowBook(ctx, &pb.BorrowBookReq{Id: created.Id})
returned, _ := proxy.ReturnBook(ctx, &pb.ReturnBookReq{Id: created.Id})
_ , _ = proxy.DeleteBook(ctx, &pb.DeleteBookReq{Id: created.Id})
```

`pb.NewLibraryServiceClientProxy` 也是 stub 生成的，它把：

- 序列化 / 反序列化
- 名字服务（`ip://`、`polaris://`、`dns://` 等）
- 重试 / 熔断 / 超时
- 日志 / 监控 filter 链

全部封装在内部。**业务代码只看到一个 Go interface**，这就是 tRPC-Go 客户端最舒服的地方。

---

## 十、第 7 步：单元测试 —— 业务规则才是真正的资产

`library_service_test.go` 里五个测试场景全部针对**业务规则**而不是序列化：

| 测试函数 | 验证的规则 |
|---|---|
| `TestCreateBook_Validation` | 标题/作者非空、负库存被拒绝、字符串自动 trim |
| `TestBorrowAndReturn` | 借/还后计数器对账、无库存借书拒绝、重复归还拒绝 |
| `TestDeleteWhileBorrowed` | 有未归还副本时禁止删除 |
| `TestGetBook_NotFound` | 不存在的 id 返回 `codeNotFound` |
| `TestCreateBook_DuplicateISBN` | 重复 ISBN 返回 `codeConflict` |

代码片段：

```go
borrowed, _ := svc.BorrowBook(ctx, &pb.BorrowBookReq{Id: created.Id})
if borrowed.Stock != 0 || borrowed.Borrowed != 1 {
    t.Fatalf("counters wrong after borrow: stock=%d borrowed=%d",
        borrowed.Stock, borrowed.Borrowed)
}

if _, err := svc.BorrowBook(ctx, &pb.BorrowBookReq{Id: created.Id}); errs.Code(err) != codeConflict {
    t.Fatalf("expected codeConflict on out-of-stock borrow, got %v", err)
}
```

> 用 **真实的内存仓储** 而不是 mock：仓储本身没有外部依赖，速度快、保真度高，
> 这是 Go 单元测试里被严重低估的一种写法。

---

## 十一、第 8 步：tRPC 配置文件 —— 一切运行时都靠它

`trpc_go.yaml` 里关键的几块：

```yaml
server:
  app: library
  server: LibraryService
  service:
    - name: trpc.library.LibraryService
      ip: 127.0.0.1
      port: 8000
      protocol: trpc
      timeout: 1000          # 单请求超时
      filter:
        - simpledebuglog     # 打印请求日志
        - recovery           # panic 自动恢复
        - trpc-robust        # 过载保护

plugins:
  log:
    default:
      - writer: console
        level: debug
```

切换协议、加监控、换名字服务，全部改 yaml 就够了，业务代码一行不动。
**这就是 tRPC-Go 强调的"配置驱动"**。

---

## 十二、跑起来！

```bash
cd trpc/library

go mod tidy
go test ./...                # 单测
go run .                     # 启动服务

# 另开一个终端
go run cmd/client/main.go    # 端到端演示
```

客户端会顺序输出：

```text
[ListBooks] 3 book(s) in catalog
  - id=1 title="The Go Programming Language" stock=3 borrowed=0
  - id=2 title="Clean Code" stock=5 borrowed=0
  - id=3 title="Designing Data-Intensive Applications" stock=2 borrowed=0
[CreateBook] id=4 title="Domain-Driven Design" stock=2
[GetBook]    id=4 author="Eric Evans"
[BorrowBook] stock=1 borrowed=1
[ReturnBook] stock=2 borrowed=0
[UpdateBook] title="Domain-Driven Design (Reference)" stock=3
[DeleteBook] ok=true
[ListBooks] catalog now has 3 book(s)
```

至此，一个 **真正基于 tRPC-Go** 的图书管理系统跑通了。

---

## 十三、整体调用链路图

```mermaid
flowchart LR
    A[client/main.go] -- ClientProxy --> B[stub library.trpc.go]
    B -- trpc 协议 --> C[server filter 链]
    C --> D[libraryServiceImpl]
    D --> E[BookRepository]
    E --> F[(in-memory map)]
```

四件事同时发生：

1. 客户端用 stub 代理把请求 marshal 成 trpc 协议帧；
2. 服务端 filter 链按顺序执行：log → recovery → robust；
3. 业务实现做参数校验、聚合不变性、业务码映射；
4. 仓储完成持久化，错误以 sentinel 形式回到业务层。

---

## 十四、踩过的坑 & 经验

1. **不要手改 `stub/`**。任何改动一次 `trpc create` 就会丢，必要的扩展请改 proto。
2. **业务码不要从 0 开始**。0~10000 是框架保留区。
3. **`UpdateBook` 不允许改 `Borrowed`**。否则借/还的不变性会被绕过。
4. **`internal/repository` 用接口隔离**。这是把 demo 演进成生产级的关键拐点。
5. **服务端单测优先用真实仓储**。除非真的有外部依赖，否则没必要 mock。
6. **`trpc_go.yaml` 的 `server.app/server.server`**，决定上报名和 polaris 注册名，不要乱填。
7. **客户端连测试**：哪怕没有压测平台，写一个像 `cmd/client/main.go` 这样的端到端脚本，
   每次提 PR 之前跑一遍，比单测更能暴露 RPC 层面的问题。

---

## 十五、可演进方向

- 把 `memoryBookRepo` 换成 MySQL/PostgreSQL，业务代码 0 改动；
- 增加 `gRPC-Gateway` 反向代理，让前端可以用 HTTP/JSON 调；
- 给借阅领域加 `Reservation`（预约）聚合，引入消息队列做异步通知；
- 接入 polaris 名字服务、自定义 filter 做鉴权；
- 用 `pb.NewLibraryServiceClientProxy` 写一个压测脚本，看 trpc 协议下的 QPS 上限。

---

## 十六、写在最后

一句话总结这次实战：

> **tRPC-Go 的本质，是把"网络协议、寻址、可观测性"做成基础设施，**
> **让你只需要写好"契约 + 业务规则"两件事。**

如果你之前写的是"伪 tRPC 项目"，建议照着这篇文章走一遍；
等你能熟练地在 `library.proto` 上加一个新方法、跑一次 `trpc create`、然后只在 `library_service.go` 里改十几行代码就上线一个新接口时，
你就真正进入 tRPC-Go 的工作模式了。




本文面向 刚接触 tRPC-Go 的同学：proto 不是写给文档看的，它是真正的"代码生成器入口"。 我们会用 trpc create 把一份 library.proto 变成一个能跑、能测、能压、能上线的微服务。 全文用到的代码都已经在本地跑通，关键文件结构、命令、输出都按真实结果给出。

从零写一个真正的 tRPC-Go 项目：图书管理系统全流程实战[tRPC-Go, gRPC, Go, 微服务, Protobuf]

服务端开发

后端

开发工具

本文详细讲解了如何使用tRPC-Go框架从零构建图书管理系统，明确区分伪tRPC项目与真正契约驱动开发的差异。通过实操步骤，从proto定义、trpccreate生成代码到业务层实现、仓储设计及单元测试，完整演示tRPC服务的开发流程。重点包括错误码映射、借还书业务规则、分层架构及配置驱动，帮助开发者掌握tRPC-Go的核心能力，快速上手生产级微服务开发。

消息队列

单元测试

PostgreSQL

数据库

服务器

MySQL

JSON

Unix

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文详细讲解了如何使用tRPC-Go框架从零构建图书管理系统，明确区分伪tRPC项目与真正契约驱动开发的差异。通过实操步骤，从proto定义、trpccreate生成代码到业务层实现、仓储设计及单元测试，完整演示tRPC服务的开发流程。重点包括错误码映射、借还书业务规则、分层架构及配置驱动，帮助开发者掌握tRPC-Go...

从零写一个真正的 tRPC-Go 项目：图书管理系统全流程实战[tRPC-Go, gRPC, Go, 微服务, Protobuf]-腾讯云开发者社区-腾讯云

从零写一个真正的 tRPC-Go 项目：图书管理系统全流程实战[tRPC-Go, gRPC, Go, 微服务, Protobuf]

从零写一个真正的 tRPC-Go 项目：图书管理系统全流程实战[tRPC-Go, gRPC, Go, 微服务, Protobuf]

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐