---
name: magic-script
description: magic-api 框架接口开发助手，提供 magic-script 脚本编写指导、DB/HTTP 模块使用及语法纠错；当用户需要在 magic-api 中编写接口脚本、调试脚本或排查脚本错误时使用
---

# Magic-Script 脚本开发助手

Magic-API 是一个基于 Java 的接口快速开发框架，支持通过 magic-script 脚本语言编写接口。magic-script 是一种基于 Mozilla Rhino 的脚本语言，语法类似 JavaScript，专为接口开发优化。

> **说明**：本 Skill 同时兼容以下称呼方式：
> - magic-api / magicapi（框架名称）
> - magic-script / MagicScript / magicscript（脚本语言名称）
> 无论用户使用哪种称呼，都指代同一套技术栈。

## 任务目标
- 本 Skill 用于：为 magic-api/magicapi 框架提供 magic-script/MagicScript 脚本编写的完整指导
- 能力包含：magic-script 语法参考、内置模块（db、http 等）使用方法、接口开发示例和脚本故障排查
- 触发条件：用户需要在 magic-api/magicapi 中编写接口脚本、调试 magic-script/MagicScript 代码或解决脚本执行错误时使用

## 操作步骤
- 标准流程：确认场景 → 阅读 SKILL.md → 查阅 references/ 文档 → 编写脚本
- 可选分支：遇到脚本错误 → 查阅 faq 相关文档

## 使用示例

**示例1：快速查询接口**
```javascript
// GET /api/user/list 分页查询
return db.table('sys_user')
    .column('id', 'userId')
    .column('name', 'userName')
    .where()
    .eq('status', 1)
    .page(page, size);
```

**示例2：带参数的增删改查**
```javascript
// POST /api/user/save 新增用户
assert not_blank(body.name) : 400, '用户名不能为空';
var userId = db.table('sys_user')
    .column('name', body.name)
    .column('create_time', now())
    .insert();
return {code: 200, data: {id: userId}};
```

**示例3：调用外部接口**
```javascript
import http;
var result = http.connect('https://api.example.com/data')
    .param({key: 'value'})
    .header('Authorization', 'Bearer xxx')
    .post()
    .getBody();
return result;
```

## 资源索引

### 语法类
| 文件 | 说明 |
|------|------|
| `references/keywords.md` | 关键字、运算符、数据类型 |
| `references/script-syntax.md` | 脚本语法详解 |
| `references/lambda-async.md` | Lambda表达式与异步调用 |

### 函数扩展
| 文件 | 说明 |
|------|------|
| `references/aggregation.md` | 聚合函数（count/sum/max/min/avg/group_concat） |
| `references/string-functions.md` | 字符串函数（uuid/is_blank/not_blank） |
| `references/date-functions.md` | 日期函数（date_format/now/current_timestamp_millis/current_timestamp） |
| `references/number-extensions.md` | Number扩展与数学函数 |
| `references/collection-extensions.md` | 列表与Map扩展 |
| `references/date-extensions.md` | 日期扩展 |
| `references/array-functions.md` | 数组创建函数 |
| `references/math-functions.md` | 数学函数（round/floor/ceil/percent） |
| `references/other-functions.md` | 其它函数（print/println/ifnull/is_null/not_null） |
| `references/object-extensions.md` | Object扩展方法 |
| `references/class-extensions.md` | Class扩展方法 |
| `references/pattern-extensions.md` | Pattern扩展方法 |

### 数据库
| 文件 | 说明 |
|------|------|
| `references/db-query.md` | 数据库查询（select/selectOne/selectInt/selectValue） |
| `references/db-update.md` | 数据库增删改（insert/update/batchUpdate/call） |
| `references/db-transaction.md` | 事务操作 |
| `references/db-cache.md` | 缓存操作（cache/deleteCache） |
| `references/single-table.md` | 单表操作（db.table链式API） |
| `references/sql-param.md` | SQL参数（#{}、${}、动态SQL、Mybatis语法） |
| `references/page.md` | 分页查询 |

### 模块
| 文件 | 说明 |
|------|------|
| `references/http-module.md` | HTTP模块调用外部接口 |
| `references/request-module.md` | Request模块获取请求信息 |
| `references/response-module.md` | Response模块设置响应 |
| `references/log-module.md` | 日志模块 |
| `references/env-module.md` | 环境配置模块 |
| `references/magic-module.md` | Magic模块（调用其他接口） |

### 集成
| 文件 | 说明 |
|------|------|
| `references/java-integration.md` | 脚本调用Java |
| `references/api-integration.md` | Java调用接口 |

### 示例
| 文件 | 说明 |
|------|------|
| `references/quick-start.md` | 快速入门（工程创建、三分钟写接口） |
| `references/quick-param.md` | 请求参数获取 |
| `references/quick-crud.md` | CRUD操作示例 |
| `references/linq.md` | Lambda/LINQ操作示例 |

### FAQ
| 文件 | 说明 |
|------|------|
| `references/faq.md` | 常见问题 |
| `references/validate.md` | 参数校验 |

## 注意事项

1. **语法限制**：magic-script 不支持 ES6 默认参数语法 `excludeValue = null`，需用 `if (excludeValue === undefined)` 判断；不支持 `new Set()`，需用数组替代

2. **数组方法**：不支持传统 `for` 循环，需用 `for (value in list)` 或 `for (index, value in list)`；**注意** Collection 扩展提供了 `reduce` 方法用于归约操作

3. **方法命名**：遍历集合用 `each` 而不是 `forEach`；获取长度用 `size()` 而不是 `length`；判断Map键用 `containsKey()` 而不是 `hasOwnProperty()`

4. **SQL参数**：`#{}` 防注入占位符用于普通参数，`${}` 字符串拼接用于动态表名/列名/排序字段（存在注入风险）

5. **类型转换**：`::type` 语法用于类型转换，如 `'123'::int`，转换失败可指定默认值 `'abc'::int(0)`

6. **获取请求参数**：
   - URL参数：直接使用变量名 `name`
   - 表单参数：直接使用变量名 `name`
   - Header参数：`header.xxx`
   - Body参数：`body.xxx`
   - Path参数：`path.xxx` 或直接使用变量名
   - Cookie参数：`cookie.xxx`
   - Session参数：`session.xxx`

7. **循环拼接参数**：`in (#{ids})` 语法会自动对集合参数展开

8. **多数据源**：使用 `db.slave.select(...)` 格式切换数据源

9. **SQL缓存**：`db.cache("cacheName", ttl).select(...)` 使用缓存

10. **事务操作**：
    - 自动事务：`db.transaction(()=>{...})`
    - 手动事务：`var tx = db.transaction(); tx.commit(); tx.rollback();`