在软件工程中，API 兼容性是一个至关重要但又经常被忽视的问题。良好的兼容性设计能够确保系统的平滑演进，避免因 API 变更导致的客户端崩溃和服务中断。本文将从多个维度探讨 API 兼容性设计的最佳实践。

什么是 API 兼容性

API 兼容性分为两种类型：

向前兼容：旧版本的客户端能够与新版本的服务端正常通信。即服务端升级后，旧客户端仍能正常工作。
向后兼容：新版本的客户端能够与旧版本的服务端正常通信。即客户端升级后，旧服务端仍能提供服务。

在实际项目中，我们通常更关注向前兼容，因为服务端的升级往往不可控，而客户端的更新节奏各异。

破坏性变更的分类

破坏性变更是指会导致现有客户端无法正常工作的 API 变更。主要分为三类：

1. 接口签名变更

// 变更前
public interface UserService {
    User getUser(String userId);
}

// 变更后 - 破坏性变更
public interface UserService {
    User getUser(String userId, boolean includeDetails);
}

这种变更会直接导致编译错误或运行时异常。

2. 行为变更

接口签名不变，但行为逻辑发生变化。

// 变更前：返回 null 表示用户不存在
public User getUser(String userId) {
    return userRepository.findById(userId);
}

// 变更后：抛出异常表示用户不存在
public User getUser(String userId) {
    User user = userRepository.findById(userId);
    if (user == null) {
        throw new UserNotFoundException(userId);
    }
    return user;
}

3. 语义变更

参数或返回值的含义发生改变。

// 变更前：limit 表示返回的最大记录数
public List<User> getUsers(int limit);

// 变更后：limit 表示从第几条开始返回
public List<User> getUsers(int offset);

保持兼容性的设计策略

1. 只增不删原则

这是最简单也最有效的策略：永远不要删除字段、方法或接口，只能新增。

public class UserDTO {
    private String id;
    private String name;
    private String email;
    
    // 新增字段不会破坏兼容性
    private String phone;
    
    // getters and setters
}

2. 方法重载

通过方法重载提供新的接口，同时保留旧接口。

public interface UserService {
    // 保留旧接口
    User getUser(String userId);
    
    // 新增重载方法
    default User getUser(String userId, boolean includeDetails) {
        User user = getUser(userId);
        if (!includeDetails) {
            user.setSensitiveData(null);
        }
        return user;
    }
}

3. 使用 @Deprecated

标记废弃接口，引导客户端逐步迁移。

public interface UserService {
    /**
     * @deprecated 使用 {@link #getUser(String, boolean)} 代替
     */
    @Deprecated
    User getUser(String userId);
    
    User getUser(String userId, boolean includeDetails);
}

4. 默认参数值

对于可选参数，提供合理的默认值。

public interface UserService {
    default User getUser(String userId) {
        return getUser(userId, false);
    }
    
    User getUser(String userId, boolean includeDetails);
}

5. 版本化 API

当无法避免破坏性变更时，引入版本化。

public interface UserServiceV1 {
    User getUser(String userId);
}

public interface UserServiceV2 {
    UserDTO getUser(String userId);
}

REST API 的兼容性设计

1. URL 版本化

在 URL 中明确标识 API 版本：

1 2	`GET /api/v1/users/{userId} GET /api/v2/users/{userId}`

2. 请求/响应字段兼容

请求字段：新增字段应该是可选的
响应字段：新增字段不会影响旧客户端的解析

v1 响应示例：

{
  "id": "123",
  "name": "张三"
}

v2 响应示例（向前兼容，新增了 email 字段）：

{
  "id": "123",
  "name": "张三",
  "email": "zhangsan@example.com"
}

3. Content Negotiation

使用 HTTP 头进行版本协商：

1	`Accept: application/vnd.myapi.v2+json`

库/SDK 的兼容性设计

二进制兼容性 vs 源码兼容性

二进制兼容性：重新编译客户端后无需重新编译即可运行
源码兼容性：客户端无需修改代码即可重新编译

Java 中的兼容性问题

// 场景1：添加接口方法 - 破坏二进制兼容性
public interface Service {
    void doWork();
    
    // 新增方法会导致实现类无法加载
    void doWork(Context context);
}

// 场景2：使用 default 方法 - 保持兼容性
public interface Service {
    void doWork();
    
    default void doWork(Context context) {
        doWork();
    }
}

数据库 Schema 的兼容性

1. 只增列不删列

-- 允许的操作
ALTER TABLE users ADD COLUMN phone VARCHAR(20);

-- 禁止的操作
ALTER TABLE users DROP COLUMN email;

2. 可空字段

新增字段应该允许 NULL。

1	`ALTER TABLE users ADD COLUMN phone VARCHAR(20) NULL;`

3. 数据迁移策略

对于非空字段，采用两阶段迁移：

-- 阶段1：添加可空字段
ALTER TABLE users ADD COLUMN phone VARCHAR(20) NULL;

-- 阶段2：填充数据
UPDATE users SET phone = 'default' WHERE phone IS NULL;

-- 阶段3：设置为非空
ALTER TABLE users MODIFY COLUMN phone VARCHAR(20) NOT NULL;

与语义版本化的关系

遵循语义版本规范（SemVer）：

MAJOR：破坏性变更（如删除接口、修改方法签名）
MINOR：向后兼容的功能新增（如新增方法、新增字段）
MINOR：向后兼容的问题修复

版本号决策示例

// PATCH: 修复 Bug
public User getUser(String userId) {
    // 修复空指针问题
    return userRepository.findById(userId).orElse(null);
}

// MINOR: 新增方法
public interface UserService {
    User getUser(String userId);
    UserDTO getUserDTO(String userId); // 新增
}

// MAJOR: 修改方法签名
public interface UserService {
    User getUser(String userId, String tenantId); // 参数变化
}