契约优先的模块解耦设计

在一个多模块系统中，比如“订单模块”创建订单时需要读取“用户模块”的用户昵称和账户余额。一开始我想得很直接：既然用户模块已经有 UserEntity，那我直接依赖它，用它的实体去查询不就行了？

当时看起来开发效率很高，但问题很快显露出来：如果用户模块后续因为业务调整修改了实体字段或数据库结构，订单模块就会直接受到影响，甚至无法正常运行。更麻烦的是，用户模块在做某些统计时也可能反过来调用订单模块的一些接口，于是两个模块之间产生了双向依赖。

这样一来，谁都离不开谁，单独维护、重构或迭代其中任意一个模块都会变得困难，整个系统开始变得脆弱。那一刻我意识到，我们表面上在拆分模块，但实际却让模块彼此深度耦合，甚至互相牵制。

1. 模块耦合问题初现

graph LR
    A[订单模块 Order] -->|直接依赖内部实体| B[用户模块 User]

在这种设计中，订单模块直接依赖用户模块的内部实体或数据库结构，看似简单直接，但已经埋下了高耦合风险：

用户模块的实体字段一旦调整，订单模块必须同步修改；
即使只想单独测试订单模块，也必须准备好用户模块或提供对应数据结构；
模块之间逐渐形成隐形的强绑定关系，缺乏清晰边界。

当业务继续演进，比如用户模块也开始调用订单模块的接口进行下单分析或积分统计时，这种单向依赖会进一步演化为双向依赖：

graph LR
    A[订单模块 Order] --> B[用户模块 User]
    B --> A

一旦出现这种双向依赖，问题将升级为循环依赖，它不仅限制了模块的独立性，还会导致编译、Bean 装配、版本管理等方面变得复杂甚至无法通过。

此时的问题不在于功能无法实现，而是模块开始基于对方的内部结构协作，缺乏稳定的交互边界，一旦这种模式继续下去，后续想要解耦的成本会越来越高。

2. 为什么内部结构不应该成为模块依赖点

在前面的场景中，订单模块之所以对用户模块产生高耦合，是因为它直接依赖了用户模块的内部实体对象或持久化结构。这种“实体直依方式”虽然开发效率高，但从模块边界的角度来看，它存在天然缺陷：

一个模块一旦依赖另一个模块的内部结构，就等于将对方数据库模型、字段变更、业务演进全部强行暴露给调用方。

这种暴露并非建立在业务契约之上，而是基于“我知道你内部怎么实现，所以我就直接拿来用”。

这意味着：

用户模块设计的任何字段，都被订单模块视作可被长期依赖的“稳定事实”；
用户模块维护人员在设计字段时不得不顾虑订单模块的使用场景；
模块之间不再是“能力协作”，而变成“结构共享”；
一旦多个模块都开始以这种方式互相依赖内部结构，系统整体将缺乏演化弹性。

换句话说，这种依赖方式实际上让两个模块变成了“同一代码片段的延伸”，而不是“两个关注点明确的独立模块”。

进一步来看：

模块协作方式	依赖的对象	协作边界	调用方是否感知对方实现	变更影响传播
基于实体依赖	内部结构（Entity）	不清晰	完全感知	极强
基于契约依赖	对外能力（接口 + DTO）	明确	只知道其输出与行为	可控

模块协作的本质应该建立在“能力”和“业务语义”的基础上，而不是共享内部结构。当模块暴露的是结构而非能力时，调用方依赖的是实现而不是契约，这种关系必然是不稳定的。

因此，为了让模块之间的协作更加可控、演化更加安全，就需要将协作模式从“实现依赖”转变为“契约依赖”。

3. 从实现依赖到契约依赖

在前面的分析中，问题的根源并不是“一个模块调用另一个模块”这种行为本身，而是调用过程依赖的是对方的内部实现。模块之间并非不能互相调用，但调用关系必须建立在一种“稳定的协作规则”之上，而不是依赖“实现细节”存在。

于是思路开始发生转变：

原始想法	后续反思
我需要用户信息 → 直接引用 `UserDomain` 去查	我只是需要“用户展示信息”或“账户状态”
实体已存在，用它最快	实体属于内部模型，不适合作为对外表达
模块之间共享实体可以减少重复代码	实际上增加了演进成本和模块耦合
只要通过就行，跑得动就够了	后期维护与演进时的压力最终会反噬开发效率

这个过程中，我逐渐意识到一个变化：

我不应该“拿对方内部结构来完成我的需求”
我应该“请求对方提供一种抽象后的稳定能力”

这意味着，合作的方式不应是“我来理解你内部怎么存储用户信息”，而应该是“你提供一种能力，返回我所需要的数据格式”。

于是，协作模式开始发生角色变化：

阶段	调用方式	依赖对象	谁主导协作
原始	直接使用对方实体	内部模型	调用方理解对方实现
演进	请求对方能力	输入/输出契约	被调用方承诺其能力

这标志着模块间的协作方式，从“实现导向”走向“契约导向”。

换句话说：

我不再依赖“你的内部怎么表示用户”；
我依赖“你愿意对外承诺什么信息”；
这种承诺即为“契约（Contract）”。

4. 契约如何被抽象

当模块协作从“实现依赖”转向“契约依赖”时，我们需要回答一个工程问题：

契约具体表现为什么？

在软件工程中，一个可执行、可维护、可测试的契约，通常由两部分共同构成：

组成部分	作用	举例
接口（Interface）	定义“能力”与“行为的入口”	`UserQueryService#getUserOverview(String userId)`
DTO（数据传输对象）	定义“调用的输入/输出数据结构”	`UserOverviewDTO`

在这种模式下，一个模块不会暴露自己的内部实体，而是通过一组明确的接口来表达它能为外部提供的“业务能力”，而 DTO 则是双方共同认可的“数据表达格式”。

举例：

public interface UserQueryService {
    UserOverviewDTO getUserOverview(String userId);
}

public class UserOverviewDTO {
    private String nickname;
    private BigDecimal accountBalance;
}

对比传统“实体直依”方式：

方式	特点	风险
直接依赖 `UserEntity`	少写代码，开发快	`UserEntity` 字段变更 → 影响调用方
使用 `UserOverviewDTO`	返回值稳定，表达清晰	DTO 新增字段通常对调用方无破坏性

通过接口与 DTO 的组合，模块之间建立的依赖变成“业务级的承诺”，而非“数据库结构级的绑定”。

换句话说，接口描述“能做什么”，DTO描述“返回什么”，而具体“怎么查”则完全属于模块内部实现，不需要暴露给调用方。

5. 契约如何被实现

在理解“契约 = 模块之间的能力承诺”之后，接下来的问题就变成了：在实际工程中，我们应如何实现这个契约，使其被可靠调用、可维护、可演化？ 这需要从契约的放置位置、实现方式，以及调用方式三个维度进行工程化拆解。

5.1 契约应该放在哪个模块？

在一个标准的多模块项目中，契约应当位于一个独立于实现逻辑的共享层中，让调用方与实现方都能面向同一个契约依赖。

常见的契约放置方式对比如下：

放置方式	特点	问题	是否推荐
放在被调用模块内部（如用户模块）	代码集中	调用方必须依赖实现模块，导致反向耦合	❌
调用方自己定义接口	无法保证双方达成一致	契约容易偏离真实能力	❌
独立抽取到公共契约模块（API层）	调用方和提供方共同依赖	契约独立演进，可复用	✅

因此，常见做法是在多模块工程中新增一个 xxx-api 或 xxx-contract 模块，如：

project-parent
│
├─ project-user-api       // 契约定义模块（接口 + DTO）
├─ project-user-service   // 用户模块实现
├─ project-order-service  // 订单模块调用

5.2 契约接口与 DTO 的组织方式

在契约模块中，通常会包含以下内容：

project-user-api
│
├─ dto/
│  └─ UserOverviewDTO.java
└─ service/
   └─ UserQueryService.java

契约层应具备以下特征：

项目	要求
DTO	保持与具体业务场景相关，避免携带内部模型字段
接口	清晰描述能力，如 `getUserOverview(String userId)`
命名	推荐使用 `{领域名}{动作或查询类型}Service`
稳定性	避免频繁变更方法签名，字段新增优于替换

5.3 在实现模块中提供契约能力实现

在原用户模块中实现该契约：

@Service
public class UserQueryServiceImpl implements UserQueryService {

    @Override
    public UserOverviewDTO getUserOverview(String userId) {
        // 内部查询获取实体
        UserEntity entity = userRepository.findById(userId);

        // 转换为契约DTO
        UserOverviewDTO dto = new UserOverviewDTO();
        dto.setNickname(entity.getNickname());
        dto.setAccountBalance(entity.getBalance());
        return dto;
    }
}

注意：实现层中仍有内部实体和逻辑，但它不会泄露到调用方模块。

5.4 在调用方（如订单模块）中依赖契约并调用

调用方只依赖 project-user-api，无需依赖 project-user-service。

@Service
public class OrderCreateService {

    private final UserQueryService userQueryService;

    public OrderCreateService(UserQueryService userQueryService) {
        this.userQueryService = userQueryService;
    }

    public void createOrder(String userId) {
        UserOverviewDTO userInfo = userQueryService.getUserOverview(userId);
        // 根据用户信息进行订单创建逻辑
    }
}

此时，订单模块完全基于能力协作，而不是解析用户模块的内部模型。

5.5 在微服务场景中如何实现契约

当模块拆分为独立服务后，契约仍然存在，但需要通过网络层调用实现。例如：

RPC方式	契约表现	实现方式
OpenFeign/REST	`@FeignClient` 接口 + DTO	将接口变为远程代理
Dubbo	接口 + 序列化DTO	注册中心发布能力
gRPC	`.proto` 文件即契约	自动生成 Stub

例如使用 OpenFeign：

@FeignClient(name = "user-service")
public interface UserQueryClient {
    @GetMapping("/user/{id}/overview")
    UserOverviewDTO getUserOverview(@PathVariable String id);
}

被调用方的能力实现依然类似于 Service 实现，只不过对外暴露为 HTTP 或 RPC。

5.6 契约升级与兼容策略

在契约变更时，应遵循以下演进原则：

修改类型	是否破坏性	策略
DTO新增字段	否	允许直接加字段
DTO删除字段	是	需版本升级
方法签名修改	是	建议新增方法，旧签名逐步废弃
新增接口能力	否	不破坏现有调用

推荐做法：

避免直接修改已有方法参数结构；
保留旧方法，逐步引导改造；
若新增更大契约块，可以新增 V2 接口。

好的，以下是经过重新组织、风格更自然、更收束、更贴近你认可的“理性工程化语境”的新版第 6 和第 7 节内容 ✅——无需再拆小节，也不再进行“教科书式列点”，而是以一种“我们走过前面过程后的总结式复盘”方式输出。

6. 契约优先设计的结构收益与演化价值

在完成契约抽象与工程实现后，模块之间的协作模式已经发生了本质变化。如果说原来的调用关系是一种“我知道你的内部结构，所以我能自己查到需要的数据”，那么契约优先的模式则转变为“我不关心你内部是如何组织的，只要你提供我需要的能力即可”。

这种变化最关键的收益在于：模块之间的依赖从“绑定实现”变成了“面向能力合作”，从而让系统具备了更强的稳定性和可演化性。

在以往直依实体的模式中，一旦某模块的实体结构发生变化（例如字段改名、表结构调整、领域模型重构等），所有依赖该模块的其他模块都可能受到影响，导致变化被迫横向扩散。而在契约优先模式下，只要接口与 DTO 的契约保持不变，内部实现可以自由调整，调用方无需同步变更。相应地，开发沟通的重点从“字段是不是对齐”转向“能力是否满足业务场景”，使协作语言从“结构层面”提升到“业务语义层面”。

这种解耦带来的一个直接效果是：模块可以不依赖完整实现即可进入开发与测试环节。在契约存在的前提下，调用方可以基于接口进行 Mock 或 Stub 测试，而不会受限于实现模块的进度甚至数据库准备情况。这对于并行开发和复杂项目中的团队协作至关重要，它让模块从“互相等待”转变为“边界已定即可独立推进”。

更进一步，当项目从单体多模块走向微服务拆分时，契约优先模式使得迁移路径更为清晰。由于模块已经通过独立契约进行能力调用，原本的接口层可以平滑切换至远程调用方式（例如 OpenFeign、Dubbo 或 gRPC），而无需大幅调整调用逻辑。如果契约本身足够稳定，迁移的影响就可以限制在通信层，而不会渗透至调用方的业务逻辑。

从演化角度来看，契约不仅是调用规范，更是模块责任边界的体现。只要契约稳定，内部模型可以不断完善甚至重构而不影响外部；只要能力表达清晰，模块可以更容易进行替换或扩展；只要接口语义明确，版本升级可以通过新增方式演进而非全局破坏式变更。这意味着，契约优先设计本质上为系统演化预留了空间，为业务不确定性提供了更从容的应对机制。

7. 总结：契约优先是一种让模块合作具备可演化性的设计方式

回看整个过程，契约优先并没有改变模块互相调用的事实，也没有增加不必要的复杂度，而是重新定义了调用的基础方式——我们不再依赖对方“如何实现”，而是围绕“能力是什么”展开协作。这种转变，使模块关系从“共享结构”变为“合作接口”，从紧耦合的实现绑定变为清晰的职责连接。

它不仅避免了循环依赖与内部结构泄露所带来的连锁风险，还让模块在面对变化时具备更高的稳定性，并能更轻松地进入测试、升级、替换乃至服务化演进阶段。从这个角度来说，契约并不是“多写了一层 DTO 和接口”，而是通过抽象边界，使模块具备了“独立存在”和“弹性协作”的能力。

当系统逐渐复杂、团队逐步扩大、业务场景持续变化时，契约优先所提供的结构清晰度、变更可控性、协作稳定性和演化可持续性将逐步显现，而这正是大型系统长期可维护的核心基础。

因此，契约优先不是一种技术技巧，而是一种结构设计理念；不是为了增加层次，而是为了减少未来不必要的复杂性；它不试图阻止模块协作，而是为模块协作设立一个清晰且可持续的边界。

当模块之间不再基于内部结构耦合，而是基于契约能力合作时，系统也才真正拥有了演进的自由空间。