java微服务rpc远程接口是服务契约，需纯抽象、可序列化、独立模块共享；按框架选定义方式（dubbo用java接口、grpc用proto、openfeign用@feignclient）；设计重稳定演进，配文档与校验。
Java 中定义微服务的 RPC 远程接口，核心是让接口既能被服务提供方实现，又能被消费方“像调用本地方法一样”远程调用。它不是普通接口的简单复用，而是一套有约束、可共享、带契约语义的约定。
接口必须是纯抽象、无实现、可跨模块共享
远程接口本质是服务契约，需满足：
- 只声明方法签名（public 方法），不包含具体逻辑或 Spring 注解（如 @Service、@RestController）
- 参数和返回值类型必须是可序列化的（如 POJO、基本类型、String、List
等），避免使用 ThreadLocal、InputStream 等不可序列化类型 - 接口需放在独立的 module（如
api模块）中，由服务提供方和服务消费方共同依赖——这是实现“两端共用同一契约”的关键 - 推荐使用标准包名规范，例如
com.example.order.api，避免与实现类混在一起
配合框架选择合适的定义方式
不同 RPC 框架对接口定义的要求略有差异：
-
Dubbo：直接定义 Java 接口即可，例如
OrderService，框架通过注解（@DubboService/@DubboReference）绑定实现与引用 -
gRPC：不写 Java 接口，而是先写
.proto文件（IDL），再用 protoc 生成 Java 接口和 stub 类。生成的xxxGrpc.xxxBlockingStub才是客户端实际调用对象 -
Spring Cloud OpenFeign：虽属 REST 风格，但常被纳入广义 RPC 场景；需在接口上加
@FeignClient，并用 Spring MVC 注解（@GetMapping）描述 HTTP 协议行为
接口设计要兼顾稳定性与演进性
因为 RPC 接口一旦发布，就可能被多个消费者依赖，修改成本高：
- 方法名、参数顺序、返回类型尽量不变更；如需扩展，优先新增方法，而非修改原有方法签名
- 建议为每个接口添加版本号（如通过 package 名或接口名后缀
OrderServiceV2），避免强兼容旧版 - 参数推荐封装为 DTO 对象（如
GetOrderRequest），而非裸传多个基础类型——便于后续加字段、做校验、兼容不同语言 - 异常处理统一用自定义业务异常（如
OrderNotFoundException），不抛 unchecked 异常（如 NullPointerException）给远程端
配套生成/管理契约文档
光有接口代码不够，还需让上下游清晰理解契约：
- 使用 Javadoc 为每个方法写明用途、参数含义、成功/失败返回场景
- 配合 Swagger 或 gRPC 的
protoc-gen-doc插件，自动生成在线 API 文档 - 在 CI 流程中加入契约校验（如比对新旧 proto 文件 diff），防止不兼容变更上线
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
