From cf0db27bc56633ab557b62449a5f19cbd03d91a9 Mon Sep 17 00:00:00 2001 From: zhangjf Date: Tue, 17 Feb 2026 09:28:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E6=A8=A1=E5=9D=97?= =?UTF-8?q?=E9=80=9A=E4=BF=A1=E6=96=B9=E5=BC=8F=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容： - 2.3 模块通信方式章节 - 2.3.1 基础服务 - Maven 依赖方式 - 2.3.2 业务服务 - OpenFeign 通信方式 - 2.3.3 通信链路追踪 - 2.3.4 通信架构图 - 2.3.5 通信方式选择标准 关键说明： ✓ fund-common 等基础服务采用 Maven 依赖方式 ✓ 业务服务间采用 OpenFeign 进行 HTTP 通信 ✓ 自动传递租户ID、用户信息、链路追踪ID ✓ 提供完整的代码示例和架构图 ✓ 明确反模式，避免错误使用 --- doc/资金服务平台 FundPlatform 架构设计文档.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/doc/资金服务平台 FundPlatform 架构设计文档.md b/doc/资金服务平台 FundPlatform 架构设计文档.md index 949e586..643e8f8 100644 --- a/doc/资金服务平台 FundPlatform 架构设计文档.md +++ b/doc/资金服务平台 FundPlatform 架构设计文档.md @@ -2309,6 +2309,199 @@ public class PerformanceAspect { | 报表中心 | fund-report | 统计分析、数据导出 | 8160-8169 | | 文件中心 | fund-file | 文件上传、存储管理 | 8170-8179 | +### 2.3 模块通信方式 + +系统采用**分层通信架构**，根据模块职责划分为基础服务和业务服务，采用不同的通信方式： + +#### 2.3.1 基础服务 - Maven 依赖方式 + +**定义**：提供基础能力、不对外暴露 HTTP 接口的模块 + +| 基础服务 | 说明 | 提供能力 | 依赖方式 | +|---------|------|---------|---------| +| **fund-common** | 公共模块 | 基础实体、工具类、统一响应格式 | Maven 依赖 | +| **fund-gateway** | API 网关 | 路由转发、统一鉴权、限流熔断 | 独立部署 | + +**特点**： +- ✅ **编译时依赖**：通过 Maven `` 直接引入 +- ✅ **本地调用**：方法级别直接调用，无网络开销 +- ✅ **强类型约束**：编译期类型检查，更安全 +- ✅ **版本统一**：通过父 POM 统一管理版本 + +**示例**： +```xml + + + com.fundplatform + fund-common + ${project.version} + +``` + +#### 2.3.2 业务服务 - OpenFeign 通信方式 + +**定义**：提供 HTTP API 接口、独立部署的业务模块 + +| 业务服务 | 说明 | 提供 API | 通信方式 | +|---------|------|---------|---------| +| **fund-sys** | 系统服务 | 用户、角色、权限、部门 API | OpenFeign | +| **fund-cust** | 客户中心 | 客户、联系人管理 API | OpenFeign | +| **fund-proj** | 项目中心 | 项目、成员管理 API | OpenFeign | +| **fund-req** | 需求中心 | 需求工单、应收款 API | OpenFeign | +| **fund-exp** | 支出中心 | 支出类型、支出管理 API | OpenFeign | +| **fund-receipt** | 收款中心 | 收款记录、账期管理 API | OpenFeign | +| **fund-report** | 报表中心 | 统计分析、数据导出 API | OpenFeign | +| **fund-file** | 文件中心 | 文件上传、存储管理 API | OpenFeign | + +**特点**： +- ✅ **松耦合**：服务间独立部署、独立升级 +- ✅ **声明式调用**：通过接口注解定义，自动生成实现 +- ✅ **负载均衡**：集成 LoadBalancer，自动分发请求 +- ✅ **服务发现**：通过 Nacos 动态获取服务地址 +- ✅ **熔断降级**：集成 Sentinel，提供容错能力 +- ✅ **链路追踪**：自动传递 TraceId、租户ID、用户信息 + +**示例**： +```java +/** + * 客户服务 Feign 客户端 + */ +@FeignClient( + name = "fund-cust", // 服务名（Nacos注册名） + path = "/api/v1/customer", // 接口路径前缀 + fallbackFactory = CustomerFallbackFactory.class // 降级处理 +) +public interface CustomerFeignClient { + + /** + * 根据客户ID查询客户信息 + */ + @GetMapping("/{customerId}") + Result getCustomerById(@PathVariable Long customerId); + + /** + * 批量查询客户信息 + */ + @PostMapping("/batch") + Result> getCustomersByIds(@RequestBody List customerIds); +} +``` + +**调用示例**： +```java +@Service +@RequiredArgsConstructor +public class ProjectService { + + // 注入 Feign 客户端 + private final CustomerFeignClient customerFeignClient; + + public ProjectDetail getProjectDetail(Long projectId) { + // 1. 查询项目基本信息 + Project project = projectMapper.selectById(projectId); + + // 2. 通过 Feign 调用客户服务获取客户信息 + Result result = customerFeignClient.getCustomerById(project.getCustomerId()); + Customer customer = result.getData(); + + // 3. 组装返回 + return ProjectDetail.builder() + .project(project) + .customer(customer) + .build(); + } +} +``` + +#### 2.3.3 通信链路追踪 + +所有 Feign 调用自动传递以下 Header 信息： + +| Header 名称 | 说明 | 来源 | 用途 | +|------------|------|------|------| +| `X-Tenant-Id` | 租户ID | TenantContextHolder | 多租户数据隔离 | +| `X-Uid` | 用户ID | 当前登录用户 | 操作日志记录 | +| `X-Uname` | 用户名 | 当前登录用户 | 操作日志记录 | +| `X-Trace-Id` | 链路追踪ID | MDC.get("traceId") | 全链路日志追踪 | + +**实现机制**： +```java +/** + * Feign 调用链拦截器 + * 自动添加租户、用户、链路追踪信息到请求头 + */ +@Component +public class FeignChainInterceptor implements RequestInterceptor { + + @Override + public void apply(RequestTemplate template) { + // 1. 传递租户ID + Long tenantId = TenantContextHolder.getTenantId(); + if (tenantId != null) { + template.header("X-Tenant-Id", String.valueOf(tenantId)); + } + + // 2. 传递用户信息 + Long uid = GlobalContext.getUid(); + String uname = GlobalContext.getUname(); + if (uid != null) { + template.header("X-Uid", String.valueOf(uid)); + template.header("X-Uname", uname); + } + + // 3. 传递链路追踪ID + String traceId = MDC.get("traceId"); + if (traceId != null) { + template.header("X-Trace-Id", traceId); + } + } +} +``` + +#### 2.3.4 通信架构图 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 前端应用 │ +│ (管理后台 + 移动端) │ +└────────────────────────────┬────────────────────────────────────────┘ + │ HTTP/HTTPS + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ fund-gateway (API网关) │ +│ 路由、鉴权、限流、熔断 │ +└──┬──────────────┬──────────────┬──────────────┬─────────────────────┘ + │ │ │ │ + │ HTTP │ HTTP │ HTTP │ HTTP + ▼ ▼ ▼ ▼ +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ +│fund-sys│ │fund-cust│ │fund-proj│ │fund-exp│ +│系统服务│ │客户中心│ │项目中心│ │支出中心│ +└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ + │ │ │ │ + │ Maven依赖 │ OpenFeign ◄──┤ OpenFeign ◄──┤ + ▼ ▼ ▼ ▼ +┌──────────────────────────────────────────────────┐ +│ fund-common (公共模块) │ +│ (Result、BaseEntity、工具类等) │ +└──────────────────────────────────────────────────┘ +``` + +#### 2.3.5 通信方式选择标准 + +| 场景 | 推荐方式 | 理由 | +|------|---------|------| +| 使用公共实体类 | Maven 依赖 | 编译期检查，无运行时开销 | +| 使用工具类方法 | Maven 依赖 | 直接调用，性能最优 | +| 跨服务调用 API | OpenFeign | 服务解耦，支持独立部署 | +| 查询其他服务数据 | OpenFeign | 通过 HTTP API，标准化通信 | +| 调用第三方服务 | OpenFeign | 统一的调用方式和错误处理 | + +**反模式**（不推荐）： +- ❌ 业务服务间通过 Maven 依赖互相引用（导致强耦合） +- ❌ 直接通过数据库访问其他服务的表（破坏服务边界） +- ❌ 使用 RestTemplate 而非 OpenFeign（缺少服务发现和负载均衡） + --- ## 三、技术架构