docs: 补充 OpenFeign 参数对象管理策略\n\n- 在 2.3 章节新增 2.3.6 参数对象(DTO)管理策略\n- 约定通用参数对象放在 fund-common 独立模块\n- 领域业务参数对象按服务分模块管理,避免跨模块 Java 类型耦合\n- 明确消费方可定义本地 DTO 并在 Service 层做映射\n- 修复技术架构章节标题被覆盖的问题

This commit is contained in:
zhangjf 2026-02-17 09:51:05 +08:00
parent cf0db27bc5
commit 2c22213326

View File

@ -2502,6 +2502,97 @@ public class FeignChainInterceptor implements RequestInterceptor {
- ❌ 直接通过数据库访问其他服务的表(破坏服务边界)
- ❌ 使用 RestTemplate 而非 OpenFeign缺少服务发现和负载均衡
#### 2.3.6 参数对象DTO管理策略
OpenFeign 调用中涉及的参数对象(请求 DTO / 响应 DTO采用 **“通用参数独立模块 + 领域参数分模块管理”** 的组合策略:
##### 2.3.6.1 通用参数对象(独立模块管理)
**定义**:跨多个业务域都会用到的通用结构,由基础公共模块统一提供。
| 对象类别 | 示例 | 所在模块 |
|----------|------|----------|
| 统一返回结果 | `Result<T>``PageResult<T>` | `fund-common` |
| 分页/排序参数 | `PageRequest``SortRequest`(预留) | `fund-common` |
| 公共基础实体 | `BaseEntity`(含 `tenant_id`、审计字段) | `fund-common` |
**约定**
- 任何服务如果需要统一返回格式或分页能力,优先复用 `fund-common` 中的通用对象;
- 通用对象由架构组维护,变更需评估对所有服务的影响。
##### 2.3.6.2 领域参数对象(分模块管理)
**定义**:只属于某个业务域的请求 / 响应对象,例如:
- 客户查询条件:`CustomerQueryDTO`fund-cust
- 项目创建请求:`ProjectCreateRequest`fund-proj
- 收款记录筛选条件:`ReceiptFilterDTO`fund-receipt
**管理策略**
- **分模块管理**
- 每个提供 API 的服务,在**自身模块内部**定义领域参数对象;
- 参数对象的 Java 类不在多个业务模块之间通过 Maven 互相依赖,避免形成隐性耦合;
- 服务之间通过 **JSON 结构契约** 进行解耦,具体字段以 API 文档为准。
- **消费方处理方式**
- 服务消费方可以:
- 直接使用与提供方字段结构一致的本地 VO/DTO并通过 JSON 序列化/反序列化完成转换;或
- 在消费方内部定义更贴近本地业务的 DTO并在 Service 层做一次字段映射。
**示例**(领域请求 DTO 定义在提供方模块):
```java
// fund-cust 模块内部
@Data
public class CustomerQueryDTO {
private String keyword;
private Integer status;
private LocalDate startDate;
private LocalDate endDate;
}
@RestController
@RequestMapping("/api/v1/customer")
public class CustomerController {
@PostMapping("/search")
public Result<List<CustomerVO>> search(@RequestBody CustomerQueryDTO query) {
// ... 省略具体实现
}
}
```
**消费方调用示例**
```java
// fund-proj 模块内部定义本地请求对象
@Data
public class CustomerSearchRequest {
private String keyword;
}
@FeignClient(name = "fund-cust", path = "/api/v1/customer")
public interface CustomerFeignClient {
@PostMapping("/search")
Result<List<CustomerVO>> search(@RequestBody CustomerQueryDTO query);
}
@Service
@RequiredArgsConstructor
public class ProjectService {
private final CustomerFeignClient customerFeignClient;
public List<CustomerVO> findCustomers(CustomerSearchRequest request) {
CustomerQueryDTO dto = new CustomerQueryDTO();
dto.setKeyword(request.getKeyword());
return customerFeignClient.search(dto).getData();
}
}
```
> **结论**
> - 通用参数对象放在 `fund-common` 独立模块统一管理;
> - 具体业务领域的参数对象采用**分模块管理**,定义在各自服务内部;
> - 业务服务间通过 OpenFeign + JSON 契约解耦,不共享彼此的领域实体类。
---
## 三、技术架构