magic-api-新手教程

原创已于 2025-12-22 15:08:32 修改 · 1.8k 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#java #前端 #服务器

于 2025-09-07 15:51:22 首次发布

该文章已生成可运行项目，

官方地址

官方测试项目地址-里面有很多示例

最近使用 magic-api框架写接口由于网上教程太少，遇到了很多问题；在ai帮助下完成第一个接口项目开发；总结一下写接口所用到的代码，希望对使用 magic-api 框架的开发者有所帮助。

1、引包

我自己的pom提供参考

log4j 、 mybatis 必须要引入不然会报错

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.7</version>
        <relativePath/>

    </parent>
    <groupId>com.example</groupId>
    <artifactId>Magic_Api</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>kmskzy</name>
    <description>kmskzy</description>


    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jersey</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.core</groupId>
                    <artifactId>jackson-databind</artifactId>
                </exclusion>
            </exclusions>

        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>



        <!--        sql server 数据库-->
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
            <version>6.4.0.jre8</version>
        </dependency>
        <!--        oracle 数据库-->
        <dependency>
            <groupId>com.oracle.database.jdbc</groupId>
            <artifactId>ojdbc8</artifactId>
            <version>19.21.0.0</version>
        </dependency>


        <!--   mybatis - plus    -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.3.2</version>
        </dependency>

        <!--lombok用来简化实体类：需要安装lombok插件-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.10</version>
        </dependency>

        <!-- druid 连接池 -->
<!--        <dependency>-->
<!--            <groupId>com.alibaba</groupId>-->
<!--            <artifactId>druid</artifactId>-->
<!--            <version>1.1.12</version>-->
<!--        </dependency>-->

        <!-- on 工具包  -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>faston</artifactId>
            <version>2.0.57</version>
        </dependency>
        <dependency>
            <groupId>com.alibaba.faston2</groupId>
            <artifactId>faston2</artifactId>
            <version>2.0.52</version>
        </dependency>
        <dependency>
            <groupId>org.on</groupId>
            <artifactId>on</artifactId>
            <version>20210307</version>
        </dependency>



        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.12</version>
        </dependency>

        <!--onwebtoken 生成token的库  登录验证-->
<!--        <dependency>-->
<!--            <groupId>com.auth0</groupId>-->
<!--            <artifactId>java-jwt</artifactId>-->
<!--            <version>3.8.3</version>-->
<!--        </dependency>-->

<!--       签名 DigestUtils-->
<!--        <dependency>-->
<!--            <groupId>commons-codec</groupId>-->
<!--            <artifactId>commons-codec</artifactId>-->
<!--        </dependency>-->
<!--        <dependency>-->
<!--            <groupId>org.apache.commons</groupId>-->
<!--            <artifactId>commons-lang3</artifactId>-->
<!--            <version>3.6</version>-->
<!--        </dependency>-->


        <!--发送请求的依赖-->
<!--        <dependency>-->
<!--            <groupId>org.apache.httpcomponents</groupId>-->
<!--            <artifactId>httpclient</artifactId>-->
<!--            <version>4.5.5</version>-->
<!--        </dependency>-->

        <!--      http工具  -->
<!--        <dependency>-->
<!--            <groupId>cn.hutool</groupId>-->
<!--            <artifactId>hutool-all</artifactId>-->
<!--            <version>5.7.1</version>-->
<!--        </dependency>-->


<!--        Magic-API -->
        <dependency>
            <groupId>org.ssssssss</groupId>
            <artifactId>magic-api-spring-boot-starter</artifactId>
            <version>2.2.1</version>
        </dependency>
 <!--        Magic-API 定时任务 -->
        <dependency>
            <groupId>org.ssssssss</groupId>
            <artifactId>magic-api-plugin-task</artifactId>
            <version>2.2.1</version>
        </dependency>


        <!--        加载本地驱动-->
<!--        <dependency>-->
<!--            <groupId>org.bouncycastle</groupId>-->
<!--            <artifactId>bcpkix-jdk15on-1.62</artifactId>-->
<!--            <version>1.62</version>-->
<!--            <scope>system</scope>-->
<!--            <systemPath>${project.basedir}/src/main/resources/lib/bcpkix-jdk15on-1.62.jar</systemPath>-->
<!--        </dependency>-->






        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-test</artifactId>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <scope>test</scope>
        </dependency>


    </dependencies>



    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>



</project>

2、配置文件-参数设置

 
我自己使用的 application.properties文件， yml参数名称一样 只是结构不同 ；
登录 账号 密码  路径； 建议配置复杂一些 比较安全   官方建议正式环境删除配置；  
magic-api.security.username=admin
magic-api.security.password=123456
magic-api.web=/skzy/web

配置接口备份表

magic-api.backup.enable=true
magic-api.backup.table-name=magic_api    #表名 按下面脚本 字段创建即可 
magic-api.backup.max-history=-1

# oracle 建表语句 提供参考 ；
 CREATE TABLE magic_api(
    ID          VARCHAR2(32),
    CREATE_DATE NUMBER(38,0),
    TAG         VARCHAR2(50),
    TYPE        VARCHAR2(50),
    NAME        VARCHAR2(100),
    CREATE_BY   VARCHAR2(50),
    CONTENT     CLOB
);

官方配置说明

3、登录

启动成功程序会打印出登录地址如下图

注意这里打印的端口是 application.properties 里面指定的，正式部署在tomcat后端口要换成tomcat配置的端口

界面截图

4、新增接口

1）、先创建分组

2、）分组下创建接口

填写接口名称接口路径

5、数据库交互

官方文档-数据库交互

1）、查询sql

// 查询sql    //db 模块会自动导入  直接调用即可
var user_list = db.select("""
     select  username,userid  from userdoc    where rownum <=5 
""");

return user_list;

通过地址+接口路径即可请求到数据 idhttp://192.168.80.110:6080/test1

2）、调用过程

--过程 
CREATE OR REPLACE PROCEDURE DHERP2.dev_test1234(p_cursor OUT SYS_REFCURSOR) AS
BEGIN
    OPEN p_cursor FOR SELECT entidentname FROM entdoc;
END;


//调用过程返回游标 oracle  
// 入参格式： #{参数名}
// 出参格式： @{参数名java.sql.Types的类型字符串}   @{LIST,REF_CURSOR}  LIST:返回报文key值 可以任意命名  REF_CURSOR:出参类型游标  若返回的是字符型写VARCHAR 
return db.call(" BEGIN dev_test1234(@{LIST,REF_CURSOR}); END;");

6、调用java代码

需要签名或者调用集成jar包的接口可以调用java类实现；

1）、调用静态方法

时间转为带时区的格式

 public static  String  zonedDateTime ( String date) {
        // 定义输入格式
        DateTimeFormatter inputFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
        // 解析为 LocalDateTime
        LocalDateTime localDateTime = LocalDateTime.parse(dateinputFormatter);
        // 假设这个时间是东八区（北京时间）
        ZoneId beijingZone = ZoneId.of("Asia/Shanghai");
        ZonedDateTime zonedDateTime = ZonedDateTime.of(localDateTimebeijingZone);
        // 输出为 ISO 8601 带时区格式
        DateTimeFormatter outputFormatter = DateTimeFormatter.ISO_OFFSET_DATE_TIME; // 默认就是 ISO_OFFSET_DATE_TIME
        String result = zonedDateTime.format(outputFormatter);
        return  result;
}

2）、调用普通方法

//java代码 
package com.example.kmskzy.util;


import org.springframework.stereotype.Service;
import java.util.Map;


@Service
public class test{

    public Map test2(Map str ){
        System.out.println(str);
        return str;
    }

}

普通方法需要 new

7、发送http请求

数据库取数、取数拼接报文、发送请求；

代码如下有详细注释

import http;
import log;



var inter_name = "获取职员"; //接口名称 打印报文使用 
// 查询sql   
var db_list = db.select("""
     select  entid,staffid,staffname  
     from staffdoc  where rownum <=2  
""");


if (db_list.getLength() == 0) {
    log.info(inter_name + '-没有待上传数据');
    return db_list;
}

//报文拼接   // sql 取数  oracle字段字段名称转大写  需要大写才能去到值  
var data = {
    //汇总取第一条数据 db_list[0]
    MT: db_list[0].ENTID,
    //明细 
    DT: db_list.map(item => ({ // 循环取  明细 
        FSKMatNum: item.STAFFID,
        FSKMatName: item.STAFFNAME
    }))

}

/*  data 格式如下 
{
    "MT": "E4C467FWITA",
    "DT": [{
        "FSKMatNum": "K4C467F9YBY",
        "FSKMatName": "系统管理员1"
    }{
        "FSKMatNum": "H0000000055",
        "FSKMatName": "魏涛"
    }]
}
*/


log.info(inter_name + '-入参：' + data::stringify); // 日志输出  on 转字符串 data::stringify  不转打印出出来是 map格式 


try{
    var url = "http//:127.0.0.1:8080/user";  //接口地址 
    var response = http.connect(url)
    .contentType('application/on')    //报文格式  on  
    // .head()    // 请求头 若没有不需要写 
    .body(data)   // 请求体 传报文  
    .post()       // 接口方式 get/post 
    .getBody();   // 获取请求到的数据 

     log.info(inter_name+'-反参：'+response::stringify); // 日志输出  on 转字符串 data::stringify  不转打印出出来是 map格式 

    // 请求成功 回写传输状态  
    if (response.code == 1){  // 状态 根据接口实际情况判断 
      //拼接sql 更新单据状态     
      var sql_up = """  
        UPDATE staffdoc SET  zt ='Y'  
        WHERE  ENTID= '${db_list[0].ENTID}'    -- ${}取变量不带引号的 字符串的需要加'${}'
      """;     
      db.update(sql_up);
    } 

    return response;
}catch(e){   // 发生异常会走这一段 打印异常信息  
    log.info(inter_name+'-反参：'+e.getMessage()); // 日志输出  on 转字符串 data::stringify  不转打印出出来是 map格式 
    return e.getMessage();
}

8、接收http请求

按下图设置请求方法、接口名称、接口路径，

设置请求参数、请求头、请求body

1）、请求参数设置

若需要必填拦截，请不要录入默认值；

2）、请求头设置

与请求参数类似

3）、请求体

请求体是测试使用不可以设置必填、验证；

需要拦截请在代码里面编写逻辑；

4）、请求信息获取

请求参数直接写请求参数名称即可获取

请求头 header.XXX 即可获取具体的参数

请求头 body.xxx 即可获取取具体的参数

return {
    'prams1': prams1 // 请求参数 
    'prams2': prams2 // 请求参数 
    'header' :header,// 请求头 
    'Body': body// 请求体 
}

5）、请求示例

通过商品编号获取库存信息

6）、body 请求参数拦截示例

import response;
 
 

if (body.goodscode == null ) {
  return response.on({
      success : 0,
      message : 'goodscode必填',
      data: []
      timestamp: new Date().getTime(),
      executeTime: 1     
  });
}
 


return db.select("""
    select b.goodsname,b.goodscode,b.GOODSSPEC a.goodsid,a.PLACENUM  
    from  OGBALANCE     a
        JOIN  goodsdoc  b ON  a.entid = b.entid AND a.goodsid = b.goodsid 
    where rownum <= 500  and b.goodscode = '${body.goodscode}'
 """
)

9、定时任务

按下图新增分组 - 新增定时任务

启用勾选填写 Cron表达式、任务名称、任务路径


import '@get:/test_java' as test_java;    //@get、@post 代表get请求 post请求  后面是调用的接口路径  
test_java();

10、接口文件存放位置（工作目录）

配置文件增加 magic-api.resource.location

#接口存盘位置
magic-api.resource.location: D:/data/magic-api

不配置会有个默认路径，启动项目会打印出来；

11、中文乱码处理

我自己电脑没乱码，放到服务器乱了接口都没法保存；

不乱码就不改，改了黑窗口打印日志会乱码；

1）、wnindows环境：tomcat\bin\catalina.bat 文件加入


set JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF-8

2）、linux环境 tomcat\bin\catalina.sh 文件加入

export JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8"

2025-12月改

本文章已经生成可运行项目

确定要放弃本次机会？

福利倒计时

: :

立减 ¥

普通VIP年卡可用

立即使用

参与评论您还未登录，请先登录后发表或查看评论