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

前端层负责提供用户界面，包括 Web 管理界面和 Swagger 文档界面；核心层处理 API 的解析、执行和响应；数据层管理 API 元数据和数据源；外部系统则是 Magic API 需要交互的各种数据库。

2.2 API 引擎工作原理

API 引擎是 Magic API 的核心组件，负责处理 API 的解析、执行和响应。下面的流程图展示了 API 请求的处理过程：

HTTP 请求路由分发解析 API 定义验证通过获取数据源处理结果格式化响应客户端请求 API 网关 API 引擎参数验证执行前置脚本执行 SQL/脚本执行后置脚本返回结果

API 请求首先通过 API 网关进行路由分发，然后由 API 引擎解析 API 定义，进行参数验证，执行前置脚本，获取数据源，执行 SQL 或脚本，处理结果，执行后置脚本，最后格式化响应并返回给客户端。

2.3 脚本引擎与 SQL 执行机制

Magic API 的一大特色是支持多种脚本语言和灵活的 SQL 执行方式。脚本引擎负责解析和执行前置脚本和后置脚本，而 SQL 执行器则负责解析和执行 SQL 语句。下面是脚本和 SQL 执行的详细过程：

1. 脚本解析与执行：Magic API 使用 JavaScript 或 Groovy 引擎来解析和执行脚本。脚本可以访问请求参数、数据库连接、HTTP 客户端等资源。
2. SQL 参数绑定：在执行 SQL 之前，Magic API 会将脚本中定义的绑定参数（如#{userId}）替换为实际的值，防止 SQL 注入攻击。
3. 多语句执行：Magic API 支持在一个 API 中执行多条 SQL 语句，结果会按顺序存储在 result 数组中。
4. 事务控制：通过beginTransaction()、commitTransaction()和rollbackTransaction()函数，开发者可以在脚本中精确控制事务的边界。

客户端 API 引擎脚本引擎 SQL 执行器数据源发送 API 请求执行前置脚本返回脚本执行结果解析并执行 SQL 执行数据库操作返回查询结果处理 SQL 执行结果执行后置脚本返回脚本处理结果返回最终响应客户端 API 引擎脚本引擎 SQL 执行器数据源

通过这种设计，Magic API 实现了脚本和 SQL 的无缝集成，让开发者能够以简洁的方式处理复杂的业务逻辑。

3. Magic API 核心功能实现

3.1 API 定义与创建

安装方法请参考官方文档。

主界面就是这样的。请求参数有点类似 MyBatis 风格的占位符，需要插入的参数得确保参数名一模一样，后面可以选择参数值，参数类型，是否必要等需求。用 #{} 来表示即可。

3.2 数据源配置与管理

Magic 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 配置
magic-api:
  # API 存储位置
  web:
    resources: classpath:magic-api
  # 数据源配置
  datasource:
    # 默认使用 primary 数据源
    default: primary
    # 启用动态数据源
    dynamic: true

这个是用 application.yml 的写法。当然，用 application.properties 去写也是一样的。这里注意，properties 的优先度是高于 yml 后缀的文件的。也就是说假如有 properties 和 yml 的配置文件同时存在时，Spring Boot 优先采用以 properties 结尾的作为配置信息。不过不建议两个同时存在，二选其一即可，只不过书写形式会有些差异，用我自己在工作时的配置作为示例：

在 API 定义中，我们可以通过注释来指定使用的数据源：

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

3.3 脚本语言与内置函数

Magic API 支持 JavaScript 和 Groovy 两种脚本语言，并提供了丰富的内置函数库。下面是一些常用的内置函数示例：

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

// HTTP 相关
// 发送 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 开发中的常见操作，让开发者能够更加专注于业务逻辑的实现。

4. Magic API 实践案例

4.1 构建一个用户管理系统

让我们通过一个简单的用户管理系统来展示 Magic API 的实际应用。这个系统需要实现用户的增删改查功能。

4.1.1 用户列表 API

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

4.1.2 创建用户 API

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

4.1.3 更新用户 API

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

4.1.4 删除用户 API

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

4.2 构建一个订单处理系统

接下来，让我们构建一个更复杂的订单处理系统，展示 Magic API 处理复杂业务逻辑的能力。

4.2.1 创建订单 API

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

4.2.2 订单支付 API

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

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

Magic API 不仅可以用于构建业务系统，还可以用于构建统一的数据查询平台，为不同的用户提供定制化的数据查询服务。

4.3.1 动态 SQL 查询 API

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

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

5.1 API 性能优化技巧

在使用 Magic API 构建高性能服务时，我们需要关注以下几个关键方面的优化：

5.1.1 缓存策略优化

对于查询频繁且数据更新不频繁的场景，合理使用缓存可以显著提升性能。Magic API 支持本地缓存和分布式缓存。

5.1.2 SQL 优化技巧

• 使用参数化查询防止 SQL 注入并提高效率
• 合理创建索引避免全表扫描
• 优化 JOIN 查询减少表连接
• 查询仅包含必要字段减少数据传输

5.1.3 批量操作与异步处理

• 对大量数据操作使用批量处理减少数据库交互
• 对耗时操作采用异步处理避免阻塞 API 响应

5.1.4 其他优化建议

1. 合理使用缓存：对于频繁查询但不常变动的数据，使用缓存可以显著提高 API 响应速度
2. 优化 SQL 语句：避免使用 SELECT *，添加合适的索引，使用分页查询等
3. 批量操作：对于批量增删改操作，使用批量 SQL 而不是逐条执行
4. 异步处理：对于耗时操作，使用异步处理避免阻塞主线程
5. 连接池配置：合理配置数据库连接池，避免连接过多或过少

5.2 开发规范与团队协作

团队开发中应建立以下规范：

1. API 命名规范：采用 RESTful 风格，使用清晰的中文描述
2. 代码风格：统一缩进、注释和错误处理格式
3. 协作流程：实施 API 设计评审、版本管理、测试规范和文档更新机制
4. 代码审查：关注命名规范、参数验证、异常处理、性能优化和日志记录

5.3 安全最佳实践

在使用 Magic API 构建系统时，安全是一个不可忽视的重要方面。以下是一些安全最佳实践：

1. 参数验证：对所有输入参数进行严格验证，防止 SQL 注入和 XSS 攻击
2. 权限控制：实施细粒度的权限控制，确保用户只能访问其有权限的资源
3. 数据加密：对敏感数据进行加密存储，使用 HTTPS 传输数据
4. 日志记录：记录关键操作日志，便于审计和问题排查
5. 限流措施：实施 API 限流，防止恶意请求和 DDoS 攻击

6. Magic API 集成与扩展

Magic API 提供了丰富的集成能力，可以与各种系统和框架无缝对接，同时还支持灵活的扩展机制，满足不同业务场景的需求。

6.1 与 Spring Boot 集成

Magic API 可以轻松集成到 Spring Boot 项目中，只需要添加相应的依赖和配置：

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

然后在 application.properties 或 application.yml 中配置 Magic API：

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

6.2 自定义函数扩展

Magic API 支持自定义函数扩展，我们可以根据业务需求添加自定义函数：

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

6.3 第三方系统集成

Magic API 可以轻松与各种第三方系统进行集成：

1. 消息队列集成：支持与 RabbitMQ、Kafka 等消息队列系统对接，实现异步消息处理
2. 缓存集成：可与 Redis 等分布式缓存集成，提升数据访问性能
3. 定时任务：可结合 Quartz 等定时任务框架，实现定期执行 API 逻辑

6.4 插件开发与扩展

Magic API 支持通过插件机制进行功能扩展，可以自定义数据源、脚本引擎或其他功能组件：

@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;
  }
}

7. 总结与展望

Magic API 作为一款轻量级的低代码 API 开发平台，为开发者提供了快速构建高质量 API 的解决方案。通过可视化界面和强大的脚本能力，Magic API 大幅降低了 API 开发的门槛，提高了开发效率。

在实际应用中，Magic API 可以广泛应用于以下场景：

• 快速原型开发：快速构建 API 原型，验证业务概念
• 业务系统开发：构建企业内部业务系统的 API 层
• 数据接口服务：为前端应用提供数据接口服务
• 微服务组件：作为微服务架构中的 API 网关或服务组件

随着低代码平台的不断发展，Magic API 也在不断完善和优化。未来，我们可以期待 Magic API 在以下方面的进一步发展：

• 支持更多的数据源和数据库类型
• 提供更丰富的可视化设计功能
• 增强 API 监控和性能分析能力
• 支持更多的脚本语言和开发方式
• 提供更完善的团队协作功能

总之，Magic API 为 API 开发带来了新的思路和方法，让开发者能够更加专注于业务逻辑的实现，提高开发效率和质量。无论是小型项目还是大型企业应用，Magic API 都能为其提供强大的支持。