Go-zero

最近更新：2026-10-24

本页是手写/批注类笔记，直接按原始笔记截图呈现（转成文字会乱序）；原始笔记文件见「Go语言相关笔记」页的原始链接。

附件文档全文（Go-zero RPC Proto ）#

Go-zero中RPC的Proto语法完整指南

go-zero中RPC的Proto语法完整指南

go-zero 的 gRPC 基于 Protobuf v3 (proto3) 语法定义，是微服务通信的核心契约。下面我会把标准 proto3 语法 + go-zero 专属用法 完整讲清楚，直接可用于项目开发。

一、基础文件结构（必写）

每个 .proto 文件必须以这三行开头，go-zero 生成代码依赖这些配置：

ProtoBuf
// 1. 指定proto版本，必须是proto3
syntax = "proto3";

// 2. 包名（防止命名冲突）
package user;

// 3. go-zero核心配置：生成go代码的包路径
option go_package = "./userpb";

二、核心语法详解

1. 数据类型（Message）

定义请求/响应结构体，字段编号必须从1开始，不能重复、不能为0。

ProtoBuf
// 用户信息结构体
message UserInfo {
int64 id = 1; // 数字类型：int32/int64/uint32等
string name = 2; // 字符串
bool gender = 3; // 布尔值
bytes avatar = 4; // 字节流（图片/文件）
repeated string tags = 5; // 数组（切片），关键字repeated
}

2. 枚举类型（Enum）

用于固定值场景（如状态、类型），第一个枚举值必须是0：

ProtoBuf
// 用户状态枚举
enum UserStatus {
STATUS_INVALID = 0; // 必须从0开始
STATUS_NORMAL = 1;
STATUS_FROZEN = 2;
}

// 在message中使用枚举
message User {
int64 id = 1;
UserStatus status = 2;
}

3. 服务定义（Service）

go-zero 生成 RPC 接口的核心，一个 service 包含多个 rpc 方法：

ProtoBuf
// 用户服务定义
service UserRpc {
// 1. 简单RPC：请求+响应（最常用）
rpc GetUser (GetUserReq) returns (GetUserResp);

// 2. 服务端流式RPC（服务端返回多条数据）
rpc ListUser (ListUserReq) returns (stream UserInfo);

// 3. 客户端流式RPC（客户端发送多条数据）
rpc BatchCreateUser (stream CreateUserReq) returns (BatchCreateUserResp);

// 4. 双向流式RPC
rpc Chat (stream ChatReq) returns (stream ChatResp);
}

4. 请求/响应结构体

每个 RPC 方法必须配套定义请求、响应消息：

ProtoBuf
// GetUser接口请求体
message GetUserReq {
int64 id = 1; // 用户ID
}

// GetUser接口响应体
message GetUserResp {
int64 id = 1;
string name = 2;
UserStatus status = 3;
}

三、go-zero 专属规范（重点）

1. 包路径规范

go_package 必须写相对路径，go-zero 会按这个路径生成代码：

ProtoBuf
option go_package = "./userpb"; // 推荐：当前目录下的userpb文件夹

2. 命名规范

文件命名：服务名.proto（如 user.proto、order.proto）
服务命名：XxxRpc（如 UserRpc、OrderRpc）
方法命名：驼峰法（GetUser、CreateOrder）
消息命名：XxxReq（请求）、XxxResp（响应）

3. 字段约束（go-zero最佳实践）

主键ID统一用 int64
分页参数固定写法：

ProtoBuf
message PageReq {
int32 page = 1; // 页码
int32 page_size = 2; // 每页条数
}

错误信息统一用 string msg 承载

四、完整可运行示例

ProtoBuf
syntax = "proto3";

package user;
option go_package = "./userpb";

// 枚举：用户状态
enum UserStatus {
STATUS_INVALID = 0;
STATUS_NORMAL = 1;
STATUS_FROZEN = 2;
}

// 用户基础信息
message UserInfo {
int64 id = 1;
string name = 2;
string phone = 3;
UserStatus status = 4;
repeated string roles = 5;
}

// 请求：获取用户
message GetUserReq {
int64 id = 1;
}

// 响应：获取用户
message GetUserResp {
UserInfo user = 1;
}

// 请求：创建用户
message CreateUserReq {
string name = 1;
string phone = 2;
}

// 响应：创建用户
message CreateUserResp {
int64 id = 1;
string msg = 2;
}

// go-zero RPC服务
service UserRpc {
rpc GetUser (GetUserReq) returns (GetUserResp);
rpc CreateUser (CreateUserReq) returns (CreateUserResp);
}

五、go-zero 生成命令

写好 .proto 后，用这个命令生成 go 代码（go-zero 专属）：

Bash
# 基础生成（推荐）
goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

# 带model生成（自动生成CRUD代码）
goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=. --model

六、常见错误避坑