RuoYi-Cloud 3.6.0 实战：手把手教你新建一个订单模块（从建包到代码生成）

RuoYi-Cloud 3.6.0 实战从零构建电商订单微服务模块在微服务架构盛行的当下RuoYi-Cloud作为基于Spring Cloud Alibaba的企业级快速开发平台为业务模块的快速迭代提供了标准化解决方案。本文将以电商系统中最高频的订单模块为例完整演示如何在已有RuoYi-Cloud项目中新建一个符合规范的业务微服务。不同于简单的功能堆砌我们将重点关注模块化设计与生产级配置涵盖从工程结构搭建到代码生成的完整闭环。1. 工程结构与初始化配置1.1 模块创建规范在IDEA中右键ruoyi-modules目录选择New → Module创建Maven项目时需注意命名规范采用ruoyi-module-{业务名}格式例如ruoyi-module-order父POM继承必须显式声明父模块为ruoyi-modules!-- pom.xml 关键配置示例 -- parent groupIdcom.ruoyi/groupId artifactIdruoyi-modules/artifactId version3.6.0/version /parent artifactIdruoyi-module-order/artifactId提示模块创建后需在父工程的pom.xml的modules节点中添加新建模块否则会导致依赖解析失败。1.2 分层目录结构设计订单模块的标准包结构应遵循RuoYi约定src/main/java/com/ruoyi/order ├── config # 专属配置类 ├── controller # 控制层 ├── domain # 实体类 │ ├── entity # 持久化实体 │ ├── vo # 视图对象 │ └── dto # 数据传输对象 ├── mapper # MyBatis接口 ├── service # 服务层 │ └── impl # 服务实现 └── task # 定时任务关键细节包路径必须与后续Nacos配置中的mybatis.type-aliases-package严格对应实体类建议继承BaseEntity获得审计字段支持2. 微服务核心配置2.1 Nacos双配置策略在resources目录下创建bootstrap.yml- 服务发现配置bootstrap-dev.yml- 开发环境覆盖配置# bootstrap.yml 核心内容 spring: application: name: ruoyi-order cloud: nacos: discovery: server-addr: 127.0.0.1:8848 config: file-extension: yml group: DEFAULT_GROUP prefix: ${spring.application.name}配置克隆技巧登录Nacos控制台找到ruoyi-system-dev.yml使用克隆功能创建ruoyi-order-dev.yml修改关键参数# 数据源配置示例 datasource: order: url: jdbc:mysql://127.0.0.1:3306/ry-order?useSSLfalse username: root password: 1234562.2 网关路由配置在ruoyi-gateway模块的application.yml中添加路由规则spring: cloud: gateway: routes: - id: ruoyi-order uri: lb://ruoyi-order predicates: - Path/order/** filters: - StripPrefix1注意网关修改后需要重启生效建议使用RuoYiGatewayApplication的debug模式验证路由匹配情况。3. 订单领域模型设计3.1 数据库建表规范订单主表建议结构CREATE TABLE order_info ( order_id bigint NOT NULL COMMENT 订单ID, order_no varchar(64) COLLATE utf8mb4_general_ci NOT NULL COMMENT 订单编号, user_id bigint NOT NULL COMMENT 用户ID, total_amount decimal(18,2) NOT NULL COMMENT 订单总额, pay_status tinyint NOT NULL DEFAULT 0 COMMENT 支付状态, order_status tinyint NOT NULL DEFAULT 0 COMMENT 订单状态, create_by varchar(64) COLLATE utf8mb4_general_ci DEFAULT COMMENT 创建者, create_time datetime DEFAULT NULL COMMENT 创建时间, update_by varchar(64) COLLATE utf8mb4_general_ci DEFAULT COMMENT 更新者, update_time datetime DEFAULT NULL COMMENT 更新时间, remark varchar(500) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT 备注, PRIMARY KEY (order_id), UNIQUE KEY idx_order_no (order_no) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_general_ci COMMENT订单主表;设计要点金额字段使用DECIMAL(18,2)避免精度丢失状态字段使用tinyint配合枚举类必须包含审计字段create_time/update_time等3.2 实体类与枚举定义// 订单状态枚举 public enum OrderStatus { UNPAID(0, 待支付), PAID(1, 已支付), SHIPPED(2, 已发货), COMPLETED(3, 已完成), CANCELLED(4, 已取消); private final int code; private final String info; } // 订单实体类 Data EqualsAndHashCode(callSuper true) TableName(order_info) public class OrderInfo extends BaseEntity { private static final long serialVersionUID 1L; TableId private Long orderId; private String orderNo; private Long userId; private BigDecimal totalAmount; private Integer payStatus; private Integer orderStatus; }4. 代码生成与定制化4.1 生成器配置要点启动RuoYiGenApplication代码生成服务在系统管理 → 代码生成中基本信息选择订单表设置生成路径为com.ruoyi.order字段配置确保每个字段都有正确注释模板选择使用crud模板默认常见问题处理字段缺失注释会导致前端表单显示异常包路径错误会使生成的代码无法编译多模块项目需确认生成路径在正确模块内4.2 生成后调整建议Controller层增强RestController RequestMapping(/order/info) public class OrderInfoController extends BaseController { Autowired private IOrderInfoService orderInfoService; GetMapping(/listByUser) public TableDataInfo listByUser(OrderInfo orderInfo) { startPage(); ListOrderInfo list orderInfoService.selectOrderListByUser(getUserId(), orderInfo); return getDataTable(list); } }Service层扩展public interface IOrderInfoService { // 生成的默认方法 ListOrderInfo selectOrderList(OrderInfo orderInfo); // 自定义业务方法 OrderInfo createOrder(OrderCreateDTO dto); void cancelOrder(Long orderId); }前端Vue调整修改src/views/order/info/index.vue中的表格列添加自定义查询条件表单5. 进阶功能集成5.1 分布式事务处理对于订单创建→库存扣减的场景添加Seata支持GlobalTransactional public OrderInfo createOrder(OrderCreateDTO dto) { // 1. 创建订单 OrderInfo order buildOrder(dto); orderMapper.insert(order); // 2. 扣减库存通过Feign调用 storageService.reduceInventory(dto.getSkuId(), dto.getQuantity()); // 3. 记录日志 orderLogService.logCreate(order); return order; }需在bootstrap.yml中添加spring: cloud: alibaba: seata: tx-service-group: ${spring.application.name}-group5.2 订单状态机设计使用状态模式管理订单生命周期public interface OrderState { void pay(OrderInfo order); void ship(OrderInfo order); void complete(OrderInfo order); void cancel(OrderInfo order); } Service public class OrderStateMachine { private MapInteger, OrderState stateMap new ConcurrentHashMap(); public void handleAction(OrderInfo order, OrderAction action) { OrderState state stateMap.get(order.getOrderStatus()); switch (action) { case PAY: state.pay(order); break; case SHIP: state.ship(order); break; // 其他动作处理... } } }6. 监控与调试技巧6.1 接口文档配置在启动类添加注解SpringBootApplication EnableSwagger2 public class RuoYiOrderApplication { public static void main(String[] args) { SpringApplication.run(RuoYiOrderApplication.class, args); } }访问http://localhost:端口号/swagger-ui.html查看API文档6.2 SkyWalking链路追踪在VM options中添加-javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_nameruoyi-order -Dskywalking.collector.backend_service127.0.0.1:11800典型问题排查流程通过Trace ID定位请求链路分析各Span耗时检查异常日志关联7. 生产环境注意事项性能优化订单查询添加Cacheable注解分页查询使用PageHelper优化安全防护PreAuthorize(ss.hasPermi(order:info:query)) public TableDataInfo list(OrderInfo orderInfo) { // ... }数据一致性重要操作添加操作日志使用Transactional保证本地事务在电商项目的实战中订单模块往往是最复杂的业务单元之一。经过上述步骤构建的订单服务不仅具备标准的CRUD功能还预留了足够的扩展点应对业务变化。当遇到跨服务调用问题时建议结合RuoYi-Cloud自带的Sentinel组件实现熔断降级。