vifo
0666c3ec7b
- 添加 backend/项目实施规范.md - 添加 backend/业务应用模块创建规则.md - 添加 backend/guides/deployment-guide.md - 添加 frontend/admin-ui-icon-guide.md - 添加 frontend/admin-ui-status.md - 更新 README.md 文档索引
152 lines
3.8 KiB
Markdown
152 lines
3.8 KiB
Markdown
# 模块间通信规范
|
||
|
||
## 🎯 设计原则
|
||
|
||
1. **松耦合** - 模块间通过 REST API 通信，禁止直接引用代码
|
||
2. **接口契约** - 通过 API 定义进行协作
|
||
3. **独立部署** - 每个模块可独立构建和部署
|
||
4. **版本管理** - API 支持版本控制
|
||
|
||
## 🔗 通信方式
|
||
|
||
### 1. 模块 → 框架（spring-ai）
|
||
|
||
```java
|
||
// 使用 FeignClient 调用框架服务
|
||
@FeignClient("rui-service-user")
|
||
public interface UserFeignClient {
|
||
|
||
@GetMapping("/api/v1/user/{id}")
|
||
Result<UserDTO> getUserById(@PathVariable Long id);
|
||
|
||
@GetMapping("/api/v1/user/current")
|
||
Result<UserDTO> getCurrentUser();
|
||
}
|
||
```
|
||
|
||
### 2. 模块 → 模块（如收银 → 支付）
|
||
|
||
```java
|
||
// 通过 FeignClient 调用其他业务模块
|
||
@FeignClient("rui-payment")
|
||
public interface PaymentFeignClient {
|
||
|
||
@PostMapping("/api/v1/pay/order")
|
||
Result<PayResult> createPayOrder(@RequestBody PayOrderDTO dto);
|
||
|
||
@GetMapping("/api/v1/pay/status/{orderNo}")
|
||
Result<PayStatus> getPayStatus(@PathVariable String orderNo);
|
||
}
|
||
```
|
||
|
||
### 3. 前端 → 后端
|
||
|
||
```typescript
|
||
// 前端通过网关调用服务
|
||
const API_GATEWAY = '/api';
|
||
|
||
// 调用收银服务
|
||
const cashierApi = {
|
||
createOrder: (data) => axios.post(`${API_GATEWAY}/cashier/order`, data),
|
||
getOrderList: () => axios.get(`${API_GATEWAY}/cashier/order/list`)
|
||
};
|
||
|
||
// 调用支付服务
|
||
const paymentApi = {
|
||
createPay: (data) => axios.post(`${API_GATEWAY}/pay/order`, data),
|
||
queryPayStatus: (orderNo) => axios.get(`${API_GATEWAY}/pay/status/${orderNo}`)
|
||
};
|
||
```
|
||
|
||
## 📐 API 规范
|
||
|
||
### URL 设计
|
||
```
|
||
/api/v1/{模块}/{资源}/{操作}
|
||
|
||
示例：
|
||
- GET /api/v1/cashier/order/list 查询订单列表
|
||
- POST /api/v1/cashier/order 创建订单
|
||
- GET /api/v1/cashier/order/{id} 查询订单详情
|
||
- PUT /api/v1/cashier/order/{id} 更新订单
|
||
- DELETE /api/v1/cashier/order/{id} 删除订单
|
||
```
|
||
|
||
### 返回格式
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
// 业务数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误处理
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "支付失败：余额不足",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 🗄️ 数据库隔离
|
||
|
||
| 模块 | 数据库/Schema | 说明 |
|
||
|------|--------------|------|
|
||
| rui-service | `rui_system` | 系统服务数据 |
|
||
| rui-cashier | `rui_cashier` | 收银业务数据 |
|
||
| rui-payment | `rui_payment` | 支付业务数据 |
|
||
|
||
**禁止**：
|
||
- 直接访问其他模块的数据库
|
||
- 直接查询其他模块的表
|
||
|
||
## 🚀 部署架构
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ Nginx │ ← 网关入口
|
||
└──────┬──────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ rui-gateway │ ← Spring Cloud Gateway
|
||
└──────┬──────┘
|
||
│
|
||
┌───┼───┐
|
||
▼ ▼ ▼
|
||
┌──┐ ┌──┐ ┌──┐
|
||
│用户│ │收银│ │支付│ ← 微服务模块
|
||
│服务│ │服务│ │服务│
|
||
└──┘ └──┘ └──┘
|
||
```
|
||
|
||
## 📋 开发流程
|
||
|
||
1. **模块 A 需要模块 B 的接口**
|
||
- 模块 A 在自身仓库定义 FeignClient 接口
|
||
- 模块 B 实现并暴露 REST API
|
||
- 不需要依赖模块 B 的代码
|
||
|
||
2. **模块间数据传递**
|
||
- 使用 DTO（Data Transfer Object）
|
||
- DTO 定义在各自模块，不共享
|
||
- 字段名保持一致
|
||
|
||
3. **接口变更**
|
||
- 向后兼容
|
||
- 版本号控制
|
||
- 通知相关模块
|
||
|
||
## 🔔 注意事项
|
||
|
||
1. **超时设置**：FeignClient 默认超时 1 秒，根据业务调整
|
||
2. **熔断降级**：使用 Sentinel 或 Hystrix
|
||
3. **链路追踪**：使用 SkyWalking 或 Zipkin
|
||
4. **日志规范**：统一日志格式，包含 traceId
|
||
|
||
---
|
||
|
||
> **核心原则**：模块间只通过 REST API 通信，禁止任何直接代码引用！ |