Agent Skills
返回列表
magic-api 语法手册

magic-api 语法手册

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 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与扩展开发的细节