Magic API：低代码接口开发平台完全指南

Magic API：低代码接口开发平台完全指南 | 极客日志

特性类别	具体功能	优势描述
开发方式	可视化设计	拖拽式操作，无需手写大量代码
	脚本编写	支持 JavaScript/Groovy 脚本，灵活处理业务逻辑
数据源	多数据源支持	支持 MySQL、Oracle、MongoDB 等多种数据库
	动态数据源	运行时动态切换数据源，适应复杂业务场景
API 管理	版本控制	支持 API 版本管理，平滑升级
	访问控制	细粒度的权限控制，保障 API 安全
	文档自动生成	自动生成 API 文档，便于团队协作
运维特性	热部署	修改立即生效，无需重启服务
	监控告警	实时监控 API 调用情况，异常自动告警
	性能分析	提供 API 性能分析工具，优化接口性能

# 数据源配置示例
spring:
  datasource:
    # 默认数据源
    primary:
      url: jdbc:mysql://localhost:3306/test?useSSL=false&serverTimezone=UTC
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
    # 业务数据源
    business:
      url: jdbc:mysql://localhost:3306/business?useSSL=false&serverTimezone=UTC
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
magic-api:
  # API 存储位置
  web:
    resources: classpath:magic-api
  # 数据源配置
  datasource:
    # 默认使用 primary 数据源
    default: primary
    # 启用动态数据源
    dynamic: true

// API 路径：/api/order/:id
// 方法：GET
// 描述：根据 ID 获取订单信息
// datasource: business // 指定使用 business 数据源
// SQL 语句
SELECT * FROM orders WHERE id = #{pathParams.id}

// 日志相关
log.debug('调试信息');
log.info('普通信息');
log.warn('警告信息');
log.error('错误信息');

// HTTP 相关
let response = http.get('https://api.example.com/data');
let postResult = http.post('https://api.example.com/submit', {name:'test'});

// 获取请求信息
let headers = headers(); // 获取所有请求头
let userAgent = header('User-Agent'); // 获取指定请求头

// 工具函数
let now = date(); // 获取当前时间
let formattedDate = dateFormat(now, 'yyyy-MM-dd HH:mm:ss'); // 格式化日期
let randomNum = random(1, 100); // 生成随机数
let uuid = uuid(); // 生成 UUID
let md5 = md5('password'); // MD5 加密

// 结果处理
setStatusCode(200); // 设置响应状态码
setHeader('Content-Type', 'application/json'); // 设置响应头

// API 路径：/api/users
// 方法：GET
// 描述：获取用户列表，支持分页和搜索
// 前置脚本
// 获取查询参数，设置默认值
let page = queryParams.page || 1;
let size = queryParams.size || 10;
let keyword = queryParams.keyword || '';

// 计算偏移量
let offset = (page - 1) * size;

// 构建查询条件
let whereClause = '';
if(keyword){ 
  whereClause = 'WHERE username LIKE #{keyword} OR email LIKE #{keyword}'; 
  binding.keyword = '%'+ keyword +'%';
}

// SQL 语句
SELECT * FROM user ${whereClause} LIMIT #{size} OFFSET #{offset};
SELECT COUNT(*) as total FROM user ${whereClause};

// 后置脚本
// 构造分页结果
return {
  "page": page,
  "size": size,
  "total": result[1][0].total,
  "totalPages": Math.ceil(result[1][0].total / size),
  "data": result[0]
};

// API 路径：/api/users
// 方法：POST
// 描述：创建新用户
// 前置脚本
// 参数验证
if(!body.username || body.username.trim()===''){ 
  setStatusCode(400);
  return {"error":"用户名不能为空","code":"USERNAME_REQUIRED"};
}
if(!body.email || body.email.trim()===''){ 
  setStatusCode(400);
  return {"error":"邮箱不能为空","code":"EMAIL_REQUIRED"};
}

// 检查用户名是否已存在
let user = select.first('SELECT * FROM user WHERE username = #{body.username}');
if(user){ 
  setStatusCode(400);
  return {"error":"用户名已存在","code":"USERNAME_EXISTS"};
}

// 对密码进行加密
body.password = md5(body.password ||'123456');
// 设置默认密码
body.createdAt = date();
body.updatedAt = date();

// SQL 语句
INSERT INTO user(username, email, password, nickname, avatar, status, createdAt, updatedAt)
VALUES(#{body.username}, #{body.email}, #{body.password}, #{body.nickname}, #{body.avatar}, #{body.status}, #{body.createdAt}, #{body.updatedAt});

// 获取刚插入的用户 ID
SELECT LAST_INSERT_ID() as id;

// 后置脚本
// 获取新创建的用户信息
let newUser = select.first('SELECT id, username, email, nickname, avatar, status, createdAt, updatedAt FROM user WHERE id = #{result[1][0].id}');

// 返回创建成功的用户信息
setStatusCode(201);
return newUser;

// API 路径：/api/users/:id
// 方法：PUT
// 描述：更新用户信息
// 前置脚本
let userId = pathParams.id;

// 检查用户是否存在
let user = select.first('SELECT * FROM user WHERE id = #{userId}');
if(!user){ 
  setStatusCode(404);
  return {"error":"用户不存在","code":"USER_NOT_FOUND"};
}

// 如果更新密码，需要加密
if(body.password){ 
  body.password = md5(body.password);
}

// 更新时间
body.updatedAt = date();

// 构建更新字段
let updateFields = [];
let updateBindings = {};
for(let key in body){
  if(key !=='id'&& key !=='createdAt'){
    // 排除 ID 和创建时间
    updateFields.push(key +' = #{'+ key +'}'); 
    updateBindings[key]= body[key];
  }
}

// 合并绑定参数
Object.assign(binding, updateBindings);

// SQL 语句
UPDATE user SET ${updateFields.join(', ')} WHERE id = #{userId};

// 后置脚本
// 获取更新后的用户信息
let updatedUser = select.first('SELECT id, username, email, nickname, avatar, status, createdAt, updatedAt FROM user WHERE id = #{userId}');
return updatedUser;

// API 路径：/api/users/:id
// 方法：DELETE
// 描述：删除用户
// 前置脚本
let userId = pathParams.id;

// 检查用户是否存在
let user = select.first('SELECT * FROM user WHERE id = #{userId}');
if(!user){ 
  setStatusCode(404);
  return {"error":"用户不存在","code":"USER_NOT_FOUND"};
}

// SQL 语句
DELETE FROM user WHERE id = #{userId};

// 后置脚本
// 检查删除是否成功
if(result >0){ 
  return {"message":"删除成功"};
}else{ 
  setStatusCode(500);
  return {"error":"删除失败","code":"DELETE_FAILED"};
}

// API 路径：/api/orders
// 方法：POST
// 描述：创建订单，包括检查库存、创建订单和扣减库存
// 前置脚本
// 开启事务
beginTransaction();
try{
  // 验证参数
  if(!body.userId ||!body.items ||!Array.isArray(body.items)|| body.items.length ===0){ 
    setStatusCode(400);
    return {"error":"参数错误","code":"INVALID_PARAMS"};
  }

  // 检查用户是否存在
  let user = select.first('SELECT * FROM user WHERE id = #{body.userId}');
  if(!user){ 
    setStatusCode(404);
    return {"error":"用户不存在","code":"USER_NOT_FOUND"};
  }

  // 检查库存并计算总价
  let totalAmount = 0;
  for(let item of body.items){
    let product = select.first('SELECT * FROM product WHERE id = #{item.productId}');
    if(!product){ 
      setStatusCode(404);
      return {"error":"商品不存在："+ item.productId,"code":"PRODUCT_NOT_FOUND"};
    }
    let inventory = select.first('SELECT * FROM inventory WHERE productId = #{item.productId}');
    if(!inventory || inventory.quantity < item.quantity){ 
      setStatusCode(400);
      return {"error":"库存不足："+ product.name,"code":"INVENTORY_INSUFFICIENT"};
    }
    totalAmount += product.price * item.quantity;
  }

  // 生成订单号
  let orderNo ='ORD'+dateFormat(date(),'yyyyMMddHHmmss')+random(1000,9999);

  // 创建订单
  let orderId =insert('INSERT INTO orders(userId, orderNo, totalAmount, status, createdAt, updatedAt) VALUES(#{body.userId}, #{orderNo}, #{totalAmount}, 0, #{date()}, #{date()})');

  // 添加订单商品
  for(let item of body.items){
    let product = select.first('SELECT * FROM product WHERE id = #{item.productId}');
    insert('INSERT INTO order_item(orderId, productId, productName, price, quantity) VALUES(#{orderId}, #{item.productId}, #{product.name}, #{product.price}, #{item.quantity})');
    // 扣减库存
    update('UPDATE inventory SET quantity = quantity - #{item.quantity} WHERE productId = #{item.productId}');
  }

  // 提交事务
  commitTransaction();

  // 返回订单信息
  let order = select.first('SELECT * FROM orders WHERE id = #{orderId}');
  let orderItems =select('SELECT * FROM order_item WHERE orderId = #{orderId}'); 
  order.items = orderItems;
  return order;
}catch(e){
  // 发生异常，回滚事务
  rollbackTransaction(); 
  log.error('创建订单失败:', e);
  setStatusCode(500);
  return {"error":"创建订单失败："+ e.message,"code":"CREATE_ORDER_FAILED"};
}

// API 路径：/api/orders/:id/pay
// 方法：POST
// 描述：订单支付
// 前置脚本
let orderId = pathParams.id;
let paymentMethod = body.paymentMethod ||'alipay'; // 默认使用支付宝

// 开启事务
beginTransaction();
try{
  // 获取订单信息
  let order = select.first('SELECT * FROM orders WHERE id = #{orderId}');
  if(!order){ 
    setStatusCode(404);
    return {"error":"订单不存在","code":"ORDER_NOT_FOUND"};
  }

  // 检查订单状态
  if(order.status !==0){ // 0 表示待支付
    setStatusCode(400);
    return {"error":"订单状态不正确","code":"INVALID_ORDER_STATUS"};
  }

  // 模拟支付处理
  // 实际应用中，这里应该调用支付网关的 API
  log.info('处理支付请求:',{orderId, amount: order.totalAmount, method: paymentMethod});

  // 生成支付流水号
  let transactionNo ='TXN'+dateFormat(date(),'yyyyMMddHHmmss')+random(1000,9999);

  // 创建支付记录
  insert('INSERT INTO payment(orderId, transactionNo, amount, paymentMethod, status, createdAt) VALUES(#{orderId}, #{transactionNo}, #{order.totalAmount}, #{paymentMethod}, 1, #{date()})');

  // 更新订单状态
  update('UPDATE orders SET status = 1, updatedAt = #{date()} WHERE id = #{orderId}'); // 1 表示已支付

  // 提交事务
  commitTransaction();

  // 发送支付成功事件
  http.post('http://localhost:8080/api/events/payment-success',{ 
    orderId: orderId, 
    orderNo: order.orderNo, 
    transactionNo: transactionNo, 
    amount: order.totalAmount 
  });

  return {"message":"支付成功","orderId": orderId,"orderNo": order.orderNo,"transactionNo": transactionNo,"amount": order.totalAmount,"paymentMethod": paymentMethod }; 
}catch(e){
  // 发生异常，回滚事务
  rollbackTransaction(); 
  log.error('支付失败:', e);
  setStatusCode(500);
  return {"error":"支付失败："+ e.message,"code":"PAYMENT_FAILED"};
}

// API 路径：/api/data/query
// 方法：POST
// 描述：动态 SQL 查询，支持复杂的查询条件和分页
// 前置脚本
// 验证参数
if(!body.table){ 
  setStatusCode(400);
  return {"error":"表名不能为空","code":"TABLE_REQUIRED"};
}

// 权限检查
let allowedTables =['user','product','order_view'];
if(!allowedTables.includes(body.table)){ 
  setStatusCode(403);
  return {"error":"无权查询该表","code":"TABLE_ACCESS_DENIED"};
}

// 构建查询条件
let conditions =[];
let bindings ={};
if(body.conditions && Array.isArray(body.conditions)){ 
  body.conditions.forEach((condition, index)=>{
    if(condition.field && condition.operator && condition.value !==undefined){
      let paramName ='param_'+ index;
      let conditionStr;
      switch(condition.operator){
        case'=':case'!=':case'>':case'>=':case'<':case'<=': 
          conditionStr = condition.field +' '+ condition.operator +' #{'+ paramName +'}'; 
          bindings[paramName]= condition.value; 
          break;
        case'LIKE': 
          conditionStr = condition.field +' LIKE #{'+ paramName +'}'; 
          bindings[paramName]='%'+ condition.value +'%'; 
          break;
        case'IN':
          if(Array.isArray(condition.value)){
            let inParams =[]; 
            condition.value.forEach((val, i)=>{
              let inParamName = paramName +'_'+ i; 
              inParams.push('#{'+ inParamName +'}'); 
              bindings[inParamName]= val;
            });
            conditionStr = condition.field +' IN ('+ inParams.join(', ')+')';
          }
          break;
        default:break;
      }
      if(conditionStr){ 
        conditions.push(conditionStr);
      }
    }
  });
}

// 构建 WHERE 子句
let whereClause = conditions.length >0?'WHERE '+ conditions.join(' AND '):'';

// 构建 ORDER BY 子句
let orderByClause ='';
if(body.orderBy && Array.isArray(body.orderBy)){
  let orderFields =[];
  body.orderBy.forEach(order=>{
    if(order.field){
      let direction = order.direction && order.direction.toUpperCase()==='DESC'?'DESC':'ASC'; 
      orderFields.push(order.field +' '+ direction);
    }
  });
  if(orderFields.length >0){ 
    orderByClause ='ORDER BY '+ orderFields.join(', ');
  }
}

// 构建分页
let limitClause ='';
let offsetClause ='';
if(body.page && body.size){ 
  limitClause ='LIMIT #{limit}'; 
  offsetClause ='OFFSET #{offset}'; 
  bindings.limit = body.size; 
  bindings.offset =(body.page -1)* body.size;
}

// 合并绑定参数
Object.assign(binding, bindings);

// SQL 语句
SELECT * FROM #{body.table} ${whereClause} ${orderByClause} ${limitClause} ${offsetClause};
SELECT COUNT(*) as total FROM #{body.table} ${whereClause};

// 后置脚本
// 构造分页结果
let resultData ={"data": result[0]};

// 如果是分页查询，添加分页信息
if(body.page && body.size){ 
  resultData.page = body.page; 
  resultData.size = body.size; 
  resultData.total = result[1][0].total; 
  resultData.totalPages = Math.ceil(result[1][0].total / body.size);
}
return resultData;

<!-- Maven 依赖 -->
<dependency>
  <groupId>org.ssssssss</groupId>
  <artifactId>magic-api-spring-boot-starter</artifactId>
  <version>2.0.0</version>
</dependency>

magic-api:
  # API 管理路径
  web:
    # 启用 Magic API 管理界面
    enable: true
    # API 管理界面路径
    path: /magic/*
    # API 存储位置
    resources: classpath:magic-api

@Component
public class CustomFunction implements FunctionLoader {
  @Override
  public void load(FunctionRepository repository){
    // 添加自定义函数
    repository.addFunction("customFunction",(params)->{
      // 函数实现
      return "Custom function result";
    });
  }
}

@Component
public class CustomDataSourcePlugin implements DataSourceProvider {
  @Override
  public DataSource getDataSource(String name){
    // 根据名称返回自定义数据源
    if("customDataSource".equals(name)){
      // 创建并配置自定义数据源
      HikariConfig config = new HikariConfig(); 
      config.setJdbcUrl("jdbc:mysql://localhost:3306/custom_db"); 
      config.setUsername("custom_user"); 
      config.setPassword("custom_password");
      return new HikariDataSource(config);
    }
    return null;
  }
}

Magic API：低代码接口开发平台完全指南

Magic API：低代码接口开发平台完全指南

摘要

1. Magic API 概述与核心概念

1.1 什么是 Magic API

1.2 Magic API 的核心特性

1.3 Magic API 的设计理念

2. Magic API 架构设计与组件分析

2.1 整体架构概览

2.2 API 引擎工作原理

2.3 脚本引擎与 SQL 执行机制

3. Magic API 核心功能实现

3.1 API 定义与创建

3.2 数据源配置与管理

3.3 脚本语言与内置函数

4. Magic API 实践案例

4.1 构建一个用户管理系统

4.1.1 用户列表 API

4.1.2 创建用户 API

4.1.3 更新用户 API

4.1.4 删除用户 API

4.2 构建一个订单处理系统

4.2.1 创建订单 API

4.2.2 订单支付 API

4.3 构建一个统一的数据查询平台

4.3.1 动态 SQL 查询 API

5. Magic API 性能优化与最佳实践

5.1 API 性能优化技巧

5.1.1 缓存策略优化

5.1.2 SQL 优化技巧

5.1.3 批量操作与异步处理

5.2 开发规范与团队协作

5.3 安全最佳实践

6. Magic API 集成与扩展

6.1 与 Spring Boot 集成

6.2 自定义函数扩展

6.3 第三方系统集成

6.4 插件开发与扩展

7. 总结与展望

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具