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:
2026-06-04 09:03:21 +08:00
parent d0771597a6
commit 0666c3ec7b
9 changed files with 2340 additions and 2 deletions
+152
View File
@@ -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. **模块间数据传递**
- 使用 DTOData Transfer Object
- DTO 定义在各自模块,不共享
- 字段名保持一致
3. **接口变更**
- 向后兼容
- 版本号控制
- 通知相关模块
## 🔔 注意事项
1. **超时设置**FeignClient 默认超时 1 秒,根据业务调整
2. **熔断降级**:使用 Sentinel 或 Hystrix
3. **链路追踪**:使用 SkyWalking 或 Zipkin
4. **日志规范**:统一日志格式,包含 traceId
---
> **核心原则**:模块间只通过 REST API 通信,禁止任何直接代码引用!