RuoYi

https://github.com/yangzongzhuan/ruoyi-vue
Admin
RuoYi Vue is an open-source rapid development framework based on Spring Boot and Vue.js, offering...
Tokens:42,108
Snippets:436
Trust Score:9.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize and Run Development Environment

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/ruoyi-ui/README.md

Commands to clone the repository, install dependencies using a mirror registry, and start the local development server.

```bash
# 克隆项目
git clone https://gitee.com/y_project/RuoYi-Vue

# 进入项目目录
cd ruoyi-ui

# 安装依赖
npm install

# 建议不要直接使用 cnpm 安装依赖，会有各种诡异的 bug。可以通过如下操作解决 npm 下载速度慢的问题
npm install --registry=https://registry.npmmirror.com

# 启动服务
npm run dev
```

--------------------------------

### Pagination Query Example

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

Example of a GET request utilizing standard pagination and sorting parameters.

```http
GET /system/user/list?pageNum=1&pageSize=20&orderByColumn=createTime&isAsc=desc
```

--------------------------------

### GET /getRouters

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

获取当前用户可访问的菜单和路由信息，用于前端动态构建菜单。

```APIDOC
## GET /getRouters

### Description
获取当前用户可访问的菜单和路由信息，用于前端动态构建菜单。

### Method
GET

### Endpoint
/getRouters

### Request Headers
- **Authorization** (String) - Required - 需包含有效的JWT令牌

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (String) - 返回消息
- **data** (List<RouterVo>) - 路由对象列表

#### Response Example
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "name": "System",
      "path": "system",
      "meta": {
        "title": "系统管理",
        "icon": "system"
      }
    }
  ]
}
```

--------------------------------

### GET /getRouters

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

Retrieves the menu configuration for the current user.

```APIDOC
## GET /getRouters

### Description
Fetches the menu routes for the current user.

### Method
GET

### Endpoint
/getRouters
```

--------------------------------

### Implement Paginated List Endpoint

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/types.md

Usage example for returning paginated data using the TableDataInfo model.

```java
@GetMapping("/list")
public TableDataInfo list(SysUser user) {
    startPage();  // 开始分页
    List<SysUser> users = userService.selectUserList(user);
    return getDataTable(users);  // 自动包装为TableDataInfo
}
```

```json
{
  "total": 100,
  "rows": [
    { "userId": 1, "userName": "admin", ... },
    { "userId": 2, "userName": "user", ... }
  ],
  "code": 200,
  "msg": "操作成功"
}
```

--------------------------------

### GET /system/user/{userId}

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

根据用户ID获取用户详细信息及角色岗位。

```APIDOC
## GET /system/user/{userId}

### Description
根据用户ID获取用户详细信息及角色岗位。

### Method
GET

### Endpoint
/system/user/{userId}

### Parameters
#### Path Parameters
- **userId** (Long) - Optional - 用户ID，不传则返回新增用户的初始化数据

### Response
#### Success Response (200)
- **data** (SysUser) - 用户对象
- **roles** (List<SysRole>) - 所有可分配的角色列表
- **roleIds** (List<Long>) - 用户已分配的角色ID列表
- **posts** (List<SysPost>) - 所有可分配的岗位列表
- **postIds** (List<Long>) - 用户已分配的岗位ID列表
```

--------------------------------

### GET /system/user/{userId}

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

根据用户ID获取用户详细信息。

```APIDOC
## GET /system/user/{userId}

### Description
获取用户详细信息。

### Method
GET

### Endpoint
/system/user/{userId}

### Parameters
#### Path Parameters
- **userId** (long) - Required - 用户ID，不传则返回新增初始化数据

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **data** (object) - 用户详细信息
```

--------------------------------

### GET /getInfo

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

获取当前登录用户的详细信息、角色及权限标识。

```APIDOC
## GET /getInfo

### Description
获取当前登录用户的详细信息、角色、权限等。

### Method
GET

### Endpoint
/getInfo

### Request Headers
- **Authorization** (String) - Required - 需包含有效的JWT令牌

### Response
#### Success Response (200)
- **user** (SysUser) - 用户对象
- **roles** (Set<String>) - 用户角色标识集合
- **permissions** (Set<String>) - 用户权限标识集合
- **pwdChrtype** (String) - 密码字符类型规则
- **isDefaultModifyPwd** (boolean) - 是否必须修改初始密码
- **isPasswordExpired** (boolean) - 密码是否已过期

#### Response Example
{
  "code": 200,
  "msg": "操作成功",
  "user": {
    "userId": 1,
    "userName": "admin"
  },
  "roles": ["admin"],
  "permissions": ["*:*:*"],
  "pwdChrtype": "0",
  "isDefaultModifyPwd": false,
  "isPasswordExpired": false
}
```

--------------------------------

### GET /system/user/list

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

Retrieves a list of users.

```APIDOC
## GET /system/user/list

### Description
Retrieves a list of system users.

### Method
GET

### Endpoint
/system/user/list

### Parameters
#### Permissions
- system:user:list
```

--------------------------------

### GET /getRouters 响应示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

返回当前用户可访问的菜单和路由树状结构数据。

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "name": "System",
      "path": "system",
      "hidden": false,
      "component": "Layout",
      "redirect": "noRedirect",
      "meta": {
        "title": "系统管理",
        "icon": "system"
      },
      "children": [
        {
          "name": "User",
          "path": "user",
          "hidden": false,
          "component": "system/user/index",
          "meta": {
            "title": "用户管理",
            "icon": "user"
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### GET /getInfo 响应示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

返回当前用户的详细信息、角色列表及权限标识。

```json
{
  "code": 200,
  "msg": "操作成功",
  "user": {
    "userId": 1,
    "userName": "admin",
    "nickName": "管理员",
    "email": "admin@qq.com",
    "phonenumber": "15888888888",
    "sex": "0",
    "avatar": "/profile/avatar/2024/01/15/avatar.jpg",
    "status": "0",
    "deptId": 103
  },
  "roles": ["admin"],
  "permissions": ["*:*:*"],
  "pwdChrtype": "0",
  "isDefaultModifyPwd": false,
  "isPasswordExpired": false
}
```

--------------------------------

### Build Project for Deployment

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/ruoyi-ui/README.md

Commands to build the project for staging or production environments.

```bash
# 构建测试环境
npm run build:stage

# 构建生产环境
npm run build:prod
```

--------------------------------

### Create User

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

Add a new user to the system.

```json
{
  "userName": "newuser",
  "nickName": "新用户",
  "password": "password123",
  "deptId": 103,
  "email": "user@example.com",
  "phonenumber": "13800138000",
  "sex": "0",
  "roleIds": [2],
  "postIds": [1]
}
```

```json
{
  "code": 200,
  "msg": "新增成功"
}
```

```json
{
  "code": 500,
  "msg": "新增用户'newuser'失败，登录账号已存在"
}
```

--------------------------------

### Configure Multi-Datasource

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Set up dynamic data sources with primary and slave database connections.

```yaml
spring:
  datasource:
    dynamic:
      primary: master
      strict: false
      datasource:
        master:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://localhost:3306/ry-vue
          username: root
          password: password
        slave:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://localhost:3307/ry-vue-read
          username: root
          password: password
```

--------------------------------

### Configure Production Environment

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Production settings for Redis, database, and logging. Activate using spring.profiles.active=prod.

```yaml
# 生产环境配置，激活方式：spring.profiles.active=prod
spring:
  redis:
    host: redis-server.example.com
    password: production-password
  datasource:
    url: jdbc:mysql://db-server.example.com:3306/ry-vue
    username: prod_user
    password: prod_password
    
logging:
  level:
    com.ruoyi: info
    org.springframework: warn
    
token:
  secret: your-production-secret-key
  expireTime: 30
```

--------------------------------

### Configure Development Environment

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Development settings for local database and Redis access. Activate using spring.profiles.active=dev.

```yaml
# 开发环境配置，激活方式：spring.profiles.active=dev
spring:
  redis:
    host: localhost
    password:
  datasource:
    url: jdbc:mysql://localhost:3306/ry-vue
    username: root
    password: password
    
logging:
  level:
    com.ruoyi: debug
    org.springframework: debug
```

--------------------------------

### BaseController分页查询示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/核心框架服务.md

在控制器方法中调用startPage以自动处理分页参数，并使用getDataTable包装返回结果。

```java
public void startPage()
```

```java
@GetMapping("/list")
public TableDataInfo list(SysUser user) {
    startPage();  // 自动分页
    List<SysUser> list = userService.selectUserList(user);
    return getDataTable(list);
}
```

--------------------------------

### 登录控制器类签名

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

SysLoginController 类的定义，位于 com.ruoyi.web.controller.system 包下。

```java
@RestController
public class SysLoginController
```

--------------------------------

### GET /getInfo 请求头示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

获取用户信息时需在请求头中携带 Bearer 令牌。

```http
Authorization: Bearer {token}
```

--------------------------------

### 查看 Vuex 目录结构

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

展示了 ruoyi-ui/src/store/ 目录下的模块化组织结构。

```text
src/store/
├── index.js                 # Store入口
├── getters.js              # 全局getter
├── modules/
│   ├── user.js            # 用户模块
│   ├── permission.js      # 权限模块
│   ├── app.js            # 应用配置模块
│   ├── dict.js           # 字典数据模块
│   ├── settings.js       # 系统设置模块
│   ├── tagsView.js       # 标签页模块
│   └── lock.js           # 屏幕锁定模块
```

--------------------------------

### POST /system/user

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

Creates a new user.

```APIDOC
## POST /system/user

### Description
Adds a new user to the system.

### Method
POST

### Endpoint
/system/user

### Parameters
#### Permissions
- system:user:add
```

--------------------------------

### GET /captchaImage 响应示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

获取验证码图片 Base64 编码及对应的 UUID。

```json
{
  "code": 200,
  "msg": "操作成功",
  "imgUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA...",
  "uuid": "e258301b-b765-42db-a537-fa5f7ceb4960"
}
```

--------------------------------

### app/ToggleDevice

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

切换当前应用运行的设备类型。

```APIDOC
## ToggleDevice

### Description
切换设备类型。

### Method
Vuex Action (dispatch)

### Parameters
- **device** (String) - Required - 设备类型，可选值: "desktop" 或 "mobile"
```

--------------------------------

### 新增用户

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

插入新用户对象，返回受影响的行数。

```java
public int insertUser(SysUser user)
```

--------------------------------

### GET /getInfo

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

Retrieves the current user's information.

```APIDOC
## GET /getInfo

### Description
Retrieves information for the currently authenticated user.

### Method
GET

### Endpoint
/getInfo
```

--------------------------------

### GET /captchaImage

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a verification code image and its associated UUID.

```APIDOC
## GET /captchaImage

### Description
Retrieves a verification code image and UUID.

### Method
GET

### Endpoint
/captchaImage

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **msg** (string) - Success message
- **imgUrl** (string) - Base64 encoded image
- **uuid** (string) - UUID for the captcha

#### Response Example
{
  "code": 200,
  "msg": "操作成功",
  "imgUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA...",
  "uuid": "e258301b-b765-42db-a537-fa5f7ceb4960"
}
```

--------------------------------

### Override Spring Boot Configuration via Command Line

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Demonstrates how to modify application settings at runtime using command-line arguments.

```bash
# 修改服务器端口
java -jar ruoyi-admin.jar --server.port=8081

# 修改Redis地址
java -jar ruoyi-admin.jar --spring.redis.host=192.168.1.100

# 修改数据库连接
java -jar ruoyi-admin.jar --spring.datasource.url=jdbc:mysql://db-server:3306/ry-vue
```

--------------------------------

### Get User Details

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieve detailed information for a specific user by ID.

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "userName": "admin",
    "nickName": "管理员",
    "deptId": 103,
    "email": "admin@qq.com",
    "roles": [{"roleId": 1, "roleName": "管理员"}]
  },
  "roles": [
    {"roleId": 1, "roleName": "管理员"},
    {"roleId": 2, "roleName": "普通用户"}
  ],
  "roleIds": [1],
  "posts": [
    {"postId": 1, "postName": "董事长"}
  ],
  "postIds": [1]
}
```

--------------------------------

### 新增用户接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

新增系统用户，需要 system:user:add 权限。

```java
@PreAuthorize("@ss.hasPermi('system:user:add')")
@Log(title = "用户管理", businessType = BusinessType.INSERT)
@PostMapping
public AjaxResult add(@Validated @RequestBody SysUser user)
```

```json
{
  "code": 200,
  "msg": "新增用户成功"
}
```

--------------------------------

### 新增用户

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

实例化 SysUser 对象并设置必要属性，通过 userService.insertUser 执行持久化操作。

```java
SysUser newUser = new SysUser();
newUser.setUserName("testuser");
newUser.setNickName("测试用户");
newUser.setPassword("encrypted_password");
newUser.setDeptId(103L);
newUser.setEmail("test@example.com");
newUser.setStatus("0");
newUser.setRoleIds(new Long[]{2L, 3L});  // 分配角色

int result = userService.insertUser(newUser);
if (result > 0) {
    return AjaxResult.success("用户创建成功");
}
```

--------------------------------

### 修改用户信息

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

更新用户信息，返回受影响的行数。

```java
public int updateUser(SysUser user)
```

--------------------------------

### Login({ commit }, userInfo)

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

执行用户登录操作，调用后端接口获取令牌并保存至本地存储。

```APIDOC
## Login({ commit }, userInfo)

### Description
用户登录操作，用于验证凭据并获取访问令牌。

### Parameters
- **userInfo** (Object) - Required - 包含 username, password, code, uuid 的对象。

### Return
- Promise<void>

### Usage Example
this.$store.dispatch('Login', { username: 'admin', password: '...', code: '...', uuid: '...' });
```

--------------------------------

### Visualize Data Flow

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

A text-based representation of the request-response lifecycle within the RuoYi-Vue architecture.

```text
前端请求 → API客户端 → Http拦截器 → 后端控制器 
→ 参数验证 → 权限检查 → 业务逻辑 → 数据库 
→ Service处理 → 返回响应 → 前端解析
```

--------------------------------

### Configure MyBatis and PageHelper

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Sets up MyBatis mapper locations and PageHelper pagination parameters in application-mybatis.yml.

```yaml
mybatis:
  # MyBatis配置文件位置
  config-location: classpath:mybatis/mybatis-config.xml
  # mapper文件位置
  mapper-locations: classpath:mybatis/mapper/**/*.xml
  # 类型别名扫描包
  type-aliases-package: com.ruoyi.system.domain,com.ruoyi.system.domain.vo

# PageHelper分页配置
pagehelper:
  helper-dialect: mysql
  reasonable: true              # 启用分页合理化
  support-methods-arguments: true
  params: count=countSql
```

--------------------------------

### 查询用户列表

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

通过创建 SysUser 查询对象并设置过滤条件，调用 userService.selectUserList 进行分页查询。

```java
// 分页查询第1页，每页10条，用户名模糊查询"admin"
SysUser query = new SysUser();
query.setUserName("admin");
List<SysUser> users = userService.selectUserList(query);
```

--------------------------------

### POST /system/user

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

新增系统用户。

```APIDOC
## POST /system/user

### Description
新增系统用户。

### Method
POST

### Endpoint
/system/user

### Parameters
#### Request Body
- **userName** (String) - Required - 登录用户名，长度3-64
- **nickName** (String) - Required - 用户昵称，长度2-30
- **email** (String) - Optional - 用户邮箱
- **phonenumber** (String) - Optional - 手机号码
- **sex** (String) - Optional - 性别（0=男，1=女，2=未知）
- **password** (String) - Required - 初始密码
- **deptId** (Long) - Required - 部门ID
- **roleIds** (Long[]) - Required - 角色ID数组
- **postIds** (Long[]) - Optional - 岗位ID数组
- **status** (String) - Optional - 账户状态（0=正常，1=停用）

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (String) - 返回消息

#### Response Example
{
  "code": 200,
  "msg": "新增用户成功"
}
```

--------------------------------

### POST /system/user

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

新增系统用户。

```APIDOC
## POST /system/user

### Description
新增用户。

### Method
POST

### Endpoint
/system/user

### Request Body
- **userName** (string) - Required - 用户名
- **nickName** (string) - Required - 昵称
- **password** (string) - Required - 密码
- **deptId** (long) - Required - 部门ID
- **email** (string) - Optional - 邮箱
- **phonenumber** (string) - Optional - 手机号
- **sex** (string) - Optional - 性别
- **roleIds** (array) - Optional - 角色ID列表
- **postIds** (array) - Optional - 岗位ID列表

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (string) - 提示信息
```

--------------------------------

### 导入用户数据接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

从Excel文件导入用户数据，需要 system:user:import 权限。

```java
@Log(title = "用户管理", businessType = BusinessType.IMPORT)
@PreAuthorize("@ss.hasPermi('system:user:import')")
@PostMapping("/importData")
public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception
```

```json
{
  "code": 200,
  "msg": "成功导入10条用户数据，失败0条"
}
```

--------------------------------

### 获取字典数据

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

通过 dispatch 调用 Action 获取字典数据，或直接从 Store 状态中读取缓存数据。

```javascript
// 在组件中获取字典数据
this.$store.dispatch('dict/GetDict', 'sys_user_sex').then(res => {
  this.options = res
})

// 或使用缓存的字典数据
const sexDict = this.$store.state.dict.dict['sys_user_sex']
```

--------------------------------

### 使用注解进行权限检查

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

通过 @PreAuthorize 注解在 Controller 方法上限制访问权限。

```java
@PreAuthorize("@ss.hasPermi('system:user:resetPwd')")
@PutMapping("/resetPwd")
public AjaxResult resetPwd(@RequestBody SysUser user) {
    // 只有拥有system:user:resetPwd权限的用户才能调用此方法
}
```

--------------------------------

### Inspect Server Logs via CLI

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/errors.md

Use standard Linux commands to monitor application logs and search for database-related errors.

```bash
# 查看服务器日志
tail -f logs/ruoyi.log

# 查看数据库错误
grep -i error logs/ruoyi.log
```

--------------------------------

### 重置用户密码

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

使用 SecurityUtils 对新密码进行加密，并更新用户记录。

```java
SysUser user = new SysUser();
user.setUserId(userId);
user.setPassword(SecurityUtils.encryptPassword("newPassword"));
userService.updateUser(user);
```

--------------------------------

### SysLoginService.login(String username, String password, String code, String uuid)

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/核心框架服务.md

执行用户登录验证，验证凭据与验证码，并返回 JWT 令牌。

```APIDOC
## login(String username, String password, String code, String uuid)

### Description
用户登录接口，用于验证用户身份、检查账户状态、校验验证码并生成 JWT 令牌。

### Parameters
- **username** (String) - Required - 用户名
- **password** (String) - Required - 密码（MD5加密）
- **code** (String) - Required - 验证码
- **uuid** (String) - Required - 验证码UUID

### Returns
- **String** - JWT 令牌

### Exceptions
- UserNotExistsException: 用户不存在
- UserDisabledException: 用户被禁用
- UserPasswordNotMatchException: 密码错误
- UserPasswordRetryLimitExceededException: 密码错误次数超限
- CaptchaException: 验证码无效或过期
```

--------------------------------

### POST /login 请求体示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

用户登录接口的 JSON 请求体，包含用户名、密码、验证码及 UUID。

```json
{
  "username": "admin",
  "password": "admin123",
  "code": "1234",
  "uuid": "e258301b-b765-42db-a537-fa5f7ceb4960"
}
```

--------------------------------

### 获取用户列表接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

分页查询用户列表，需要 system:user:list 权限。

```java
@PreAuthorize("@ss.hasPermi('system:user:list')")
@GetMapping("/list")
public TableDataInfo list(SysUser user)
```

```json
{
  "code": 200,
  "msg": "操作成功",
  "total": 100,
  "rows": [
    {
      "userId": 1,
      "userName": "admin",
      "nickName": "管理员",
      "email": "admin@qq.com",
      "phonenumber": "15888888888",
      "sex": "0",
      "status": "0",
      "deptId": 103,
      "createTime": "2024-01-15 10:30:00"
    }
  ]
}
```

--------------------------------

### 实现单文件上传接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

通过MultipartFile接收文件，验证扩展名后保存至指定目录，并返回访问路径。

```java
@PostMapping("/upload")
public AjaxResult upload(@RequestParam MultipartFile file) throws IOException {
    if (file.isEmpty()) {
        return error("上传文件为空");
    }
    
    // 验证文件类型
    String fileName = file.getOriginalFilename();
    String fileExtension = fileName.substring(fileName.lastIndexOf(".") + 1).toLowerCase();
    List<String> allowedExtensions = Arrays.asList("jpg", "jpeg", "png", "gif");
    
    if (!allowedExtensions.contains(fileExtension)) {
        return error("不支持的文件类型");
    }
    
    // 保存文件
    String uploadPath = RuoYiConfig.getProfile() + "/upload/" + LocalDate.now();
    File uploadDir = new File(uploadPath);
    if (!uploadDir.exists()) {
        uploadDir.mkdirs();
    }
    
    String newFileName = IdUtils.fastUUID() + "." + fileExtension;
    File targetFile = new File(uploadDir, newFileName);
    file.transferTo(targetFile);
    
    // 返回文件访问URL
    String fileUrl = "/profile/upload/" + LocalDate.now() + "/" + newFileName;
    return success(fileUrl);
}
```

--------------------------------

### 刷新令牌有效期

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/核心框架服务.md

定义refreshToken方法签名，用于更新Redis缓存中的用户过期时间。

```java
public void refreshToken(LoginUser loginUser)
```

--------------------------------

### POST /system/user/importTemplate

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

获取用户导入模板。

```APIDOC
## POST /system/user/importTemplate

### Description
获取用户导入模板。

### Method
POST

### Endpoint
/system/user/importTemplate

### Response
#### Success Response (200)
- **Content-Type** (string) - application/vnd.ms-excel
```

--------------------------------

### Service层异常捕获

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/errors.md

在Service实现类中捕获底层异常并转换为自定义的ServiceException抛出。

```java
@Service
public class SysUserServiceImpl implements ISysUserService {
    
    public int insertUser(SysUser user) {
        try {
            // 检查唯一性
            if (!checkUserNameUnique(user)) {
                throw new DuplicateKeyException("用户名已存在");
            }
            
            return userMapper.insertUser(user);
        } catch (DuplicateKeyException e) {
            throw new ServiceException("用户名已存在");
        } catch (Exception e) {
            log.error("新增用户异常", e);
            throw new ServiceException("新增用户失败");
        }
    }
}
```

--------------------------------

### 创建 Controller 控制器

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

定义 RESTful API 接口，通过 @PreAuthorize 进行权限控制，并使用 @Log 记录操作日志。

```java
@RestController
@RequestMapping("/system/product")
public class SysProductController extends BaseController {
    @Autowired
    private ISysProductService productService;

    @PreAuthorize("@ss.hasPermi('system:product:list')")
    @GetMapping("/list")
    public TableDataInfo list(SysProduct product) {
        startPage();
        List<SysProduct> list = productService.selectProductList(product);
        return getDataTable(list);
    }

    @PreAuthorize("@ss.hasPermi('system:product:add')")
    @Log(title = "产品管理", businessType = BusinessType.INSERT)
    @PostMapping
    public AjaxResult add(@Validated @RequestBody SysProduct product) {
        product.setCreateBy(getUsername());
        return toAjax(productService.insertProduct(product));
    }

    @PreAuthorize("@ss.hasPermi('system:product:edit')")
    @Log(title = "产品管理", businessType = BusinessType.UPDATE)
    @PutMapping
    public AjaxResult edit(@Validated @RequestBody SysProduct product) {
        product.setUpdateBy(getUsername());
        return toAjax(productService.updateProduct(product));
    }

    @PreAuthorize("@ss.hasPermi('system:product:remove')")
    @Log(title = "产品管理", businessType = BusinessType.DELETE)
    @DeleteMapping("/{productIds}")
    public AjaxResult remove(@PathVariable Long[] productIds) {
        return toAjax(productService.deleteProductByIds(productIds));
    }
}
```

--------------------------------

### PUT /system/user

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

修改用户信息。

```APIDOC
## PUT /system/user

### Description
修改用户信息。

### Method
PUT

### Endpoint
/system/user

### Parameters
#### Request Body
- **userId** (Long) - Required - 用户ID
- **userName** (String) - Required - 登录用户名
- **nickName** (String) - Required - 用户昵称
- **email** (String) - Optional - 邮箱
- **phonenumber** (String) - Optional - 手机号
- **sex** (String) - Optional - 性别
- **deptId** (Long) - Required - 部门ID
- **roleIds** (Long[]) - Required - 角色ID数组
- **postIds** (Long[]) - Optional - 岗位ID数组
- **status** (String) - Optional - 账户状态

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (String) - 返回消息

#### Response Example
{
  "code": 200,
  "msg": "修改用户成功"
}
```

--------------------------------

### PUT /system/user

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

修改用户信息。

```APIDOC
## PUT /system/user

### Description
修改用户信息。

### Method
PUT

### Endpoint
/system/user

### Request Body
- **userId** (long) - Required - 用户ID
- **userName** (string) - Required - 用户名
- **nickName** (string) - Required - 昵称
- **deptId** (long) - Required - 部门ID
- **email** (string) - Optional - 邮箱
- **phonenumber** (string) - Optional - 手机号
- **sex** (string) - Optional - 性别
- **roleIds** (array) - Optional - 角色ID列表
- **postIds** (array) - Optional - 岗位ID列表

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (string) - 提示信息
```

--------------------------------

### 调用 Login Action

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

演示如何通过 dispatch 调用登录操作并处理回调。

```javascript
// 使用示例
this.$store.dispatch('Login', {
  username: this.username,
  password: this.password,
  code: this.captcha.code,
  uuid: this.captcha.uuid
}).then(() => {
  // 登录成功
  this.$router.push({ path: this.$route.query.redirect || '/' })
}).catch(error => {
  // 处理错误
})
```

--------------------------------

### 查询用户岗位组

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

根据用户名获取用户所属的岗位组，返回逗号分隔的字符串。

```java
public String selectUserPostGroup(String userName)
```

--------------------------------

### 查询用户角色组

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

根据用户名获取用户所属的角色组，返回逗号分隔的字符串。

```java
public String selectUserRoleGroup(String userName)
```

--------------------------------

### 查询用户列表

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

根据 SysUser 对象提供的条件查询用户列表。

```java
public List<SysUser> selectUserList(SysUser user)
```

--------------------------------

### 实现 Service 层

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

定义业务逻辑接口及其实现类，处理数据持久化前的业务逻辑。

```java
// ISysProductService.java
public interface ISysProductService {
    List<SysProduct> selectProductList(SysProduct product);
    SysProduct selectProductById(Long productId);
    int insertProduct(SysProduct product);
    int updateProduct(SysProduct product);
    int deleteProductByIds(Long[] productIds);
}

// SysProductServiceImpl.java
@Service
public class SysProductServiceImpl implements ISysProductService {
    @Autowired
    private SysProductMapper productMapper;

    @Override
    public List<SysProduct> selectProductList(SysProduct product) {
        return productMapper.selectProductList(product);
    }

    @Override
    public int insertProduct(SysProduct product) {
        product.setCreateTime(DateUtils.getNowDate());
        return productMapper.insertProduct(product);
    }

    @Override
    public int updateProduct(SysProduct product) {
        product.setUpdateTime(DateUtils.getNowDate());
        return productMapper.updateProduct(product);
    }

    @Override
    public int deleteProductByIds(Long[] productIds) {
        return productMapper.deleteProductByIds(productIds);
    }
}
```

--------------------------------

### 获取用户信息接口定义

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

获取当前登录用户详细信息、角色及权限的接口方法。

```java
@GetMapping("getInfo")
public AjaxResult getInfo()
```

--------------------------------

### register(data)

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端API客户端.md

用户注册接口。

```APIDOC
## register(data)

### Description
用户注册接口。

### Parameters
- **data** (Object) - Required - 注册信息对象，包含username, password, nickName, email, phonenumber
```

--------------------------------

### 实现Excel数据导入

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

利用ExcelUtil工具类解析上传的Excel文件，并对每行数据进行校验与入库处理。

```java
@PostMapping("/importExcel")
public AjaxResult importExcel(@RequestParam MultipartFile file) throws Exception {
    ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
    List<SysUser> userList = util.importExcel(file.getInputStream());
    
    String msg = "";
    int successNum = 0;
    int failNum = 0;
    
    for (SysUser user : userList) {
        try {
            // 验证用户数据
            if (StringUtils.isEmpty(user.getUserName())) {
                throw new Exception("用户名不能为空");
            }
            
            // 新增用户
            userService.insertUser(user);
            successNum++;
        } catch (Exception e) {
            failNum++;
            msg += user.getUserName() + "导入失败：" + e.getMessage() + "；";
        }
    }
    
    msg = "导入成功" + successNum + "条，失败" + failNum + "条。" + msg;
    return success(msg);
}
```

--------------------------------

### 异步同步用户数据到第三方系统

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

在 Service 层更新数据库后，使用 AsyncManager 异步调用第三方接口，避免阻塞主线程。

```java
@Service
public class SysUserServiceImpl implements ISysUserService {
    @Autowired
    private SysUserMapper userMapper;
    @Autowired
    private ThirdPartyApiService thirdPartyService;
    @Autowired
    private AsyncManager asyncManager;

    @Override
    public int updateUser(SysUser user) {
        // 1. 更新数据库
        int result = userMapper.updateUser(user);
        
        // 2. 异步同步到第三方系统
        if (result > 0) {
            asyncManager.execute(() -> {
                try {
                    thirdPartyService.syncUserInfo(user);
                } catch (Exception e) {
                    log.error("同步用户信息失败", e);
                    // 可选：记录同步失败日志
                }
            });
        }
        
        return result;
    }
}
```

--------------------------------

### 获取用户详细信息接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

根据用户ID获取详细信息及角色岗位，需要 system:user:query 权限。

```java
@PreAuthorize("@ss.hasPermi('system:user:query')")
@GetMapping(value = { "/", "/{userId}" })
public AjaxResult getInfo(@PathVariable(value = "userId", required = false) Long userId)
```

--------------------------------

### BaseController响应与用户信息获取示例

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/核心框架服务.md

提供success和error响应方法，以及获取当前登录用户信息的辅助方法。

```java
public AjaxResult success(Object data)
```

```java
public AjaxResult error(String msg)
```

```java
public String getUsername()
```

```java
public Long getUserId()
```

```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    user.setCreateBy(getUsername());
    user.setCreateTime(new Date());
    return toAjax(userService.insertUser(user));
}
```

--------------------------------

### ISysUserService 接口定义

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

用户业务层接口定义，位于 com.ruoyi.system.service 包下。

```java
public interface ISysUserService
```

--------------------------------

### 调用登录接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端API客户端.md

使用login函数进行用户登录，并在成功后处理返回的JWT令牌。

```javascript
// 调用示例
login('admin', 'admin123', '1234', 'uuid-xxx').then(res => {
  // res.token: JWT令牌
  localStorage.setItem('token', res.token)
}).catch(err => {
  // 处理错误
})
```

--------------------------------

### Configure Redis Connection Settings

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Defines the Redis server host, port, database index, and connection pool parameters for the Lettuce client.

```yaml
spring:
  data:
    redis:
      host: localhost          # Redis服务器地址
      port: 6379              # Redis服务器端口
      database: 0             # 数据库索引（0-15）
      password:               # 密码（无密码留空）
      timeout: 10s            # 连接超时时间
      lettuce:
        pool:
          min-idle: 0         # 连接池最小空闲连接
          max-idle: 8         # 连接池最大空闲连接
          max-active: 8       # 连接池最大活跃连接
          max-wait: -1ms      # 最大等待时间（-1=无限）
```

--------------------------------

### POST /login

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/README.md

Authenticates a user and returns a JWT token.

```APIDOC
## POST /login

### Description
Authenticates the user with credentials.

### Method
POST

### Endpoint
/login
```

--------------------------------

### 修改用户接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

修改现有用户信息，需要 system:user:edit 权限。

```java
@PreAuthorize("@ss.hasPermi('system:user:edit')")
@Log(title = "用户管理", businessType = BusinessType.UPDATE)
@PutMapping
public AjaxResult edit(@Validated @RequestBody SysUser user)
```

```json
{
  "code": 200,
  "msg": "修改用户成功"
}
```

--------------------------------

### 获取导入模板接口

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

下载用户导入所需的Excel模板文件。

```java
@PostMapping("/importTemplate")
public void importTemplate(HttpServletResponse response)
```

--------------------------------

### SecurityUtils Methods

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/核心框架服务.md

A collection of static methods for user context and security operations.

```APIDOC
## SecurityUtils

### Description
Utility class for handling user authentication context and password security operations.

### Methods
- **getLoginUser()**: Returns the current logged-in user object.
- **getUserId()**: Returns the ID of the current user.
- **getUsername()**: Returns the username of the current user.
- **isAdmin(Long userId)**: Checks if the specified user ID has administrator privileges.
- **encryptPassword(String password)**: Encrypts a raw password string.
- **matchesPassword(String rawPassword, String encodedPassword)**: Verifies if a raw password matches an encoded password.
```

--------------------------------

### 用户注册数据对象

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端API客户端.md

register接口所需的注册信息对象结构。

```javascript
{
  username: "newuser",
  password: "password123",
  nickName: "新用户",
  email: "user@example.com",
  phonenumber: "13800138000"
}
```

--------------------------------

### Import Users

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/endpoints.md

Import user data from an Excel file.

```json
{
  "code": 200,
  "msg": "成功导入10条用户数据，失败0条"
}
```

--------------------------------

### tagsView/AddView

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

添加一个新的已访问标签页。

```APIDOC
## tagsView/AddView

### Description
添加已访问的标签页。

### Parameters
- **view** (Object) - Required - 包含 name, path, title 的视图对象

### Example
this.$store.dispatch('tagsView/AddView', {
  name: 'User',
  path: '/system/user',
  title: '用户管理'
})
```

--------------------------------

### POST /system/user/importData

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

导入Excel中的用户数据。

```APIDOC
## POST /system/user/importData

### Description
导入Excel中的用户数据。

### Method
POST

### Endpoint
/system/user/importData

### Parameters
#### Request Body
- **file** (MultipartFile) - Required - Excel文件
- **updateSupport** (boolean) - Optional - 是否更新已存在的用户（默认false）

### Response
#### Success Response (200)
- **code** (int) - 状态码
- **msg** (String) - 返回消息

#### Response Example
{
  "code": 200,
  "msg": "成功导入10条用户数据，失败0条"
}
```

--------------------------------

### 获取路由信息接口定义

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

获取当前用户可访问菜单和路由信息的接口方法。

```java
@GetMapping("getRouters")
public AjaxResult getRouters()
```

--------------------------------

### Configure File Upload Paths

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/configuration.md

Define the storage path for uploaded files, supporting Windows, Linux, or relative paths.

```yaml
ruoyi:
  # Windows
  profile: D:/ruoyi/uploadPath
  
  # Linux
  profile: /home/ruoyi/uploadPath
  
  # 相对路径
  profile: ./uploadPath
```

--------------------------------

### 后端登录认证流程

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/登录认证.md

后端处理登录请求的逻辑，包括验证码校验、用户身份验证及令牌生成。

```java
// 登录后生成令牌
public String login(String username, String password, String code, String uuid) {
    // 1. 验证验证码
    validateCaptcha(code, uuid);
    
    // 2. 验证用户名密码
    SysUser user = userService.selectUserByUserName(username);
    if (user == null || !passwordMatch(password, user.getPassword())) {
        throw new UserPasswordNotMatchException();
    }
    
    // 3. 创建登录用户对象
    LoginUser loginUser = new LoginUser(user, permissions);
    
    // 4. 生成令牌
    String token = tokenService.createToken(loginUser);
    
    // 5. 记录登录日志
    recordLoginLog(user);
    
    return token;
}

// 后续请求会在JwtAuthenticationTokenFilter中验证令牌
```

--------------------------------

### dict/GetDict

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/前端状态管理.md

获取指定类型的字典数据，支持缓存机制。

```APIDOC
## dict/GetDict

### Description
获取字典数据（如果未缓存则从服务器获取）。

### Parameters
- **dictType** (String) - Required - 字典类型，如"sys_user_sex"

### Returns
- Promise<Array> - 字典选项数组

### Example
this.$store.dispatch('dict/GetDict', 'sys_user_sex').then(res => {
  this.sexOptions = res
})
```

--------------------------------

### 执行异步耗时操作

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/常见开发场景.md

利用AsyncManager将耗时任务放入异步线程池执行，确保主线程能立即返回响应给用户。

```java
@Service
public class UserService {
    @Autowired
    private AsyncManager asyncManager;

    @PostMapping("/sendEmail")
    public AjaxResult sendEmail(String userId) {
        // 立即返回给用户
        asyncManager.execute(() -> {
            // 异步执行耗时操作
            try {
                Thread.sleep(5000);  // 模拟耗时操作
                mailService.sendEmail(userId);
                log.info("邮件发送成功");
            } catch (Exception e) {
                log.error("邮件发送失败", e);
            }
        });
        
        return success("邮件发送中，请稍候");
    }
}
```

--------------------------------

### 检查邮箱唯一性

Source: https://github.com/yangzongzhuan/ruoyi-vue/blob/master/_autodocs/api-reference/用户管理.md

校验邮箱是否在系统中唯一。

```java
public boolean checkEmailUnique(SysUser user)
```
Tokens:
Raw