接口设计是一场博弈。你写下的每一个方法签名，都在向未来传递一个不可撤回的承诺。维护业务接口的真正难点，不在于让今天的代码跑通，而在于让三个月后的另一个开发者（很可能是你自己）不会对着你的签名骂街。Java开发者常有一种错觉：只要把字段封装成POJO、把逻辑拆进Service，接口就“设计好了”。但业务接口的腐烂，往往从第一次“加一个参数”开始。那个被反复追加的userId、status、extraMap，就像墙上的裂纹，等你想修补时，整面墙已经快塌了。

接口是合同，不是工具

很多人把接口当成“调用工具”，想怎么加方法就怎么加，想怎么改参数就怎么改。每个公共方法都是一份具有法律效力的合同，一旦发布，你就欠下了兼容性的债。业务接口尤其如此——调用方可能是内部其他团队，可能是外部系统，甚至可能是凌晨三点线上告警时手忙脚乱的运维脚本。合同思维要求你先把“谁在调用、何时调用、调用失败时怎么办”想清楚，再落笔写签名。

一个接口的签名，就是你对调用方做出的一组承诺：输入什么、输出什么、抛出什么异常、保证什么副作用。比如OrderService.pay(Long orderId, BigDecimal amount)，你承诺了orderId存在、amount为正、支付成功返回true，否则抛异常。如果某天你想加上“支付渠道”参数，直接改签名就是单方面撕毁合同。优雅的做法是新增一个PaymentRequest对象，或者干脆新增一个方法payWithChannel(...)，旧方法保留并委托给新方法。永远不要为了“反正内部调用”而随意改动签名——内部接口的兼容性债，比外部接口更难还，因为没人逼你做版本管理。

参数对象：隐形的债务契约

业务接口的参数列表是重灾区。void updateUser(String id, String name, Integer age, String address, String phone, String email)——这种签名看起来直白，实则灾难。调用方永远搞不清第4个参数是address还是phone，IDE的提示也救不了人。参数超过三个，就应该考虑封装成对象，这不是教条，而是认知负担的物理定律。人的工作记忆只能同时处理大约七个信息块，六个裸参数直接让调用方大脑过载。

更关键的是，参数对象是扩展的缓冲垫。你定义一个UpdateUserRequest，里面放上name、age、address，未来加一个nickname字段，只需要在Request里加属性，接口签名纹丝不动。这就是“开闭原则”在接口层面最朴素的体现：对修改关闭，对扩展开放。但注意，参数对象不能沦为“垃圾桶”。很多开发者图省事，直接定义一个Map<String, Object>传进去——这等于把合同撕了，改成“你猜”。调用方看到Map，就像收到一份没有目录的合同，每个key都可能是坑。优雅的参数对象应该具有显式的字段名、类型、校验注解，最好还有默认值。比如@NotNull标记必填字段，@Size(max=50)限制长度，这样接口自带了约束说明。

子标题：返回值，别让调用方拆盲盒

Object、Map、List<Map<String, Object>>——这类返回值是接口设计的另一大毒瘤。业务接口的返回值必须是确定的、结构化的、可预期的。你返回一个Map，等于把解析逻辑甩给调用方，让他们去猜“key到底是userName还是username”。更糟的是，某些接口返回null表示“查不到”，返回空List表示“没有列表”，但调用方常常忘了判null，NPE就在线上炸了。

优雅的做法是：要么返回Optional，要么返回明确的对象，要么返回一个封装了状态码和数据的Result。但别过度设计。如果是简单的查询，返回Optional<User>是合理的；如果是分页查询，返回PageResult<User>包含total、list；如果可能发生业务失败（比如余额不足），那就应该用异常或者一个带错误码的Response。关键在于，返回值要消除歧义，让调用方不需要读文档就能知道怎么处理。有一种丑陋的折衷是boolean返回——boolean updateStatus(...)，调用方看到false，不知道是参数非法、记录不存在还是更新失败。boolean是接口界的“薛定谔的猫”，不打开看永远不知道答案。不如返回UpdateResult，里面带上成功标志和失败原因。

版本策略：与其美化，不如明确淘汰

很多团队回避接口版本管理，觉得“反正我们自己人用”。但业务接口的演化是必然的。优雅的接口设计，不是在每个方法名后面加V2、V3，而是建立清晰的版本规则。常见的做法是URL路径带版本，如/api/v1/orders、/api/v2/orders；或者Header里带版本号。但更重要的是语义化版本：大版本号变表示不兼容变更，小版本号变表示向后兼容的扩展。一旦发布v1，就不要轻易改v1的行为，哪怕你觉得“调一下参数校验应该没事”。

真正见功底的地方在于“优雅地废弃旧接口”。不要直接删掉方法，那是在逼调用方紧急升级。应该标注@Deprecated，并在文档里写明“请使用newMethod替代”。在Java中，@Deprecated不仅是个注解，更是一种社交礼仪——告诉别人这里新路已通，旧路即将关闭，但给你留了缓冲期。同时，内部接口的版本管理要用代码约束，而不是靠开发者的记性。比如在接口发布时，用ArchUnit写个测试，禁止任何人直接修改已发布接口的签名，只能新增方法或新增版本。这样就把“契约保护”从口头承诺上升到了自动化防线。

子标题：异常，也是接口的一部分

业务接口的异常设计往往被忽视。很多开发者习惯抛通用的Exception或者RuntimeException，调用方只好catch(Exception e)，然后一脸懵。异常是接口的暗语——你抛什么异常，就是在告诉调用方“这里可能出哪种问题”。优雅的业务接口应该定义一套业务异常体系，比如BizException携带错误码和错误信息，NotFoundException、ConflictException等继承自它。调用方看到异常类型，几乎不需要读消息就能知道该怎么处理：重试、转人工、还是直接提示用户。

更高级的做法是，接口上声明受检异常（checked exception）——但很多人避之不及。其实受检异常的价值在于强迫调用方处理。如果调用方真的无法处理，他可以选择捕获并包装成运行时异常。但如果你不声明，调用方根本不知道还有这回事。平衡点在于：可恢复的失败用受检异常，不可恢复的编程错误用运行时异常。但业务接口中，大部分失败（如余额不足、库存不够）都是可恢复的——调用方可以捕获后返回友好的提示。所以别怕受检异常，它让接口合同写得更明白。同时，避免异常吞噬。在catch里打一行日志然后返回null，是最破坏接口契约的行为之一——你让调用方得到了一个假装的“成功”。

文档与自描述：接口的“用户体验”

业务接口的维护，不仅靠代码，还靠文档。但传统Javadoc往往写不全，或者写完了代码已经改了十遍。最好的文档是让接口本身让人一看就懂。方法命名、参数命名、封装类型、校验注解，这些本身就是文档。Java的类型系统是强大的表达工具：Optional<User> findById(Long id)比User findUser(Long id)更明确；void submit(OrderSubmitRequest request)比void submit(Map param)更安全。

但同时，规范化的Javadoc仍然必要，因为它能记录“为什么”。比如方法createOrder，注释里写“注意：如果订单金额超过1万，需要先走风控审核” —— 这种信息类型系统表达不出来，但调用方必须知道。别小看“@throws”标签，它是在接口合同里注明“可能出现的违约情形”。当调用方看到@throws InventoryInsufficientException，他立刻明白要处理这个分支。

另一个被低估的自描述技术是用注解来表达约束。比如在参数对象上使用@Valid和@NotNull、@Size，在方法上使用@PreAuthorize（Spring Security）声明权限。这样接口的“使用条件”就显式地写在签名旁了，而不是埋在方法体里。调用方不用看实现，就知道“必须有管理员权限才能调用这个接口”——这就是优雅的合同。再进一步，可以用Spring REST Docs或OpenAPI注解，把接口的示例请求/响应生成到文档中，让契约有一个可执行的样本。

演进：为“变更”而设计，而不是为“现状”

最后，最优雅的接口设计不是面向未来一步到位，而是面向变更保持灵活性。业务需求永远在变，你不可能预知一切。所以接口设计的关键，不是试图猜中所有变化，而是确保当变化来临时，你可以以最小的代价修改接口而不破坏现有调用方。技巧包括：

避免暴露内部实现细节。例如，不要返回JPA实体类，那会把持久层映射直接变成接口契约，一旦表结构调整，接口就崩了。

使用DTO（数据传输对象）作为接口的边界。DTO和领域模型分离，是业务接口维护的经典解法。实体类用来操作数据库，DTO用来对外通信，两者互不影响。

保持接口方法粒度适中。太粗的接口（一个方法做所有事）难复用，太细的接口（一个字段一个getter）难组合。好的粒度是“一个业务动作对应一个方法”，比如payOrder、cancelOrder，而不是doOrder。

学会优雅地拒绝新需求。当产品经理说“顺便加个参数”，你要反问：“这个参数是为了新业务，还是补旧逻辑？能不能做成新接口？”接口设计者的核心职责之一，就是保护现有合同的稳定性，懂得说“不”比懂得说“是”更重要。当然，说“不”之后要给出替代方案——新增一个版本，或者扩展一个字段。

维护业务接口的终极准则：像设计公共API一样对待每一个内部接口。哪怕只有一个调用方，也假设未来会有十个不同的调用方。有了这种心态，你自然会追求清晰的命名、明确的结构、稳健的版本策略和诚实的异常设计。接口是你的代码与他人的代码之间的桥梁，优雅的桥梁不应该摇摇欲坠，而应该在岁月的荷载下依然坚固。每一次你写下public interface，其实都在给未来的自己写一封信——你想收到一封布满歧义的信，还是一封结构化、有注释、有过期提示的明信片？

真正难的不是写代码，而是让接口在五年后依然能让人一眼看懂。所以，下次你要改一个已有的方法签名时，停三秒，问问自己：这是扩展，还是破坏？如果你答不上来，那就去新建一个接口吧。优雅不是设计出来的，而是在拒绝不优雅的变更中，一笔一笔雕刻出来的。业务接口的维护，最终拼的不是技术，而是你对未来的敬畏心。