RuoYi全栈开发实战从零构建业务模块的避坑指南在微服务架构中新增一个完整业务模块往往涉及前后端十余个环节的协同配置。许多开发者虽然熟悉单个技术点却在模块化开发中频繁遭遇接口404、路由失效、跨域报错等典型问题。本文将基于RuoYi-Cloud与RuoYi-App的实战组合演示如何系统性地完成从数据库设计到前端联调的全流程开发特别聚焦那些官方文档未曾明说的配置细节和排错技巧。1. 后端模块工程化构建1.1 模块创建与依赖管理新建ruoyi-app模块时建议采用继承父pom而非简单复制依赖。在pom.xml中需要特别注意以下关键配置parent groupIdcom.ruoyi/groupId artifactIdruoyi/artifactId version3.8.0/version /parent dependencies !-- 必须包含的starter -- dependency groupIdcom.ruoyi/groupId artifactIdruoyi-common-core/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis Plus配置 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId /dependency /dependencies常见问题排查表问题现象可能原因解决方案启动报Bean冲突依赖版本不一致使用mvn dependency:tree检查冲突无法注入Mapper未扫描到包在启动类添加MapperScan(com.ruoyi.app.mapper)事务失效代理模式错误确认EnableTransactionManagement已启用1.2 领域模型与数据持久化实体类设计应遵循RuoYi规范建议采用Lombok简化代码Data TableName(app_user) public class AppUser { TableId(type IdType.AUTO) private Long userId; NotBlank(message 用户名不能为空) Size(min 2, max 20) private String userName; // 逻辑删除标记需配合全局配置 TableLogic private Integer delFlag; }Mapper接口需要特别注意动态SQL的编写规范select idselectUserList resultTypeAppUser SELECT * FROM app_user where if testuserName ! null and userName ! AND user_name LIKE concat(%, #{userName}, %) /if AND del_flag 0 /where /select提示MyBatis Plus的TableField注解可解决字段名映射问题如TableField(user_name)2. Nacos配置中心实战2.1 服务注册关键参数在bootstrap.yml中以下配置项直接影响服务发现spring: cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: dev # 多环境隔离 group: DEFAULT_GROUP ephemeral: true # 是否临时实例 metadata: version: 1.0 # 元数据可用于灰度发布2.2 网关路由配置陷阱网关配置ruoyi-gateway-dev.yml常见问题路径匹配冲突多个服务配置了相同Path前缀过滤器顺序错误StripPrefix应在认证过滤器之前负载均衡失效服务名未正确注册到Nacos推荐的路由配置模板- id: ruoyi-app uri: lb://ruoyi-app predicates: - Path/app/v1/** filters: - StripPrefix2 # 去除/app/v1前缀 - name: AuthFilter args: excludePaths: /app/v1/public/*3. 前端联调深度优化3.1 请求封装最佳实践在utils/request.js中需要统一处理const service axios.create({ baseURL: process.env.VUE_APP_BASE_API, timeout: 10000, headers: { X-Requested-With: XMLHttpRequest, Content-Type: application/json;charsetUTF-8 } }) // 请求拦截器 service.interceptors.request.use(config { // 自动添加Token if (store.getters.token) { config.headers[Authorization] Bearer getToken() } // 微服务网关标识 config.headers[Gateway-Type] mobile-app return config })3.2 跨域解决方案对比方案适用场景优缺点网关CORS配置生产环境安全但配置复杂开发代理本地开发简单需重启Nginx反向代理测试环境灵活但需运维推荐开发环境配置devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: } } } }4. 全链路调试技巧4.1 日志追踪方案SkyWalking链路追踪# 启动参数添加 -javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_nameruoyi-app日志关联IDSlf4j RestController public class AppUserController { GetMapping(/list) public TableDataInfo list() { log.info(查询用户列表请求到达); MDC.put(traceId, UUID.randomUUID().toString()); // ... } }4.2 接口文档自动化Swagger集成配置Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(com.ruoyi.app.controller)) .paths(PathSelectors.any()) .build() .globalOperationParameters(Collections.singletonList( new ParameterBuilder() .name(Authorization) .description(访问令牌) .modelRef(new ModelRef(string)) .parameterType(header) .required(false) .build())); }联调阶段建议开启Knife4j增强UIknife4j.enabletrue knife4j.productionfalse在实际项目交付中模块初始化时最容易忽略的是Nacos配置的版本控制。我们团队曾因未指定配置版本号导致测试环境读取了生产配置后来通过建立严格的配置命名规范避免了此类问题例如采用{应用名}-{环境}-{版本}.yml的格式管理所有配置文件。