第一次遇到API版本化问题，是因为我改动了登录接口的返回格式。原本返回{ "token": "xxx" }，现在我想增加用户信息，改成{ "token": "xxx", "user": { ... } }。

我觉得这是个优化——多返回数据总是好事，对吧？

第二天，前端同事气急败坏地找我：“登录功能挂了！你们后端怎么不通知就改接口？”

我理直气壮：“我加字段而已，旧的客户端应该自动忽略不认识的字段啊。”

他发来一张截图，是他们的APP日志：“TypeError: Cannot read property 'token' of undefined”。原来他们的代码写的是response.token，而现在返回的是response.data.token。

“等等，我没改字段名啊。”
“我们用的是三年前的老SDK，它会自动把响应包一层data。”

那一刻，我明白了：API一旦发布，就不再是你的私有财产。它是一份与无数客户端签订的、无法轻易撕毁的契约。

我们团队花了三年时间，踩遍了API版本化的所有坑，最终找到了一条在“向前兼容”和“代码整洁”之间的狭窄出路。这不是一篇关于URL中该用/v1/还是/v2/的教程，而是一个关于如何在现实约束下做设计决策的故事。

第一章：最初的混乱——每个人都以为自己懂版本化

1.1 URL版本化的陷阱

刚开始，我们采用了最直观的方式：URL中带版本号。

// UserController.java
@RestController
public class UserController {
    
    @GetMapping("/api/v1/users/{id}")
    public UserV1 getUserV1(@PathVariable Long id) {
        User user = userService.getById(id);
        return UserV1.from(user);
    }
    
    @GetMapping("/api/v2/users/{id}") 
    public UserV2 getUserV2(@PathVariable Long id) {
        User user = userService.getById(id);
        return UserV2.from(user);
    }
}

看起来多么清晰！v1和v2分离，互不干扰。我们还专门建立了dto/v1和dto/v2包，里面是一模一样的类，除了包名不同。

问题很快出现了：

1. 代码爆炸：每增加一个版本，就多一套Controller、一套DTO、一套Mapper。UserV1、UserV2、UserV3... 它们95%的代码都一样。
2. Bug修复地狱：发现UserV1的一个字段映射有错误，我改完UserV1，还得记得去改UserV2、UserV3... 常常忘记。
3. 逻辑不一致：更可怕的是，有些版本里加了特殊的业务逻辑：

// UserV2Mapper.java
public UserV2 from(User user) {
    UserV2 dto = new UserV2();
    dto.setId(user.getId());
    dto.setName(user.getName());
    
    // 只有v2才有的特殊逻辑
    if ("admin".equals(user.getRole())) {
        dto.setAccessLevel("HIGH");
    }
    return dto;
}

等我们需要v3时，要么复制这段特殊逻辑，要么重新实现。几个月后，没人记得这些特殊逻辑为什么存在，该不该保留。

1.2 请求头版本化的困境

于是我们换了一种思路：版本号放请求头，URL保持不变。

@GetMapping("/api/users/{id}")
public ResponseEntity<?> getUser(
    @PathVariable Long id,
    @RequestHeader(value = "API-Version", defaultValue = "v1") String version) {
    
    User user = userService.getById(id);
    
    if ("v1".equals(version)) {
        return ResponseEntity.ok(UserV1.from(user));
    } else if ("v2".equals(version)) {
        return ResponseEntity.ok(UserV2.from(user));
    }
    // ... 更多的if-else
}

新的问题：

1. if-else地狱：每个API都要写一长串版本判断，代码丑陋不堪。
2. 文档灾难：怎么给前端同事写文档？“调用/api/users/1，如果你想要v1的格式，请求头加API-Version: v1；如果你想要v2，加API-Version: v2...” 前端同事每次调用都要查版本号。
3. 缓存混乱：同一个URL返回不同内容，缓存系统要疯了。

第二章：顿悟时刻——版本化不是版本隔离

在一次代码审查中，我的导师指着一个v3版本的API问我：“这个getUserV3方法和getUserV2，除了返回字段多了两个，业务逻辑有什么不同？”

我想了想：“好像...没有。”
“那为什么要有两段几乎一样的代码？”
“因为...版本要隔离？”
“你在隔离什么？隔离相同的业务逻辑吗？”

这个提问让我重新思考API版本化的本质。我们到底在为什么做版本化？

2.1 梳理真正的变更类型

我拉上团队，一起梳理了我们所有API的变更历史，发现变更其实只有三类：

1. 字段增删改：比如v1返回{ "name": "张三" }，v2想改成{ "fullName": "张三" }
2. 结构变化：比如v1返回扁平结构，v2变成嵌套结构
3. 业务逻辑变化：比如v1的用户状态只有3种，v2变成了5种

只有第三种变更才真正需要不同的业务逻辑。前两种变更，只是在呈现方式上不同，背后的业务逻辑是一样的。

2.2 关键洞察：区分“领域模型”和“API模型”

这个洞察改变了一切。我们不再为每个版本创建独立的业务逻辑，而是：

// 领域模型 - 业务的真实表达，只有一套
public class User {
    private Long id;
    private String username;
    private String email;
    private LocalDateTime createTime;
    // ... 其他业务字段
}

// API模型 - 不同版本的视图，可以有多套
public class UserV1Response {
    private Long id;
    private String name;  // 注意：v1叫name，v2叫username
    private String email;
}

public class UserV2Response {
    private Long id;
    private String username;  // v2改名了
    private String email;
    private String createTime; // v2格式化成字符串
}

现在，业务逻辑只有一套：

public User getUserById(Long id) {
    // 只关心业务逻辑，不关心API版本
    return userRepository.findById(id);
}

版本差异在转换层处理：

public class UserApiAdapter {
    
    public UserV1Response toV1(User user) {
        UserV1Response response = new UserV1Response();
        response.setId(user.getId());
        response.setName(user.getUsername()); // 字段名映射
        response.setEmail(user.getEmail());
        return response;
    }
    
    public UserV2Response toV2(User user) {
        UserV2Response response = new UserV2Response();
        response.setId(user.getId());
        response.setUsername(user.getUsername());
        response.setEmail(user.getEmail());
        response.setCreateTime(user.getCreateTime().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
        return response;
    }
}

第三章：实践演进——我们的三层架构方案

基于以上洞察，我们设计了一个三层的架构，它成为了我们版本化策略的核心。

3.1 第一层：路由层（决定用哪个版本）

我们最终选择了URL路径版本化，但不是每个方法都有版本，而是在网关层面做路由：

# 网关配置
spring:
  cloud:
    gateway:
      routes:
      - id: user_api_v1
        uri: lb://user-service
        predicates:
        - Path=/api/v1/users/**
        filters:
        - RewritePath=/api/v1/(?<segment>.*), /$\{segment}  # 去掉版本前缀
        - name: ApiVersion
          args:
            version: v1
            
      - id: user_api_v2  
        uri: lb://user-service
        predicates:
        - Path=/api/v2/users/**
        filters:
        - RewritePath=/api/v2/(?<segment>.*), /$\{segment}
        - name: ApiVersion
          args:
            version: v2

这样，服务内部接收到的请求路径是不带版本号的/users/**，但同时网关会注入一个X-API-Version请求头。

3.2 第二层：控制层（适配不同版本）

在Controller层，我们统一处理所有版本的请求，通过拦截器自动处理版本：

@RestController
@RequestMapping("/users")
public class UserController {
    
    @GetMapping("/{id}")
    public ResponseEntity<?> getUser(@PathVariable Long id) {
        User user = userService.getUserById(id);
        
        // 从ThreadLocal获取当前请求的版本（由拦截器设置）
        ApiVersion version = ApiVersionContext.getCurrentVersion();
        
        // 使用适配器转换
        Object response = userApiAdapter.toResponse(user, version);
        
        return ResponseEntity.ok(response);
    }
}

// 适配器核心逻辑
public class UserApiAdapter {
    
    public Object toResponse(User user, ApiVersion version) {
        switch (version) {
            case V1:
                return toV1(user);
            case V2:
                return toV2(user);
            case V3:
                return toV3(user);
            default:
                return toLatest(user);
        }
    }
    
    private UserV1Response toV1(User user) {
        // 转换逻辑
    }
    
    // ... 其他版本转换
}

3.3 第三层：业务层（保持纯净）

业务层完全不知道版本的存在：

@Service
public class UserService {
    
    // 业务逻辑完全不知道API版本
    public User getUserById(Long id) {
        // 复杂的业务逻辑
        User user = userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
        
        // 各种业务处理...
        enrichUserDetails(user);
        calculateUserStats(user);
        
        return user;
    }
}

这个架构的美妙之处在于：

1. 业务逻辑保持纯净，不掺和版本问题
2. 新加版本时，只需要在适配器层添加一个转换方法
3. 同一个业务逻辑可以服务多个API版本

第四章：向前兼容的具体策略

有了架构，我们还需要具体的策略来处理向前兼容。经过多次迭代，我们总结出了“向前兼容四原则”。

原则一：只添加，不修改（Add Only）

错误示范：

// v1响应
public class UserResponse {
    private String name;
}

// v2响应（错误：修改了字段名）
public class UserResponse {
    private String fullName; // 原来叫name，现在改名了
}

正确做法：

// v1响应保持不变
public class UserResponse {
    private String name;
}

// v2响应添加新字段，旧字段保持兼容
public class UserResponse {
    private String name;      // 保持v1的字段，不删除
    private String fullName;  // 新增字段
    
    // 保持向后兼容的getter
    public String getName() {
        return name != null ? name : fullName;
    }
}

原则二：字段的语义不改变（Same Semantics）

这是最容易踩的坑。有一次，我们把age字段从“周岁”改成了“虚岁”，导致前端显示的用户年龄都大了一岁。

现在，我们的规则是：如果一个字段的语义要改变，就新增一个字段，而不是修改现有字段。

public class UserResponse {
    // 旧字段：周岁年龄
    @Deprecated
    @JsonPropertyDescription("年龄（周岁），已废弃，请使用ageInYears")
    private Integer age;
    
    // 新字段：明确语义
    @JsonPropertyDescription("年龄（周岁）")
    private Integer ageInYears;
    
    // 另一个新字段，用于不同语义
    @JsonPropertyDescription("年龄（虚岁）")
    private Integer ageInLunarYears;
}

原则三：默认值保持稳定（Stable Defaults）

我们曾经在一个布尔字段上栽过跟头。v1中，isPremium字段在用户不是会员时返回false，v2中我们改了逻辑，返回null。结果一堆前端应用崩溃。

现在的规则：默认值的语义必须稳定。

public class UserResponse {
    private Boolean isPremium;
    
    // 在序列化时确保默认值稳定
    @JsonSerialize(nullsUsing = PremiumNullSerializer.class)
    public Boolean getIsPremium() {
        return isPremium != null ? isPremium : false;
    }
}

原则四：废弃要温柔（Gentle Deprecation）

当我们真的需要移除一个字段时，我们采用“三阶段废弃法”：

第一阶段：标记废弃，但保持功能

public class UserResponse {
    @Deprecated
    @JsonProperty("oldField")
    private String oldField; // 已经不用了，但还保留
    
    @JsonProperty("newField")
    private String newField;
    
    // 保持兼容：如果访问oldField，返回newField的值
    public String getOldField() {
        return newField;
    }
}

第二阶段：文档警告，监控使用
我们在API文档中明确标记字段已废弃，并通过日志监控还有多少客户端在使用：

public String getOldField() {
    log.warn("Deprecated field 'oldField' accessed, please migrate to 'newField'");
    DeprecationMetrics.recordAccess("oldField");
    return newField;
}

第三阶段：默认返回null，准备移除

public String getOldField() {
    // 不再返回实际值，而是null
    // 但还没有移除字段，防止客户端报错
    return null;
}

六个月后，如果监控显示没有客户端再访问这个字段，我们才在下一个大版本中移除它。

第五章：版本演进的实际案例

让我用一个具体的例子展示我们的完整流程。假设我们要改进“获取用户列表”API。

初始版本（v1）

// v1：简单分页
@GetMapping("/users")
public List<UserV1> getUsersV1(
    @RequestParam int page,
    @RequestParam int size) {
    
    Page<User> users = userService.getUsers(page, size);
    return users.map(userApiAdapter::toV1);
}

需求：v2需要更灵活的分页和过滤

错误的做法（很多人这么干）：

// 错误：直接修改v1接口
@GetMapping("/users")
public List<UserV2> getUsersV2(
    @RequestParam int page,
    @RequestParam int size,
    @RequestParam(required = false) String nameFilter, // 新增参数
    @RequestParam(required = false) String roleFilter, // 新增参数
    @RequestParam(defaultValue = "id") String sortBy) { // 新增参数
    
    // 完全重写的业务逻辑...
}

这会破坏所有v1的客户端。

我们的做法：

1. 保持v1完全不变
2. 创建v2的新端点（注意：不是修改v1，而是新增）

@GetMapping("/api/v2/users")
public PageResponse<UserV2> getUsersV2(
    @ModelAttribute UserQuery query) { // 使用查询对象，更灵活
    
    Page<User> users = userService.getUsers(query.toPageable());
    return PageResponse.from(users.map(userApiAdapter::toV2));
}

3. 在服务层共享逻辑

@Service
public class UserService {
    
    // v1和v2共享的业务逻辑
    public Page<User> getUsers(int page, int size) {
        return getUsers(UserQuery.builder()
            .page(page)
            .size(size)
            .build());
    }
    
    // v2使用的增强逻辑
    public Page<User> getUsers(UserQuery query) {
        Specification<User> spec = buildSpecification(query);
        return userRepository.findAll(spec, query.toPageable());
    }
    
    // 构建查询条件（v2新增的功能，v1不需要）
    private Specification<User> buildSpecification(UserQuery query) {
        return (root, criteriaQuery, cb) -> {
            List<Predicate> predicates = new ArrayList<>();
            
            if (query.getNameFilter() != null) {
                predicates.add(cb.like(root.get("name"), "%" + query.getNameFilter() + "%"));
            }
            
            if (query.getRoleFilter() != null) {
                predicates.add(cb.equal(root.get("role"), query.getRoleFilter()));
            }
            
            return cb.and(predicates.toArray(new Predicate[0]));
        };
    }
}

4. 适配器处理响应差异

public class UserApiAdapter {
    
    // v1响应：简单列表
    public List<UserV1> toV1List(Page<User> users) {
        return users.getContent().stream()
            .map(this::toV1)
            .collect(Collectors.toList());
    }
    
    // v2响应：包含分页信息
    public PageResponse<UserV2> toV2Page(Page<User> users) {
        return PageResponse.of(
            users.getContent().stream()
                .map(this::toV2)
                .collect(Collectors.toList()),
            users.getTotalElements(),
            users.getTotalPages(),
            users.getNumber(),
            users.getSize()
        );
    }
}

这样的好处：

• v1客户端完全不受影响
• v2客户端获得新功能
• 业务逻辑最大程度复用
• 当v1最终被废弃时，只需删除v1的端点和适配器，业务逻辑仍然保留

第六章：工具和自动化

手动维护版本兼容性容易出错，我们建立了一些自动化工具。

6.1 API契约测试

使用OpenAPI和契约测试，确保每个版本的API都符合约定：

@SpringBootTest
public class UserApiContractTest {
    
    @Test
    public void v1_contract_should_be_stable() {
        // 自动生成v1的OpenAPI文档
        String currentSchema = generateOpenApiSchema("v1");
        
        // 与已保存的契约对比
        String savedSchema = loadSavedSchema("user-api-v1.json");
        
        assertThat(currentSchema).isEqualTo(savedSchema);
    }
    
    @Test 
    public void v2_should_include_all_v1_fields() {
        // 验证v2响应包含所有v1字段
        UserV2Response v2Sample = createSampleV2Response();
        UserV1Response v1Sample = adapter.toV1(v2Sample.toUser());
        
        // 使用反射检查所有v1字段在v2中都有对应
        assertAllV1FieldsPresentInV2(v1Sample, v2Sample);
    }
}

6.2 版本兼容性检查器

我们写了一个简单的注解处理器，在编译时检查版本兼容性：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface ApiVersionCompatibility {
    String since() default "v1";
    String until() default "";
}

// 使用示例
@ApiVersionCompatibility(since = "v1", until = "v3") // v1引入，v3废弃
public class UserResponse {
    @ApiFieldCompatibility(since = "v1")
    private Long id;
    
    @ApiFieldCompatibility(since = "v1", until = "v2") // v1引入，v2重命名
    private String name;
    
    @ApiFieldCompatibility(since = "v2") // v2新增
    private String username;
}

编译时检查器会确保：

• 没有字段在声明支持的版本中被删除
• 字段的语义变更被正确标记
• 废弃时间符合规则

6.3 客户端使用分析

我们在网关层加了简单的日志，记录每个API端点的版本使用情况：

@Component
public class ApiVersionFilter implements GlobalFilter {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getPath().value();
        String version = extractVersionFromPath(path); // 从路径提取版本
        
        // 记录指标
        metrics.recordApiCall(path, version);
        
        return chain.filter(exchange);
    }
}

每月分析一次，决定哪些旧版本可以安全废弃。

第七章：平衡的艺术

经过三年的实践，我们最终找到了自己的平衡点：

7.1 何时创建新版本？

我们的决策树：

1. 如果是字段添加 → 直接添加，不创建新版本
2. 如果是字段删除或重命名 → 标记废弃，考虑下个大版本移除
3. 如果是结构重大变化 → 创建新版本
4. 如果是业务逻辑变化导致行为不一致 → 创建新版本

7.2 维护多少个版本？

我们的策略是：N-2。

• 当前主要支持版本：最新版本（N）
• 仍然支持的旧版本：N-1
• 即将废弃的版本：N-2（只修复严重bug）
• 更旧的版本：已废弃，文档保留但不再支持

7.3 代码组织

src/main/java/com/example/
├── domain/              # 领域模型（无版本概念）
│   ├── User.java
│   └── UserService.java
├── api/
│   ├── v1/              # v1 API适配层
│   │   ├── UserV1Controller.java
│   │   ├── UserV1Response.java
│   │   └── UserV1Adapter.java
│   ├── v2/              # v2 API适配层
│   ├── shared/          # 版本共享组件
│   └── adapter/         # 版本适配器
└── config/
    └── ApiVersionConfig.java # 版本路由配置

结语：版本化是一种沟通，而不是隔离

三年前，我以为API版本化是技术问题。三年后，我明白了它本质上是沟通问题。

• 与过去版本的沟通（兼容性）
• 与现在版本的沟通（清晰性）
• 与未来版本的沟通（扩展性）

我们最终选择的这条路，其实是在说：“我们尊重已经存在的约定，但我们也要向前走。我们会带上愿意跟我们走的人，但不会突然甩开那些还在原地的人。”

这需要技术决策，但更需要同理心——理解客户端升级的困难，理解业务需求的紧迫，理解代码维护的成本。

现在，当我再看到那个登录接口时，我不再想着“怎么改它”，而是想：“怎么在保持它工作的同时，提供更好的选择？”

这就是我们的出路：不是粗暴地切断过去，也不是僵化地固守现在，而是在时间的河流中，架起一座座桥梁，让改变可以平缓地发生。

API版本化的最高境界，是让变化发生得如此自然，以至于使用者几乎察觉不到断裂，只觉得一切都在变得更好。

而我们作为API的设计者，就是那个在幕后搭桥的人。