magic-api 语法手册
将以下提示词粘贴到你的 AI 对话框中:
请根据官方安装指南 https://skillhub.cn/install/skillhub.md,帮我把 @user_4b767fa8/magic-api-skill 安装到当前 AI 助手中。
技能介绍
解决什么问题
magic-api(脚本语言为 MagicScript)用脚本替代了 Controller、Service、Dao、Mapper、XML、VO 一整套 Java 对象,接口逻辑写在一段脚本里。代价是语法既不像 Java 也不像 JavaScript:var 定义变量、exit 200,'ok',[1,2,3] 直接返回响应、SQL 既能用 #{id} 预编译也能用 ${id} 拼接、动态条件还要写成 ?{condition,expression}。这些细节散落在官方文档里,写接口时往往是在不同页面之间来回翻。
这个技能把语法参考和脚本生成合在一起,避免一边查文档一边手写。
核心能力与工作方式
技能以 prompt-executer 方式运行,内部按模式分流:
- 语法查阅:问“
db.select怎么用”“动态 SQL 怎么写”时,从内置知识库定位章节,返回语法格式、参数说明、返回值、示例和注意事项。 - 代码编写:描述需求(例如“分页查询用户列表”)时,直接产出一段带注释的完整脚本,再解释关键语法点和设计取舍;有替代方案时给出推荐理由。
- 混合模式:同时包含查语法和写代码意图时,先给脚本再补说明。
知识库覆盖内容:
- MagicScript 语法:关键字、运算符、
byte/short/int/long/BigDecimal、`Logger等类型,?.可选链、::type` 强制转换、lambda、try/catch/finally、异步调用、反引号嵌入其他脚本语言。 - 请求参数:
body、header、path、cookie、session与同名变量映射,以及自定义变量、path.id与 RequestParam 的优先级冲突。 - SQL:
#{}、${}、?{}三种参数语义,MyBatis 动态 SQL 标签,数据源切换,事务与缓存。 db模块:select/selectOne/selectValue/selectInt/page/update/insert/batchUpdate/call(存储过程),列名转换和单表操作 API。- 其他模块:
response(分页、重定向、下载、图片、Cookie、response.end())、http(基于 RestTemplate)、env、magic(跨接口调用)、log。 - Java 集成与扩展:Bean 注入、
MagicFunction自定义函数、@MagicModule自定义模块、拦截器、统一响应格式和状态码。
适用边界与注意事项
- 这是私有 prompt-executor 技能,知识库为静态文本,不会像文档站点那样随版本实时更新;使用前先核对你当前的 magic-api 版本(部分特性标注了最低版本,如
instanceof需要 v2.0.0+)。 - 生成的 SQL 会默认采用
#{}防注入写法,只有在明确需要做字符串拼接时才使用${};不要把动态拼接当作默认习惯。 - 涉及事务时需要确认提交与回滚路径,技能会检查
db.transaction的用法,但不会替代你对业务一致性的判断。 - Java 扩展部分(自定义函数、模块、
ResultProvider、异常拦截)要求能读懂注解和接口实现,技能给出的是结构参考,接入前仍需在真实工程里验证签名与配置项。 - 写入生产环境前,请把返回结果与你现有的响应结构、鉴权和异常处理对齐。
使用场景
- 在Magic-API中写带查询条件的SQL,不确定#{id}与´${id}注入差异时,需要直接检索参数语义、动态SQL标签和正确示例
- 需要调用数据库存储过程,但不熟悉db.call传参、返回Map结构和事务配合时,希望获得一段可运行脚本和关键语法点解释
- 要把Magic-API接口通过magic.call或magic.execute调用另一个MagicAPI接口时,需要确认path、parameters传参方式和返回值包含的code、message字段
- 现有Java服务想封装自定义模块或统一拦截器,需要参考MagicFunction接口、@MagicModule注解和ResultProvider的实现思路
适合人员
- 正在维护Magic-API线上接口的后端工程师,需要快速查询语法用法并得到可直接提交的脚本
- 全栈开发者在编写免Controller的轻量接口,希望确认body、header、path等参数映射和响应封装方式
- 需要统一接口文档和响应结构的Java架构师,关注自定义注解、拦截器和异常处理是否可行
- 项目里已部署Magic-API的团队技术负责人,想在升级版本时核对动态SQL与扩展开发的细节