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：快速查询接口

// GET /api/user/list 分页查询
return db.table('sys_user')
    .column('id', 'userId')
    .column('name', 'userName')
    .where()
    .eq('status', 1)
    .page(page, size);

示例2：带参数的增删改查

// 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：调用外部接口

import http;
var result = http.connect('https://api.example.com/data')
    .param({key: 'value'})
    .header('Authorization', 'Bearer xxx')
    .post()
    .getBody();
return result;

资源索引

语法类

函数扩展

数据库

模块

集成

示例

FAQ

注意事项

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

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

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

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

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

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

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

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

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

1. 事务操作：
• 自动事务：db.transaction(()=>{...})
• 手动事务：var tx = db.transaction(); tx.commit(); tx.rollback();