跳到主要内容

安装配置

本章介绍如何在不同操作系统上安装 gRPC 开发环境，包括 Protocol Buffers 编译器和各语言的 gRPC 库。

安装 Protocol Buffers​

Protocol Buffers（简称 protobuf）是 gRPC 的基础，需要先安装 protobuf 编译器 protoc。

Windows 安装​

# 使用 Chocolatey 安装
choco install protoc

# 或使用 Scoop 安装
scoop install protobuf

# 或手动安装
# 1. 从 GitHub 下载 zip 文件
# https://github.com/protocolbuffers/protobuf/releases
# 2. 解压后将 bin 目录添加到 PATH 环境变量

验证安装：

protoc --version
# 输出: libprotoc 25.x 或更高版本

macOS 安装​

# 使用 Homebrew 安装
brew install protobuf

# 验证安装
protoc --version

Linux 安装​

# Ubuntu/Debian
sudo apt update
sudo apt install -y protobuf-compiler

# CentOS/RHEL
sudo yum install -y protobuf-compiler

# 或从源码安装
# 下载源码：https://github.com/protocolbuffers/protobuf/releases
# 解压后执行：
./configure
make
make check
sudo make install

# 更新动态链接库
sudo ldconfig

# 验证安装
protoc --version

安装 gRPC​

Go 语言​

# 安装 Go gRPC 库
go get google.golang.org/grpc

# 安装 protoc Go 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# 确保 $GOPATH/bin 在 PATH 中
export PATH="$PATH:$(go env GOPATH)/bin"

Python​

# 安装 gRPC 和 protobuf
pip install grpcio grpcio-tools

# 验证安装
python -c "import grpc; print(grpc.__version__)"

Node.js​

# 使用 npm 安装
npm install @grpc/grpc-js @grpc/proto-loader

# 或使用 yarn
yarn add @grpc/grpc-js @grpc/proto-loader

# 验证安装
node -e "console.log(require('@grpc/grpc-js').Server)"

Java​

Maven 项目添加依赖：

<dependencies>
    <!-- gRPC 核心库 -->
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>1.59.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
        <version>1.59.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
        <version>1.59.0</version>
    </dependency>
    
    <!--javax.annotation 依赖 -->
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

Gradle 项目添加依赖：

dependencies {
    implementation 'io.grpc:grpc-netty-shaded:1.59.0'
    implementation 'io.grpc:grpc-protobuf:1.59.0'
    implementation 'io.grpc:grpc-stub:1.59.0'
    implementation 'javax.annotation:javax.annotation-api:1.3.2'
}

C++​

# Ubuntu/Debian
sudo apt install -y libgrpc++-dev protobuf-compiler-grpc

# macOS
brew install grpc

# 或从源码编译
git clone --recurse-submodules -b v1.59.0 --depth 1 --shallow-submodules https://github.com/grpc/grpc
cd grpc
mkdir -p cmake/build
cd cmake/build
cmake ../..
make -j$(nproc)
sudo make install

项目结构​

一个典型的 gRPC 项目结构如下：

my-grpc-project/
├── proto/                    # Protocol Buffers 定义文件
│   └── hello.proto
├── server/                   # 服务端代码
│   └── main.go
├── client/                   # 客户端代码
│   └── main.go
└── generated/                # 生成的代码
    ├── hello.pb.go
    └── hello_grpc.pb.go

代码生成​

安装完成后，可以使用 protoc 生成代码：

Go 语言​

# 生成 Go 代码
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       proto/hello.proto

Python​

# 生成 Python 代码
python -m grpc_tools.protoc -I./proto \
       --python_out=./generated \
       --grpc_python_out=./generated \
       proto/hello.proto

Java​

使用 protoc 插件或 Maven/Gradle 插件自动生成：

<!-- Maven 插件配置 -->
<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
            <version>1.7.1</version>
        </extension>
    </extensions>
    <plugins>
        <plugin>
            <groupId>org.xolstice.maven.plugins</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>0.6.1</version>
            <configuration>
                <protocArtifact>com.google.protobuf:protoc:3.25.0:exe:${os.detected.classifier}</protocArtifact>
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.59.0:exe:${os.detected.classifier}</pluginArtifact>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                        <goal>compile-custom</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Node.js​

# 使用 @grpc/proto-loader 动态加载 proto 文件（推荐）
# 无需预生成代码

# 或使用静态代码生成
npm install -g grpc-tools
grpc_tools_node_protoc -I./proto \
    --js_out=import_style=commonjs,binary:./generated \
    --grpc_out=./generated \
    --plugin=protoc-gen-grpc=`which grpc_tools_node_protoc_plugin` \
    proto/hello.proto

验证环境​

创建一个简单的 proto 文件测试环境：

// test.proto
syntax = "proto3";

package test;

option go_package = "./test";

service TestService {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

生成代码并检查是否成功：

# Go
protoc --go_out=. --go-grpc_out=. test.proto

# Python
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. test.proto

# 检查生成的文件
ls *.pb.go  # Go
ls *_pb2.py # Python

常见问题​

1. protoc 命令找不到​

# 检查 protoc 是否在 PATH 中
which protoc

# 如果不在，添加到 PATH
export PATH="$PATH:/path/to/protobuf/bin"

2. 版本不兼容​

确保 protoc 和 gRPC 库版本兼容。建议使用最新稳定版本。

3. 插件找不到​

# Go 插件
export PATH="$PATH:$(go env GOPATH)/bin"

# Node.js 插件
npm install -g grpc-tools

小结​

本章我们学习了：

  1. Protocol Buffers 安装：在不同系统上安装 protoc 编译器
  2. gRPC 库安装：各语言的 gRPC 库和插件安装
  3. 项目结构：标准的 gRPC 项目结构
  4. 代码生成：使用 protoc 生成各语言代码
  5. 环境验证：测试开发环境是否配置正确

下一章我们将深入学习 Protocol Buffers 的语法和使用方法。