java API接口怎么兼容

在 Java 里“API 接口怎么兼容”通常指在不改坏已有调用方的前提下演进接口，也就是向后兼容（Backward Compatibility）。下面从原则、常见做法、反例和工具几个角度说明。

一、什么是 Java API 兼容

一般指：

• 二进制兼容：老 .class 文件调用新 jar 不报错
• 源码兼容：老代码重新编译也不报错
• 行为兼容：功能结果和以前一致

实际中最常要求的是二进制 + 行为兼容。

二、推荐做法（怎么做到兼容）

1. 优先“加”不“改”

✅ 新增方法，不修改老方法签名

public interface UserService {
    User getUser(Long id);

    // 新增，不影响老调用
    default User getUserWithCache(Long id) {
        return getUser(id);
    }
}

2. 使用 default 方法（Java 8+）

接口演进利器：

public interface OrderService {
    Order createOrder(Order order);

    default Order createOrderV2(Order order, boolean async) {
        return createOrder(order);
    }
}

✅ 老实现类不用改
❌ 不能删除 default 方法（否则可能破坏兼容）

3. 方法重载而不是改签名

❌ 不兼容：

// 旧
void send(String msg);
// 新
void send(String msg, String type);

✅ 兼容：

void send(String msg);
void send(String msg, String type);

4. 用新类 / 新接口，不破坏老的

// 老
UserApiV1

// 新
UserApiV2

调用方自己迁移，互不干扰。

5. 用 Optional / 默认值兜底

default String getName() {
    return "";
}

避免 NullPointerException 导致行为不兼容。

6. 序列化 / JSON 接口兼容

• 不加 required
• 不删字段（用 @Deprecated）
• 不随便改字段类型

@Deprecated
private String oldName;
private String name;

三、常见“不兼容”操作（要避免）

❌ 删除方法 / 字段
❌ 改方法名、参数类型、返回值
❌ 改异常类型（checked → unchecked）
❌ 改接口继承关系
❌ 改方法语义（即使签名没变）

四、废弃（Deprecation）规范

@Deprecated(since = "2.0", forRemoval = true)
void oldMethod();

✅ 给调用方迁移时间
❌ 不要立刻删

五、版本与契约管理

• 接口 URL：/api/v1、/api/v2
• Maven：语义化版本 1.2.3
  • 主版本：不兼容
  • 次版本：向下兼容
  • 修订号：Bug 修复

六、工具辅助检测兼容性

• japicmp：自动比对 jar 兼容性
• Clirr：老工具
• RevAPI
• CI 中加兼容检查，防止误提交

七、一句话总结

Java API 兼容的核心：只加不改、不删、不偷偷变行为，用 default / 重载 / 新版本平滑演进。

如果你说的是 REST API / RPC / 某个具体框架（Spring、Dubbo、Feign），可以告诉我，我给你更具体的方案。