---
title: "接口兼容与版本升级"
---


RPC 的接口和 DTO 是客户端、服务端共同依赖的协议。一次改动可能同时影响 Java 方法代理、HTTP 路由和序列化格式。

### 1、 共享模块怎么放

```text
user-api
├── UserService.java
└── User.java
```

只放接口、DTO、枚举和协议常量。不要把数据库实体、Mapper、服务实现、Web 容器和注册中心客户端放进去。这样客户端升级协议时不会被迫升级服务端实现依赖。

### 2、 相对安全的变更

- DTO 新增可选字段，旧客户端通常可以忽略。
- 新增接口路径或新方法，保留旧接口一段时间。
- 新增方法尽量使用不同名称，避免重载带来的方法元数据和映射歧义。
- 服务端先兼容旧客户端，再发布客户端。

### 3、 高风险变更

以下改动应视为不兼容，至少要做双版本或灰度验证：

- 修改 `@Mapping` 路径或 `@NamiMapping` 的 HTTP 方法。
- 修改参数名、路径变量、query/body 位置。
- 修改返回类型、字段类型、枚举值语义。
- 删除旧字段，或把必填字段改成旧版本无法理解的类型。
- 只升级一端的二进制序列化组件。

### 4、 协议示例

旧接口：

```java
public interface UserService {
    User getById(long userId);
}
```

新增能力时优先增加新方法，而不是改变原方法返回值：

```java
public interface UserService {
    User getById(long userId);
    UserDetail getDetailById(long userId);
}
```

服务端先实现并发布，确认旧客户端仍能调用，再发布依赖新方法的客户端。

### 5、 序列化兼容测试

升级前至少验证：

- 基本类型、集合、null 和空集合。
- 日期、枚举、嵌套 DTO。
- 新 DTO 读取旧响应，旧 DTO 读取新增字段后的响应。
- 400/500 错误响应是否仍能被客户端识别。
- HTTP + snack4 与实际部署依赖是否一致。

建议保存脱敏的请求/响应样本，建立 provider/client 的集成测试，不要只依赖“本地能启动”。

### 6、 推荐发布顺序

```text
发布兼容版服务端
      ↓
观察旧客户端和错误率
      ↓
发布新客户端
      ↓
确认无旧客户端后再删除旧接口
```

如果更换 channel、coder、serialization 或 Discovery 插件，应单独做回滚方案。当前仓库源码中的 Nami 核心 API 包括 `Nami.builder()`、`NamiBuilder.create`、`@NamiClient`、`@NamiMapping`、`@NamiBody` 和 `NamiAttach`；升级时应以目标版本源码为准，不要把旧资料中的 `NamiAttachment` 当成 4.x API。