Api Magic Gen

基于magic-api的Java接口专业版，支持多数据源、拦截器、OpenAPI导出、性能监控、接口版本和团队协作管理。

Install

openclaw skills install @thcjp/api-magic-gen

接口魔法生成专业版

核心能力

能力分类	免费版	专业版
脚本行数上限	100行	无上限
数据源	单数据源	多数据源切换
拦截器	无	自定义拦截器链
全局变量	无	支持定义与共享
文档导出	无	OpenAPI 3.0自动生成
性能监控	无	接口级QPS/RT/错误率
版本管理	Git	内置版本+灰度发布
团队协作	单人	多人编辑+权限控制
安全增强	基础认证	鉴权+限流+IP白名单+SQL审计
优先支持	社区	工单优先响应

能力分类

执行能力分类操作,处理用户输入并返回结果。

输入: 用户提供能力分类所需的参数和指令。

输出: 返回能力分类的处理结果。

执行能力分类操作，处理输入数据并返回结果
验证执行结果，确认输出符合预期格式
参考能力分类相关配置参数进行设置

脚本行数上限

执行脚本行数上限操作,处理用户输入并返回结果。

输入: 用户提供脚本行数上限所需的参数和指令。

输出: 返回脚本行数上限的处理结果。

执行脚本行数上限操作，处理输入数据并返回结果
验证执行结果，确认输出符合预期格式
参考脚本行数上限相关配置参数进行设置

数据源

执行数据源操作,处理用户输入并返回结果。

输入: 用户提供数据源所需的参数和指令。

输出: 返回数据源的处理结果。

执行数据源操作，处理输入数据并返回结果
验证执行结果，确认输出符合预期格式
参考数据源相关配置参数进行设置

能力覆盖范围

本skill还覆盖以下能力场景: magic、的接口全功能专业、含多数据源、性能监控与团队协、作能力、Java、后端团队与企业的、接口快速生成全功、能专业版、在免费版基础上新、增多数据源切换、性能监控告警、接口版本管理、团队协作编辑、灰度发布等高级能、配套面向架构师、前端的多角色场景、Use、需要系统监控、日志分析、运维告警、部署管理时使用、不适用于物理硬件。这些能力在上述核心功能中均有对应处理逻辑。

适用场景

场景一：企业API网关（架构师视角）

作为BFF层统一聚合后端微服务接口，对前端提供定制化API，屏蔽后端服务拆分细节。

javascript

// 聚合多个微服务接口
var user = http.get("http://user-service/users/" + path.id);
var orders = http.get("http://order-service/orders?userId=" + path.id);

return {
    user: user.data,
    recentOrders: orders.data.slice(0, 5)
};

场景二：多团队协作开发（运维视角）

通过权限控制隔离不同团队的脚本目录，支持代码评审与灰度发布。

yaml

magic-api:
  team:
    enabled: true
    roles:
      - name: "trade-team"
        paths: ["/api/trade/*"]
        publish: "review-required"
      - name: "user-team"
        paths: ["/api/user/*"]
        publish: "auto"

场景三：对外开放SaaS API（产品视角）

为SaaS产品提供对外API，配套OpenAPI文档、鉴权、限流、配额管理。

场景四：多数据源业务隔离（开发者视角）

不同业务模块使用独立数据库，通过注解切换数据源，避免跨库JOIN混乱。

javascript

// 使用@datasource注解切换数据源
// @datasource: trade_db
var order = db.selectOne("select * from orders where id = ?", path.id);

// @datasource: user_db
var user = db.selectOne("select * from users where id = ?", order.userId);

使用流程

优秀步：启用专业版功能

yaml

magic-api:
  web: /magic/web
  edition: pro
  multi-datasource:
    enabled: true
  interceptor:
    enabled: true
  monitor:
    enabled: true
    slow-threshold-ms: 500
  openapi:
    enabled: true
    path: /v3/api-docs

第二步：配置多数据源

yaml

spring:
  datasource:
    trade:
      url: jdbc:mysql://localhost:3306/trade_db
      username: ${TRADE_DB_USER}
      password: ${TRADE_DB_PASS}
    user:
      url: jdbc:postgresql://localhost:5432/user_db
      username: ${USER_DB_USER}
      password: ${USER_DB_PASS}

第三步：定义全局拦截器

javascript

// 鉴权拦截器（在Web UI的"拦截器"配置中定义）
var token = request.header("Authorization");
if (!token) {
    return {code: 401, msg: "缺少Token"};
}
var userId = cache.get("token:" + token);
if (!userId) {
    return {code: 401, msg: "Token无效或已过期"};
}
// 注入到全局变量供后续脚本使用
global.currentUserId = userId;

完整上手时间约300秒（含多数据源与拦截器配置）。

输入格式

参数名	类型	必填	说明
content	string	是	相关说明
content	string	否	相关说明, 默认: 全部维度
strict_level	string	否	审查严格度, 可选: strict/normal/loose, 默认: normal

输出格式

json

{
  "success": true,
  "data": {
    "overall_grade": "A",
    "total_score": 92,
    "max_score": 100,
    "summary": "处理完成",
    "details": [
      {
        "item": "代码风格",
        "status": "pass",
        "score": 95,
        "comment": "符合规范"
      },
      {
        "item": "安全合规",
        "status": "warn",
        "score": 80,
        "comment": "符合规范"
      }
    ],
    "improvements": [
      {
        "priority": "high",
        "suggestion": "建议优化",
        "expected_gain": "+5分"
      },
      {
        "priority": "medium",
        "suggestion": "建议优化",
        "expected_gain": "+3分"
      }
    ]
  },
  "error": null
}

异常处理

错误场景	原因	处理方式
待审查内容为空	用户未提供内容	提示用户提供待审查的代码
内容格式不识别	传入不支持的内容格式	列出支持的格式, 建议转换后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
检查项超出范围	传入了不存在的检查维度	列出可用检查维度, 使用默认全部检查
审查超时	内容过长导致处理超时	建议分段审查, 每段不超过5000字
其他异常	内部处理异常	检查输入后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令

依赖说明

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux
JDK: 8+
Maven: 3.5+
Spring Boot: 2.x/3.x

依赖说明

依赖项	类型	是否必需	获取方式
JDK	运行时	必需	adoptium.net 官方下载
Maven	构建工具	必需	maven.apache.org 官方下载
magic-api-spring-boot-starter	Java依赖	必需	Maven中央仓库
Spring Boot	Java框架	必需	Maven中央仓库
JDBC驱动	Java依赖	必需	根据数据库类型选择
Prometheus	监控系统	可选	prometheus.io 官方下载
Grafana	可视化面板	可选	grafana.com 官方下载
配置中心(Nacos/Apollo)	配置管理	可选	各自官方仓库

API Key 配置

数据库密码: 通过环境变量注入（TRADE_DB_PASS、USER_DB_PASS等），禁止硬编码
告警Webhook: 通过ALERT_WEBHOOK_URL环境变量配置
钉钉机器人Token: 通过DINGTALK_TOKEN环境变量配置
配置中心凭证: 通过NACOS_USERNAME/NACOS_PASSWORD等环境变量配置

可用性分类

分类: MD+EXEC（）
说明: 基于Markdown的AI Skill，

案例展示

OpenAPI文档自动生成

专业版自动为所有接口生成OpenAPI 3.0文档，前端可直接通过Swagger UI查看与调试。

访问 http://localhost:9999/v3/api-docs 获取JSON，或 http://localhost:9999/swagger-ui.html 查看可视化文档。

接口脚本中通过注解补充元信息：

javascript

// @summary: 查询用户订单列表
// @tags: [订单, 用户]
// @response: OrderListResponse
var orders = db.select("select * from orders where user_id = ?", global.currentUserId);
return {code: 200, data: orders};

性能监控与告警

yaml

magic-api:
  monitor:
    enabled: true
    slow-threshold-ms: 500       # 慢接口阈值
    error-rate-alert: 0.05       # 错误率告警阈值5%
    metrics-export:
      type: prometheus
      path: /metrics
    alert:
      webhook: ${ALERT_WEBHOOK_URL}
      dingtalk: ${DINGTALK_TOKEN}

限流与配额

javascript

// @rate-limit: 100/minute         # 每分钟100次
// @quota: 10000/day               # 每日1万次
var data = db.select("select * from products");
return {code: 200, data: data};

灰度发布

yaml

magic-api:
  publish:
    strategy: canary
    canary-percentage: 10         # 10%流量灰度
    auto-promote: false           # 需手动确认全量

常见问题

Q1：多数据源切换失效怎么办？

A：检查@datasource注解是否在脚本优秀行，且数据源名称与配置文件中一致。跨数据源事务不支持，需通过分布式事务框架（如Seata）处理。

Q2：OpenAPI文档不显示接口说明？

A：确认接口脚本中已添加@summary、@tags、@response等注解。专业版支持通过YAML格式注解提供更详细的请求/响应模型定义。

Q3：灰度发布后如何快速回滚？

A：通过Web UI的"发布历史"一键回滚到任意历史版本。建议每次发布前打Tag，便于精准回滚。

Q4：性能监控数据如何长期存储？

A：专业版支持将监控指标导出到Prometheus，配合Grafana实现长期存储与可视化。建议保留90天明细数据，1年聚合数据。

Q5：限流策略如何动态调整？

A：通过配置中心或Web UI的"限流管理"页面动态调整，无需重启服务。建议按接口重要程度分级配置：核心接口1000QPS，非核心接口100QPS。

Q6：如何防止SQL注入？

A：(1) 强制使用?参数占位符；(2) 开启SQL审计日志定期审查；(3) 对动态拼接SQL的脚本增加代码评审要求；(4) 数据库账号最小权限原则，禁止DROP/ALTER。

Q7：团队协作时如何避免冲突？

A：(1) 按业务域划分目录权限；(2) 启用编辑锁，同一脚本同时只能一人编辑；(3) 修改前先拉取最新版本；(4) 重要接口修改必须经过评审。

Q8：如何与已有Spring Boot Controller共存？

A：magic-api接口与Spring MVC Controller可以共存，magic-api拦截器仅对/api/*路径生效。建议通过路径前缀区分：magic-api用/api/，传统Controller用/controller/。

错误处理

错误场景	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

已知限制

需要API Key，无Key环境无法使用