From 2c22213326e1c38e1dcf7d267d980c725a36e854 Mon Sep 17 00:00:00 2001 From: zhangjf Date: Tue, 17 Feb 2026 09:51:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20OpenFeign=20?= =?UTF-8?q?=E5=8F=82=E6=95=B0=E5=AF=B9=E8=B1=A1=E7=AE=A1=E7=90=86=E7=AD=96?= =?UTF-8?q?=E7=95=A5\n\n-=20=E5=9C=A8=202.3=20=E7=AB=A0=E8=8A=82=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=202.3.6=20=E5=8F=82=E6=95=B0=E5=AF=B9=E8=B1=A1?= =?UTF-8?q?=EF=BC=88DTO=EF=BC=89=E7=AE=A1=E7=90=86=E7=AD=96=E7=95=A5\n-=20?= =?UTF-8?q?=E7=BA=A6=E5=AE=9A=E9=80=9A=E7=94=A8=E5=8F=82=E6=95=B0=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1=E6=94=BE=E5=9C=A8=20fund-common=20=E7=8B=AC=E7=AB=8B?= =?UTF-8?q?=E6=A8=A1=E5=9D=97\n-=20=E9=A2=86=E5=9F=9F=E4=B8=9A=E5=8A=A1?= =?UTF-8?q?=E5=8F=82=E6=95=B0=E5=AF=B9=E8=B1=A1=E6=8C=89=E6=9C=8D=E5=8A=A1?= =?UTF-8?q?=E5=88=86=E6=A8=A1=E5=9D=97=E7=AE=A1=E7=90=86=EF=BC=8C=E9=81=BF?= =?UTF-8?q?=E5=85=8D=E8=B7=A8=E6=A8=A1=E5=9D=97=20Java=20=E7=B1=BB?= =?UTF-8?q?=E5=9E=8B=E8=80=A6=E5=90=88\n-=20=E6=98=8E=E7=A1=AE=E6=B6=88?= =?UTF-8?q?=E8=B4=B9=E6=96=B9=E5=8F=AF=E5=AE=9A=E4=B9=89=E6=9C=AC=E5=9C=B0?= =?UTF-8?q?=20DTO=20=E5=B9=B6=E5=9C=A8=20Service=20=E5=B1=82=E5=81=9A?= =?UTF-8?q?=E6=98=A0=E5=B0=84\n-=20=E4=BF=AE=E5=A4=8D=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E7=AB=A0=E8=8A=82=E6=A0=87=E9=A2=98=E8=A2=AB?= =?UTF-8?q?=E8=A6=86=E7=9B=96=E7=9A=84=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/资金服务平台 FundPlatform 架构设计文档.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) 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 契约解耦，不共享彼此的领域实体类。 + --- ## 三、技术架构