小重构，大收益！技术重构实践：如何优雅升级老旧接口

重构格言："优秀系统不是设计出来的，而是通过持续重构演进而来的。"
—— Martin Fowler《重构：改善既有代码的设计》

希望本文能为您的重构之旅提供指引，让老旧系统焕发新生！

一、背景：一个“稳定”接口的隐患

下面WEB控制器方法，是我们历史悠久的短信服务（SMS）里的短信发送接口。

1. @RestController
2. @RequestMapping({"/smsSend", "/sendSms"})
3. public class SmsSendController {
5.     @GetMapping
6.     @PreventDuplicateRequest(key = "SmsSendController_smsSend", spEL = "{#phones, T(com.sms.common.utils.MD5Util).getMD5(#content)}", expireSeconds = 5)
7.     public String smsSend(@RequestParam("account") String account,
8.                           @RequestParam("sign") String sign,
9.                           @RequestParam("mphone") String phones,// 多个用逗号分隔
10.                           @RequestParam("content") String content) {
11.         return sendSms(account, sign, phones, content);//"SUCCESS" + msgIds.substring(0, msgIds.length() - 1);
12.     }
13. }

复制代码

这个接口是在若干年前开发的，彼时，大家技术能力有限。
该接口响应格式简单粗暴——成功时返回 SUCCESS 拼接消息ID，失败时直接返回错误原因字符串。例如：

1. SUCCESS123456,789012  // 成功示例
2. 短信账户密码错误        // 失败示例

复制代码

这种设计在早期快速迭代阶段勉强可用，但随着系统复杂度提升，其弊端日益凸显：

• 客户端解析困难：需通过字符串前缀匹配判断成功与否，易因格式微调引发故障
  
• 可观测性差：缺乏唯一请求标识，排查问题如大海捞针
  
• 扩展性受限：无法携带额外数据（如运营商回执、计费信息）
  

为此，我决定做一个小小的升级，同时要兼容当前响应值。
我们计划使用 Result 对象来实现相应结构的标准化，即 code/msg/data 的形式，符合RESTful API的最佳实践。例如：

1. // 错误响应
2. {"reqId":"a369331163aba36","message":"短信账户错误","code":500,"data":null,"timestamp":1745285069433,"success":false}
3. //成功响应
4. {"reqId":"a6a0bb2f83844d9","message":"发送成功","code":200,"data":["2504223325367695"],"timestamp":1745285136909,"success":true}

复制代码

二、重构目标：鱼与熊掌兼得

怎么进行这项代码重构呢？

• 为该接口增加版本号参数，不同版本响应值不同。
  
• 改造现有WEB控制器方法的返回值。原先返回 String， 变更这个返回值。
  
• 这个API方法所调用的 sendSms，变更其返回值，以明确方法职责。
  

1. @RestController
2. @RequestMapping({"/smsSend", "/sendSms"})
3. public class SmsSendController {
5.     @GetMapping({"/{version}", ""})
6.     @PreventDuplicateRequest(key = "SmsSendController_smsSend", spEL = "{#phones, T(com.sms.common.utils.MD5Util).getMD5(#content)}", expireSeconds = 5)
7.     public Object smsSend(@RequestParam("account") String account,
8.                           @RequestParam("sign") String sign,
9.                           @RequestParam("mphone") String phones,// 多个用逗号分隔
10.                           @RequestParam("content") String content
11.             , @PathVariable(value = "version", required = false) String version) {
12.         Result<List<String>> listResult = sendSms(account, sign, phones, content);
13.         if ("v2".equals(version)) {
14.             // v2版本返回值
15.             listResult.setReqId(MDC.get("traceId"));
16.             return listResult;
17.         } else {
18.             // v1版本返回值
19.             if (listResult.isSuccess())
20.                 return "SUCCESS" + String.join(",", listResult.getResult());
21.             else
22.                 return listResult.getMessage();
23.         }
24.     }
25. }

复制代码

三、重构收益：从能用走向好用

1. 响应结构标准化

• 可维护性提升：统一使用 Result 结构体，符合 RESTful 设计规范
  
• 错误处理增强：Result 中的 code 和 success 字段使调用方能够通过统一逻辑处理成功与失败场景（如 if (result.isSuccess())），避免了旧版中依赖字符串内容（如判断是否以“SUCCESS”开头）的脆弱逻辑。同时，精准错误码也可指导用户处理（如 code=501 提示账户余额不足）
  
• 显著降低客户端使用成本：相比原始的“SUCCESS+ID”或“错误字符串”，调用方无需通过字符串解析逻辑（如前缀匹配、异常分支判断）即可快速识别请求结果
  

2. 版本兼容性设计

实现方式：

1. @GetMapping({"/{version}", ""})
2. public Object smsSend(..., @PathVariable String version) {
3.     if ("v2".equals(version)) { /* 新版本逻辑 */ }
4.     else { /* 旧版本兼容 */ }
5. }

复制代码

• 平滑升级：通过兼容新旧版本共存，旧客户端无需立即改造，避免“一刀切”式升级带来的兼容性风险。
  
• 灰度发布能力：通过 URL 路径控制新老版本流量比例
  

3. 请求追踪集成

• 日志可追溯：通过 reqId 快速关联请求全链路日志
  
• 调试效率提升：快速定位具体请求的服务器处理线程，故障定位时间缩短 70%
  

4. 底层逻辑与接口解耦

• 统一内部返回类型：将 sendSms 方法的返回值从原始字符串改为 Result，使底层逻辑专注于业务处理（生成标准化结果），而控制器层仅负责“按版本格式化响应”，减少了控制器中的条件判断逻辑，符合“单一职责原则”。
  
• 隔离版本差异逻辑：版本相关的响应转换（如旧版字符串拼接、新版 Result 装配）集中在控制器层，底层服务（如 sendSms）和 Result 模型保持无版本依赖，便于后续扩展更多版本（如 v3、v4）而不影响核心逻辑。
  

四、总结

小重构，大收益！
本次小重构通过版本化路径设计和响应格式分层兼容，在不破坏现有调用的前提下实现了接口的标准化升级，显著提升了接口的可维护性、调用方体验和错误处理能力。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！