rui-docs/backend/模块间通信规范.md

模块间通信规范

🎯 设计原则

1. 松耦合 - 模块间通过 REST API 通信，禁止直接引用代码
2. 接口契约 - 通过 API 定义进行协作
3. 独立部署 - 每个模块可独立构建和部署
4. 版本管理 - API 支持版本控制

🔗 通信方式

1. 模块 → 框架（rui-framework）

// 使用 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. 模块 → 模块（如收银 → 支付）

// 通过 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. 前端 → 后端

// 前端通过网关调用服务
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}       删除订单

返回格式

{
    "code": 200,
    "message": "success",
    "data": {
        // 业务数据
    }
}

错误处理

{
    "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 通信，禁止任何直接代码引用！