docs: 迁移 spring-ai 通用文档到 rui-docs
- 添加 backend/项目实施规范.md - 添加 backend/业务应用模块创建规则.md - 添加 backend/guides/deployment-guide.md - 添加 frontend/admin-ui-icon-guide.md - 添加 frontend/admin-ui-status.md - 更新 README.md 文档索引
This commit is contained in:
@@ -0,0 +1,152 @@
|
||||
# 模块间通信规范
|
||||
|
||||
## 🎯 设计原则
|
||||
|
||||
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 通信,禁止任何直接代码引用!
|
||||
Reference in New Issue
Block a user