# api接口设计器

**Repository Path**: cbt2442064484_admin/api-interface-designer

## Basic Information

- **Project Name**: api接口设计器
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# API 接口设计器模块

## 模块简介

API 接口设计器是一个强大的可视化 API 开发工具，支持多数据源连接、SQL 配置、接口定义和在线测试功能。

### 核心功能

- ✅ **多数据源管理** - 支持 MySQL、Oracle、SQL Server、PostgreSQL 等多种数据库
- ✅ **可视化接口配置** - 通过界面配置 API 接口，无需编写代码
- ✅ **SQL 动态执行** - 支持参数化 SQL，自动参数绑定
- ✅ **JSON 响应** - 统一的 JSON 格式响应
- ✅ **在线测试** - 内置测试工具，可实时测试接口
- ✅ **安全防护** - SQL 注入检测、语法验证、权限控制
- ✅ **性能优化** - 连接池管理、缓存支持、限流降级

## 技术架构

### 后端技术栈

- Spring Boot 2.7.13
- Spring Cloud Alibaba
- MyBatis Plus
- Dynamic-Datasource (多数据源)
- Druid (连接池)
- JSQLParser (SQL 解析)
- FastJSON2 (JSON 处理)
- Sentinel (限流降级)

### 前端技术栈

- Vue 2.x
- Element UI
- Axios

## 快速开始

### 1. 数据库初始化

执行以下 SQL 脚本创建数据库和表：

```bash
# 1. 创建数据库
mysql -u root -p < sql/api-designer.sql

# 2. 导入菜单和权限配置
mysql -u root -p < sql/apidesigner-menu.sql
```

### 2. 配置 Nacos

在 Nacos 中添加配置 `ruoyi-api-designer.yml`:

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/zhdb_api_designer?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root
        password: root1234

mybatis-plus:
  mapper-locations: classpath*:mapper/apidesigner/**/*.xml
  type-aliases-package: com.ruoyi.apidesigner.domain
```

### 3. 启动模块

确保 Nacos 服务正常运行，然后启动 `ruoyi-api-designer` 模块。

访问地址：`http://localhost:9208`

### 4. 配置网关路由

在网关配置中添加路由:

```yaml
spring:
  cloud:
    gateway:
      routes:
        - id: ruoyi-api-designer
          uri: lb://ruoyi-api-designer
          predicates:
            - Path=/api/**,/apidesigner/**
          filters:
            - StripPrefix=1
```

## 使用指南

### 4.1 数据源管理

1. 登录系统，进入 **API 设计器 > 数据源管理**
2. 点击 **新增** 按钮
3. 填写数据源信息：
   - 数据源名称：自定义名称
   - 数据库类型：选择数据库类型
   - JDBC URL：数据库连接地址
   - 用户名/密码：数据库认证信息
4. 点击 **测试连接** 验证配置
5. 保存后状态设为 **正常**

**支持的数据库类型：**

| 数据库类型 | 驱动类名                                     | 默认端口 |
| ---------- | -------------------------------------------- | -------- |
| MySQL      | com.mysql.cj.jdbc.Driver                     | 3306     |
| Oracle     | oracle.jdbc.OracleDriver                     | 1521     |
| SQL Server | com.microsoft.sqlserver.jdbc.SQLServerDriver | 1433     |
| PostgreSQL | org.postgresql.Driver                        | 5432     |

### 4.2 接口设计

#### 4.2.1 创建接口

1. 进入 **API 设计器 > 接口设计器**
2. 点击 **新增** 按钮
3. 填写基本信息：
   - 接口名称：用户友好的名称
   - 接口路径：如 `/user/list`
   - 请求方法：GET/POST/PUT/DELETE
   - 数据源：选择已配置的数据源
   - 接口类型：查询/操作

#### 4.2.2 配置 SQL

切换到 **SQL 配置** 标签页：

1. 选择 SQL 类型（查询/插入/更新/删除）
2. 编写 SQL 语句，使用 `#{paramName}` 作为参数占位符

   **基本示例：**

   ```sql
   -- 查询用户列表
   SELECT * FROM sys_user
   WHERE dept_id = #{deptId}
   AND status = #{status}

   -- 带分页的查询
   SELECT u.*, d.dept_name
   FROM sys_user u
   LEFT JOIN sys_dept d ON u.dept_id = d.dept_id
   WHERE u.status = '0'
   ORDER BY u.create_time DESC
   ```

3. 配置参数映射（可选）

   **示例：**

   ```json
   {
     "userId": "id",
     "userName": "name",
     "deptId": "dept_id"
   }
   ```

4. 启用分页支持（查询接口）
5. 点击 **验证 SQL** 检查语法

#### 4.2.3 支持空参数的 SQL 配置

**场景说明：**
当某些查询参数可能为空时，系统会自动忽略这些条件，使 SQL 能够灵活执行。

**配置方式 1：使用 AND 条件（推荐）**

```sql
-- 当参数为空时，自动移除对应的 AND 条件
SELECT * FROM sys_user
WHERE 1=1
AND dept_id = #{deptId}
AND status = #{status}
AND user_name = #{userName}
```

**执行效果：**

| 传递的参数 | 实际执行的 SQL |
| ---------- | -------------- |
| `deptId=100, status="0", userName="张三"` | `SELECT * FROM sys_user WHERE 1=1 AND dept_id = 100 AND status = '0' AND user_name = '张三'` |
| `deptId=100, status="0"` | `SELECT * FROM sys_user WHERE 1=1 AND dept_id = 100 AND status = '0'` |
| 只有 `deptId=100` | `SELECT * FROM sys_user WHERE 1=1 AND dept_id = 100` |
| 不传参数 | `SELECT * FROM sys_user WHERE 1=1` |

**配置方式 2：单个 WHERE 条件**

```sql
-- 当只有一个条件且参数为空时，WHERE 会自动替换为 WHERE 1=1
SELECT * FROM sys_user
WHERE user_id = #{userId}
```

**执行效果：**

| 传递的参数 | 实际执行的 SQL |
| ---------- | -------------- |
| `userId=1` | `SELECT * FROM sys_user WHERE user_id = 1` |
| 不传参数或 userId 为空 | `SELECT * FROM sys_user WHERE 1=1` |

**配置方式 3：使用 OR 条件**

```sql
-- 当参数为空时，自动移除 OR 条件
SELECT * FROM sys_user
WHERE status = '0'
OR user_name = #{userName}
```

**注意事项：**

1. **空值判断**：当参数值为 `null` 或空字符串 `""` 时，会被视为空参数
2. **WHERE 1=1**：建议在 WHERE 子句中使用 `WHERE 1=1` 作为起始条件，方便后续动态添加 AND 条件
3. **参数命名**：确保 `#{}` 中的参数名与前端传递的参数名一致
4. **SQL 注入防护**：系统会自动转义字符串参数，防止 SQL 注入

**完整示例：**

```sql
-- 多条件可选查询
SELECT 
    u.user_id,
    u.user_name,
    u.email,
    d.dept_name
FROM sys_user u
LEFT JOIN sys_dept d ON u.dept_id = d.dept_id
WHERE 1=1
-- 部门 ID 为空时，不限制部门
AND u.dept_id = #{deptId}
-- 用户名为空时，不限制用户名
AND u.user_name LIKE CONCAT('%', #{userName}, '%')
-- 状态为空时，不限制状态
AND u.status = #{status}
-- 时间范围可选
AND u.create_time >= #{startTime}
AND u.create_time <= #{endTime}
ORDER BY u.create_time DESC
```

#### 4.2.4 高级配置

切换到 **高级配置** 标签页：

- **缓存配置**：启用缓存，设置 TTL
- **限流配置**：设置每秒最大请求数
- **超时配置**：设置接口超时时间
- **请求/响应参数**：定义参数结构
- **请求头**：自定义 HTTP 头

#### 4.2.5 发布接口

1. 保存接口配置
2. 选中接口记录
3. 点击 **发布** 按钮
4. 接口状态变为 **已发布**

### 4.3 接口测试

#### 方式一：通过测试页面

1. 在接口列表中点击 **测试** 按钮
2. 进入测试页面
3. 设置请求参数（JSON 格式）

   **示例 1：传递全部参数**

   ```json
   {
     "deptId": 100,
     "status": "0",
     "userName": "张"
   }
   ```

   **示例 2：只传递部分参数（空参数自动忽略）**

   ```json
   {
     "deptId": 100,
     "status": "",
     "userName": null
   }
   ```

   实际执行的 SQL 只会包含 `deptId` 条件

4. 点击 **执行测试**
5. 查看响应结果和执行信息

#### 方式二：直接调用 API

接口发布后，可通过网关直接调用：

```bash
# GET 请求
curl -X GET "http://gateway-url/api/user/list?deptId=100&status=0"

# POST 请求
curl -X POST "http://gateway-url/api/user/create" \
  -H "Content-Type: application/json" \
  -d '{"userName": "test", "email": "test@example.com"}'
```

### 4.4 接口调用示例

#### 示例 1：查询用户列表

**接口配置：**

- 路径：`/user/list`
- 方法：GET
- SQL：
  ```sql
  SELECT user_id, user_name, email, dept_id
  FROM sys_user
  WHERE status = #{status}
  ORDER BY create_time DESC
  ```

**调用方式：**

```bash
GET /api/user/list?status=0&pageNum=1&pageSize=10
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "user_id": 1,
        "user_name": "admin",
        "email": "admin@example.com",
        "dept_id": 100
      }
    ],
    "total": 1,
    "pageNum": 1,
    "pageSize": 10
  },
  "executeTime": 45
}
```

#### 示例 2：创建用户

**接口配置：**

- 路径：`/user/create`
- 方法：POST
- SQL：
  ```sql
  INSERT INTO sys_user (user_name, email, dept_id, create_time)
  VALUES (#{userName}, #{email}, #{deptId}, NOW())
  ```

**调用方式：**

```bash
POST /api/user/create
Content-Type: application/json

{
  "userName": "test",
  "email": "test@example.com",
  "deptId": 100
}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "rows": 1
  },
  "executeTime": 23
}
```

## 安全配置

### 权限控制

系统基于若依权限框架，所有操作都需要相应权限：

| 权限标识                       | 说明       |
| ------------------------------ | ---------- |
| apidesigner:datasource:list    | 数据源查询 |
| apidesigner:datasource:add     | 数据源新增 |
| apidesigner:datasource:edit    | 数据源修改 |
| apidesigner:datasource:remove  | 数据源删除 |
| apidesigner:datasource:test    | 数据源测试 |
| apidesigner:definition:list    | 接口查询   |
| apidesigner:definition:add     | 接口新增   |
| apidesigner:definition:edit    | 接口修改   |
| apidesigner:definition:remove  | 接口删除   |
| apidesigner:definition:publish | 接口发布   |
| apidesigner:definition:offline | 接口下线   |
| apidesigner:definition:test    | 接口测试   |

### SQL 安全

- ✅ **SQL 注入检测** - 自动检测并阻止危险 SQL
- ✅ **语法验证** - 使用 JSQLParser 验证 SQL 语法
- ✅ **危险操作拦截** - 禁止 DROP、TRUNCATE、ALTER 等危险操作
- ✅ **参数化查询** - 使用参数占位符，防止注入

## 性能优化

### 连接池配置

```yaml
dynamic:
  datasource:
    primary: master
    datasource:
      master:
        driver-class-name: com.mysql.cj.jdbc.Driver
        url: jdbc:mysql://localhost:3306/zhdb
        username: root
        password: root
        # 连接池配置
        initial-size: 5
        min-idle: 5
        max-active: 20
        max-wait: 60000
```

### 缓存配置

```yaml
api:
  designer:
    enable-cache: true
    cache-default-ttl: 300 # 5 分钟
```

### 限流配置

在接口配置中设置 `rateLimit` 参数，或在全局配置：

```yaml
sentinel:
  datasource:
    ds1:
      nacos:
        server-addr: localhost:8848
        dataId: ruoyi-api-designer-sentinel
        rule-type: flow
```

## 常见问题

### Q1: 数据源连接失败？

**检查项：**

1. 数据库服务是否启动
2. JDBC URL 格式是否正确
3. 用户名密码是否正确
4. 数据库驱动是否已加载
5. 防火墙是否开放端口

### Q2: SQL 验证失败？

**解决方法：**

1. 检查 SQL 语法是否正确
2. 确保参数占位符格式为 `#{paramName}`
3. 避免使用数据库特定函数（除非所有数据源都支持）
4. 检查表名和字段名是否正确

### Q3: 接口调用返回 404？

**检查项：**

1. 接口是否已发布（状态为"已发布"）
2. 接口路径是否正确
3. 网关路由是否配置
4. 服务是否正常运行

### Q4: 如何调试 SQL 执行？

**方法：**

1. 开启 debug 日志：
   ```yaml
   logging:
     level:
       com.ruoyi.apidesigner: debug
   ```
2. 查看控制台输出的 SQL 语句
3. 使用测试页面查看执行结果

## 开发计划

- [ ] 支持存储过程调用
- [ ] 支持批量操作
- [ ] 支持事务管理
- [ ] 支持接口文档自动生成
- [ ] 支持接口性能监控
- [ ] 支持数据源连接池监控
- [ ] 支持接口调用统计分析

## 技术支持

如有问题，请联系技术支持团队或提交 Issue。

---

**版本：** v1.0.0  
**更新日期：** 2026-03-06  
**作者：** RuoYi Team