Jetbrains idea对proto的支持JetBrains IntelliJ IDEA

JetBrains IntelliJ IDEA — Protobuf & gRPC 全面支持指南

适用版本：IntelliJ IDEA 2023.3+ （Ultimate 版内置完整支持，Community 版需安装插件）

1. Proto 文件编辑支持

IntelliJ IDEA Ultimate 从 2020.2 起内置 Protocol Buffers 插件，提供：

.proto 文件语法高亮（proto2 / proto3）
代码补全（message、service、enum、option 等关键字）
import 路径自动补全与跳转
message 字段编号冲突检测
Find Usages / Go to Definition 跨文件导航
重构支持（Rename message、field 等）

解决 import 标红问题

当 .proto 文件中的 import 语句标红（无法解析）时，需要配置 Proto Source Root：

方法一：IDE 设置（推荐）

Settings → Languages & Frameworks → Protocol Buffers

import path + 添加 proto source root 路径

此时 import 其他proto"; 即可正确解析。

方法二：Mark Directory As（简易）

右键点击 proto 目录 → Mark Directory as → Sources Root

注意：方法二可能导致 Maven 构建与 IDE 的 source root 认知冲突，推荐使用方法一。

2. Maven 项目中集成 Proto 编译

2.1 插件配置（protobuf-maven-plugin）

<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>
                <!-- protoc 编译器 -->
                <protocArtifact>
                    com.google.protobuf:protoc:3.19.1:exe:${os.detected.classifier}
                </protocArtifact>
                <!-- gRPC Java 代码生成插件 -->
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>
                    io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
                </pluginArtifact>
                <!-- proto 文件根目录 -->
                <protoSourceRoot>./proto</protoSourceRoot>
                <!-- 生成代码输出目录 -->
                <outputDirectory>src/main/java</outputDirectory>
                <!-- 仅编译需要的 proto -->
                <includes>
                    <include>grpc/**</include>
                </includes>
                <!-- 不清空输出目录（与手写代码共存） -->
                <clearOutputDirectory>false</clearOutputDirectory>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>       <!-- 生成 Message 类 -->
                        <goal>compile-custom</goal> <!-- 生成 gRPC Stub 类 -->
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2.2 Maven 依赖

<dependencies>
    <!-- Protobuf 运行时 -->
    <dependency>
        <groupId>com.google.protobuf</groupId>
        <artifactId>protobuf-java</artifactId>
    </dependency>
    <dependency>
        <groupId>com.google.protobuf</groupId>
        <artifactId>protobuf-java-util</artifactId>
    </dependency>
    <!-- gRPC -->
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
    </dependency>
</dependencies>

2.3 编译命令

# 完整编译（含 proto 代码生成）
mvn clean compile

2.4 Spring Boot 3.x 适配（javax → jakarta）

gRPC 生成代码默认使用 javax.annotation，Spring Boot 3.x 需要 jakarta.annotation，可通过 maven-antrun-plugin 自动替换：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <id>replace-javax-to-jakarta-annotation</id>
            <phase>process-sources</phase>
            <goals><goal>run</goal></goals>
            <configuration>
                <target>
                    <replace dir="${basedir}"
                             includes="**/grpc/**/*.java"
                             token="javax.annotation.Generated"
                             value="jakarta.annotation.Generated"/>
                </target>
            </configuration>
        </execution>
    </executions>
</plugin>

3. gRPC Client 测试（内置工具）

IntelliJ IDEA Ultimate 2023.3+ 内置了 gRPC Client，无需第三方工具即可调用 gRPC 接口。

3.1 通过 Endpoints 面板

打开 View → Tool Windows → Endpoints
面板会自动扫描项目中的 .proto 文件，列出所有 gRPC Service 和 Method
点击任意方法右侧的 ▶ 按钮，即可发起调用

3.2 通过 .http 文件调用 gRPC

在 .http 文件中使用 GRPC 关键字（替代 GET/POST）：

基本请求（Unary）

### 调用 ServiceGrpc.test 方法
GRPC localhost:9090/ServiceGrpc/test

{
  "name": "hello"
}

携带 Metadata（请求头）

### 带认证信息的 gRPC 调用
GRPC localhost:9090/ServiceGrpc/test
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
auth_uid: 100001

{
  "name": "hello"
}

使用环境变量

先在 http-client.env.json 中定义环境：

{
  "dev": {
    "grpc_host": "dev-server:9090"
  },
  "local": {
    "grpc_host": "localhost:9090"
  }
}

然后在 .http 文件中引用：

### 使用环境变量
GRPC {{grpc_host}}/ServiceGrpc/test

{
  "name": "hello"
}

3.3 Server Streaming 请求

### Server streaming 示例
GRPC localhost:9090/ServiceGrpc/streamMethod

{
  "query": "test"
}

IDE 会在 Response 面板实时展示流式返回的消息。

3.4 gRPC Server Reflection（免 .proto 文件）

如果 gRPC Server 启用了 Server Reflection，IntelliJ 可以在不依赖本地 .proto 文件的情况下：

自动发现所有 Service 和 Method
提供请求体的 JSON Schema 补全

在 .http 文件中直接调用即可，IDE 会通过 Reflection 协议获取服务定义。

4. REST Client (.http 文件) 完整示例

将以下内容保存为 .http 文件（如 grpc-test.http），放在项目任意位置：

### ==================================================
### gRPC 接口测试
### ==================================================

### 1. 测试 CommerceServiceGrpc.test（Unary）
GRPC {{grpc_host}}/ServiceGrpc/test

{
  "name": "hello"
}

### ==================================================

对应的 http-client.env.json：

{
  "local": {
    "rest_host": "http://localhost:8080",
    "grpc_host": "localhost:9090"
  },
  "dev": {
    "rest_host": "https://dev-api",
    "grpc_host": "dev-grpc:9090"
  }
}

5. 常用操作速查表

操作	快捷方式 / 菜单
跳转到 message 定义	`Cmd + Click`（Mac）/ `Ctrl + Click`（Win）
查找 message 被引用的位置	`Cmd + Alt + F7` / `Ctrl + Alt + F7`
Proto 文件结构概览	`Cmd + F12` / `Ctrl + F12`
运行 .http 文件中的请求	点击行号旁的 ▶ 按钮，或 `Ctrl + Enter`
切换 .http 环境	运行按钮旁的环境下拉菜单
打开 Endpoints 面板	`View → Tool Windows → Endpoints`
配置 Proto Import Path	`Settings → Languages & Frameworks → Protocol Buffers`
Maven 重新导入	`Cmd + Shift + I`（Mac）/ `Ctrl + Shift + O`（Win）

Jetbrains idea对proto的支持