# rocket-api

**Repository Path**: yuanxuegui/rocket-api

## Basic Information

- **Project Name**: rocket-api
- **Description**: API敏捷开发框架，用于API接口功能的快速开发。不再定义Controller,Service,Dao,Mybatis,xml,Entity,VO等对象和方法.以springboot starter 形式集成使用
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/alenfive/rocket-api
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 744
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NovaCloud RocketAPI

<div align="center">

**数据服务开发平台 - 让API开发更简单、更高效**

[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Groovy](https://img.shields.io/badge/Groovy-4.0.24-orange.svg)](http://groovy-lang.org/)
[![Version](https://img.shields.io/badge/Version-5.2.0--SNAPSHOT-blue.svg)]()
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

</div>

---

## 📖 项目简介

NovaCloud RocketAPI 是一个基于 Spring Boot 的低代码 API 敏捷开发框架，通过可视化界面和脚本引擎，将传统的 Controller-Service-Dao 三层架构简化为只需编写 SQL 或 Groovy 脚本即可完成 API 开发。

### 核心价值

- **拒绝重复 CRUD**：50% 以上的功能只需编写 SQL 或 MongoDB 查询语句
- **标准化开发**：统一的 API 规范、返回格式、异常处理
- **高效交付**：服务端研发效率提升 300%-500%，人力成本减少 3 倍
- **低门槛**：测试人员或运维人员也可参与简单 API 开发
- **动态热更**：在线修改、即时生效，无需重启服务

### 适用场景

✅ **适合**：
- 数据查询类 API（报表、统计、列表）
- 简单的 CRUD 操作
- 快速原型开发
- 内部管理系统
- 数据集成与转换

❌ **不适合**：
- 复杂业务逻辑（建议用传统 Java 开发）
- 高性能要求场景（Groovy 有性能损耗）
- 需要精细控制的底层接口

---

## ✨ 核心特性

### 🚀 快速开发
- **零样板代码**：无需定义 `Controller`、`Service`、`Dao`、`MyBatis`、`XML`、`Entity`、`VO` 等对象和方法
- **脚本驱动**：50% 以上的功能只需编写 SQL 或 MongoDB 原始执行脚本即可完成开发
- **一行代码**：大部分业务需求仅需一行代码即可实现
- **低门槛**：测试人员或运维人员也可参与 API 开发

### 💻 可视化界面
- **图形化配置**：可视化界面管理 API，入参自动封装到可执行脚本
- **多数据库支持**：支持所有关系型数据库 SQL 语句和非关系型 MongoDB 查询语句
- **智能提示**：提供代码提示、SQL 提示、语法提示功能
- **在线调试**：内置 POSTMAN 调试工具，支持保存调试信息和自动生成文档

### 🔧 动态热更新
- **即时生效**：在线动态编译，无需重启服务
- **远程发布**：一键发布到线上环境
- **版本控制**：支持历史记录比对、回滚等功能
- **历史追溯**：保存历史调用记录，便于问题回溯

### 🛡️ 安全与权限
- **用户管理**：完善的用户管理和权限控制
- **行为审计**：记录历史操作行为
- **Sa-Token 集成**：基于 Sa-Token 的安全认证机制
- **多租户支持**：支持多租户架构

### 📊 监控与统计
- **API 监控**：实时监控 API 访问情况
- **统计分析**：提供 API 调用统计数据
- **报表生成**：自动生成 API 使用报表
- **数据脱敏**：支持敏感数据脱敏处理

### 🌐 多数据源支持
- **关系型数据库**：MySQL、PostgreSQL、Oracle、SQL Server、DB2、KingBase、ClickHouse
- **非关系型数据库**：MongoDB、ElasticSearch
- **大数据引擎**：Presto
- **动态切换**：支持运行时动态数据源管理

---

## 🏗️ 技术架构

### 工作原理

1. **动态路由注册**
   - 将 API 信息、请求方式、请求路径、处理逻辑存储于数据库中
   - 调用 Spring Boot 提供的 `RequestMappingHandlerMapping.registerMapping/unregisterMapping` 实现动态管理 RequestMapping

2. **脚本引擎**
   - 基于 Java 1.8+ 提供的 `ScriptEngineManager` 方法
   - 调用 Groovy 引擎赋予数据处理能力
   - 实现代码逻辑的动态编译和发布，无需重启服务

3. **Starter 集成**
   - 以 Spring Boot Starter 形式集成到业务项目中
   - 无侵入性，新老项目都能快速集成

### 技术栈

- **核心框架**：Spring Boot（继承自 novacloud-framework 父 POM）
- **脚本引擎**：Apache Groovy 4.0.24
- **数据库迁移**：Liquibase
- **模板引擎**：Thymeleaf
- **安全认证**：Sa-Token
- **多租户**：NovaCloud Tenant
- **构建工具**：Maven 3.6+
- **JDK 版本**：Java 17+

---

## 🚦 快速开始
### 前置要求

- JDK 17 或更高版本
- Maven 3.6+
- MySQL 5.7+ / PostgreSQL 12+（或其他支持的数据库）

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://your-repo/novacloud-rocketapi.git
cd novacloud-rocketapi
```

#### 2. 配置数据库

在 `src/main/resources/application-dev.yml` 中配置数据库连接：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/rocketapi?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
```

#### 3. 编译打包

```bash
mvn clean install -DskipTests
```

#### 4. 启动应用

```bash
mvn spring-boot:run
```

或者直接运行打包后的 JAR 文件：

```bash
java -jar target/novacloud-rocketapi-5.2.0-SNAPSHOT.jar
```

#### 5. 访问管理界面

启动成功后，访问：`http://localhost:8081/rocketapi`

默认端口为 8081，可在配置文件中修改。

---

## 📝 使用指南

### 一、独立运行模式

#### 1. 登录管理界面

启动应用后，访问：`http://localhost:8081/rocketapi`

首次使用会自动初始化数据库表结构（通过 Liquibase），无需手动建表。

#### 2. 创建第一个 API

**步骤 1：新建 API**
- 点击左侧菜单"API 管理" → "新建 API"
- 填写基本信息：
  - **名称**：用户列表查询
  - **路径**：`/user/list`
  - **请求方式**：GET
  - **服务名称**：数据服务
  - **数据源**：default（默认数据源）
  - **类型**：QL（SQL 模式）或 CODE（Groovy 代码模式）

**步骤 2：编写脚本**

**SQL 模式（推荐简单查询）**：
```sql
SELECT * FROM users WHERE status = :status
```

参数说明：
- `:status` - 从请求参数中自动获取，支持路径参数、查询参数、请求体参数
- SQL 模式下自动识别增删改查操作
- 支持分页：访问 `/user/list/page?pageSize=10&pageNumber=1`

**Groovy 代码模式（复杂业务逻辑）**：
```groovy
// 简单查询
def result = db.find("SELECT * FROM users WHERE id = :id", [id: params.id])
return result

// 条件查询
def status = params.status ?: 1
def list = db.find("SELECT * FROM users WHERE status = :status", [status: status])
return [code: 200, data: list, total: list.size()]

// 插入操作
def id = db.insert("INSERT INTO users(name, email) VALUES(:name, :email)", [
    name: params.name,
    email: params.email
])
return [code: 200, message: "创建成功", id: id]

// 更新操作
def count = db.update("UPDATE users SET name = :name WHERE id = :id", [
    name: params.name,
    id: params.id
])
return [code: 200, affected: count]

// 删除操作
def count = db.remove("DELETE FROM users WHERE id = :id", [id: params.id])
return [code: 200, deleted: count]
```

**步骤 3：测试 API**
- 点击右侧"调试"标签页
- 填写测试参数
- 点击"发送"按钮查看返回结果
- 查看执行日志和 SQL 语句

**步骤 4：发布 API**
- 测试通过后，点击"发布"按钮
- API 立即生效，无需重启服务
- 可通过 `http://localhost:8081/api/user/list` 访问

---

### 二、集成到现有 Spring Boot 项目

#### 1. 添加 Maven 依赖

```xml
<dependency>
    <groupId>com.hyhy.novacloud</groupId>
    <artifactId>novacloud-rocketapi</artifactId>
    <version>5.2.0-SNAPSHOT</version>
</dependency>
```

#### 2. 配置数据源

在 `application.yml` 中配置主数据源：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/rocketapi?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  # RocketAPI 配置
  rocket-api:
    service-name: my-service        # 服务名称（用于数据隔离）
    base-register-path: /rocketapi  # 管理界面访问路径
    service-title: 我的 API 平台     # 页面标题
    secret-key: your-secret-key     # 远程发布密钥
    view-enabled: true              # 是否启用管理界面
    sync-enabled: true              # 是否启用远程发布
```

#### 3. 配置多数据源（可选）

如需使用多个数据源，在管理界面的"数据源管理"中配置：

```yaml
# 示例：PostgreSQL 数据源配置
{
  "name": "pg-datasource",
  "driverClassName": "org.postgresql.Driver",
  "url": "jdbc:postgresql://localhost:5432/mydb",
  "username": "postgres",
  "password": "password"
}
```

在脚本中切换数据源：
```groovy
// 使用指定数据源查询
def result = db.find("SELECT * FROM users", "pg-datasource")
return result
```

#### 4. 启动应用

确保主类添加了必要的注解：

```java
@SpringBootApplication
@EnableScheduling  // 如果需要定时检测数据源连接
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
```

启动后访问：`http://localhost:8080/rocketapi`（端口根据你的配置）

---

### 三、脚本开发详解

#### 1. 内置函数库

RocketAPI 提供了丰富的内置函数，可直接在脚本中使用：

**数据库操作（db）**：
```groovy
// ✅ 查询列表（返回 List<Map>）
def list = db.find("SELECT * FROM users WHERE age > :age", [age: 18])

// ✅ 查询单条（返回 Map，无数据返回 null）
def user = db.findOne("SELECT * FROM users WHERE id = :id", [id: 1])

// ✅ 计数查询（返回 Long）
def count = db.count("SELECT COUNT(1) FROM users WHERE status = :status", [status: 1])

// ✅ 自动分页（推荐）
// 访问: /api/user/list/page?pageNumber=1&pageSize=10
// 返回: {content: [...], totalElements: 100, totalPages: 10}
def page = db.pager("SELECT * FROM users ORDER BY create_time DESC")

// ✅ 手动分页
def total = db.count("SELECT COUNT(1) FROM users")
def list = db.find("SELECT * FROM users LIMIT :offset, :pageSize", [
    offset: (params.pageNumber - 1) * params.pageSize,
    pageSize: params.pageSize
])
return db.pager(total, list)

// ✅ 插入操作（返回自增 ID）
def id = db.insert("INSERT INTO users(name, email) VALUES(:name, :email)", [
    name: "张三",
    email: "zhangsan@example.com"
])

// ✅ 更新操作（返回影响行数）
def count = db.update("UPDATE users SET name = :name WHERE id = :id", [
    name: "李四",
    id: 1
])

// ✅ 删除操作（返回删除行数）
def count = db.remove("DELETE FROM users WHERE id = :id", [id: 1])

// ✅ 批量操作
def params = [
    [name: "用户A", sex: 1],
    [name: "用户B", sex: 2]
]
def sql = """sql
INSERT INTO users(name, sex) VALUES(:name, :sex)
"""
db.batchUpdate(sql, params)

// ✅ 指定数据源查询
def result = db.findOne("SELECT * FROM users WHERE id = :id", "mysql-datasource", [id: 1])

// ✅ 缓存查询（单位：毫秒）
// 注意：缓存仅支持 .find() 方法
def cached = db.cache("user_list_key", 3000).find("SELECT * FROM users LIMIT 100")

// ✅ 清除缓存
db.cacheClear("user_list_key")
```

**参数说明**：
- `#{param}` 和 `:param` 两种方式都可以使用，推荐使用 `:param`
- 所有方法都支持可选的参数 Map，不传则从请求参数中自动获取
- `db.pager()` 会自动从请求中读取 `pageNumber` 和 `pageSize` 参数

**日志输出（log）**：
```groovy
log.info("用户ID: {}, 姓名: {}", params.id, params.name)
log.debug("调试信息: {}", someVariable)
log.error("错误信息: {}", errorMessage)
log.warn("警告信息")
```

**工具函数（utils）**：
```groovy
// JSON 处理
def jsonStr = utils.toJson([name: "张三", age: 18])
def map = utils.fromJson(jsonStr)

// 日期处理
def now = utils.now()                    // 当前时间
def date = utils.parseDate("2024-01-01") // 解析日期
def str = utils.formatDate(now, "yyyy-MM-dd") // 格式化日期

// MD5 加密
def md5 = utils.md5("password")

// UUID 生成
def uuid = utils.uuid()

// 空值判断
def isEmpty = utils.isEmpty(value)
def isNotEmpty = utils.isNotEmpty(value)
```

**断言函数（assert）**：
```groovy
// 参数校验
assert.notNull(params.id, "用户ID不能为空")
assert.notBlank(params.name, "姓名不能为空")
assert.isTrue(params.age > 0, "年龄必须大于0")

// 业务校验
def user = db.findOne("SELECT * FROM users WHERE id = :id", [id: params.id])
assert.notNull(user, "用户不存在")
```

**上下文函数（context）**：
```groovy
// 获取当前用户信息（需集成 Sa-Token）
def userId = context.getUserId()
def username = context.getUsername()

// 获取请求信息
def method = context.getMethod()      // GET/POST
def path = context.getPath()          // 请求路径
def ip = context.getIp()              // 客户端IP
```

**环境变量（env）**：
```groovy
// 获取配置项
def value = env.getProperty("some.config.key")
def defaultValue = env.getProperty("key", "default")
```

#### 2. 参数传递方式

**路径参数**：
```
API 路径：/user/{id}
请求 URL：/user/123
脚本引用：params.id 或 :id
```

**查询参数**：
```
请求 URL：/user/list?status=1&type=admin
脚本引用：params.status 或 :status
```

**请求体参数（POST/PUT）**：
```json
{
  "name": "张三",
  "age": 18,
  "email": "zhangsan@example.com"
}
```
脚本引用：`params.name`、`:name`

**获取整个请求体**：
```groovy
def body = bodyRoot  // 获取完整的 JSON 对象
return body
```

#### 3. 事务处理

```groovy
// 方式一：自动事务（推荐）
db.transaction {
    db.insert("INSERT INTO orders(user_id, amount) VALUES(:userId, :amount)", 
        [userId: params.userId, amount: params.amount])
    db.update("UPDATE users SET balance = balance - :amount WHERE id = :userId",
        [amount: params.amount, userId: params.userId])
}

// 方式二：手动控制
def transactionManager = context.getTransactionManager()
def status = transactionManager.getTransaction(new DefaultTransactionDefinition())
try {
    // 业务逻辑
    transactionManager.commit(status)
} catch (Exception e) {
    transactionManager.rollback(status)
    throw e
}
```

#### 4. 多数据源操作

```groovy
// 从 MySQL 查询用户
def mysqlUsers = db.find("SELECT * FROM users", "mysql-ds")

// 从 PostgreSQL 查询订单
def pgOrders = db.find("SELECT * FROM orders", "pg-ds")

// 跨库关联（需要在 Groovy 中处理）
def result = []
mysqlUsers.each { user ->
    def orders = pgOrders.findAll { it.user_id == user.id }
    result << [user: user, orders: orders]
}
return result
```

#### 5. MongoDB 操作

```groovy
// 查询
def list = mongo.find("users", [status: 1])

// 条件查询
def query = [age: [\$gt: 18], status: 1]
def adults = mongo.find("users", query)

// 插入
def id = mongo.insert("users", [name: "张三", age: 18])

// 更新
def count = mongo.update("users", [id: 1], [\$set: [name: "李四"]])

// 删除
def count = mongo.remove("users", [id: 1])

// 聚合查询
def pipeline = [
    [\$match: [status: 1]],
    [\$group: [_id: "\$city", count: [\$sum: 1]]]
]
def result = mongo.aggregate("users", pipeline)
```

#### 6. 高级用法

**调用外部 HTTP 接口**：
```groovy
def http = new groovyx.net.http.HTTPBuilder('https://api.example.com')
def response = http.request(groovyx.net.http.Method.GET) {
    uri.path = '/users/' + params.id
    headers.'Authorization' = 'Bearer token'
}
return response
```

**文件上传处理**：
```groovy
def file = params.file  // MultipartFile 对象
def fileName = file.originalFilename
def bytes = file.bytes
// 保存到文件系统或 OSS
return [code: 200, message: "上传成功", fileName: fileName]
```

**Excel 导出**：
```groovy
def data = db.find("SELECT * FROM users")
def excelBytes = utils.exportExcel(data, "用户列表")
response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
response.setHeader("Content-Disposition", "attachment; filename=users.xlsx")
response.getOutputStream().write(excelBytes)
return null
```

---

### 四、API 类型说明

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| **QL** | SQL 模式，直接写 SQL 语句 | 简单 CRUD 操作 |
| **CODE** | Groovy 代码模式 | 复杂业务逻辑、多数据源、事务处理 |
| **MONGO** | MongoDB 查询模式 | MongoDB 数据库操作 |

---

## 💡 纯 SQL 模式（推荐新手）

纯 SQL 模式是 RocketAPI 的特色功能，让你只需编写 SQL 语句，无需任何 Groovy 代码即可完成 API 开发。

### 设计思想

通过自动识别脚本内容 + PATH 后缀约定，智能判断并执行相应的数据库操作：
- 自动识别 INSERT/UPDATE/DELETE/SELECT
- 通过 URL 后缀区分查询类型（列表/分页/单条/计数）
- 脚本中**只能包含纯 SQL**，连注释都不允许

### 使用规则

#### 1. 新增操作（INSERT）

**API 配置**：
- 路径：`/api/user`
- 请求方式：POST
- 类型：**QL**
- 脚本：
```sql
INSERT INTO users(id, name, email) VALUES(:id, :name, :email)
```

**等价于**：`db.insert()`

**返回值**：自增 ID

---

#### 2. 更新操作（UPDATE）

**API 配置**：
- 路径：`/api/user`
- 请求方式：PUT
- 类型：**QL**
- 脚本：
```sql
UPDATE users SET name = :name, email = :email WHERE id = :id
```

**等价于**：`db.update()`

**返回值**：影响行数

---

#### 3. 删除操作（DELETE）

**API 配置**：
- 路径：`/api/user/{id}`
- 请求方式：DELETE
- 类型：**QL**
- 脚本：
```sql
DELETE FROM users WHERE id = :id
```

**等价于**：`db.remove()`

**返回值**：删除行数

---

#### 4. 列表查询（SELECT - 返回列表）

**API 配置**：
- 路径：`/api/users`
- 请求方式：GET
- 类型：**QL**
- 脚本：
```sql
SELECT * FROM users WHERE status = :status
```

**等价于**：`db.find()`

**返回值**：List<Map>

**访问示例**：
```
GET /api/users?status=1
返回: [{id: 1, name: "张三"}, {id: 2, name: "李四"}]
```

---

#### 5. 分页查询（SELECT - 自动分页）⭐

**API 配置**：
- 路径：`/api/users/page`  ← 注意 `/page` 后缀
- 请求方式：GET
- 类型：**QL**
- 脚本：
```sql
SELECT * FROM users ORDER BY create_time DESC
```

**等价于**：`db.pager()`

**返回值**：
```json
{
  "content": [...],
  "totalElements": 100,
  "totalPages": 10,
  "pageNumber": 1,
  "pageSize": 10
}
```

**访问示例**：
```
GET /api/users/page?pageNumber=1&pageSize=10
```

**说明**：
- 框架会自动从请求参数中读取 `pageNumber` 和 `pageSize`
- 自动添加 LIMIT/OFFSET（根据不同数据库方言）
- 自动执行 COUNT 查询获取总数

---

#### 6. 单条查询（SELECT - 返回第一条）

**API 配置**：
- 路径：`/api/user/first`  ← 注意 `/first` 后缀
- 请求方式：GET
- 类型：**QL**
- 脚本：
```sql
SELECT * FROM users WHERE id = :id
```

**等价于**：`db.findOne()`

**返回值**：Map（单个对象）

**访问示例**：
```
GET /api/user/first?id=1
返回: {id: 1, name: "张三", email: "zhangsan@example.com"}
```

---

#### 7. 计数查询（SELECT - 返回数量）

**API 配置**：
- 路径：`/api/users/count`  ← 注意 `/count` 后缀
- 请求方式：GET
- 类型：**QL**
- 脚本：
```sql
SELECT COUNT(1) FROM users WHERE status = :status
```

**等价于**：`db.count()`

**返回值**：Long（数量）

**访问示例**：
```
GET /api/users/count?status=1
返回: 100
```

---

### 完整示例：用户管理 API

使用纯 SQL 模式，5 分钟即可创建完整的 CRUD API：

| 功能 | 请求方式 | 路径 | SQL 脚本 |
|------|---------|------|----------|
| 创建用户 | POST | `/api/users` | `INSERT INTO users(name, email) VALUES(:name, :email)` |
| 更新用户 | PUT | `/api/users/{id}` | `UPDATE users SET name=:name WHERE id=:id` |
| 删除用户 | DELETE | `/api/users/{id}` | `DELETE FROM users WHERE id=:id` |
| 用户列表 | GET | `/api/users` | `SELECT * FROM users` |
| 分页查询 | GET | `/api/users/page` | `SELECT * FROM users ORDER BY create_time DESC` |
| 单条查询 | GET | `/api/users/first` | `SELECT * FROM users WHERE id=:id` |
| 统计数量 | GET | `/api/users/count` | `SELECT COUNT(1) FROM users` |

**优势**：
- ✅ 零学习成本，会 SQL 就会开发 API
- ✅ 无需编写任何 Java/Groovy 代码
- ✅ 自动参数绑定（`:param` 或 `#{param}`）
- ✅ 自动识别操作类型
- ✅ 自动处理分页、计数等复杂逻辑

---

### SQL 模式特殊后缀总结

| 后缀 | 功能 | 等价方法 | 返回值 |
|------|------|---------|--------|
| 无后缀 | 列表查询 | `db.find()` | List<Map> |
| `/page` | 分页查询 | `db.pager()` | Page 对象 |
| `/count` | 计数查询 | `db.count()` | Long |
| `/first` | 单条查询 | `db.findOne()` | Map |

**示例**：
```
GET /api/user/list          → 返回所有用户列表
GET /api/user/list/page     → 返回分页数据
GET /api/user/list/count    → 返回用户总数
GET /api/user/list/first    → 返回第一个用户
```

---

### 纯 SQL 模式 vs Groovy 模式对比

| 特性 | 纯 SQL 模式（QL） | Groovy 模式（CODE） |
|------|------------------|-------------------|
| 学习成本 | ⭐ 低（只需会 SQL） | ⭐⭐⭐ 中（需学 Groovy） |
| 开发速度 | ⚡ 快 | 🐢 中等 |
| 灵活性 | 一般 | 高 |
| 多数据源 | ❌ 不支持 | ✅ 支持 |
| 事务控制 | ❌ 不支持 | ✅ 支持 |
| 复杂逻辑 | ❌ 不支持 | ✅ 支持 |
| HTTP 调用 | ❌ 不支持 | ✅ 支持 |
| 适用场景 | 简单 CRUD | 复杂业务 |

**建议**：
- 🎯 **80% 的场景**使用纯 SQL 模式（快速、简单）
- 🎯 **20% 的复杂场景**使用 Groovy 模式（灵活、强大）

---

## 📂 项目结构

```
novacloud-rocketapi/
├── src/main/java/com/github/alenfive/rocketapi/
│   ├── annotation/          # 自定义注解
│   ├── config/              # 配置类
│   ├── controller/          # 控制器
│   │   ├── dataapi/         # 数据服务相关控制器
│   │   ├── ApiController.java
│   │   ├── RemoteController.java
│   │   └── ViewController.java
│   ├── datasource/          # 数据源实现
│   │   ├── factory/         # 数据源工厂
│   │   ├── MySQLDataSource.java
│   │   ├── PostgreSQLDataSource.java
│   │   ├── OracleDataSource.java
│   │   └── ...
│   ├── entity/              # 实体类
│   │   ├── dataapi/         # 数据服务实体
│   │   ├── vo/              # 视图对象
│   │   └── ...
│   ├── exception/           # 异常处理
│   ├── extend/              # 扩展功能
│   ├── function/            # 函数库
│   ├── permission/          # 权限管理
│   ├── script/              # 脚本引擎
│   ├── service/             # 服务层
│   └── utils/               # 工具类
├── src/main/resources/
│   ├── db/changelog/        # 数据库迁移脚本
│   ├── static/rocketapi/    # 前端静态资源
│   ├── templates/rocketapi/ # 前端模板
│   └── application.yml      # 配置文件
└── docs/plans/              # 设计文档
```

---

## 🔌 集成到现有项目

### Maven 依赖

在你的 Spring Boot 项目中添加以下依赖：

```xml
<dependency>
    <groupId>com.hyhy.novacloud</groupId>
    <artifactId>novacloud-rocketapi</artifactId>
    <version>5.2.0-SNAPSHOT</version>
</dependency>
```

### 配置项

在 `application.yml` 中添加基本配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/rocketapi?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  rocket-api:
    service-name: my-service          # 服务名称（用于数据隔离）
    base-register-path: /rocketapi    # 管理界面路径
    service-title: 我的 API 平台       # 页面标题
    secret-key: your-secret-key       # 远程发布密钥
    view-enabled: true                # 是否启用管理界面（生产环境建议关闭）
    sync-enabled: true                # 是否启用远程发布
    map-underscore-to-camel-case: true # 下划线转驼峰
    
    # 集群配置（可选）
    cluster-type: None                # None: 单机, Redis: 集群模式
    
    # SQL 模式后缀配置
    sql-model:
      pager-suffix: /page             # 分页后缀
      count-suffix: /count            # 计数后缀
      find-one-suffix: /first         # 单条后缀
    
    # 分页参数配置
    pager:
      page-size-var-name: pageSize    # 每页大小参数名
      page-no-var-name: pageNumber    # 页码参数名
      default-page-size-value: 20     # 默认每页大小
      default-page-no-value: 1        # 默认页码
    
    # 数据源健康检查
    datasource:
      check:
        enabled: true                 # 是否开启数据源连接检测
        fixed-delay: PT1M             # 检测周期（ISO-8601格式）

novacloud:
  tenant:
    enabled: false  # 是否启用多租户（根据实际需求配置）
```

**重要配置说明**：

1. **service-name**：不同服务的数据以此隔离，同一数据库中多个服务共用时需设置不同名称
2. **secret-key**：远程发布时的签名密钥，生产环境务必修改为强密码
3. **view-enabled**：生产环境如果管理界面暴露在外网，建议设置为 `false`
4. **cluster-type**：集群部署时设置为 `Redis`，需配置 Redis 连接信息
5. **map-underscore-to-camel-case**：自动将数据库下划线字段转换为驼峰命名

---

## 📊 性能数据

根据多个实际项目验证：

| 指标 | 提升幅度 |
|------|---------|
| 服务端开发效率 | 300% - 500% |
| 前后端联调效率 | 100% |
| 测试效率 | 200% |
| 人力成本 | 降低 3 倍 |

---

## 🔐 安全与权限

### Sa-Token 集成

RocketAPI 集成了 Sa-Token 进行身份认证和权限控制。

**配置示例**：
```yaml
sa-token:
  token-name: Authorization
  token-prefix: "Bearer"
  is-read-cookie: false
  is-read-header: true
  is-concurrent: true
  is-share: false
```

**在脚本中获取用户信息**：
```groovy
def userId = context.getUserId()
def username = context.getUsername()
def roles = context.getRoles()

// 权限校验
if (!roles.contains('admin')) {
    throw new RuntimeException("无权限访问")
}
```

### API 发布状态管理

每个 API 都有发布状态控制：

- **未发布（0）**：只能在管理界面调试，外部无法访问
- **已发布（1）**：可以通过 HTTP 请求访问

**发布流程**：
1. 创建或编辑 API
2. 点击"保存"按钮（此时状态为未发布）
3. 测试通过后，点击"发布"按钮
4. API 立即生效，外部可访问

### 远程发布（跨环境同步）

支持将 API 从一个环境同步到另一个环境（如从开发环境到生产环境）。

**使用步骤**：

1. **配置目标环境**：
   ```yaml
   # 生产环境 application.yml
   spring:
     rocket-api:
       secret-key: your-strong-secret-key  # 必须设置密钥
       sync-enabled: true                   # 启用接收远程发布
   ```

2. **在源环境执行远程发布**：
   - 点击"远程发布"按钮
   - 选择要发布的 API（支持全选或部分选择）
   - 填写目标环境地址：`http://prod-server:8080/rocketapi`
   - 填写密钥：`your-strong-secret-key`
   - 点击"发布"

3. **增量发布 vs 全量发布**：
   - **增量发布**：只发布选中的 API
   - **全量发布**：发布所有 API 和目录结构

**安全机制**：
- 基于时间戳和签名验证，防止篡改
- 签名算法：`MD5(timestamp + increment + apiInfos + directories + secretKey)`
- 目标环境可以关闭接收功能（`sync-enabled: false`）

### 版本管理

RocketAPI 提供完整的版本控制功能：

#### 1. 版本号规范

采用语义化版本号：`v1.0.0`、`v1.1.0`、`v2.0.0`

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

#### 2. 发布新版本

```bash
POST /rocketapi/data-api/admin/versions
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "version": "v1.2.0",
  "changelog": "新增用户筛选功能"
}
```

#### 3. 查看版本列表

```bash
POST /rocketapi/data-api/admin/versions/list
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "status": "PUBLISHED",  // PUBLISHED | DRAFT | ARCHIVED
  "pageNumber": 1,
  "pageSize": 10
}
```

返回：
```json
{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "ver-001",
        "apiInfoId": "api-001",
        "apiName": "用户列表查询",
        "version": "v1.2.0",
        "changelog": "新增用户筛选功能",
        "publisher": "张三",
        "publishTime": "2024-01-15 10:30:00",
        "status": "PUBLISHED"
      }
    ],
    "total": 5
  }
}
```

#### 4. 版本对比

```bash
POST /rocketapi/data-api/admin/versions/diff
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "baseVersion": "v1.1.0",
  "targetVersion": "v1.2.0"
}
```

返回两个版本之间的差异（脚本、参数等）。

#### 5. 版本回滚

如果新版本有问题，可以申请回滚到旧版本：

```bash
POST /rocketapi/data-api/admin/versions/rollback
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "targetVersion": "v1.1.0",
  "reason": "v1.2.0 存在性能问题，需要回滚"
}
```

回滚申请会记录申请人信息和原因，便于追溯。

#### 6. 历史版本自动保存

- 每次修改 API 都会自动保存到 `api_info_history` 表
- 记录修改人、修改时间、脚本内容
- 支持查看任意历史版本
- 支持一键恢复到历史版本

### 生产环境安全建议

1. **关闭管理界面**：
   ```yaml
   spring:
     rocket-api:
       view-enabled: false  # 禁止访问管理界面
   ```

2. **启用远程发布密钥**：
   ```yaml
   spring:
     rocket-api:
       secret-key: your-strong-secret-key-here
       sync-enabled: true
   ```

3. **配置 HTTPS**：
   ```yaml
   server:
     ssl:
       enabled: true
       key-store: classpath:keystore.p12
       key-store-password: your-password
       key-store-type: PKCS12
   ```

4. **限制 IP 访问**：
   通过 Nginx 或防火墙限制管理界面的访问 IP

5. **定期备份数据库**：
   - 备份 `api_info` 表（API 定义）
   - 备份 `api_info_history` 表（历史记录）
   - 备份 `api_directory` 表（目录结构）

### 数据字段加密（SM4）

RocketAPI 支持在脚本中通过 `crypto` 函数对敏感字段进行“入库前加密”，并通过索引字段支持等值查询。

**1) 配置启用**

```yaml
spring:
  rocket-api:
    crypto:
      enabled: true
      algorithm: SM4
      index-algorithm: HMAC-SM3
      key-id: data-key-v1
      key-source: env # env|config|kms
      key-env: ROCKET_API_CRYPTO_KEY
      key-plain: "" # 仅开发兜底
      # key-source=kms 时生效
      kms-endpoint: https://kms.example/api/v1/key/plain
      kms-key-name: rocketapi-sm4
      kms-token-env: ROCKET_API_KMS_TOKEN
      kms-token-plain: ""
      kms-token-header: Authorization
```

**2) 脚本使用示例**

```groovy
// 写入前加密
db.insert("""
insert into customer(id, name, phone_enc, phone_idx)
values(:id, :name, :phoneEnc, :phoneIdx)
""", [
  id: params.id,
  name: params.name,
  phoneEnc: crypto.encrypt(params.phone),
  phoneIdx: crypto.index(params.phone)
])

// 按手机号等值查询
def row = db.findOne("""
select id, name, phone_enc
from customer
where phone_idx = :phoneIdx
""", [phoneIdx: crypto.index(params.phone)])
```

**3) 建表与迁移建议**

- 敏感字段采用 `*_enc` 存密文，如 `phone_enc`
- 等值检索字段采用 `*_idx`，如 `phone_idx`，并建立索引
- 历史明文数据分批回填后下线明文字段

---

## 📊 监控与调试

### 执行日志

在调试模式下，可以查看：
- SQL 语句及参数
- 执行耗时
- Groovy 代码中的 log 输出
- 异常堆栈信息

**开启调试日志**：
```yaml
logging:
  level:
    com.github.alenfive.rocketapi: debug
```

### API 统计

管理界面提供：
- API 调用次数统计
- 平均响应时间
- 错误率分析
- 热门 API 排行

### 历史版本

- 每次修改自动保存历史版本
- 支持版本对比
- 一键回滚到任意版本
- 查看修改人和修改时间

---

## 🔑 数据服务管理（Data API）

RocketAPI 提供了企业级的数据服务管理能力，包括访问控制、审批流程、监控告警等。

### 1. API 访问密钥（Access Key）

类似阿里云的 AK/SK 机制，用于外部系统调用 API 时的身份认证。

**创建访问密钥**：
```bash
POST /rocketapi/data-api/admin/access-key
Content-Type: application/json

{
  "appName": "订单系统",
  "description": "用于订单系统调用用户API"
}
```

返回：
```json
{
  "code": 200,
  "data": {
    "id": "ak-001",
    "appKey": "AKID1234567890ABCDEF",
    "appSecret": "SK1234567890abcdef1234567890abcdef",
    "appName": "订单系统",
    "status": 0
  }
}
```

**使用密钥调用 API**：
```bash
GET /api/user/list
Headers:
  X-API-Key: AKID1234567890ABCDEF
  X-API-Secret: SK1234567890abcdef1234567890abcdef
```

### 2. API 申请审批流程

外部系统需要调用 API 时，需要先提交申请，管理员审批通过后才能获得访问权限。

**提交申请**：
```bash
POST /rocketapi/data-api/apply
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "apiPath": "/api/user/list",
  "serviceName": "订单系统",
  "reason": "需要同步用户数据",
  "validDays": 365
}
```

**审批申请**（管理员）：
```bash
POST /rocketapi/data-api/admin/apply/{id}/approve
Content-Type: application/json

{
  "status": 1,  // 1=通过, 2=拒绝
  "remark": "同意申请",
  "callFrequency": 1000  // 调用频率限制（次/天）
}
```

审批通过后，系统会自动生成访问密钥并返回给申请人。

### 3. API 权限管理

可以为每个访问密钥配置细粒度的 API 访问权限。

**授权 API**：
```bash
POST /rocketapi/data-api/admin/permission/grant
Content-Type: application/json

{
  "accessKeyId": "ak-001",
  "apiInfoId": "api-001",
  "apiPath": "/api/user/list",
  "callFrequency": 1000,  // 调用频率限制
  "validFrom": "2024-01-01 00:00:00",
  "validTo": "2024-12-31 23:59:59"
}
```

**撤销权限**：
```bash
POST /rocketapi/data-api/admin/permission/revoke
Content-Type: application/json

{
  "accessKeyId": "ak-001",
  "apiPath": "/api/user/list"
}
```

### 4. 限流控制

防止 API 被过度调用，保护后端服务。

**配置限流规则**：
```bash
POST /rocketapi/data-api/admin/rate-limit
Content-Type: application/json

{
  "apiPath": "/api/user/list",
  "limitType": "ACCESS_KEY",  // ACCESS_KEY | IP | GLOBAL
  "maxCalls": 1000,           // 最大调用次数
  "timeWindow": 3600,         // 时间窗口（秒）
  "blockTime": 300            // 超限后封禁时长（秒）
}
```

**限流类型**：
- **ACCESS_KEY**：按访问密钥限流
- **IP**：按客户端 IP 限流
- **GLOBAL**：全局限流

### 5. 数据脱敏

对敏感数据进行脱敏处理，保护用户隐私。

**配置脱敏规则**：
```bash
POST /rocketapi/data-api/admin/mask-rule
Content-Type: application/json

{
  "apiPath": "/api/user/list",
  "fieldName": "phone",
  "maskType": "PHONE",  // PHONE | ID_CARD | EMAIL | NAME | CUSTOM
  "maskPattern": "***"  // 自定义脱敏模式
}
```

**内置脱敏类型**：
- **PHONE**：`138****5678`
- **ID_CARD**：`110101********1234`
- **EMAIL**：`a****@example.com`
- **NAME**：`张*`
- **CUSTOM**：自定义规则

### 6. API 评价与反馈

用户可以对接口的服务质量进行评价。

**提交评价**：
```bash
POST /rocketapi/data-api/evaluation
Content-Type: application/json

{
  "apiInfoId": "api-001",
  "rating": 5,  // 1-5 星
  "comment": "响应速度快，文档清晰"
}
```

**查看评价**（管理员）：
```bash
GET /rocketapi/data-api/admin/evaluation/list?apiInfoId=api-001
```

### 7. 监控告警

实时监控 API 运行状态，异常情况及时告警。

**监控指标**：
- QPS（每秒查询数）
- 平均响应时间
- 错误率
- P95/P99 延迟
- 活跃调用方数量

**告警规则**：
```bash
POST /rocketapi/data-api/admin/alert-rule
Content-Type: application/json

{
  "apiPath": "/api/user/list",
  "metricType": "ERROR_RATE",  // ERROR_RATE | RESPONSE_TIME | QPS
  "threshold": 5.0,            // 阈值
  "operator": ">",             // > | < | >= | <=
  "duration": 300,             // 持续时间（秒）
  "alertLevel": "HIGH",        // LOW | MEDIUM | HIGH
  "notifyChannels": ["EMAIL", "SMS"]
}
```

### 8. 报表统计

提供多维度的数据统计报表。

**可用报表**：
- API 调用趋势图
- 热门 API 排行
- 调用方活跃度分析
- 错误分布统计
- 满意度调查

**查询报表**：
```bash
POST /rocketapi/data-api/admin/report/call-trend
Content-Type: application/json

{
  "timeRange": "LAST_7_DAYS",  // LAST_24_HOURS | LAST_7_DAYS | LAST_30_DAYS
  "apiPath": "/api/user/list",
  "groupBy": "HOUR"            // HOUR | DAY | WEEK
}
```

---

## ❓ 常见问题

### 1. 启动时提示表不存在

**原因**：Liquibase 未自动执行初始化脚本

**解决**：
```yaml
spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.xml
```

检查数据库连接配置是否正确，确保有建表权限。

### 2. 脚本中如何获取请求参数？

所有请求参数都会自动注入到 `params` 对象中：

```groovy
// GET /api/user?id=1&name=张三
def id = params.id        // 1
def name = params.name    // "张三"

// POST /api/user with body: {"age": 18}
def age = params.age      // 18

// 路径参数 /api/user/{id}
def id = params.id
```

**在 SQL 中使用参数**：
```sql
-- 方式一：使用 :param 语法（推荐）
SELECT * FROM users WHERE id = :id AND name = :name

-- 方式二：使用 #{param} 语法
SELECT * FROM users WHERE id = #{id} AND name = #{name}
```

**在 Groovy 代码中使用参数**：
```groovy
// 直接访问 params 对象
def user = db.findOne("SELECT * FROM users WHERE id = :id", [id: params.id])

// 或者省略参数 Map，框架会自动从 params 中提取
def user = db.findOne("SELECT * FROM users WHERE id = :id")
```

### 3. 如何实现分页？

**方式一：SQL 模式自动分页**
```
访问：GET /api/user/list/page?pageNumber=1&pageSize=10
脚本：SELECT * FROM users
返回：{content: [...], totalElements: 100, totalPages: 10}
```

**方式二：Groovy 手动分页**
```groovy
def page = db.pager("SELECT * FROM users ORDER BY create_time DESC")
return page
```

**方式三：自定义分页参数**
```yaml
spring:
  rocket-api:
    pager:
      page-size-var-name: size    # 自定义参数名
      page-no-var-name: current
```

### 4. 多数据源如何配置？

**步骤 1**：在管理界面"数据源管理"中添加数据源

**步骤 2**：填写配置 JSON
```json
{
  "name": "mysql-slave",
  "driverClassName": "com.mysql.cj.jdbc.Driver",
  "url": "jdbc:mysql://192.168.1.100:3306/mydb",
  "username": "root",
  "password": "password",
  "maxActive": 10,
  "minIdle": 5
}
```

**步骤 3**：在脚本中使用
```groovy
def result = db.find("SELECT * FROM users", "mysql-slave")
```

### 5. 如何处理事务？

```groovy
// 推荐方式：使用 db.transaction
db.transaction {
    db.insert("INSERT INTO orders(...) VALUES(...)")
    db.update("UPDATE inventory SET stock = stock - 1 WHERE ...")
}
// 如果抛出异常，自动回滚
```

### 6. 性能优化建议

1. **使用缓存**：
   ```groovy
   // 缓存 3 秒（单位：毫秒）
   def data = db.cache("user_list", 3000).find("SELECT * FROM users")
   
   // 注意：
   // - 缓存仅支持 .find() 方法
   // - 默认使用 LinkedHashMap LRU 实现
   // - 如需 Redis 等分布式缓存，需实现 IDBCache 接口
   ```

2. **避免 N+1 查询**：
   ```groovy
   // ❌ 不好
   users.each { user ->
       user.orders = db.find("SELECT * FROM orders WHERE user_id = :id", [id: user.id])
   }
   
   // ✅ 好
   def userIds = users.collect { it.id }
   def allOrders = db.find("SELECT * FROM orders WHERE user_id IN (:ids)", [ids: userIds])
   // 然后在 Groovy 中关联
   ```

3. **使用索引**：确保常用查询字段有索引

4. **批量操作**：
   ```groovy
   def params = [
       [name: "用户A", sex: 1],
       [name: "用户B", sex: 2]
   ]
   def sql = """sql
   INSERT INTO users(name, sex) VALUES(:name, :sex)
   """
   db.batchUpdate(sql, params)
   ```

5. **合理设置缓存时间**：
   - 热点数据：3000-60000 毫秒（3秒-1分钟）
   - 配置数据：300000-3600000 毫秒（5分钟-1小时）
   - 静态数据：可以考虑更长时间或手动清除

### 7. 如何调用外部 API？

```groovy
import groovyx.net.http.HTTPBuilder
import static groovyx.net.http.Method.*
import static groovyx.net.http.ContentType.*

def http = new HTTPBuilder('https://api.example.com')
def result = http.request(GET, JSON) {
    uri.path = '/users/' + params.id
    headers.'Authorization' = 'Bearer token'
    
    response.success = { resp, json ->
        return json
    }
    response.failure = { resp ->
        throw new RuntimeException("请求失败: ${resp.statusLine}")
    }
}
return result
```

### 8. 集群部署注意事项

1. **配置 Redis**：
   ```yaml
   spring:
     rocket-api:
       cluster-type: Redis
     redis:
       host: 192.168.1.100
       port: 6379
       password: redis-password
   ```

2. **共享会话**：确保所有节点连接到同一个 Redis

3. **远程发布**：只需向任意一个节点发布，会自动同步到其他节点

### 9. 纯 SQL 模式有什么限制？

**限制条件**：
1. ✅ 脚本中**只能包含纯 SQL 语句**
2. ❌ **不允许有任何注释**（包括 `--` 和 `/* */`）
3. ❌ **不允许有 Groovy 代码**
4. ❌ **不支持多数据源切换**
5. ❌ **不支持事务控制**

**如果需要在 SQL 中添加说明**：
```groovy
// ❌ 错误：SQL 模式中不能有注释
-- 这是注释
SELECT * FROM users

// ✅ 正确：使用 CODE 模式
def result = db.find("SELECT * FROM users")  // 可以加注释
return result
```

**何时选择纯 SQL 模式**：
- ✅ 简单的 CRUD 操作
- ✅ 单表查询
- ✅ 快速原型开发
- ❌ 需要复杂业务逻辑 → 使用 CODE 模式
- ❌ 需要多数据源 → 使用 CODE 模式
- ❌ 需要事务控制 → 使用 CODE 模式

---

## 🆚 同类方案对比

| 特性 | RocketAPI | Dataway | Magic-API | APIjson | GraphQL |
|------|-----------|---------|-----------|---------|----------|
| 可视化界面 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 动态热更新 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 多数据源支持 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Groovy 脚本 | ✅ | ❌ | ✅ | ❌ | ❌ |
| SQL 直接执行 | ✅ | ✅ | ✅ | ❌ | ❌ |
| MongoDB 支持 | ✅ | ❌ | ✅ | ❌ | ❌ |
| 版本控制 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 权限管理 | ✅ | ❌ | ✅ | ❌ | ❌ |
| 多租户支持 | ✅ | ❌ | ❌ | ❌ | ❌ |

---

## 💡 最佳实践

### 1. API 设计规范

**路径命名**：
```
✅ GET    /api/users              # 获取用户列表
✅ GET    /api/users/{id}         # 获取单个用户
✅ POST   /api/users              # 创建用户
✅ PUT    /api/users/{id}         # 更新用户
✅ DELETE /api/users/{id}         # 删除用户
✅ GET    /api/users/{id}/orders  # 获取用户订单

❌ GET    /api/getUserList
❌ POST   /api/createUser
```

**返回格式统一**：
```groovy
// 成功响应
return [
    code: 200,
    message: "success",
    data: result
]

// 错误响应
throw new RuntimeException("用户不存在")
// 全局异常处理器会自动转换为：
// { code: 500, message: "用户不存在" }
```

### 2. 参数校验

```groovy
// 方式一：使用 assert 函数
assert.notNull(params.id, "用户ID不能为空")
assert.notBlank(params.name, "姓名不能为空")
assert.isTrue(params.age > 0 && params.age < 150, "年龄不合法")
assert.matches(params.phone, "^1[3-9]\\d{9}$", "手机号格式错误")

// 方式二：手动校验
if (!params.id) {
    throw new IllegalArgumentException("用户ID不能为空")
}

// 方式三：数据库校验
def user = db.findOne("SELECT * FROM users WHERE id = :id", [id: params.id])
assert.notNull(user, "用户不存在")
```

### 3. 错误处理

```groovy
try {
    // 业务逻辑
    def result = db.insert("INSERT INTO users(...) VALUES(...)")
    return [code: 200, data: result]
} catch (DuplicateKeyException e) {
    // 主键冲突
    throw new RuntimeException("用户已存在")
} catch (Exception e) {
    log.error("创建用户失败: {}", e.message, e)
    throw new RuntimeException("系统繁忙，请稍后重试")
}
```

### 4. 性能优化

**使用缓存**：
```groovy
// 热点数据缓存 5 分钟
def config = db.cache("sys_config", 300000L)
    .findOne("SELECT * FROM sys_config WHERE key = :key", [key: params.key])
return config
```

**避免大事务**：
```groovy
// ❌ 不好：事务中包含 HTTP 请求
db.transaction {
    db.insert("INSERT INTO orders...")
    http.post("https://notify.example.com/order-created")  // 慢操作
}

// ✅ 好：先提交事务，再发送通知
db.transaction {
    db.insert("INSERT INTO orders...")
}
http.post("https://notify.example.com/order-created")  // 异步通知
```

**批量操作**：
```groovy
// ❌ 不好：循环插入
params.users.each { user ->
    db.insert("INSERT INTO users(...) VALUES(...)", user)
}

// ✅ 好：批量插入
db.batchUpdate("INSERT INTO users(name, email) VALUES(:name, :email)", 
    params.users.collect { [name: it.name, email: it.email] })
```

### 5. 代码复用

**提取公共函数**：
```groovy
// 在 API 中定义工具方法
def calculatePrice(def amount, def discount) {
    return amount * discount
}

def validateUser(def userId) {
    def user = db.findOne("SELECT * FROM users WHERE id = :id", [id: userId])
    assert.notNull(user, "用户不存在")
    return user
}

// 业务逻辑
def user = validateUser(params.userId)
def price = calculatePrice(params.amount, 0.8)
return [user: user, price: price]
```

**使用配置化常量**：
```yaml
# application.yml
app:
  constants:
    max-page-size: 100
    default-discount: 0.9
```

```groovy
// 脚本中读取
def maxPageSize = env.getProperty("app.constants.max-page-size", "100").toInteger()
assert.isTrue(params.pageSize <= maxPageSize, "每页大小不能超过${maxPageSize}")
```

### 6. 日志规范

```groovy
// 关键操作记录日志
log.info("用户登录: userId={}, ip={}", params.userId, context.getIp())

// 异常情况记录详细日志
try {
    // 业务逻辑
} catch (Exception e) {
    log.error("订单创建失败: orderId={}, error={}", params.orderId, e.message, e)
    throw new RuntimeException("订单创建失败")
}

// 调试信息使用 debug 级别
log.debug("查询参数: {}", params)
```

### 7. 安全实践

**防止 SQL 注入**：
```groovy
// ✅ 安全：使用参数化查询
def user = db.findOne("SELECT * FROM users WHERE name = :name", [name: params.name])

// ❌ 危险：字符串拼接（禁止！）
def user = db.findOne("SELECT * FROM users WHERE name = '${params.name}'")
```

**敏感数据脱敏**：
```groovy
def users = db.find("SELECT * FROM users")
users.each { user ->
    // 手机号脱敏
    if (user.phone) {
        user.phone = user.phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2")
    }
    // 身份证脱敏
    if (user.idCard) {
        user.idCard = user.idCard.replaceAll("(\\d{6})\\d{8}(\\d{4})", "$1********$2")
    }
}
return users
```

**权限控制**：
```groovy
def currentUser = context.getUserId()
def targetUser = params.userId

// 只能查看自己的信息
if (currentUser != targetUser && !context.hasRole('admin')) {
    throw new RuntimeException("无权限访问")
}

return db.findOne("SELECT * FROM users WHERE id = :id", [id: targetUser])
```

### 8. 测试技巧

**使用内置调试工具**：
1. 在管理界面点击“调试”标签
2. 填写测试参数
3. 查看返回结果和执行日志
4. 保存为测试用例，方便回归测试

**Mock 外部依赖**：
```groovy
// 测试环境下 Mock HTTP 请求
if (env.getProperty("spring.profiles.active") == "test") {
    return [mock: true, data: [...]]
}

// 正常调用外部 API
def result = http.get("https://api.example.com/data")
return result
```

---

## 📚 更多资源

### 官方文档

- **原始项目**：[Rocket API on Gitee](https://gitee.com/alenfive/rocket-api)
- **语雀文档**：[Rocket API 详细文档](https://www.yuque.com/alenfive/rocket-api)

### 相关开源项目

- **[Dataway](https://www.dataql.net/)** - HASOR 旗下的数据接口开发框架
- **[Magic-API](https://ssssssss.org/guide/intro.html)** - 基于 Java 的接口快速开发框架
- **[APIjson](http://apijson.org/)** - 腾讯开源的 JSON 协议传输标准
- **[GraphQL](https://graphql.cn/)** - Facebook 开源的 API 查询语言

### 技术博客

- Groovy 官方文档：[http://groovy-lang.org/documentation.html](http://groovy-lang.org/documentation.html)
- Sa-Token 文档：[https://sa-token.cc/](https://sa-token.cc/)
- Spring Boot 官方文档：[https://spring.io/projects/spring-boot](https://spring.io/projects/spring-boot)

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📄 许可证

本项目采用 Apache License 2.0 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 👥 联系方式

- **项目维护**：NovaCloud Team
- **问题反馈**：请通过 GitHub Issues 提交

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！**

Made with ❤️ by NovaCloud Team

</div>