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-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