tansci/magic-script-skill/SKILL.md

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

// 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;

资源索引

语法类

文件	说明
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();