若依（RuoYi-Vue）单体架构实战手册：自定义业务模块全流程开发指南

文档说明

本文档面向若依（RuoYi-Vue）单体版的初级/中级开发者，提供从环境搭建到自定义业务模块开发的全流程标准化操作指南。手册聚焦「低代码、高效率」的核心开发理念，所有操作步骤均经过实测验证，可直接落地；同时补充关键注意点与问题规避方案，帮助开发者快速上手并规避常见坑点。

一、开发前准备：环境搭建与项目初始化

1. 环境要求（强制统一版本）

环境版本的统一性是避免依赖冲突、编译失败的核心前提，所有环境需严格遵循以下要求配置：

环境	版本要求	验证方式	备注
JDK	8（推荐）	终端执行 java -version，输出 1.8.xxx 或 17.xxx	全模块必须统一版本，禁止混合使用；推荐JDK8，兼容性更强
Maven	3.6.0+	终端执行 mvn -v，输出版本 ≥3.6.0	建议配置阿里云镜像加速依赖下载，避免中央仓库访问超时
MySQL	5.7.30+ / 8.0.28+（推荐）	登录数据库执行 select version();	需提前创建编码为UTF-8的ruoyi数据库；MySQL8.0需注意驱动类差异（若依已兼容）
IDE	IntelliJ IDEA 2021+	安装「Lombok」「MyBatisX」插件（Settings→Plugins）	必须开启注解处理器（Settings→Build→Compiler→Annotation Processors），否则Lombok注解失效
前端环境	Node.js 16+、pnpm 8+	终端执行 node -v/pnpm -v	推荐用pnpm，比npm/yarn更节省磁盘空间、安装速度更快；若用npm/yarn，命令可直接替换

2. 项目初始化（标准化步骤）

2.1 源码下载与解压

单体架构后端Ruoyi-vue，前端Ruoyi-vue3

2.1.1后端仓库代码地址：

Gitee（推荐，国内访问快）：https://gitee.com/y_project/RuoYi-Vue
GitHub：https://github.com/yangzongzhuan/RuoYi-Vue
下载后解压至非中文、无空格路径（如 D:\dev\RuoYi-Vue（示例路径）），避免中文路径导致的编码异常、启动失败等问题。

2.1.2前端仓库代码地址：

Gicode（推荐，国内访问快）：https://gitcode.com/yangzongzhuan/RuoYi-Vue3
下载后解压至非中文、无空格路径（如 D:\dev\RuoYi-Vue\RuoYi-Vue3（示例路径）），避免中文路径导致的编码异常、启动失败等问题。

2.1.3 整理好可以直接使用的仓库地址：

https://gitee.com/pomegranate-bag-shuai-li/project

2.2 数据库初始化

数据库是项目运行的基础，需严格按以下步骤执行，避免表结构缺失（现在展示是以IDEA里面的数据库连接工具为例）：

打开IDEA，打开Datebase，成功连接到自己的mysql。
执行初始化SQL文件：
- 核心表结构：sql/ry_20250522.sql（文件名随版本更新，以实际下载的源码为准）
- 定时任务表（可选）：sql/quartz.sql（无需定时任务功能可跳过）
验证：

2.3 配置文件修改

核心修改数据库连接配置，确保项目能正常连接数据库：

打开配置文件：ruoyi-admin/src/main/resources/application-druid.yml
修改数据库连接信息（替换为自己的MySQL账号密码）：

yaml 复制代码

spring:
    datasource:
        type: com.alibaba.druid.pool.DruidDataSource
        driverClassName: com.mysql.cj.jdbc.Driver
        druid:
            # 主库数据源
            master:
                url: jdbc:mysql://localhost:3306/ry_vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8  # ry_vue 数据库名
                username: root  # 数据库用户名
                password: 123456  # 数据库密码

注意：若MySQL部署在远程服务器，需将localhost改为服务器IP，同时开放3306端口。
（可选）修改端口：若本地8080端口被占用，可修改application.yml中的server.port（如改为8081）。
修改 ruoyi-admin/src/main/resources/application.yml

yaml 复制代码

# 项目相关配置
ruoyi:
  # 名称
  name: RuoYi
  # 版本
  version: 3.9.1
  # 版权年份
  copyrightYear: 2025
  # 文件路径 示例（ Windows配置D:/ruoyi/uploadPath，Linux配置 /home/ruoyi/uploadPath）
  profile: D:/ruoyi/uploadPath
  # 获取ip地址开关
  addressEnabled: false
  # 验证码类型 math 数字计算 char 字符验证
  captchaType: math

# 开发环境配置
server:
  # 服务器的HTTP端口，默认为8080
  port: 8080
  servlet:
    # 应用的访问路径
    context-path: /
  tomcat:
    # tomcat的URI编码
    uri-encoding: UTF-8
    # 连接数满后的排队数，默认为100
    accept-count: 1000
    threads:
      # tomcat最大线程数，默认为200
      max: 800
      # Tomcat启动初始化的线程数，默认值10
      min-spare: 100

# 日志配置
logging:
  level:
    com.ruoyi: debug
    org.springframework: warn

# 用户配置
user:
  password:
    # 密码最大错误次数
    maxRetryCount: 5
    # 密码锁定时间（默认10分钟）
    lockTime: 10

# Spring配置
spring:
  # 资源信息
  messages:
    # 国际化资源文件路径
    basename: i18n/messages
  profiles:
    active: druid
  # 组件扫描配置，确保ruoyi-service模块的组件被扫描到
  main:
    # 允许Bean定义覆盖，避免配置冲突
    allow-bean-definition-overriding: true
  # 文件上传
  servlet:
    multipart:
      # 单个文件大小
      max-file-size: 10MB
      # 设置总上传的文件大小
      max-request-size: 20MB
  # 服务模块
  devtools:
    restart:
      # 热部署开关
      enabled: true
  # redis 配置
  redis:
    # 地址
    host: localhost
    # 端口，默认为6379
    port: 6379
    # 数据库索引
    database: 0
    # 密码
#    password:
    # 连接超时时间
    timeout: 10s
    lettuce:
      pool:
        # 连接池中的最小空闲连接
        min-idle: 0
        # 连接池中的最大空闲连接
        max-idle: 8
        # 连接池的最大数据库连接数
        max-active: 8
        # #连接池最大阻塞等待时间（使用负值表示没有限制）
        max-wait: -1ms

# token配置
token:
  # 令牌自定义标识
  header: Authorization
  # 令牌密钥
  secret: abcdefghijklmnopqrstuvwxyz
  # 令牌有效期（默认30分钟）
  expireTime: 30

# MyBatis配置
mybatis:
  # 搜索指定包别名（排除ruoyi-service，因为它使用MyBatis-Plus）
  typeAliasesPackage: com.ruoyi.common.core.domain.entity,com.ruoyi.system.**.domain,com.ruoyi.generator.**.domain,com.ruoyi.quartz.domain
  # 配置mapper的扫描，找到所有的mapper.xml映射文件
  mapperLocations: classpath*:mapper/**/*Mapper.xml
  # 加载全局的配置文件
  configLocation: classpath:mybatis/mybatis-config.xml

# MyBatis-Plus配置（用于ruoyi-service模块）
mybatis-plus:
  # 配置mapper的扫描，找到ruoyi-service模块的mapper.xml映射文件
  mapper-locations: classpath*:mapper/**/*Mapper.xml
  # 配置类型别名的包路径
  type-aliases-package: com.ruoyi.service.domain
  # 全局配置
  global-config:
    db-config:
      # 主键类型
      id-type: AUTO
      # 逻辑删除配置
      logic-delete-field: delFlag
      logic-delete-value: 1
      logic-not-delete-value: 0
  # 配置
  configuration:
    # 开启驼峰命名转换
    map-underscore-to-camel-case: true
    # SQL打印
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

# PageHelper分页插件
pagehelper:
  helperDialect: mysql
  supportMethodsArguments: true
  params: count=countSql

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
  pathMapping: /dev-api

# 防盗链配置
referer:
  # 防盗链开关
  enabled: false
  # 允许的域名列表
  allowed-domains: localhost,127.0.0.1,ruoyi.vip,www.ruoyi.vip

# 防止XSS攻击
xss:
  # 过滤开关
  enabled: true
  # 排除链接（多个用逗号分隔）
  excludes: /system/notice
  # 匹配链接
  urlPatterns: /system/*,/monitor/*,/tool/*

2.4 项目启动验证

分别启动后端和前端，验证项目初始化是否成功：

2.4.1 后端启动

打开IDEA，点击「File→Open」，选择解压后项目的根目录pom.xml，导入项目。
等待Maven依赖下载完成（IDEA右下角有进度条，进度条消失即完成；若下载缓慢，检查Maven镜像配置）。
找到启动类：ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java，右键点击「Run 'RuoYiApplication'」。
验证：控制台输出 (♥◠‿◠)ﾉﾞ若依启动成功！！！，且无报错信息，说明后端启动完成。

2.4.2 前端启动

使用Vscode打开这个前端的Vue3项目。
执行依赖安装命令：

xml 复制代码

pnpm install  #首次安装

若安装失败（如依赖冲突、网络问题），清空缓存后重试

xml 复制代码

pnpm cache clean && pnpm install  # 注意：若未安装pnpm，可先执行npm install -g pnpm全局安装。

启动前端项目：

xml 复制代码

pnpm run dev

验证：终端输出访问地址（默认http://localhost:80），打开浏览器访问该地址，输入默认账号admin、密码123456，能成功登录系统即初始化完成。登录界面如下：验证是否可以成功登录。

二、核心开发流程：自定义业务模块搭建

创建自定义模块。我这个目的是创建一个新的模块里面去写相关项目的CRUD和业务等。也可以创建多个自定义模块。可以照搬。

步骤1：创建自定义业务模块（以ruoyi-service为例）

推荐创建独立的自定义模块，隔离核心模块与业务模块，便于后期维护和扩展。

1.1 新建Maven模块（可视化操作）

在IDEA中，右键点击根工程RuoYi-Vue → 「New」 → 「Module」。
选择「Maven」选Spring Boot，填写东西。配置项填写值说明Name：ruoyi-service模块名称，采用「小写+短横线」命名规范GroupId：com.ruoyi与根工程保持一致，确保依赖层级正确ArtifactId：ruoyi-service与模块名称一致，作为依赖标识Version3.9.1与根工程版本一致，避免版本冲突
点击「Next」完成模块创建，一直下一步即可。

1.2 配置模块依赖（核心）

模块依赖是模块间交互的基础，需替换ruoyi-service/pom.xml的全部内容为以下代码（已适配JDK8+MyBatis-Plus+Lombok，避免依赖冲突，兼容使用mybatis）：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 继承若依根工程，统一版本管理，避免版本混乱 -->
    <parent>
        <groupId>com.ruoyi</groupId>
        <artifactId>ruoyi</artifactId>
        <version>3.9.1</version>
        <relativePath>../pom.xml</relativePath>
    </parent>

    <groupId>com.ruoyi</groupId>
    <artifactId>ruoyi-service</artifactId>
    <version>3.9.1</version>
    <name>ruoyi-service</name>
    <description>若依自定义业务模块</description>

    <!-- 统一JDK版本，强制编译为JDK8，避免兼容问题 -->
    <properties>
        <java.version>8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

    <dependencies>
        <!-- 依赖若依公共模块（核心工具类、基础实体等），排除原生MyBatis避免与MP冲突 -->
        <dependency>
            <groupId>com.ruoyi</groupId>
           <artifactId>ruoyi-common</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.mybatis</groupId>
                    <artifactId>mybatis</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.mybatis.spring.boot</groupId>
                    <artifactId>mybatis-spring-boot-starter</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- MyBatis-Plus核心依赖（兼容JDK8，简化CRUD操作，无需手动写SQL） -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.5.3.1</version>
        </dependency>

        <!-- Lombok（简化实体类，自动生成get/set/toString等方法，减少冗余代码） -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
           <scope>provided</scope> <!-- 编译时生效，运行时不依赖 -->
        </dependency>

        <!-- Spring Web（提供RESTful接口能力，支持HTTP请求处理） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 单元测试依赖（可选，用于模块内接口/方法测试） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- 编译插件，强制指定JDK8编译 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <!-- 源码编译版本 -->
                    <!-- 生成字节码版本 -->
                    <target>8</target>
                    <!-- 编码格式 -->
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

1.3 注册模块到根工程

需在根工程的pom.xml中声明自定义模块，确保Maven打包时能识别该模块：

xml 复制代码

<modules>
    <module>ruoyi-admin</module>
    <module>ruoyi-framework</module>
    <module>ruoyi-system</module>
    <module>ruoyi-quartz</module>
    <module>ruoyi-generator</module>
    <module>ruoyi-common</module>
    <module>ruoyi-service</module> <!-- 新增自定义模块 -->
</modules>

1.4 让ruoyi-admin加载自定义模块

ruoyi-admin是项目的启动模块，需添加对自定义模块的依赖，才能扫描到自定义模块的Controller、Service等组件：

xml 复制代码

<dependencies>
    <!-- 原有依赖保持不变 -->
    ...
    
    <!-- 新增：依赖自定义业务模块 -->
    <dependency>
        <groupId>com.ruoyi</groupId>
        <artifactId>ruoyi-service</artifactId>
    </dependency>
</dependencies>

1.5 配置模块专属配置文件

为自定义模块创建专属配置文件，隔离全局配置，便于模块独立维护：

在ruoyi-service/src/main/resources目录下，右键「New→File」，新建文件application-service.yml。
写入以下配置（仅作用于当前模块，核心配置MyBatis-Plus与日志）：

YAML 复制代码

# ========== ruoyi-service模块专用配置 ==========
# MyBatis-Plus配置，需要手动在主配置中引入
mybatis-plus:
  # 配置mapper.xml文件路径
  mapper-locations: classpath:mapper/**/*.xml
  # 配置类型别名的包路径
  type-aliases-package: com.ruoyi.service.domain
  # 配置
  configuration:
    # 开启驼峰命名转换，_自动转Java驼峰命名
    map-underscore-to-camel-case: true
    # 开启SQL日志打印，开发环境建议开启
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    # 配置本地缓存作用域，避免缓存问题
    local-cache-scope: STATEMENT
    # 配置超时时间
    default-statement-timeout: 30
  # 全局配置
  global-config:
    banner: false # 关闭MP启动banner
    db-config:
      # 主键策略：MySQL使用自增
      id-type: AUTO
      # 逻辑删除配置，对应数据库的del_flag字段
      logic-delete-field: delFlag
      logic-delete-value: 1
      logic-not-delete-value: 0
      # 字段插入策略：非空字段才插入
      insert-strategy: NOT_NULL
      update-strategy: NOT_NULL

# ========== 其他配置建议 ==========
# 这些配置建议在ruoyi-admin的主配置文件中配置
# spring:
#   component-scan:
#     base-packages: com.ruoyi.service
#   main:
#     allow-bean-definition-overriding: true

# ========== 日志配置建议 ==========
# logging:
#   level:
#     com.ruoyi.service.mapper: debug
#     com.baomidou.mybatisplus: warn
#     org.springframework: warn

1.6 添加MyBatis-Plus配置类

配置类用于扫描当前模块的Mapper接口、注册分页插件等核心功能，确保MyBatis-Plus正常工作：

在ruoyi-service模块下创建包结构：src/main/java/com/ruoyi/service/config（右键「New→Package」，逐层创建）。
在config包下新建MyBatisPlusConfig.java：

Java 复制代码

package com.ruoyi.service.config;

import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import javax.sql.DataSource;

/**
 * 仅ruoyi-service模块的MyBatis-Plus配置类
 * 作用：扫描当前模块Mapper、配置分页插件
 */
@Configuration
// 仅扫描当前模块的Mapper接口（避免和其他模块冲突）
@MapperScan("com.ruoyi.service.mapper")
@ConditionalOnBean(DataSource.class)
public class MyBatisPlusConfig {

    /**
     * 配置MP分页插件（必须，否则分页功能失效）
     */
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 适配MySQL的分页插件
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

2.1 前置配置：基础权限体系搭建（含字典、菜单）

在使用若依代码生成器生成业务代码前，需先完成基础权限体系搭建，核心包括系统管理下的字典管理（业务枚举项配置）、菜单管理（业务模块菜单框架搭建），以及用户管理、角色管理、部门管理、岗位管理的基础配置（用户，角色，部门，岗位在自己开发的项目中一般都存在可以直接使用若依里面的表然后系统管理员才有权限修改等操作）要理好之间的关系。完整的基础权限体系是若依框架开发的前置必要步骤，能确保生成的代码直接适配系统权限管控规则，避免后续因基础配置缺失导致功能异常或权限失控。

用户管理、角色管理、部门管理、岗位管理需要自己理清你项目需要用到哪些然后修改即可（很重要但是项目不同这个不一样无法介绍）

2.1 字典管理配置（以服务单状态为例）

sql 复制代码

CREATE TABLE `t_service` (
  `service_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '服务单ID',
  `service_no` VARCHAR(32) NOT NULL COMMENT '服务单号',
  `customer_id` BIGINT NOT NULL COMMENT '客户ID',
  `service_type` VARCHAR(16) DEFAULT NULL COMMENT '服务类型',
  `service_status` VARCHAR(16) DEFAULT '0' COMMENT '服务状态（0=待处理 1=处理中 2=已完成）',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` CHAR(1) DEFAULT '0' COMMENT '删除标志（0=正常 1=删除）',
  PRIMARY KEY (`service_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='服务单表';

业务模块中若存在枚举类型字段（如服务单状态、服务类型），需先在字典管理中配置对应字典项，生成代码时可直接关联字典，实现页面下拉选择、状态文本转换等功能。以下是服务单状态字典的配置步骤：

登录若依后台系统，通过左侧导航栏展开「系统管理」→「字典管理」，点击页面右上角「新增」按钮，进入字典类型添加页面。
配置字典类型基础信息：配置项填写值说明字典名称服务单状态字典的直观名称，用于后台管理识别字典类型service_status字典唯一标识，需与实体类字段注解对应（后续生成代码时关联），格式规范为「业务模块_字段名」状态正常启用该字典类型备注服务单状态字典（0=待处理 1=处理中 2=已完成）补充字典用途，便于后期维护
添加字典数据项：保存字典类型后，点击该字典类型右侧的「字典数据」按钮，进入字典项配置页面，点击「新增」按钮依次添加以下数据：字典标签字典值排序状态，待处理 0，处理中 1 ，已完成2
验证：返回字典管理列表页，确认「service_status」字典类型及对应数据项已正常保存。

2.1.2 菜单管理前置配置（完整搭建业务模块菜单框架）

菜单管理的完整配置需在代码生成前完成，形成完整的"一级菜单+子菜单"结构，确保生成的代码路由 能直接与菜单对应 ，权限控制正常生效。配置需遵循"先建一级菜单、再建子菜单"的逻辑，详细步骤如下：

进入菜单配置页面：通过左侧导航栏展开「系统管理」→「菜单管理」，点击页面右上角「新增」按钮。
配置一级菜单基础信息 （服务单管理）：

2.2 代码生成：使用若依生成器一键生成CRUD代码

完成字典管理和基础菜单配置后，即可使用若依自带的代码生成器一键生成Controller、Service、Mapper、实体类等基础代码，大幅减少重复开发工作。代码生成器可直接关联已配置的字典 ，生成适配的页面下拉选择组件和数据转换逻辑。

若依自带的代码生成器可一键生成Controller、Service、Mapper、实体类等基础代码，大幅减少重复开发工作，需先配置再使用。

2.1 配置代码生成器

打开配置文件：ruoyi-generator/src/main/resources/generator.yml。
修改配置（适配自定义模块ruoyi-service）：

yaml 复制代码

 gen:
 	# 生成代码的作者（会显示在代码注释中，便于后期维护）
  author: 张三
  # 生成代码的基础包路径（必须与自定义模块的包路径一致）
  packageName: com.ruoyi.service
  # 是否自动去除表前缀（false=保留前缀，true=去除；如t_service→Service）
  autoRemovePre: false
  # 表前缀（仅autoRemovePre=true时生效，多个前缀用逗号分隔）
  tablePrefix: sys_,t_
  # 是否允许覆盖本地已存在的文件（false=禁止覆盖，避免误删自定义代码；true=强制覆盖）
  allowOverwrite: false

3.修改 ruoyi-generator/src/main/resources/xml/mapper.xml.vm成下面的

xml 复制代码

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="${packageName}.mapper.${ClassName}Mapper">

    <resultMap type="${packageName}.domain.${ClassName}" id="${ClassName}Result">
        #foreach ($column in $columns)
            <result property="${column.javaField}"    column="${column.columnName}"    />
        #end
    </resultMap>

    <sql id="select${ClassName}Vo">
        select #foreach($column in $columns) $column.columnName#if($foreach.count != $columns.size()),#end#end from ${tableName}
    </sql>

    <select id="select${ClassName}List" parameterType="${packageName}.domain.${ClassName}" resultMap="${ClassName}Result">
        <include refid="select${ClassName}Vo"/>
        <where>
            #foreach($column in $columns)
                #set($queryType=$column.queryType)
                #set($javaField=$column.javaField)
                #set($javaType=$column.javaType)
                #set($columnName=$column.columnName)
                #if($column.query && $queryType == "EQ")
                    <if test="$javaField != null #if($javaType == 'String' ) and $javaField != ''#end"> and $columnName = #{$javaField}</if>
                #end
            #end
        </where>
    </select>

    <select id="select${ClassName}By${pkColumn.capJavaField}" parameterType="${pkColumn.javaType}" resultMap="${ClassName}Result">
        <include refid="select${ClassName}Vo"/>
        where ${pkColumn.columnName} = #{${pkColumn.javaField}}
    </select>

    <insert id="insert${ClassName}" parameterType="${packageName}.domain.${ClassName}" #if($pkColumn.increment) useGeneratedKeys="true" keyProperty="${pkColumn.javaField}"#end>
        insert into ${tableName}
        <trim prefix="(" suffix=")" suffixOverrides=",">
            #foreach($column in $columns)
                #if($column.columnName != $pkColumn.columnName || !$pkColumn.increment)
                    <if test="$column.javaField != null #if($column.javaType == 'String' ) and $column.javaField != ''#end">$column.columnName,</if>
                #end
            #end
        </trim>
        <trim prefix="values (" suffix=")" suffixOverrides=",">
            #foreach($column in $columns)
                #if($column.columnName != $pkColumn.columnName || !$pkColumn.increment)
                    <if test="$column.javaField != null #if($column.javaType == 'String' ) and $column.javaField != ''#end">#{$column.javaField},</if>
                #end
            #end
        </trim>
    </insert>

    <update id="update${ClassName}" parameterType="${packageName}.domain.${ClassName}">
        update ${tableName}
        <trim prefix="SET" suffixOverrides=",">
            #foreach($column in $columns)
                #if($column.columnName != $pkColumn.columnName)
                    <if test="$column.javaField != null #if($column.javaType == 'String' ) and $column.javaField != ''#end">$column.columnName = #{$column.javaField},</if>
                #end
            #end
        </trim>
        where ${pkColumn.columnName} = #{${pkColumn.javaField}}
    </update>

    <delete id="delete${ClassName}By${pkColumn.capJavaField}" parameterType="${pkColumn.javaType}">
        delete from ${tableName} where ${pkColumn.columnName} = #{${pkColumn.javaField}}
    </delete>

    <delete id="delete${ClassName}By${pkColumn.capJavaField}s" parameterType="String">
        delete from ${tableName} where ${pkColumn.columnName} in
        <foreach item="${pkColumn.javaField}" collection="array" open="(" separator="," close=")">
            #{${pkColumn.javaField}}
        </foreach>
    </delete>
</mapper>

2.2 准备业务数据库表（模拟数据库表示例表）

代码生成器基于数据库表生成代码，需先创建业务表。以「服务单管理」为例，执行以下SQL创建t_service表：

sql 复制代码

CREATE TABLE `t_service` (
  `service_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '服务单ID',
  `service_no` VARCHAR(32) NOT NULL COMMENT '服务单号',
  `customer_id` BIGINT NOT NULL COMMENT '客户ID',
  `service_type` VARCHAR(16) DEFAULT NULL COMMENT '服务类型',
  `service_status` VARCHAR(16) DEFAULT '0' COMMENT '服务状态（0=待处理 1=处理中 2=已完成）',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` CHAR(1) DEFAULT '0' COMMENT '删除标志（0=正常 1=删除）',
  PRIMARY KEY (`service_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='服务单表';

INSERT INTO `t_service` (
  `service_no`, 
  `customer_id`, 
  `service_type`, 
  `service_status`, 
  `create_time`, 
  `update_time`, 
  `del_flag`
) VALUES
-- 待处理状态
('SRV2025122300001', 10001, 'REPAIR', '0', '2025-12-20 09:15:30', '2025-12-20 09:15:30', '0'),
('SRV2025122300002', 10002, 'CONSULT', '0', '2025-12-21 10:20:15', '2025-12-21 10:20:15', '0'),
('SRV2025122300003', 10003, 'REFUND', '0', '2025-12-22 14:30:45', '2025-12-22 14:30:45', '0'),
-- 处理中状态
('SRV2025122300004', 10001, 'REPAIR', '1', '2025-12-19 08:40:20', '2025-12-23 11:25:10', '0'),
('SRV2025122300005', 10004, 'CONSULT', '1', '2025-12-18 15:10:50', '2025-12-23 09:10:30', '0'),
('SRV2025122300006', 10005, 'INSTALL', '1', '2025-12-17 11:05:15', '2025-12-22 16:40:25', '0'),
-- 已完成状态
('SRV2025122300007', 10002, 'REPAIR', '2', '2025-12-15 09:30:00', '2025-12-20 17:15:40', '0'),
('SRV2025122300008', 10003, 'REFUND', '2', '2025-12-14 13:20:30', '2025-12-19 10:05:10', '0'),
('SRV2025122300009', 10006, 'INSTALL', '2', '2025-12-10 10:15:20', '2025-12-15 14:30:50', '0'),
-- 已删除的记录（模拟软删除）
('SRV2025122300010', 10007, 'CONSULT', '0', '2025-12-08 16:45:10', '2025-12-10 08:20:15', '1');

注意：表结构需遵循若依规范，如逻辑删除字段统一为del_flag，时间字段统一为create_time、update_time。

2.3 后台生成代码（可视化操作）

确保ruoyi-admin模块已启动，登录若依后台系统。
进入「系统工具 → 代码生成」菜单（左侧导航栏）。
点击「导入」按钮，在弹出的窗口中选择t_service表，点击「确定」（若未显示表，检查数据库连接是否正确）。
点击t_service表右侧的「编辑」按钮，补充生成配置：

配置项填写值说明包名com.ruoyi.service与自定义模块包路径一致模块名service与模块名称一致，用于生成接口路径、前端路由业务名service与表名前缀一致，用于生成类名前缀功能名服务单管理自定义，显示在代码注释、前端页面中作者张三与generator.yml中的author一致