Spring Boot接口设计：saveOrUpdate合并写的利弊与业务迭代陷阱

在开发Spring Boot后台应用时，一个常见的设计争议是：新增（Create）和修改（Update）操作，应该合并为一个saveOrUpdate接口，还是拆分为两个独立的接口？

项目初期，拆分似乎理所当然。但随着功能增多，要求“合二为一”以简化代码和前端调用的声音会逐渐出现。于是，代码中开始出现如下模式：

public void saveOrUpdate(PetDTO dto) {
    if (dto.getId() == null) {
        // 新增逻辑
    } else {
        // 修改逻辑
    }
}

这种写法看似简洁高效，却常常为项目后期的维护埋下隐患。

一、问题的本质：业务阶段演进

这并非简单的编码风格问题，而是一个业务阶段问题。
在项目早期，功能简单、字段少、校验逻辑单纯，saveOrUpdate确实能提高开发效率。
然而，随着业务复杂化，新增与修改的需求差异会日益明显：

• 新增：需关注数据唯一性、初始化状态、默认值填充。
• 修改：需确保数据存在、验证当前状态是否允许变更、控制特定字段的修改权限。

此时，是否拆分接口，将直接决定后续80%的维护成本。

二、合并写（saveOrUpdate）的典型问题

1. 校验逻辑混杂与膨胀

新增和修改的校验关注点截然不同。合并后，方法内势必充斥大量的条件判断：

if (dto.getId() == null) {
    // 执行新增校验：必填项、唯一性等
} else {
    // 执行修改校验：数据存在性、状态流转约束等
}

当校验规则持续增加，该方法会迅速变得臃肿且难以阅读。

2. 接口语义与参数含义模糊

合并接口导致单个参数在不同场景下含义不清。例如，某个字段在新增时必填，但在修改时禁止更新。为了处理这种情况，代码中不得不引入更多基于id是否存在的条件分支，使得接口契约变得不清晰。

3. 前端调用心智负担加重

对前端而言，合并接口未必更友好。开发者必须明确知晓：何时传id、哪些字段传了无效、哪些字段传了会触发错误。表面上的接口简化，实际上增加了调用方的理解和调试成本。

三、拆分写的核心价值：隔离业务生命周期

拆分的意义远不止于代码“清晰”，其核心价值在于强制分离处于不同生命周期的业务逻辑。

1. 新增接口 (create)：核心关注“创建”的合法性。

   • 能否创建？
   • 初始状态是什么？
   • 是否与现有数据冲突？

     public void create(CreatePetDTO dto) {
     // 纯粹的新增逻辑
     }

2. 修改接口 (update)：核心关注“变更”的合法性与约束。

   • 目标数据是否存在？
   • 当前状态是否允许修改？
   • 哪些字段允许被更新？

     public void update(UpdatePetDTO dto) {
     // 纯粹的修改逻辑
     }

将这两件本质不同的事情分开处理，符合单一职责原则，能显著提升代码的长期可维护性。

四、何时可以考虑合并写？

并非所有场景都必须拆分。在以下情况下，合并写是可以接受的折中方案：

1. 非核心或工具型功能：如内部配置表、简单的数据字典等。
2. 结构极其稳定的简单实体：字段很少（如3-5个），几乎没有业务校验和状态流转。
3. 明确无扩展预期的功能：能够确定该功能在未来不会变得复杂。

五、工程化折中方案：接口分离，逻辑复用

许多成熟项目采用一种更稳妥的模式：对外暴露语义清晰的独立接口，在内部复用核心处理逻辑。

public void create(CreatePetDTO dto) {
    doSaveOrUpdate(dto, true);
}

public void update(UpdatePetDTO dto) {
    doSaveOrUpdate(dto, false);
}

private void doSaveOrUpdate(BasePetDTO dto, boolean isCreate) {
    // 提取公共的保存或更新逻辑，根据isCreate标志位执行差异化校验或操作
}

这种方式兼顾了接口的清晰性和代码的复用性，在SpringBoot项目中是一种值得推荐的实践。

六、一个实用的决策标准

如果难以抉择，可以使用这个简单的标准进行判断：
新增与修改操作，对数据的“约束条件”是否完全一致？

• 一致 → 可以考虑合并。
• 不一致 → 强烈建议拆分。

这条准则在实践中具有很高的指导性。

七、总结：为未来预留设计空间

许多项目后期的混乱，根源往往在于早期将不同生命周期的业务逻辑塞进了一个“万能接口”。新增与修改是否拆分，不是一个简单的编码偏好问题，而是是否愿意为未来的业务变化预留设计空间的考量。前期为了省几行代码而做的合并，往往会在系统迭代时，以更高的bug修复成本和更重的认知负担偿还。