根本原因是生成路径未被Maven或IDE识别为源码目录；需配置插件将target/generated-sources/protobuf/java加入源路径，并在IDE中标记为Generated Sources Root。
gRPC Java项目里，protoc 生成的代码为啥总报错找不到类？
根本原因不是没生成，而是生成路径没被 Maven 或 IDE 当作源码目录识别。默认 protoc 把 Java 类写进 target/generated-sources/protobuf/java，但这个路径不在 Maven 的 compile 生命周期源码路径里。
- 用 Maven 构建时，必须加
maven-compiler-plugin插件，并显式把该路径加入sourceDirectory（或用build-helper-maven-pluginattach） - IntelliJ IDEA 不会自动刷新 generated 目录，右键目录 → Mark as Generated Sources Root 才能补全 import 和跳转
- Gradle 用户别直接用
protobuf { generateProtoTasks }就完事，得确认sourceSets.main.java.srcDir包含了输出路径，否则编译报cannot find symbol
Protobuf 编译插件选 protobuf-maven-plugin 还是 grpc-java 官方插件？
用 protobuf-maven-plugin。它专注 .proto 编译，和 gRPC 解耦；而 grpc-java 官方不维护 Maven 插件，所谓“官方插件”其实是社区维护的 protobuf-maven-plugin + grpc-protobuf 依赖组合。
-
protobuf-maven-plugin支持多语言输出（Java / Kotlin / Scala），也支持 gRPC stub 生成（靠grpc-java提供的protoc-gen-grpc-java插件） - 关键配置项：
plugin下要指定protoc-gen-grpc-java的版本，且必须和项目引入的io.grpc:grpc-protobuf版本严格一致，否则生成的 stub 会调用不存在的方法 - 别漏掉
includeStdTypes = true，否则google/protobuf/timestamp.proto这类标准类型会编译失败
Maven 中 protobuf-maven-plugin 的执行时机为什么总卡在 generate-sources 阶段之后？
因为插件默认绑定到 generate-sources，但如果你在 pom.xml 里写了多个 execution，或者用了 executions + id 却没显式指定 phase，Maven 可能按字母序执行，导致生成代码晚于编译触发点。
- 每个
execution必须明确写<phase>generate-sources</phase>，不能依赖默认值 - 如果同时生成普通 Java 和 gRPC stub，建议拆成两个
execution：一个只跑java，一个只跑grpc-java，避免参数冲突 - 执行前先
mvn clean compile -X看日志里是否真有[INFO] Compiling 3 protocol buffer file(s) to ...，没这行说明插件压根没跑
生成的 *Grpc.java 类里，bindService() 方法返回 ServerServiceDefinition，但实际启动 Server 时却要用 addService()？
这是 gRPC Java 的设计分层：生成类只负责定义服务契约和序列化逻辑，不参与运行时注册。你拿到的 ServerServiceDefinition 是“可注册的服务描述”，不是“已注册的服务实例”。
立即学习“Java免费学习笔记（深入）”；
-
bindService()返回的是服务定义对象，必须手动传给ServerBuilder.addService()才真正挂载 - 常见错误是直接 new 一个
MyServiceImpl()就以为服务起来了，其实没注册，客户端调用会立刻返回UNIMPLEMENTED - 如果用了 Spring Boot，别指望
@GrpcService自动注册——那是grpc-spring-boot-starter的扩展行为，原生 gRPC 没这功能
最常被跳过的一步是验证生成代码是否真被编译器看见：删掉 target/generated-sources，clean 重编，再看 IDE 是否还报红。如果还红，问题一定出在路径声明或插件执行顺序上，而不是 .proto 写错了。
