diff --git a/doc/资金服务平台 FundPlatform 架构设计文档.md b/doc/资金服务平台 FundPlatform 架构设计文档.md index 643e8f8..eec8e3a 100644 --- a/doc/资金服务平台 FundPlatform 架构设计文档.md +++ b/doc/资金服务平台 FundPlatform 架构设计文档.md @@ -2502,6 +2502,97 @@ public class FeignChainInterceptor implements RequestInterceptor { - ❌ 直接通过数据库访问其他服务的表(破坏服务边界) - ❌ 使用 RestTemplate 而非 OpenFeign(缺少服务发现和负载均衡) +#### 2.3.6 参数对象(DTO)管理策略 + +OpenFeign 调用中涉及的参数对象(请求 DTO / 响应 DTO),采用 **“通用参数独立模块 + 领域参数分模块管理”** 的组合策略: + +##### 2.3.6.1 通用参数对象(独立模块管理) + +**定义**:跨多个业务域都会用到的通用结构,由基础公共模块统一提供。 + +| 对象类别 | 示例 | 所在模块 | +|----------|------|----------| +| 统一返回结果 | `Result`、`PageResult` | `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> 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> search(@RequestBody CustomerQueryDTO query); +} + +@Service +@RequiredArgsConstructor +public class ProjectService { + + private final CustomerFeignClient customerFeignClient; + + public List findCustomers(CustomerSearchRequest request) { + CustomerQueryDTO dto = new CustomerQueryDTO(); + dto.setKeyword(request.getKeyword()); + return customerFeignClient.search(dto).getData(); + } +} +``` + +> **结论**: +> - 通用参数对象放在 `fund-common` 独立模块统一管理; +> - 具体业务领域的参数对象采用**分模块管理**,定义在各自服务内部; +> - 业务服务间通过 OpenFeign + JSON 契约解耦,不共享彼此的领域实体类。 + --- ## 三、技术架构