# 【RuoYi-SpringBoot3-Pro】：Magic API 低代码开发

本文详细介绍 [RuoYi-SpringBoot3-Pro](https://github.com/undsky/RuoYi-SpringBoot3-Pro) 框架中集成的 Magic API 低代码开发平台，帮助开发者快速构建 REST API 接口。


> GitHub：`https://github.com/undsky/RuoYi-SpringBoot3-Pro`

## 一、什么是 Magic API？

[Magic API](https://www.ssssssss.org/magic-api/pages/quick/intro/) 是一个基于 Java 的接口快速开发框架，通过 Web 界面编写脚本即可完成接口开发，无需定义 Controller、Service、Mapper 等传统分层代码。

### 1.1 核心优势

| 特性 | 说明 |
|------|------|
| 可视化开发 | 通过 Web 界面编写接口，所见即所得 |
| 即时生效 | 接口修改后无需重启，立即生效 |
| 脚本语言 | 基于 Java 语法的脚本语言，学习成本低 |
| 数据库操作 | 内置强大的数据库操作 API |
| 多数据源 | 支持动态切换多个数据源 |
| 参数校验 | 内置参数校验功能 |
| 接口文档 | 自动生成接口文档 |
| 版本控制 | 支持接口历史记录和回滚 |

### 1.2 适用场景

- 快速原型开发
- 简单 CRUD 接口
- 数据查询报表
- 临时接口需求
- 低代码平台集成

## 二、项目集成

### 2.1 Maven 依赖

RuoYi-SpringBoot3-Pro 已集成 Magic API 2.2.2 版本：

```xml

<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-spring-boot-starter</artifactId>
    <version>2.2.2</version>
</dependency>


<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-redis</artifactId>
    <version>2.2.2</version>
</dependency>
```

### 2.2 配置文件

在 `application.yml` 中配置 Magic API：

```yaml
# Magic API 配置
# 官方文档：https://www.ssssssss.org/magic-api/pages/config/spring-boot/
magic-api:
  # Web 编辑器访问路径（生产环境建议设为 null 禁用）
  web: /magic/web
  
  # 编辑器配置文件
  editor-config: classpath:./magic-editor-config.js
  
  # 接口存储方式
  resource:
    type: database           # 存储类型：database（数据库）/ file（文件）
    tableName: magic_api_file  # 存储表名
  
  # 接口访问前缀
  prefix: /magic/api
  
  # 编辑器登录认证
  security:
    username: jyx            # 登录用户名
    password: jyx_692483     # 登录密码
  
  # 历史记录备份
  backup:
    enable: true             # 是否启用备份
    max-history: -1          # 最大历史记录数（-1 表示不限制）
    table-name: magic_backup_record  # 备份表名
  
  # 响应结果格式
  response: |- 
    {
      code: code,
      msg: message,
      data,
    }
```

### 2.3 编辑器主题配置

`magic-editor-config.js` 文件配置编辑器主题：

```javascript
var MAGIC_EDITOR_CONFIG = {
    theme: 'dark',  // 主题：dark（暗色）/ light（亮色）
}
```

### 2.4 安全配置

Magic API 接口默认放行，在 `SecurityConfig.java` 中配置：

```java
@Bean
public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception {
    httpSecurity
        .authorizeHttpRequests(auth -> auth
            // Magic API 接口放行
            .requestMatchers("/magic/**").permitAll()
            .anyRequest().authenticated()
        );
    return httpSecurity.build();
}
```

## 三、访问编辑器

### 3.1 访问地址

启动项目后，访问 Magic API 编辑器：

```
http://localhost:8087/magic/web
```

### 3.2 登录认证

使用配置文件中设置的账号密码登录：

- 用户名：`jyx`
- 密码：`jyx_692483`

### 3.3 编辑器界面

```
┌─────────────────────────────────────────────────────────────┐
│  Magic API Editor                                    [用户] │
├─────────────┬───────────────────────────────────────────────┤
│             │                                               │
│  接口列表    │              脚本编辑区                        │
│             │                                               │
│  📁 分组1    │  // 编写接口脚本                              │
│    └─ 接口1  │  var list = db.select("""                    │
│    └─ 接口2  │      SELECT * FROM sys_user                  │
│  📁 分组2    │  """)                                        │
│    └─ 接口3  │  return list                                 │
│             │                                               │
├─────────────┼───────────────────────────────────────────────┤
│  接口配置    │              执行结果                          │
│  请求方式    │  [                                            │
│  请求路径    │    {"userId": 1, "userName": "admin"},       │
│  请求参数    │    {"userId": 2, "userName": "test"}         │
│             │  ]                                            │
└─────────────┴───────────────────────────────────────────────┘
```

## 四、接口开发

### 4.1 创建第一个接口

1. 点击左侧「+」创建分组
2. 在分组下创建接口
3. 配置请求方式和路径
4. 编写脚本代码
5. 点击「执行」测试
6. 点击「保存」发布

### 4.2 基础语法

Magic API 使用类 Java 语法的脚本语言：

```javascript
// 变量定义
var name = "张三"
var age = 18

// 条件判断
if (age >= 18) {
    return "成年人"
} else {
    return "未成年人"
}

// 循环
var list = [1, 2, 3, 4, 5]
for (item in list) {
    print(item)
}

// 函数定义
var add = (a, b) => a + b
return add(1, 2)
```

### 4.3 获取请求参数

```javascript
// 获取 Query 参数：/api/user?name=张三&age=18
var name = name        // 直接使用参数名
var age = age

// 获取 Path 参数：/api/user/{id}
var userId = path.id

// 获取 Body 参数（JSON）
var user = body
var userName = body.userName

// 获取 Header
var token = header.Authorization

// 获取完整请求对象
var request = request
```

### 4.4 数据库操作

Magic API 内置强大的数据库操作 API：

```javascript
// 查询列表
var list = db.select("""
    SELECT * FROM sys_user WHERE status = '0'
""")

// 查询单条
var user = db.selectOne("""
    SELECT * FROM sys_user WHERE user_id = #{userId}
""")

// 带参数查询
var users = db.select("""
    SELECT * FROM sys_user 
    WHERE dept_id = #{deptId} 
    AND user_name LIKE CONCAT('%', #{keyword}, '%')
""")

// 分页查询
var page = db.page("""
    SELECT * FROM sys_user WHERE status = '0'
""")

// 插入数据
var result = db.insert("""
    INSERT INTO sys_user (user_name, nick_name, email) 
    VALUES (#{userName}, #{nickName}, #{email})
""")

// 更新数据
var result = db.update("""
    UPDATE sys_user SET nick_name = #{nickName} WHERE user_id = #{userId}
""")

// 删除数据
var result = db.delete("""
    DELETE FROM sys_user WHERE user_id = #{userId}
""")
```

### 4.5 链式查询

```javascript
// 使用链式 API 构建查询
var list = db.table('sys_user')
    .where()
    .eq('status', '0')
    .like('user_name', keyword)
    .orderBy('create_time desc')
    .page(pageNum, pageSize)
    .select()

// 插入
db.table('sys_user').insert({
    userName: '张三',
    nickName: '小张',
    email: 'zhangsan@example.com'
})

// 更新
db.table('sys_user')
    .where()
    .eq('user_id', 1)
    .update({
        nickName: '新昵称'
    })

// 删除
db.table('sys_user')
    .where()
    .eq('user_id', 1)
    .delete()
```

### 4.6 多数据源

```javascript
// 切换数据源
var list = db.slave.select("""
    SELECT * FROM other_table
""")

// 或使用 datasource 指定
var list = db.datasource('slave').select("""
    SELECT * FROM other_table
""")
```

## 五、接口鉴权

### 5.1 鉴权拦截器

RuoYi-SpringBoot3-Pro 实现了 Magic API 的请求拦截器，支持登录验证和权限校验：

```java
@Component
public class MagicApiRequestInterceptor implements RequestInterceptor {
    
    @Override
    public Object preHandle(ApiInfo info, MagicScriptContext context, 
            MagicHttpServletRequest request, MagicHttpServletResponse response) {
        
        // 获取接口配置的选项
        boolean needLogin = StringUtils.equals("true", info.getOptionValue(Options.REQUIRE_LOGIN));
        String role = info.getOptionValue(Options.ROLE);
        String permission = info.getOptionValue(Options.PERMISSION);
        
        // 需要角色或权限时，自动要求登录
        if (StringUtils.isNotBlank(role) || StringUtils.isNotBlank(permission)) {
            needLogin = true;
        }
        
        // 登录校验
        if (needLogin) {
            try {
                SecurityUtils.getLoginUser();
            } catch (Exception e) {
                return new JsonBean<>(401, "用户未登录");
            }
        }
        
        // 角色校验
        if (StringUtils.isNotBlank(role)) {
            if (!SecurityUtils.hasRole(role)) {
                return new JsonBean<>(403, "用户权限不足");
            }
        }
        
        // 权限校验
        if (StringUtils.isNotBlank(permission)) {
            if (!SecurityUtils.hasPermi(permission)) {
                return new JsonBean<>(403, "用户权限不足");
            }
        }
        
        return null;  // 返回 null 表示放行
    }
}
```

### 5.2 配置接口权限

在 Magic API 编辑器中，为接口配置权限选项：

| 选项 | 说明 | 示例值 |
|------|------|--------|
| `require_login` | 是否需要登录 | `true` / `false` |
| `role` | 需要的角色 | `admin` |
| `permission` | 需要的权限 | `system:user:list` |

**配置方式：**

1. 在编辑器中选择接口
2. 点击「选项」标签
3. 添加对应的选项配置

### 5.3 获取当前用户

在脚本中获取当前登录用户信息：

```javascript
import com.ruoyi.common.utils.SecurityUtils

// 获取当前用户 ID
var userId = SecurityUtils.getUserId()

// 获取当前用户名
var username = SecurityUtils.getUsername()

// 获取当前用户信息
var loginUser = SecurityUtils.getLoginUser()
var user = loginUser.getUser()
```

## 六、Redis 缓存

### 6.1 基础操作

Magic API 集成了 Redis 插件，可直接使用：

```javascript
// 设置缓存
redis.set('key', 'value')

// 设置缓存（带过期时间，单位秒）
redis.set('key', 'value', 3600)

// 获取缓存
var value = redis.get('key')

// 删除缓存
redis.del('key')

// 判断是否存在
var exists = redis.exists('key')

// 设置过期时间
redis.expire('key', 3600)
```

### 6.2 接口缓存示例

```javascript
// 先从缓存获取
var cacheKey = 'user:list:' + deptId
var list = redis.get(cacheKey)

if (list == null) {
    // 缓存不存在，查询数据库
    list = db.select("""
        SELECT * FROM sys_user WHERE dept_id = #{deptId}
    """)
    // 存入缓存，1小时过期
    redis.set(cacheKey, list, 3600)
}

return list
```

### 6.3 Hash 操作

```javascript
// 设置 Hash 字段
redis.hset('user:1', 'name', '张三')
redis.hset('user:1', 'age', 18)

// 获取 Hash 字段
var name = redis.hget('user:1', 'name')

// 获取所有字段
var user = redis.hgetAll('user:1')

// 删除 Hash 字段
redis.hdel('user:1', 'name')
```

## 七、高级特性

### 7.1 事务支持

```javascript
import db

// 开启事务
db.transaction(() => {
    db.update("""
        UPDATE account SET balance = balance - 100 WHERE user_id = 1
    """)
    db.update("""
        UPDATE account SET balance = balance + 100 WHERE user_id = 2
    """)
})
```

### 7.2 异步执行

```javascript
import async

// 异步执行
async.run(() => {
    // 耗时操作
    db.insert("""
        INSERT INTO log (content) VALUES ('异步日志')
    """)
})

return "请求已接收"
```

### 7.3 HTTP 请求

```javascript
import http

// GET 请求
var result = http.get('https://api.example.com/users')

// POST 请求
var result = http.post('https://api.example.com/users', {
    body: {
        name: '张三',
        age: 18
    }
})

// 带 Header 的请求
var result = http.get('https://api.example.com/users', {
    headers: {
        'Authorization': 'Bearer token'
    }
})
```

### 7.4 参数校验

```javascript
import assert

// 非空校验
assert.notNull(userId, '用户ID不能为空')
assert.notBlank(userName, '用户名不能为空')

// 条件校验
assert.isTrue(age >= 18, '年龄必须大于等于18')

// 正则校验
assert.regx(email, '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$', '邮箱格式不正确')
```

### 7.5 日志输出

```javascript
import log

log.info('这是一条信息日志')
log.warn('这是一条警告日志')
log.error('这是一条错误日志')
log.debug('这是一条调试日志')
```

## 八、实战示例

### 8.1 用户列表接口

```javascript
/**
 * 接口路径：GET /magic/api/user/list
 * 请求参数：pageNum, pageSize, userName, status
 */

// 参数处理
var pageNum = pageNum ?: 1
var pageSize = pageSize ?: 10

// 构建查询
var query = db.table('sys_user')
    .where()
    .eq('del_flag', '0')

// 动态条件
if (userName) {
    query.like('user_name', userName)
}
if (status) {
    query.eq('status', status)
}

// 分页查询
var page = query.orderBy('create_time desc')
    .page(pageNum, pageSize)
    .select()

return page
```

### 8.2 用户详情接口

```javascript
/**
 * 接口路径：GET /magic/api/user/{id}
 * 路径参数：id
 */

import assert

// 参数校验
assert.notNull(path.id, '用户ID不能为空')

// 查询用户
var user = db.selectOne("""
    SELECT u.*, d.dept_name 
    FROM sys_user u
    LEFT JOIN sys_dept d ON u.dept_id = d.dept_id
    WHERE u.user_id = #{path.id} AND u.del_flag = '0'
""")

if (user == null) {
    return {
        code: 404,
        msg: '用户不存在'
    }
}

return user
```

### 8.3 新增用户接口

```javascript
/**
 * 接口路径：POST /magic/api/user
 * 请求体：userName, nickName, email, phonenumber, deptId
 */

import assert
import com.ruoyi.common.utils.SecurityUtils

// 参数校验
assert.notBlank(body.userName, '用户名不能为空')
assert.notBlank(body.nickName, '昵称不能为空')

// 检查用户名是否存在
var exists = db.selectOne("""
    SELECT 1 FROM sys_user WHERE user_name = #{body.userName} AND del_flag = '0'
""")
if (exists) {
    return {
        code: 500,
        msg: '用户名已存在'
    }
}

// 插入用户
var result = db.insert("""
    INSERT INTO sys_user (user_name, nick_name, email, phonenumber, dept_id, 
        password, create_by, create_time)
    VALUES (#{body.userName}, #{body.nickName}, #{body.email}, #{body.phonenumber}, 
        #{body.deptId}, #{SecurityUtils.encryptPassword('123456')}, 
        #{SecurityUtils.getUsername()}, NOW())
""")

return {
    code: 200,
    msg: '新增成功'
}
```

### 8.4 统计报表接口

```javascript
/**
 * 接口路径：GET /magic/api/report/user-stats
 * 请求参数：startDate, endDate
 */

// 用户统计
var stats = db.selectOne("""
    SELECT 
        COUNT(*) as totalCount,
        SUM(CASE WHEN status = '0' THEN 1 ELSE 0 END) as activeCount,
        SUM(CASE WHEN status = '1' THEN 1 ELSE 0 END) as disabledCount
    FROM sys_user 
    WHERE del_flag = '0'
""")

// 部门分布
var deptStats = db.select("""
    SELECT d.dept_name, COUNT(u.user_id) as userCount
    FROM sys_dept d
    LEFT JOIN sys_user u ON d.dept_id = u.dept_id AND u.del_flag = '0'
    WHERE d.del_flag = '0'
    GROUP BY d.dept_id, d.dept_name
    ORDER BY userCount DESC
    LIMIT 10
""")

// 注册趋势
var trend = db.select("""
    SELECT DATE(create_time) as date, COUNT(*) as count
    FROM sys_user
    WHERE del_flag = '0'
    AND create_time BETWEEN #{startDate} AND #{endDate}
    GROUP BY DATE(create_time)
    ORDER BY date
""")

return {
    stats: stats,
    deptStats: deptStats,
    trend: trend
}
```

## 九、生产环境配置

### 9.1 禁用编辑器

生产环境建议禁用 Web 编辑器：

```yaml
magic-api:
  web: null  # 设为 null 禁用编辑器
```

### 9.2 修改默认密码

```yaml
magic-api:
  security:
    username: your_username
    password: your_strong_password
```

### 9.3 接口访问控制

通过 Spring Security 控制 Magic API 接口访问：

```java
.requestMatchers("/magic/api/**").authenticated()  // 需要登录
.requestMatchers("/magic/web/**").hasRole("ADMIN") // 仅管理员
```

## 十、常见问题

### 10.1 接口不生效

- 检查是否点击「保存」按钮
- 检查接口路径是否正确
- 查看控制台是否有错误日志

### 10.2 数据库连接失败

- 检查数据源配置是否正确
- 确认数据库服务是否启动
- 查看连接池配置

### 10.3 权限校验失败

- 确认接口配置了正确的权限选项
- 检查请求是否携带有效的 Token
- 验证用户是否拥有对应权限

## 十一、总结

RuoYi-SpringBoot3-Pro 集成的 Magic API 具有以下特点：

- **开箱即用**：预配置完善，启动即可使用
- **可视化开发**：Web 界面编写接口，所见即所得
- **即时生效**：无需重启，修改立即生效
- **数据库持久化**：接口存储在数据库，支持版本控制
- **权限集成**：与 RuoYi 权限体系无缝集成
- **Redis 支持**：内置 Redis 插件，轻松实现缓存

Magic API 适合快速开发简单接口，与传统 Controller 开发方式互补，可根据实际需求灵活选择。

---

+ 项目地址：[RuoYi-SpringBoot3-Pro](https://github.com/undsky/RuoYi-SpringBoot3-Pro)
+ 开发文档：[RuoYi-SpringBoot3-Pro 文档](https://www.undsky.com/blog/?category=RuoYi-SpringBoot3-Pro#)

本文详细介绍 RuoYi-SpringBoot3-Pro 框架中集成的 Magic API 低代码开发平台，帮助开发者快速构建 REST API 接口。

【RuoYi-SpringBoot3-Pro】：Magic API 低代码开发

低代码

后端

开发工具

RuoYi-SpringBoot3-Pro框架集成MagicAPI低代码开发平台，支持可视化接口开发，无需编写传统分层代码。提供数据库操作、多数据源、参数校验、接口文档自动生成等功能，与SpringSecurity权限体系无缝集成。通过Web界面快速构建RESTAPI，实现零代码开发，提升开发效率。

低代码开发

原型开发

数据库

GitHub

Redis

JSON

Java

AI驱动 智领未来

tencentdb-catalog

腾讯云数据库特惠，新用户首单0.5折起


weda

腾讯云BI新客户首次购买9.9元起！


文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【RuoYi-SpringBoot3-Pro】：Magic API 低代码开发-腾讯云开发者社区-腾讯云

【RuoYi-SpringBoot3-Pro】：Magic API 低代码开发

【RuoYi-SpringBoot3-Pro】：Magic API 低代码开发

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐