你好呀，我的老朋友！我是老寇，欢迎来到老寇IoT云平台！

一、Spring gRPC 配置

Spring gRPC官方地址 (opens new window)

1.1 Server 端配置（spring.grpc.server）

gRPC 服务提供者需要配置 Server 端，用于暴露 gRPC 接口。

属性说明

属性	类型	默认值	说明
spring.grpc.server.port	int	9090	gRPC 服务监听端口
spring.grpc.server.servlet.enabled	boolean	true	是否通过 Servlet 容器提供 gRPC 服务。设为 false 时使用独立 Netty 端口

配置示例

# laokou-distributed-id 服务端配置
spring:
  grpc:
    server:
      servlet:
        enabled: false   # 禁用 Servlet 模式，使用独立 gRPC 端口
      port: 10111        # gRPC 服务监听端口
  # 需要注册gprc_port端口到Nacos服务发现，否则客户端无法通过discovery://服务名访问
  cloud:
	nacos:
	  discovery:
		metadata:
		  grpc_port: ${GRPC_PORT:10111}

说明：servlet.enabled=false 表示 gRPC 走独立端口（10111），与 HTTP Servlet（如 Tomcat 的 9094）互不干扰，生产环境推荐此做法。

Maven 依赖

<!-- gRPC Server 端 Starter -->
<dependency>
    <groupId>org.springframework.grpc</groupId>
    <artifactId>spring-grpc-server-web-spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-servlet-jakarta</artifactId>
        </exclusion>
    </exclusions>
</dependency>

---

1.2 Client 端配置（spring.grpc.client）

gRPC 调用方需要配置 Client 端通道（Channel），用于连接远程 gRPC 服务。

属性说明

属性	类型	默认值	说明
spring.grpc.client.channels.<name>.address	String	—	gRPC 服务地址
spring.grpc.client.channels.<name>.enable-keep-alive	boolean	false	是否开启 TCP Keep-Alive 心跳
spring.grpc.client.channels.<name>.idle-timeout	Duration	—	连接空闲超时时间

地址格式说明：

• 服务发现：discovery://服务名（配合 Nacos Loadbalancer）
• 直连：static://host:port（开发/测试环境）

配置示例

# laokou-auth / laokou-admin 客户端配置
spring:
  grpc:
    client:
      channels:
        laokou-distributed-id:                        # 通道名称（对应目标服务名）
          address: discovery://laokou-distributed-id   # 通过 Nacos 服务发现
          enable-keep-alive: true                      # 开启 Keep-Alive 心跳
          idle-timeout: 60s                            # 空闲超时 60 秒

Maven 依赖

<!-- gRPC Client 端 Starter -->
<dependency>
    <groupId>org.springframework.grpc</groupId>
    <artifactId>spring-grpc-client-spring-boot-starter</artifactId>
</dependency>

---

1.3 Server + Client 完整示例

spring:
  grpc:
    server:
      servlet:
        enabled: false       # 独立 gRPC 端口
      port: 9097             # gRPC 服务端口
    client:
      channels:
        my-service:
          address: discovery://my-service    # 服务发现
          enable-keep-alive: true
          idle-timeout: 60s
  # 需要注册gprc_port端口到Nacos服务发现，否则客户端无法通过discovery://服务名访问
  cloud:
	nacos:
	  discovery:
	  	metadata:
		  grpc_port: ${GRPC_PORT:10111}

---

1.4 版本管理（根 pom.xml）

<properties>
    <spring-grpc.version>1.0.2</spring-grpc.version>         <!-- Spring gRPC -->
    <grpc.version>1.79.0</grpc.version>                       <!-- io.grpc -->
    <protobuf.version>3.25.8</protobuf.version>               <!-- Protobuf -->
    <protobuf-maven-plugin.version>5.0.0</protobuf-maven-plugin.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- Spring gRPC BOM -->
        <dependency>
            <groupId>org.springframework.grpc</groupId>
            <artifactId>spring-grpc-dependencies</artifactId>
            <version>${spring-grpc.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- gRPC BOM -->
        <dependency>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-bom</artifactId>
            <version>${grpc.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Protobuf Java -->
        <dependency>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
            <version>${protobuf.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

---

二、Protobuf 代码生成

2.1 生成流程

.proto 文件
    ├── protoc 编译器 ──────────────→ 消息类（Request/Response Java 文件）
    └── protoc-gen-grpc-java 插件 ──→ gRPC Stub 类（Blocking/Async/Future Stub）

所有生成文件输出到：target/generated-sources/protobuf/

---

2.2 Proto 文件编写

语法说明

// 1. 指定 proto3 语法（必须放在第一行）
syntax = "proto3";

// 2. Java 代码生成选项
option java_multiple_files = true;                          // 每个消息生成独立 .java 文件
option java_package = "org.laokou.distributed.id.proto";    // Java 包名
option java_outer_classname = "DistributedIdProto";         // 外层包装类名

// 3. 定义消息体（Message）
message GenerateIdRequest {
    // 空消息体
}

message GenerateBatchIdRequest {
    int32 num = 1;          // 字段编号从 1 开始
}

message GenerateIdResponse {
    string code = 1;        // 状态码
    string msg = 2;         // 状态消息
    int64 data = 3;         // 生成的 ID
}

message GenerateBatchIdsResponse {
    string code = 1;
    string msg = 2;
    repeated int64 data = 3;  // repeated = Java List<Long>
}

// 4. 定义 gRPC 服务接口
service DistributedIdServiceI {
    rpc generateId(GenerateIdRequest) returns (GenerateIdResponse);
    rpc generateBatchIds(GenerateBatchIdRequest) returns (GenerateBatchIdsResponse);
}

选项说明

选项	值	说明
java_multiple_files	true	每个 message / service 生成独立 .java 文件
java_package	包名	生成的 Java 代码包路径
java_outer_classname	类名	外层包装类名（存放文件描述符等公共元数据）

常用字段类型

Proto 类型	Java 类型	说明
int32	int	32 位整数
int64	long	64 位整数
string	String	字符串
bool	boolean	布尔值
double	double	双精度浮点
float	float	单精度浮点
bytes	ByteString	字节数组
repeated T	List<T>	列表/数组

---

2.3 生成的文件清单

以 distributed_id.proto 为例，编译后生成：

文件	生成器	说明
GenerateIdRequest.java	protoc	请求消息类
GenerateIdRequestOrBuilder.java	protoc	消息构建器接口
GenerateIdResponse.java	protoc	响应消息类
GenerateIdResponseOrBuilder.java	protoc	消息构建器接口
GenerateBatchIdRequest.java	protoc	批量请求消息类
GenerateBatchIdsResponse.java	protoc	批量响应消息类
DistributedIdProto.java	protoc	外层包装类
DistributedIdServiceIGrpc.java	protoc-gen-grpc-java	gRPC Stub 类

其中 DistributedIdServiceIGrpc.java 包含以下内部类：

内部类	用途
AsyncService	异步服务接口（服务端实现用）
DistributedIdServiceIImplBase	服务端抽象基类
DistributedIdServiceIBlockingStub	同步阻塞客户端 Stub
DistributedIdServiceIFutureStub	异步 Future 客户端 Stub
DistributedIdServiceIStub	异步回调客户端 Stub

---

2.4 Maven 插件配置

所需组件一览

组件	GAV	版本	作用
Protobuf Maven Plugin	io.github.ascopes:protobuf-maven-plugin	5.0.0	Maven 构建插件
Protoc 编译器	自动下载	3.25.8	编译 .proto → Java 消息类
gRPC Java 代码生成器	io.grpc:protoc-gen-grpc-java	1.79.0	编译 .proto → gRPC Stub 类

完整插件配置（pom.xml）

<build>
    <plugins>
        <plugin>
            <groupId>io.github.ascopes</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>${protobuf-maven-plugin.version}</version>
            <configuration>
                <!-- 启用 Java 代码生成 -->
                <javaEnabled>true</javaEnabled>
                <!-- protoc 编译器版本（自动从 Maven 仓库下载） -->
                <protoc>${protobuf.version}</protoc>
                <plugins>
                    <!-- gRPC 代码生成插件（自动从 Maven 仓库下载） -->
                    <plugin kind="binary-maven">
                        <groupId>io.grpc</groupId>
                        <artifactId>protoc-gen-grpc-java</artifactId>
                        <version>${grpc.version}</version>
                        <!-- 省略 @Generated 注解 -->
                        <options>@generated=omit</options>
                    </plugin>
                </plugins>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <!--
                          generate     → 编译 src/main/proto/ 下的 .proto 文件
                          generate-test → 编译 src/test/proto/ 下的 .proto 文件
                        -->
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

关键说明：

• kind="binary-maven"：从 Maven 仓库自动下载 protoc-gen-grpc-java 可执行文件，无需手动安装
• <options>@generated=omit</options>：省略 @Generated 注解，避免 CheckStyle / SpotBugs 检查报错
• <goal>generate</goal>：正式代码用，<goal>generate-test</goal>：测试代码用

---

2.5 目录结构

laokou-distributed-id-proto/
├── pom.xml
├── src/
│   └── main/
│       └── proto/
│           └── distributed_id.proto          ← 源 proto 文件
└── target/
    └── generated-sources/
        └── protobuf/
            └── org/laokou/distributed/id/proto/
                ├── DistributedIdProto.java
                ├── DistributedIdServiceIGrpc.java
                ├── GenerateIdRequest.java
                ├── GenerateIdRequestOrBuilder.java
                ├── GenerateIdResponse.java
                ├── GenerateIdResponseOrBuilder.java
                ├── GenerateBatchIdRequest.java
                ├── GenerateBatchIdRequestOrBuilder.java
                ├── GenerateBatchIdsResponse.java
                └── GenerateBatchIdsResponseOrBuilder.java

---

2.6 执行代码生成

# 方式一：完整编译（推荐）
cd laokou-service/laokou-distributed-id/laokou-distributed-id-proto
mvn compile

# 方式二：仅执行 protobuf 生成
mvn protobuf:generate

---

三、调用关系总览

┌─────────────────────────────────────────────────────────┐
│                     Proto 模块                           │
│  distributed_id.proto                                    │
│       │                                                  │
│       ├── protoc → 消息类 (Request/Response)              │
│       └── protoc-gen-grpc-java → Stub 类                 │
└─────────────────┬───────────────────────┬───────────────┘
                  │                       │
          ┌───────▼────────┐    ┌─────────▼──────────┐
          │  gRPC 客户端    │    │   gRPC 服务端       │
          │                │    │                     │
          │ laokou-auth    │    │ laokou-distributed  │
          │ laokou-admin   │    │ -id                 │
          │                │    │                     │
          │ 配置:           │    │ 配置:                │
          │ spring.grpc    │    │ spring.grpc         │
          │  .client       │    │  .server            │
          │  .channels     │    │  .port: 10111       │
          │  .laokou-xxx   │    │  .servlet           │
          │   .address:    │    │   .enabled: false   │
          │    discovery:  │    │                     │
          │    //xxx       │    │                     │
          └───────┬────────┘    └─────────▲──────────┘
                  │                       │
                  │    ┌──────────┐       │
                  └───→│  Nacos   │───────┘
                       │ 服务发现  │
                       │ 负载均衡  │
                       └──────────┘

---

四、快速上手：新增一个 gRPC 服务

步骤 1：编写 .proto 文件

在 src/main/proto/ 下新建 .proto 文件：

syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.laokou.xxx.proto";
option java_outer_classname = "XxxProto";

message XxxRequest {
    string name = 1;
}

message XxxResponse {
    string code = 1;
    string msg = 2;
    string data = 3;
}

service XxxServiceI {
    rpc doSomething(XxxRequest) returns (XxxResponse);
}

步骤 2：配置 pom.xml

参考 2.4 Maven 插件配置 添加 protobuf-maven-plugin。

步骤 3：编译生成代码

mvn compile

步骤 4：服务端实现

@GrpcService
public class XxxGrpcServer extends XxxServiceIGrpc.XxxServiceIImplBase {

    @Override
    public void doSomething(XxxRequest request, StreamObserver<XxxResponse> responseObserver) {
        XxxResponse response = XxxResponse.newBuilder()
            .setCode("OK")
            .setMsg("成功")
            .setData("Hello, " + request.getName())
            .build();
        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }
}

步骤 5：服务端 YAML 配置

spring:
  grpc:
    server:
      servlet:
        enabled: false
      port: 10222
  # 需要注册gprc_port端口到Nacos服务发现，否则客户端无法通过discovery://服务名访问
  cloud:
    nacos:
	  discovery:
	    metadata:
		  grpc_port: ${GRPC_PORT:10222}

步骤 6：客户端调用

@Service
public class XxxGrpcClient {

	@GrpcClient(serviceId = "laokou-distributed-id")
	private XxxServiceIGrpc.XxxServiceIBlockingV2Stub xxxServiceIBlockingV2Stub;

    public String doSomething(String name) {
        XxxRequest request = XxxRequest.newBuilder()
            .setName(name)
            .build();
        XxxResponse response = xxxServiceIBlockingV2Stub.doSomething(request);
        return response.getData();
    }
}

步骤 7：客户端 YAML 配置

spring:
  grpc:
    client:
      channels:
        xxx:
          address: discovery://xxx
          enable-keep-alive: true
          idle-timeout: 60s

我是老寇，我们下次再见啦！