Magic API

https://github.com/ssssssss-team/magic-api
Admin
Magic API is a Java-based fast interface development framework that allows for HTTP API interface...
Tokens:83,053
Snippets:503
Trust Score:-
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Script example using env.get()

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

Script example showing how to use the env module to read Spring configuration properties, including a call with a default value.

```javascript
// 读取 Spring 配置
var appName = env.get('spring.application.name');
var timeout = env.get('custom.timeout', '30');
```

--------------------------------

### HTTP module usage examples

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

Shows how to use the http module for GET, POST JSON, form submission, and error handling. The GET example uses param, header, and expectString; the POST JSON uses body; the form uses data; the error handling catches RestTemplate exceptions.

```javascript
// GET
var resp = http.connect('https://api.example.com/users')
    .param('page', 1)
    .header('Authorization', 'Bearer xxx')
    .expectString()
    .get();
return resp.getBody();

// POST JSON
var resp2 = http.connect('https://api.example.com/order')
    .body({userId: 1, amount: 99.9})
    .expectString()
    .post();

// form 提交
var resp3 = http.connect('https://api.example.com/login')
    .data('username', 'admin')
    .data('password', '123456')
    .post();

// 错误处理：捕获 RestTemplate 异常
try {
    var r = http.connect('https://api.example.com/none').get();
} catch (e) {
    return '请求失败: ' + e;
}
```

--------------------------------

### ResponseModule script example

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

JavaScript example showing how to use the response module in scripts: file download, image output, redirect, and direct output stream usage.

```javascript
// 文件下载
return response.download(db.selectValue('select content from file_tbl where id = #{id}', {id: 1}), '导出.xlsx');

// 输出图片
return response.image(db.selectValue('select img from img_tbl where id = #{id}', {id: 1}), 'image/png');

// 重定向并终止
response.redirect('/login');

// 直接输出流（如 excel 生成）
var os = response.getOutputStream();
os.write(bytes);
return response.end();
```

--------------------------------

### RequestModule script example

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

JavaScript example showing how to use the request module in scripts: retrieving an uploaded file and getting the client IP with custom header names.

```javascript
// 上传文件
var file = request.getFile('avatar');
return file;                       // MultipartFile

// 客户端 IP（可追加自定义 header 名）
return request.getClientIP('X-Real-IP', 'X-Forwarded-For');
```

--------------------------------

### Spring Boot Application Entry Point

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/11-spring-boot-starter.md

Standard Spring Boot application entry point used to start the demo application that integrates magic-api. Run this main class to launch the application with the configured properties.

```java
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

--------------------------------

### Redis script usage

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/15-plugins.md

Example of using Redis in a script: retrieves the value for key 'foo'.

```javascript
redis.get('foo')
```

--------------------------------

### Configure magic-api in application.properties

Source: https://github.com/ssssssss-team/magic-api/blob/master/README.md

Configure the server port, the web UI entry path (magic-api.web), and the resource storage location (magic-api.resource.location). When the resource location starts with classpath, it is read-only.

```properties
server.port=9999
#配置web页面入口
magic-api.web=/magic/web
#配置文件存储位置。当以classpath开头时，为只读模式
magic-api.resource.location=/data/magic-api
```

--------------------------------

### Calling Magic APIs from script and Java with MagicAPIService

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/02-magic-api-service.md

Shows how to call another Magic API from a script using the magic module (commented lines) and from Java using MagicAPIService. The Java example demonstrates execute for raw return values, call for wrapped responses, and invoke which throws MagicAPIException when the interface is not found.

```java
// 在脚本中调用另一个接口（module: magic）
// return magic.call('POST', '/order/create', {userId:1, amount: 99.9});
// return magic.execute('GET', '/user/detail', {id: 1});
// return magic.invoke('/common/uuid', {});

// 在 Java 中调用
@RestController
public class OrderController {
    @Autowired
    private MagicAPIService magicAPIService;

    @GetMapping("/call-magic")
    public Object callMagic() {
        Map<String, Object> ctx = new HashMap<>();
        ctx.put("id", 100);
        // 原始返回值
        Map<String, Object> raw = magicAPIService.execute("GET", "/user/detail", ctx);
        // 带 code/message 包装
        Object wrapped = magicAPIService.call("GET", "/user/detail", ctx);
        // 错误处理：找不到接口时抛 MagicAPIException
        try {
            magicAPIService.invoke("/not/exist", ctx);
        } catch (MagicAPIException e) {
            return "接口不存在: " + e.getMessage();
        }
        return wrapped;
    }
}
```

--------------------------------

### KeyValueResource abstract class declaration and constructors

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/10-resource-storage.md

Abstract base class for path + Map content model. Constructors take separator, path, readonly flag, and parent. Subclasses implement put(String, String) and get(String). Other methods like separator(), name(), getResource(), mkdir(), parent(), write(), dirs(), files(), getAbsolutePath(), getFilePath() are based on key concatenation. renameTo is final and uses abstract renameTo(Map<String,String>).

```java
public abstract class KeyValueResource implements Resource {
    public KeyValueResource(String separator, String path, KeyValueResource parent) { ... }
    public KeyValueResource(String separator, String path, boolean readonly, KeyValueResource parent) { ... }
    abstract void put(String key, String value);                  // 子类实现写入
    abstract String get(String key);                              // 子类实现读取
    // 其余：separator()/name()/getResource()/mkdir()/parent()/write()/dirs()/files()/getAbsolutePath()/getFilePath() 等基于 key 拼接
}
```

--------------------------------

### Example JSON response from nebula plugin

Source: https://github.com/ssssssss-team/magic-api/blob/master/magic-api-plugins/magic-api-plugin-nebula/nebula插件.md

Example JSON response returned by the nebula plugin. The data contains nodes and edges arrays, which can be used by front-end component libraries like AntV G6 for visualization.

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "nodes": [
            {
                "edgeSize": 1,
                "assignee.name": "中航纽赫融资租赁（上海）有限公司",
                "type": "vertex",
                "assignee.addr": "上海市中国（上海）自由贸易试验区正定路530号A5库区集中辅助区三层318室",
                "assignee.legal_person": "周勇",
                "registrant.addr": "上海市浦东新区南泉路1261号",
                "registrant.name": "中航国际租赁有限公司",
                "id": "中航纽赫融资租赁（上海）有限公司",
                "assignee.type": "企业"
            },
            {
                "edgeSize": 15,
                "type": "vertex",
                "transferor.name": "陕西海富融资租赁有限公司",
                "transferor.legal_person": "刘子瑜",
                "transferor.type": "企业",
                "transferor.addr": "陕西省西安市西安经济技术开发区未央路170号赛高城市广场2号楼企业总部大厦26层05单元",
                "registrant.addr": "广东省深圳市前海深港合作区南山街道梦海大厦5035号前海华润金融中心T5写字楼1808",
                "registrant.name": "深圳前海盈峰商业保理有限公司",
                "id": "陕西海富融资租赁有限公司"
            }, ...
        ],
        "edges": [
            {
                "dst": "陕西海富融资租赁有限公司",
                "src": "中航纽赫融资租赁（上海）有限公司",
                "source": "中航纽赫融资租赁（上海）有限公司",
                "label": "trans_with",
                "type": "edge",
                "target": "陕西海富融资租赁有限公司",
                "name": "trans_with",
                "ranking": 0,
                "value": 0
            },...
        ]
    },
    "timestamp": 1692149280167,
    "requestTime": 1692149280143,
    "executeTime": 24
}
```

--------------------------------

### SQL module script usage examples

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Shows common SQL module operations in JavaScript: select with named parameters, cached queries, insert returning primary key, pagination (default and manual), transactions (automatic and manual), multi-datasource access, and stored procedure calls.

```javascript
// 基本查询（SQL 中 #{}为参数占位）
var list = db.select("select * from user where name = #{name}", {name: '张三'});

// 带缓存的查询
var cached = db.cache('userCache', 60).select("select * from user where id = #{id}", {id: 1});

// 插入返回主键
var newId = db.insert("insert into user(name) values (#{name})", 'id', {name: '李四'});

// 分页（默认从 page/size 参数读取）
var paged = db.page("select * from user");

// 手动分页
var paged2 = db.page("select * from user", 10, 0);

// 事务
db.transaction(() => {
    db.update("update account set money = money - 100 where id = #{id}", {id: 1});
    db.update("update account set money = money + 100 where id = #{id}", {id: 2});
});

// 手动事务
var tx = db.transaction();
try {
    db.update("insert into log(content) values (#{content})", {content: 'x'});
    tx.commit();
} catch (e) {
    tx.rollback();
    throw e;
}

// 多数据源
return db.otherDs.select("select * from order_item");

// 存储过程（sql 类型参数）
var result = db.call("{call get_user_info(?, ?)}");
```

--------------------------------

### POST /backup/full

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

Performs a full backup of the system.

```APIDOC
## POST /backup/full

### Description
Performs a full backup of the system.

### Method
POST

### Endpoint
/backup/full

### Parameters
None

### Response
#### Success Response (200)
- **result** (Boolean) - Indicates success.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### Dialect interface definition

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/06-db-infrastructure.md

Defines the Dialect interface for database-specific SQL generation, including methods to match a database by JDBC URL or connection, get count SQL, and get pagination SQL.

```java
public interface Dialect {
    Pattern REPLACE_ORDER_BY = ...;
    default boolean match(String jdbcUrl) { return false; }
    default boolean match(Connection connection) throws SQLException { return match(connection.getMetaData().getURL()); }
    default String getCountSql(String sql) { return "select count(1) from ( \n" + 去掉 order by ... + "\n ) count_"; }
    String getPageSql(String sql, BoundSql boundSql, long offset, long limit);
}
```

--------------------------------

### Call management endpoints with curl

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

Shows how to log in, fetch the resource tree, save an interface entity, and push remotely using curl. Requires security configuration and a valid Magic-Token.

```bash
# 登录（启用 security 配置后）
curl -X POST http://localhost:9999/magic/web/login \
  -d 'username=admin&password=admin123' -i            # 响应头 Magic-Token: <token>

# 带 token 获取资源树
curl -X POST http://localhost:9999/magic/web/resource \
  -H 'Magic-Token: <token>'

# 保存一个接口实体（内容为 ROT13 加密后的 json + script）
curl -X POST "http://localhost:9999/magic/web/resource/file/api/save" \
  -H 'Magic-Token: <token>' --data-binary @entity.rot13

# 远程推送
curl -X POST "http://localhost:9999/_magic-api-sync" \
  -F 'timestamp=1650000000000' -F 'mode=full' -F 'sign=<sign>' -F 'file=@magic-api.zip'
```

--------------------------------

### GET /backup

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

Returns the script content from the backup for the given timestamp and ID.

```APIDOC
## GET /backup

### Description
Returns the script content from the backup for the given timestamp and ID.

### Method
GET

### Endpoint
/backup

### Parameters
#### Query Parameters
- **timestamp** (Long) - Required - The timestamp of the backup.
- **id** (String) - Required - The ID of the backup.

### Response
#### Success Response (200)
- **script** (String) - The script content from the backup.

#### Response Example
```json
{
  "script": "return 'hello';"
}
```
```

--------------------------------

### Construct and register ApiInfo programmatically

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/14-core-models.md

Shows how to programmatically construct an ApiInfo entity and register it. Sets id, name, path, method, groupId, script, and a parameter with validation. The final registration line is commented out because it is normally done by the resource service.

```java
// 编程式构造接口实体并注册
ApiInfo api = new ApiInfo();
api.setId(UUID.randomUUID().toString());
api.setName("用户详情");
api.setPath("detail");
api.setMethod("GET");
api.setGroupId("0");
api.setScript("return db.selectOne(\"select * from user where id = #{id}\", {id: id});");
List<Parameter> params = new ArrayList<>();
Parameter p = new Parameter("id", null);
p.setRequired(true);
p.setDataType(DataType.Integer);
p.setValidateType(Constants.VALIDATE_TYPE_PATTERN);
p.setExpression("\\d+");
p.setError("id必须为数字");
params.add(p);
api.setParameters(params);
// 注册到动态注册表（通常由资源服务自动完成）
// registry.register(api);
```

--------------------------------

### GET /backup/{id}

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

Retrieves the historical backups for a specific object ID.

```APIDOC
## GET /backup/{id}

### Description
Retrieves the historical backups for a specific object ID.

### Method
GET

### Endpoint
/backup/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The object ID to retrieve backups for.

### Response
#### Success Response (200)
- **backups** (Array) - List of backup records for the object.

#### Response Example
```json
[
  {
    "id": "backup-id",
    "timestamp": 1650000000000
  }
]
```
```

--------------------------------

### transaction()

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Starts a transaction and returns a manual control object for explicit commit/rollback.

```APIDOC
## transaction()

### Description
Starts a transaction and returns a manual control object for explicit commit/rollback.

### Method
CALL

### Response
#### Success Response
- **Transaction** - Manual transaction control object.
```

--------------------------------

### Script switching data sources with db module

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/08-dynamic-datasource.md

Shows how to use the default data source and switch by key in scripts. The db module automatically uses the data source specified by the interface option default_data_source.

```javascript
// 默认数据源
db.select('select * from t1');
// 按 key 切换
db.other.select('select * from t2');
// 接口选项 default_data_source 指定后，db 模块自动使用该数据源
```

--------------------------------

### GET /backups

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

Retrieves the most recent 100 backup records, sorted by timestamp in descending order.

```APIDOC
## GET /backups

### Description
Retrieves the most recent 100 backup records, sorted by timestamp in descending order.

### Method
GET

### Endpoint
/backups

### Parameters
#### Query Parameters
- **timestamp** (Long) - Optional - The timestamp to filter backups.

### Response
#### Success Response (200)
- **backups** (Array) - List of backup records.

#### Response Example
```json
[
  {
    "id": "backup-id",
    "timestamp": 1650000000000
  }
]
```
```

--------------------------------

### Elasticsearch script usage

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/15-plugins.md

Example of using Elasticsearch in a script: searches the 'user' index with a match_all query.

```javascript
elasticsearch.index('user').search({'query': {'match_all': {}}})
```

--------------------------------

### magic-api application.properties Configuration

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/11-spring-boot-starter.md

Configuration properties for the magic-api starter. Sets the server port to 9999, the web editor path to /magic/web, the resource location, the API prefix, and enables SQL logging and caching. Also configures security credentials for the editor.

```properties
# application.properties
server.port=9999
magic-api.web=/magic/web
magic-api.resource.location=/data/magic-api
magic-api.prefix=/api
magic-api.show-sql=true
magic-api.cache.enable=true
magic-api.cache.capacity=10000
magic-api.cache.ttl=60000
magic-api.security.username=admin
magic-api.security.password=admin123
```

--------------------------------

### Cluster plugin Maven dependency

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/15-plugins.md

Maven dependency for the cluster plugin, used as an example of adding a plugin dependency.

```xml
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-cluster</artifactId>
    <version>2.2.2</version>
</dependency>
```

--------------------------------

### MongoDB script usage

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/15-plugins.md

Example of using MongoDB in a script: selects the 'test' database, 'user' collection, and finds documents where age equals 18.

```javascript
mongo.database('test').collection('user').find({age: 18})
```

--------------------------------

### MagicPluginConfiguration 接口定义

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/15-plugins.md

所有插件必须实现此接口，提供插件描述（名称/全局变量/JS文件名）和可选的额外 Controller 注册。

```java
public interface MagicPluginConfiguration {
    Plugin plugin();                                     // 插件描述（名称/全局变量/JS文件名）
    default MagicControllerRegister controllerRegister() { return (mapping, configuration) -> { }; }  // 额外 Controller
}
```

--------------------------------

### Transaction class definition

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/06-db-infrastructure.md

Defines the Transaction class with a constructor that starts a transaction using DefaultTransactionDefinition, and methods to rollback or commit. Used via db.transaction() in scripts.

```java
public class Transaction {
    public Transaction(DataSourceTransactionManager dataSourceTransactionManager) { ... } // 构造时开启事务（DefaultTransactionDefinition）
    public void rollback();
    public void commit();
}
```

--------------------------------

### 缓存方法

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

提供缓存设置和删除方法。缓存键由 SqlCache.buildSqlCacheKey(sql, params) 计算（MD5）；update/insert/batchUpdate 成功后自动 deleteCache(this.cacheName)。

```java
public SQLModule cache(String cacheName, long ttl)   // 使用缓存（克隆模块，cacheName 可为 null）
public SQLModule cache(String cacheName)             // ttl=0（用默认）
public SQLModule deleteCache(String name)            // 删除指定缓存，返回 this
```

--------------------------------

### Java registration of dynamic data source

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/08-dynamic-datasource.md

Registers a HikariDataSource with a key, name, and maxRows using MagicDynamicDataSource.put. The example uses key 'ds-001', name '报表库', and maxRows 1000.

```java
@Component
public class DataSourceRegistrar {
    @Autowired
    private MagicDynamicDataSource magicDynamicDataSource;

    public void register() {
        HikariDataSource ds = new HikariDataSource();
        ds.setJdbcUrl("jdbc:mysql://localhost:3306/report");
        ds.setUsername("root");
        ds.setPassword("xxx");
        // key=report，maxRows=1000；名称 "报表库"
        magicDynamicDataSource.put("ds-001", "report", "报表库", ds, 1000);
    }
}
```

--------------------------------

### Using nebula module to execute nGQL queries

Source: https://github.com/ssssssss-team/magic-api/blob/master/magic-api-plugins/magic-api-plugin-nebula/nebula插件.md

Shows how to use the nebula module in magic-api. It imports the module, defines an nGQL query string, executes it with executeJson, converts the result, and also demonstrates executeNebulaModel. Other methods are not listed; refer to the source class org.ssssssss.magicapi.nebula.NebulaModule.

```js
import nebula;
var ngsl = 
    """"
        USE db_name;MATCH p_=(p:`assignee`)-[*3]-(p2:`transferor`) where  id(p2) == "阿里巴巴"  or id(p)== "阿里巴巴" RETURN p_ limit 1000'
    """
var resultJson = nebula.executeJson(ngsl)
nebula.convert(resultJson)


nebula.executeNebulaModel(ngsl)

其他支持的方法不太常用, 这里不再一一列举, 可参考源码
org.ssssssss.magicapi.nebula.NebulaModule
```

--------------------------------

### MagicBackupService 接口定义

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/13-backup.md

定义备份服务接口，包含常量 FETCH_SIZE=100 及备份、查询、删除等方法。doBackupAll 抛出 IOException，removeBackup 返回删除条数。

```java
public interface MagicBackupService {

    int FETCH_SIZE = 100;

    void doBackup(Backup backup);
    void doBackupAll(String name, String createBy) throws IOException;
    List<Backup> backupList(long timestamp);      // 按时间戳查最近 FETCH_SIZE 条
    List<Backup> backupById(String id);           // 按对象 ID 查
    Backup backupInfo(String id, long timestamp); // 精确查某条
    List<Backup> backupByTag(String tag);         // 按标签查
    long removeBackup(String id);                 // 删除对象全部备份，返回删除条数
    long removeBackupByTimestamp(long timestamp); // 删除 create_date < timestamp 的记录
}
```

--------------------------------

### SqlCache interface definition

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/06-db-infrastructure.md

Defines the SqlCache interface with methods for building cache keys, putting, getting, and deleting cached values. Default key generation uses MD5 of SQL and parameters.

```java
public interface SqlCache {
    default String buildSqlCacheKey(String sql, Object[] params) { return MD5Utils.encrypt(sql + ":" + Arrays.toString(params)); }
    void put(String name, String key, Object value);
    void put(String name, String key, Object value, long ttl);
    <T> T get(String name, String key);
    void delete(String name);
}
```

--------------------------------

### MagicAPIService 接口定义

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/02-magic-api-service.md

Java 侧调用已配置接口/函数的统一入口接口。定义 execute、call、invoke、upload、download、push、processNotify 等方法。

```java
public interface MagicAPIService {

    <T> T execute(String method, String path, Map<String, Object> context);
    <T> T call(String method, String path, Map<String, Object> context);
    <T> T invoke(String path, Map<String, Object> context);
    boolean upload(InputStream inputStream, String mode) throws IOException;
    void download(String groupId, List<SelectedResource> resources, OutputStream os) throws IOException;
    JsonBean<?> push(String target, String secretKey, String mode, List<SelectedResource> resources);
    boolean processNotify(MagicNotify magicNotify);
}
```

--------------------------------

### EnvModule class with @MagicModule("env")

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

Defines the EnvModule class annotated with @MagicModule("env"). It provides get methods to read Spring environment properties, with an optional default value.

```java
@MagicModule("env")
public class EnvModule {
    public EnvModule(Environment environment) { ... }
    public String get(String key);                              // environment.getProperty(key)
    public String get(String key, String defaultValue);         // getProperty(key, defaultValue)
}
```

--------------------------------

### MagicExceptionHandler interface definition

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/03-request-handler.md

Defines the MagicExceptionHandler interface with default exception handler methods. Implement this interface to get unified exception output: InvalidArgumentException uses its own code, other exceptions use code=-1 and log an error.

```java
public interface MagicExceptionHandler {
    @ExceptionHandler(Exception.class)
    @ResponseBody
    default Object exceptionHandler(Exception e) { return new JsonBean<>(-1, e.getMessage()); }

    @ExceptionHandler(InvalidArgumentException.class)
    @ResponseBody
    default Object exceptionHandler(InvalidArgumentException e) { return new JsonBean<>(e.getCode(), e.getMessage()); }
}
```

--------------------------------

### 编写自定义脚本模块

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/01-magic-configuration.md

使用 @MagicModule 注解定义脚本模块，脚本中通过 import myutil; 引入，然后调用 concat 方法拼接字符串。

```java
@MagicModule("myutil")                       // 脚本中 import myutil;
public class MyUtilModule {
    @Comment("拼接字符串")
    public String concat(String a, String b) {
        return a + b;
    }
}
```

```javascript
import myutil; return myutil.concat('a','b');
```

--------------------------------

### Call configured interfaces via MagicAPIService

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/README.md

Shows how to inject MagicAPIService and call configured interfaces from Java. Use execute() for raw data without code/message wrapping, call() for wrapped responses, and invoke() for functions.

```java
// 注入 MagicAPIService（同时是以 "magic" 模块暴露到脚本中的服务）
@Autowired
private MagicAPIService magicAPIService;

// 以 GET 方式调用路径为 /user/detail 的接口（不含 code/message 包装）
Map<String, Object> context = new HashMap<>();
context.put("id", 1);
Map<String, Object> data = magicAPIService.execute("GET", "/user/detail", context);

// 带 code/message 包装的调用
Object result = magicAPIService.call("GET", "/user/detail", context);

// 调用函数 /utils/format
magicAPIService.invoke("/utils/format", context);
```

--------------------------------

### Java 自定义 SQL 拦截器与分页方言

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/06-db-infrastructure.md

包含两个 Java 示例：SlowSqlInterceptor 实现 SQLInterceptor 接口，用于统计慢 SQL（超过 1000ms 打印）；MyDialect 实现 Dialect 接口，自定义分页方言，通过 List<Dialect> Bean 注入。

```java
// Java 侧自定义 SQL 拦截器（统计慢 SQL）
@Component
public class SlowSqlInterceptor implements SQLInterceptor {
    @Override
    public Object postHandle(BoundSql boundSql, Object result, RequestEntity requestEntity) {
        if (requestEntity != null && System.currentTimeMillis() - requestEntity.getRequestTime() > 1000) {
            System.out.println("慢SQL: " + boundSql.getSql());
        }
        return result;
    }
}
```

```java
// Java 侧自定义分页方言（实现后通过 List<Dialect> Bean 注入）
@Component
public class MyDialect implements Dialect {
    @Override
    public String getPageSql(String sql, BoundSql boundSql, long offset, long limit) {
        return sql + " limit " + offset + "," + limit;
    }
}
```

--------------------------------

### 内置管理端点

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/endpoints.md

由各 Controller 提供，包括 UI、资源管理、数据源、备份、推送等管理功能。

```APIDOC
## [管理端点]

### Description
内置管理端点由各 Controller 提供，包括 UI（magic-api.web 配置）、资源管理、数据源、备份、推送等。未配置 magic-api.web 则不注册管理端点。

### Method
取决于具体 Controller 定义。

### Endpoint
base + 具体路径，其中 base 为 magic-api.web 配置值。

### Parameters
取决于具体端点。

### Request Example
（无固定示例，取决于具体端点）

### Response
取决于具体端点。
```

--------------------------------

### 分页方法

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

提供多种分页方法，支持自动获取分页条件、手动分页、手动 count SQL 和手动 count 值。分页流程：方言生成 getCountSql（count>0 时才查数据）→ 方言 getPageSql 生成分页 SQL → 执行 → resultProvider.buildPageResult(...)（默认 PageResult{total, list}）。PageProvider.getPage 从脚本上下文中读取 page/size 变量。

```java
public Object page(RuntimeContext runtimeContext, String sqlOrXml)                            // 分页条件自动获取（PageProvider）
public Object page(RuntimeContext runtimeContext, String sqlOrXml, Map<String, Object> params)
public Object page(RuntimeContext runtimeContext, String sqlOrXml, long limit, long offset)    // 手动分页
public Object page(RuntimeContext runtimeContext, String sqlOrXml, long limit, long offset, Map<String, Object> params)
public Object page(RuntimeContext runtimeContext, String countSqlOrXml, String sqlOrXml)       // 手动 count SQL
public Object page(RuntimeContext runtimeContext, String countSqlOrXml, String sqlOrXml, Map<String, Object> params)
public Object page(RuntimeContext runtimeContext, int count, String sqlOrXml, long limit, long offset, Map<String, Object> params)  // 手动 count 值
```

--------------------------------

### DatabaseResource class declaration and constructors

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/10-resource-storage.md

Database storage implementation extending KeyValueResource. Constructors take JdbcTemplate, tableName, path, readonly, cachedContent, and parent. Table structure is two columns: path(512) and content(mediumtext). readAll() loads entire table into cachedContent cache; read() throws MagicResourceNotFoundException when no data. Assembled by MagicAPIAutoConfiguration.magicDatabaseResource when magic-api.resource.type=database.

```java
public class DatabaseResource extends KeyValueResource {
    public DatabaseResource(JdbcTemplate template, String tableName) { ... }
    public DatabaseResource(JdbcTemplate template, String tableName, boolean readonly) { ... }
    public DatabaseResource(JdbcTemplate template, String tableName, String path, boolean readonly) { ... }
    public DatabaseResource(JdbcTemplate template, String tableName, String path, boolean readonly, KeyValueResource parent) { ... }
    public DatabaseResource(JdbcTemplate template, String tableName, String path, boolean readonly, Map<String, String> cachedContent, KeyValueResource parent) { ... }
}
```

--------------------------------

### MagicWorkbenchController 类声明与构造

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

定义 MagicWorkbenchController 类，继承 MagicController 并实现 MagicExceptionHandler。构造函数接收 MagicConfiguration、MagicAPIProperties 和插件列表，并在构造时向 MagicScriptEngine 注册 SQLModule 和 MagicAPIService 类以提供编辑器代码提示。

```java
public class MagicWorkbenchController extends MagicController implements MagicExceptionHandler {
    public MagicWorkbenchController(MagicConfiguration configuration, MagicAPIProperties properties, List<Plugin> plugins) { ... }
}
```

--------------------------------

### FileResource class declaration and constructor

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/10-resource-storage.md

Standard file system implementation. Constructor takes a File, readonly flag, and rootPath. Supports suffix filtering via files(String suffix) and directory structure export via processExport. getFilePath() returns the file path relative to rootPath.

```java
public class FileResource implements Resource {
    public FileResource(File file, boolean readonly, String rootPath) { ... }
}
```

--------------------------------

### Minimal magic-api configuration

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/README.md

Minimal configuration for magic-api. Sets the server port, the web path for the online editor, and the resource location for storing scripts.

```properties
server.port=9999
magic-api.web=/magic/web
magic-api.resource.location=/data/magic-api
```

--------------------------------

### 备份记录表建表 SQL

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/13-backup.md

建表语句，定义备份记录表 magic_backup_record_v2，主键为 (id, create_date)，content 为 blob 类型。

```sql
CREATE TABLE `magic_backup_record_v2` (
  `id` varchar(32) NOT NULL COMMENT '原对象ID',
  `create_date` bigint(13) NOT NULL COMMENT '备份时间',
  `tag` varchar(32) DEFAULT NULL COMMENT '标签',
  `type` varchar(32) DEFAULT NULL COMMENT '类型',
  `name` varchar(64) DEFAULT NULL COMMENT '原名称',
  `content` blob COMMENT '备份内容',
  `create_by` varchar(64) DEFAULT NULL COMMENT '操作人',
  PRIMARY KEY (`id`,`create_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

--------------------------------

### pascal()

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Sets column case conversion to PascalCase and returns a cloned module.

```APIDOC
## pascal()

### Description
Sets column case conversion to PascalCase and returns a cloned module.

### Method
CALL

### Response
#### Success Response
- **SQLModule** - Cloned module with PascalCase column conversion.
```

--------------------------------

### 数据源切换（动态属性）

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

通过 getDynamicAttribute 方法实现动态数据源切换，脚本中 db.key.select(...) 或 db.key.table(...) 会切换到 key 数据源的克隆模块，key 为 null 时使用默认数据源。数据源未设置时抛出 NullPointerException("当前数据源未设置")。

```java
@Transient
public SQLModule getDynamicAttribute(String key) { ... }
```

--------------------------------

### 执行顺序总结

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/09-interceptors-and-result.md

展示 magic-api 拦截器与结果处理的执行顺序，包括 preHandle、executeScript、postHandle、response、afterCompletion 等步骤，以及异常路径和 throw-exception 配置的影响。

```text
接收请求
  → preHandle 链（依次，首个返回非 null 短路）
  → executeScript
  → postHandle 链（首个返回非 null 短路，替换响应）
  → response()（ResponseEntity/NullValue 透传，其余 buildResult）
  → afterCompletion 链（始终执行）
  → Access-Control-Expose-Headers（测试请求）
```

--------------------------------

### getDynamicAttribute(String key)

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Switches to a cloned SQLModule bound to the specified data source key. If key is null, uses the default data source. Throws NullPointerException if the data source is not set.

```APIDOC
## getDynamicAttribute(String key)

### Description
Switches to a cloned SQLModule bound to the specified data source key. If key is null, uses the default data source. Throws NullPointerException if the data source is not set.

### Method
GET (script access)

### Endpoint
`db.key.select(...)` / `db.key.table(...)`

### Parameters
#### Path Parameters
- **key** (String) - Required - Data source key; null uses default data source.

### Response
#### Success Response
- **SQLModule** - Cloned module bound to the specified data source.

#### Error Handling
- **NullPointerException** - Thrown when the data source is not set.
```

--------------------------------

### http.method

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

设置请求方法。

```APIDOC
## method

### Description
设置请求方法

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
- **method** (HttpMethod) - Required - HTTP 方法（如 GET, POST 等）

### Request Example
```js
http.connect('https://api.example.com/users').method(HttpMethod.GET)
```

### Response
#### Success Response (200)
- **HttpModule** - 当前实例，支持链式调用

#### Response Example
```js
// 返回 this
```
```

--------------------------------

### 自定义权限拦截器（精细到接口）

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/09-interceptors-and-result.md

定义 Spring 配置类 AuthConfig，注册 AuthorizationInterceptor Bean。重写 requireLogin、getUserByToken、login 和 allowVisit 方法，实现基于 token 的登录校验与接口访问控制。示例中固定 token 为 "token-123"，用户名/密码为 admin/pwd，失败时抛出 MagicLoginException。allowVisit 当前始终返回 true，注释提示需自行扩展角色校验。

```java
@Configuration
public class AuthConfig {

    @Bean
    public AuthorizationInterceptor myAuthorizationInterceptor() {
        return new AuthorizationInterceptor() {
            @Override
            public boolean requireLogin() { return true; }

            @Override
            public MagicUser getUserByToken(String token) throws MagicLoginException {
                if ("token-123".equals(token)) {
                    return new MagicUser("1", "admin", token, 7200);
                }
                throw new MagicLoginException("token无效");
            }

            @Override
            public MagicUser login(String username, String password) throws MagicLoginException {
                if ("admin".equals(username) && "pwd".equals(password)) {
                    return new MagicUser("1", "admin", "token-123", 7200);
                }
                throw new MagicLoginException("用户名或密码不正确");
            }

            @Override
            public boolean allowVisit(MagicUser magicUser, MagicHttpServletRequest request,
                                      Authorization authorization, MagicEntity entity) {
                if (magicUser == null) return false;
                // 示例规则：接口保存/删除仅授予指定角色（实现细节自行扩展）
                return true;
            }
        };
    }
}
```

--------------------------------

### login 方法处理登录与 token 续期

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/12-web-controllers.md

处理登录请求。当 requireLogin 为 true 且用户名密码为空时，尝试用现有 token 续期；否则调用授权拦截器的 login 方法并设置响应头。返回 JsonBean<Boolean>。

```java
public JsonBean<Boolean> login(String username, String password,
                               MagicHttpServletRequest request, MagicHttpServletResponse response) throws MagicLoginException {
    if (configuration.getAuthorizationInterceptor().requireLogin()) {
        if (StringUtils.isBlank(username) && StringUtils.isBlank(password)) {
            // 空凭证：尝试用已有 token 续期
            configuration.getAuthorizationInterceptor().getUserByToken(request.getHeader(Constants.MAGIC_TOKEN_HEADER));
        } else {
            MagicUser user = configuration.getAuthorizationInterceptor().login(username, password);
            response.setHeader(Constants.MAGIC_TOKEN_HEADER, user.getToken());
            response.setHeader(HttpHeaders.ACCESS_CONTROL_EXPOSE_HEADERS, Constants.MAGIC_TOKEN_HEADER);
        }
    }
    return new JsonBean<>(true);
}
```

--------------------------------

### http.execute

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/07-http-and-servlet-modules.md

执行请求，返回 ResponseEntity。

```APIDOC
## execute

### Description
执行请求，返回 ResponseEntity

### Method
N/A

### Endpoint
N/A

### Parameters
无

### Request Example
```js
var resp = http.connect('https://api.example.com/users').execute();
```

### Response
#### Success Response (200)
- **ResponseEntity<?>** - 响应实体

#### Response Example
```js
// 返回 ResponseEntity
```
```

--------------------------------

### BoundSql 类定义与核心方法

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/06-db-infrastructure.md

BoundSql 类用于封装 SQL 参数处理与执行。构造函数接受 RuntimeContext、SQL 字符串或 XML、参数列表或 Map 以及 SQLModule。提供获取 SQL、参数、执行拦截器管线等方法。execute 方法支持缓存，当 cacheable=true 且 cacheName 非空时使用 SqlCache。

```java
public class BoundSql {

    public BoundSql(RuntimeContext runtimeContext, String sqlOrXml, List<Object> parameters, SQLModule sqlModule) { ... }
    public BoundSql(RuntimeContext runtimeContext, String sqlOrXml, Map<String, Object> parameters, SQLModule sqlModule) { ... }

    public SQLModule getSqlModule();
    public Set<String> getExcludeColumns();
    public void setExcludeColumns(Set<String> excludeColumns);
    public void addParameter(Object value);
    public String getSql();
    public void setSql(String sql);
    public Object[] getParameters();
    public List<Object[]> getBatchParameters();
    public List<SqlParameter> getDeclareParameters();
    public void setParameters(List<Object> parameters);
    public RuntimeContext getRuntimeContext();
    <T> T execute(List<SQLInterceptor> interceptors, Supplier<T> supplier);        // cacheable=true
    <T> T execute(List<SQLInterceptor> interceptors, Supplier<T> supplier, boolean cacheable);
}
```

--------------------------------

### MagicResourceStorage 接口定义

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/02-magic-api-service.md

定义实体序列化到 Resource 和生成映射 key 的接口。包含默认的 read/write 方法，以及 buildMappingKey 等抽象方法。

```java
public interface MagicResourceStorage<T extends MagicEntity> {
    String separatorWithCRLF = "\r\n================================\r\n";
    String separatorWithLF = "\n================================\n";

    String folder();                 // 文件夹名（api/function/datasource/task…）
    String suffix();                 // 允许的后缀，空则不限
    Class<T> magicClass();
    boolean requirePath();           // 是否必须有 path
    default boolean requiredScript() { return true; }
    default boolean allowRoot() { return false; }
    default T read(byte[] bytes) { ... }          // 反序列化（JSON + 分隔符 + script）
    default byte[] write(MagicEntity entity) { ... }  // 序列化（JSON(script=null) + 分隔符 + script）
    default T readResource(Resource resource) { ... }
    String buildMappingKey(T entity);
    default String buildKey(MagicEntity entity) { return buildMappingKey((T) entity); }
    default void validate(T entity) { }
    void setMagicResourceService(MagicResourceService magicResourceService);
}
```

--------------------------------

### select(RuntimeContext, String sqlOrXml, Map<String, Object> params)

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Executes a query with parameters and returns a list of maps.

```APIDOC
## select(RuntimeContext runtimeContext, String sqlOrXml, Map<String, Object> params)

### Description
Executes a query with parameters and returns a list of maps.

### Method
CALL

### Parameters
#### Request Body
- **runtimeContext** (RuntimeContext) - Required - Runtime context.
- **sqlOrXml** (String) - Required - SQL or XML identifier.
- **params** (Map<String, Object>) - Required - Query parameters.

### Response
#### Success Response
- **List<Map<String, Object>>** - Query results.
```

--------------------------------

### Create magic_api_file_v2 table

Source: https://github.com/ssssssss-team/magic-api/blob/master/db/README.md

Required table for magic-api 0.7.x and later. Stores file paths and content. The primary key is file_path.

```sql
CREATE TABLE `magic_api_file_v2` (
  `file_path` varchar(512) NOT NULL,
  `file_content` mediumtext,
  PRIMARY KEY (`file_path`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
```

--------------------------------

### page(RuntimeContext, String countSqlOrXml, String sqlOrXml)

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/04-sql-module.md

Executes a paginated query using a manual count SQL.

```APIDOC
## page(RuntimeContext runtimeContext, String countSqlOrXml, String sqlOrXml)

### Description
Executes a paginated query using a manual count SQL.

### Method
CALL

### Parameters
#### Request Body
- **runtimeContext** (RuntimeContext) - Required - Runtime context.
- **countSqlOrXml** (String) - Required - SQL or XML for count query.
- **sqlOrXml** (String) - Required - SQL or XML for data query.

### Response
#### Success Response
- **Object** - Page result (default PageResult{total, list}).
```

--------------------------------

### Configure file storage (default)

Source: https://github.com/ssssssss-team/magic-api/blob/master/_autodocs/api-reference/10-resource-storage.md

Sets magic-api.resource.type=file to use file-based storage. The location and readonly properties configure the storage path and read-only mode.

```properties
magic-api.resource.type=file
magic-api.resource.location=/data/magic-api
magic-api.resource.readonly=false
```
Tokens:
Raw