docs: 补充模块通信方式说明
新增内容： - 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 ✓ 提供完整的代码示例和架构图 ✓ 明确反模式，避免错误使用
This commit is contained in:
zhangjf
parent
297ea8e259
commit
cf0db27bc5
@ -2309,6 +2309,199 @@ public class PerformanceAspect {
|
|||||||
| 报表中心 | fund-report | 统计分析、数据导出 | 8160-8169 |
|
| 报表中心 | fund-report | 统计分析、数据导出 | 8160-8169 |
|
||||||
| 文件中心 | fund-file | 文件上传、存储管理 | 8170-8179 |
|
| 文件中心 | fund-file | 文件上传、存储管理 | 8170-8179 |
|
||||||
|
|
||||||
|
### 2.3 模块通信方式
|
||||||
|
|
||||||
|
系统采用**分层通信架构**，根据模块职责划分为基础服务和业务服务，采用不同的通信方式：
|
||||||
|
|
||||||
|
#### 2.3.1 基础服务 - Maven 依赖方式
|
||||||
|
|
||||||
|
**定义**：提供基础能力、不对外暴露 HTTP 接口的模块
|
||||||
|
|
||||||
|
| 基础服务 | 说明 | 提供能力 | 依赖方式 |
|
||||||
|
|---------|------|---------|---------|
|
||||||
|
| **fund-common** | 公共模块 | 基础实体、工具类、统一响应格式 | Maven 依赖 |
|
||||||
|
| **fund-gateway** | API 网关 | 路由转发、统一鉴权、限流熔断 | 独立部署 |
|
||||||
|
|
||||||
|
**特点**：
|
||||||
|
- ✅ **编译时依赖**：通过 Maven `<dependency>` 直接引入
|
||||||
|
- ✅ **本地调用**：方法级别直接调用，无网络开销
|
||||||
|
- ✅ **强类型约束**：编译期类型检查，更安全
|
||||||
|
- ✅ **版本统一**：通过父 POM 统一管理版本
|
||||||
|
|
||||||
|
**示例**：
|
||||||
|
```xml
|
||||||
|
<!-- 业务模块依赖 fund-common -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>com.fundplatform</groupId>
|
||||||
|
<artifactId>fund-common</artifactId>
|
||||||
|
<version>${project.version}</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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<Customer> getCustomerById(@PathVariable Long customerId);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 批量查询客户信息
|
||||||
|
*/
|
||||||
|
@PostMapping("/batch")
|
||||||
|
Result<List<Customer>> getCustomersByIds(@RequestBody List<Long> 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<Customer> 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（缺少服务发现和负载均衡）
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 三、技术架构
|
## 三、技术架构
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user