Api Magic Gen

面向Java后端团队与企业的接口快速生成全功能专业版。在免费版基础上新增多数据源切换、自定义拦截器、全局变量、OpenAPI文档导出、性能监控告警、接口版本管理、团队协作编辑、灰度发布等高级能力，配套面向架构师、运维、前端的多角色场景指南。Use when 需要系统监控、日志分析、运维告警、部署管理时使用。不适用...

天轰穿@thcjp

Install

openclaw skills install @thcjp/api-magic-gen

核心功能: 本技能提供化工作流场景等能力。

核心功能: 本技能提供中文交互等能力。

核心功能: 本技能提供全功能专业版、、运维告警、部署管理时使用、时使用等能力。

接口魔法生成专业版

专业版专属特性

能力	免费版	付费版
基础功能	支持	支持
接口魔法生成专业版OpenAPI导出	不支持	支持
接口魔法生成专业版性能监控	不支持	支持
代码静态分析与质量评分	不支持	支持
依赖漏洞检测与升级建议	不支持	支持
批量代码审查与报告生成	不支持	支持

功能能力

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

上手指南

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

适用范围

场景一：企业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:数据库://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	否	api-magic-gen处理的内容输入
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
}

错误恢复方案

错误场景	原因	处理方式
待审查内容为空	用户未提供内容	提示用户提供待审查的代码
内容格式不识别	传入不支持的内容格式	列出支持的格式, 建议转换后
检查项超出范围	传入了不存在的检查维度	列出可用检查维度, 使用默认全部检查
审查超时	内容过长导致处理超时	建议分段审查, 每段不超过5000字
其他异常	内部处理异常	检查输入后

安装与配置

运行环境

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

使用约束

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

问题排查手册

错误现象	可能原因	诊断步骤	解决方案
接口无法访问	数据源配置错误	检查数据源配置文件，确认URL、用户名、密码正确	修正数据源配置，重新启动服务
拦截器未生效	拦截器配置错误	检查拦截器配置，确认拦截器类路径正确，且已添加到拦截器链	修正拦截器配置，重新启动服务
OpenAPI文档无法生成	接口未添加注解	检查接口脚本，确认已添加`@summary`、`@tags`、`@response`等注解	添加必要的注解，重新生成文档
性能监控数据缺失	Prometheus配置错误	检查Prometheus配置文件，确认指标路径正确，且已启用指标导出	修正Prometheus配置，重新启动服务
团队协作冲突	文件版本不一致	检查版本控制工具，确认最新代码已同步	同步最新代码，解决冲突

安全提示

风险项	等级	防护措施	验证方法
SQL注入攻击	高	使用参数化查询，禁用动态SQL拼接	定期进行SQL审计，检查日志
未授权访问	高	实施严格的认证和授权机制	定期进行安全审计，检查访问控制
代码执行漏洞	中	限制脚本执行权限，使用沙箱环境	定期进行代码审查，检查执行权限
数据泄露	高	加密敏感数据，实施数据访问控制	定期进行数据安全检查，验证加密措施
配置泄露	高	确保配置文件安全，限制访问权限	定期检查配置文件权限，确保安全

差异化分析

提升效率	量化分析
接口开发效率	提升约40%，通过自动化生成接口和文档，减少人工编写时间
性能监控效率	提升约30%，通过自动收集和展示性能数据，减少手动监控时间
团队协作效率	提升约25%，通过多人协作编辑和权限控制，提高团队协作效率
安全管理效率	提升约20%，通过自动化安全检查和配置管理，减少安全风险

差异化对比	特点
自动化程度	高，提供自动化接口生成、文档导出、性能监控等功能
多数据源支持	支持多数据源切换，满足复杂业务需求
安全性	提供鉴权、限流、IP白名单等安全措施，保障接口安全
团队协作	支持多人协作编辑和权限控制，提高团队协作效率
可视化	提供OpenAPI文档和性能监控的可视化界面，方便使用和维护

功能介绍

自动化执行: 基于magic-api的接口全功能专业版，含多数据源、拦截器、OpenAPI导出、性能监控与团队协作能力。
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果
信息检索: 快速搜索和过滤目标数据

效能分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

优势对比

对比维度	接口魔法生成专业版	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	基于magic-api的接口全功能专业版，含多数据源、拦截器、OpenAPI导出	通用场景	通用场景

技术支持

Q1: 接口魔法生成专业版支持哪些输入格式？

A1: 基于magic-api的接口全功能专业版，含多数据源、拦截器、OpenAPI导出、性能监控与团队协作能力。。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

故障恢复

针对接口魔法生成专业版使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

接口魔法生成专业版通用排查步骤

检查输入参数: 确认所有必填参数已提供且格式正确
查看日志输出: 定位具体错误行和异常类型
验证环境配置: 确认依赖库版本和运行环境满足要求
逐步调试: 缩小问题范围,隔离故障模块

疑问与回应

故障恢复流程

针对接口魔法生成专业版使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

用户常见问题

适用边界

涉及关键决策的场景需人工复核,避免因自动化遗漏关键因素
API调用受平台速率限制,高频场景需实现请求队列和退避策略
文件路径需使用合法字符,避免特殊字符导致路径解析异常
命令执行权限需遵循最小权限原则,避免以root/administrator权限运行