API 文档

QT Tool 提供完整的 REST API，支持通过 HTTP 请求进行文件处理和配置管理。

基础信息

服务器地址

默认地址: http://127.0.0.1:9999
协议: HTTP
内容类型: application/json

通用响应格式

所有接口返回统一的 JSON 格式：

成功响应

json

{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}

错误响应

json

{
  "success": false,
  "message": "错误描述",
  "data": null
}

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
500	服务器内部错误

接口列表

测试接口

接口	方法	描述
`/process/test`	GET	测试服务是否正常运行

配置管理

接口	方法	描述
`/process/configs`	GET	获取所有输出配置
`/process/limits`	GET	获取指定配置的文件类型限制

文件处理

接口	方法	描述
`/process/check`	POST	检查文件是否存在
`/process`	POST	处理 ZIP 文件

接口详情

1. 测试接口

测试服务是否正常运行。

请求：

http

GET /process/test

响应：

json

{
  "success": true,
  "message": "测试成功",
  "data": "测试成功"
}

使用示例：

bash

curl http://127.0.0.1:9999/process/test

2. 获取配置列表

获取所有可用的输出配置。

请求：

http

GET /process/configs

响应：

json

{
  "success": true,
  "message": "获取配置文件成功",
  "data": [
    {
      "name": "Android 图标",
      "description": "Android 应用图标",
      "base_path": "./android"
    },
    {
      "name": "iOS 图标",
      "description": "iOS 应用图标",
      "base_path": "./ios"
    }
  ]
}

响应字段：

字段	类型	说明
name	string	配置名称
description	string	配置描述
base_path	string	输出根目录

使用示例：

bash

curl http://127.0.0.1:9999/process/configs

3. 获取文件类型限制

获取指定配置的允许文件类型。

请求：

http

GET /process/limits?config_index=0

查询参数：

参数	类型	必填	说明
config_index	number	是	配置索引（从 0 开始）

响应：

json

{
  "success": true,
  "message": "获取可选的配置后缀成功",
  "data": [".png", ".svg"]
}

响应字段：

字段	类型	说明
data	array	允许的文件扩展名列表

使用示例：

bash

curl "http://127.0.0.1:9999/process/limits?config_index=0"

JavaScript 示例：

javascript

const configIndex = 0;
fetch(`http://127.0.0.1:9999/process/limits?config_index=${configIndex}`)
  .then(res => res.json())
  .then(data => console.log(data));

4. 检查文件是否存在

检查目标文件是否已存在。

请求：

http

POST /process/check
Content-Type: application/json

{
  "name": "icon.png",
  "config_index": 0
}

请求参数：

参数	类型	必填	说明
name	string	是	文件名
config_index	number	是	配置索引

响应（文件不存在）：

json

{
  "success": true,
  "message": "请求校验文件成功",
  "data": true
}

响应（文件已存在）：

json

{
  "success": true,
  "message": "请求校验文件成功",
  "data": false
}

响应字段：

字段	类型	说明
data	boolean	`true` 表示文件不存在，可以处理；`false` 表示文件已存在

使用示例：

bash

curl -X POST http://127.0.0.1:9999/process/check \
  -H "Content-Type: application/json" \
  -d '{"name":"icon.png","config_index":0}'

JavaScript 示例：

javascript

fetch('http://127.0.0.1:9999/process/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'icon.png',
    config_index: 0
  })
})
  .then(res => res.json())
  .then(data => {
    if (data.data) {
      console.log('文件不存在，可以处理');
    } else {
      console.log('文件已存在');
    }
  });

5. 处理 ZIP 文件

处理 ZIP 文件并解压到指定目录。

请求：

http

POST /process
Content-Type: application/json

{
  "name": "icon.png",
  "path": "/path/to/input.zip",
  "config_index": 0
}

请求参数：

参数	类型	必填	说明
name	string	是	输出文件名（必须以 .png 结尾）
path	string	是	ZIP 文件的绝对路径
config_index	number	是	配置索引

参数说明：

name: 输出文件名，必须以 .png 结尾
path: ZIP 文件的绝对路径，服务器必须有读取权限
config_index: 配置索引，从 /process/configs 获取

响应（成功）：

json

{
  "success": true,
  "message": "处理文件完成",
  "data": null
}

响应（失败）：

json

{
  "success": false,
  "message": "ZIP 文件内容格式与配置文件(Android 图标)不符合",
  "data": null
}

常见错误：

错误信息	说明	解决方法
ZIP 文件不存在	指定的 ZIP 文件不存在	检查文件路径是否正确
文件名格式不正确	文件名不以 .png 结尾	修改文件名
文件已存在	目标文件已存在	删除已存在文件或使用不同文件名
ZIP 文件内容格式与配置文件不符合	ZIP 内部结构与配置不匹配	检查 ZIP 文件结构和配置规则

使用示例：

bash

curl -X POST http://127.0.0.1:9999/process \
  -H "Content-Type: application/json" \
  -d '{
    "name": "icon.png",
    "path": "/home/user/icons.zip",
    "config_index": 0
  }'

JavaScript 示例：

javascript

async function processFile(zipPath, fileName, configIndex) {
  const response = await fetch('http://127.0.0.1:9999/process', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: fileName,
      path: zipPath,
      config_index: configIndex
    })
  });

  const result = await response.json();
  return result;
}

// 使用示例
processFile('/home/user/icons.zip', 'icon.png', 0)
  .then(result => {
    if (result.success) {
      console.log('处理成功');
    } else {
      console.error('处理失败:', result.message);
    }
  });

Python 示例：

python

import requests

def process_file(zip_path, file_name, config_index):
    url = 'http://127.0.0.1:9999/process'
    data = {
        'name': file_name,
        'path': zip_path,
        'config_index': config_index
    }
    response = requests.post(url, json=data)
    return response.json()

# 使用示例
result = process_file('/home/user/icons.zip', 'icon.png', 0)
if result['success']:
    print('处理成功')
else:
    print(f'处理失败: {result["message"]}')

完整工作流示例

以下是一个完整的 API 使用流程：

1. 获取配置列表

bash

curl http://127.0.0.1:9999/process/configs

响应：

json

{
  "success": true,
  "message": "获取配置文件成功",
  "data": [
    {
      "name": "Android 图标",
      "description": "Android 应用图标",
      "base_path": "./android"
    }
  ]
}

2. 获取文件类型限制

bash

curl "http://127.0.0.1:9999/process/limits?config_index=0"

响应：

json

{
  "success": true,
  "message": "获取可选的配置后缀成功",
  "data": [".png", ".svg"]
}

3. 检查文件是否存在

bash

curl -X POST http://127.0.0.1:9999/process/check \
  -H "Content-Type: application/json" \
  -d '{"name":"icon.png","config_index":0}'

响应：

json

{
  "success": true,
  "message": "请求校验文件成功",
  "data": true
}

4. 处理文件

bash

curl -X POST http://127.0.0.1:9999/process \
  -H "Content-Type: application/json" \
  -d '{
    "name": "icon.png",
    "path": "/home/user/icons.zip",
    "config_index": 0
  }'

响应：

json

{
  "success": true,
  "message": "处理文件完成",
  "data": null
}

错误处理

错误码

错误码	说明
400	请求参数错误
500	服务器内部错误

常见错误

1. 配置索引错误

请求：

json

{
  "name": "icon.png",
  "path": "/path/to/file.zip",
  "config_index": 999
}

响应：

json

{
  "success": false,
  "message": "选择的配置文件不存在",
  "data": null
}

2. 文件名格式错误

请求：

json

{
  "name": "icon.jpg",
  "path": "/path/to/file.zip",
  "config_index": 0
}

响应：

json

{
  "success": false,
  "message": "文件名格式不正确: icon.jpg",
  "data": null
}

3. ZIP 文件不存在

请求：

json

{
  "name": "icon.png",
  "path": "/path/to/nonexistent.zip",
  "config_index": 0
}

响应：

json

{
  "success": false,
  "message": "ZIP 文件不存在: /path/to/nonexistent.zip",
  "data": null
}

SDK 示例

JavaScript SDK

javascript

class QTToolClient {
  constructor(baseUrl = 'http://127.0.0.1:9999') {
    this.baseUrl = baseUrl;
  }

  async test() {
    const res = await fetch(`${this.baseUrl}/process/test`);
    return res.json();
  }

  async getConfigs() {
    const res = await fetch(`${this.baseUrl}/process/configs`);
    return res.json();
  }

  async getLimits(configIndex) {
    const res = await fetch(
      `${this.baseUrl}/process/limits?config_index=${configIndex}`
    );
    return res.json();
  }

  async checkFile(fileName, configIndex) {
    const res = await fetch(`${this.baseUrl}/process/check`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: fileName, config_index: configIndex })
    });
    return res.json();
  }

  async process(zipPath, fileName, configIndex) {
    const res = await fetch(`${this.baseUrl}/process`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name: fileName,
        path: zipPath,
        config_index: configIndex
      })
    });
    return res.json();
  }
}

// 使用示例
const client = new QTToolClient();

async function main() {
  // 测试连接
  await client.test();

  // 获取配置
  const configs = await client.getConfigs();
  console.log('配置列表:', configs.data);

  // 处理文件
  const result = await client.process(
    '/home/user/icons.zip',
    'icon.png',
    0
  );
  console.log('处理结果:', result);
}

main();

Python SDK

python

import requests

class QTToolClient:
    def __init__(self, base_url='http://127.0.0.1:9999'):
        self.base_url = base_url

    def test(self):
        return requests.get(f'{self.base_url}/process/test').json()

    def get_configs(self):
        return requests.get(f'{self.base_url}/process/configs').json()

    def get_limits(self, config_index):
        return requests.get(
            f'{self.base_url}/process/limits',
            params={'config_index': config_index}
        ).json()

    def check_file(self, file_name, config_index):
        return requests.post(
            f'{self.base_url}/process/check',
            json={'name': file_name, 'config_index': config_index}
        ).json()

    def process(self, zip_path, file_name, config_index):
        return requests.post(
            f'{self.base_url}/process',
            json={
                'name': file_name,
                'path': zip_path,
                'config_index': config_index
            }
        ).json()

# 使用示例
client = QTToolClient()

# 测试连接
print(client.test())

# 获取配置
configs = client.get_configs()
print(f'配置列表: {configs["data"]}')

# 处理文件
result = client.process('/home/user/icons.zip', 'icon.png', 0)
print(f'处理结果: {result}')

下一步

查看配置说明了解如何配置输出规则
了解服务器模式的更多细节
查看插件使用了解浏览器插件的集成方式

API 文档 ​

基础信息 ​

服务器地址 ​

通用响应格式 ​

成功响应 ​

错误响应 ​

HTTP 状态码 ​

接口列表 ​

测试接口 ​

配置管理 ​

文件处理 ​

接口详情 ​

1. 测试接口 ​

2. 获取配置列表 ​

3. 获取文件类型限制 ​

4. 检查文件是否存在 ​

5. 处理 ZIP 文件 ​

完整工作流示例 ​

1. 获取配置列表 ​

2. 获取文件类型限制 ​

3. 检查文件是否存在 ​

4. 处理文件 ​

错误处理 ​

错误码 ​

常见错误 ​

1. 配置索引错误 ​

2. 文件名格式错误 ​

3. ZIP 文件不存在 ​

SDK 示例 ​

JavaScript SDK ​

Python SDK ​

下一步 ​

API 文档

基础信息

服务器地址

通用响应格式

成功响应

错误响应

HTTP 状态码

接口列表

测试接口

配置管理

文件处理

接口详情

1. 测试接口

2. 获取配置列表

3. 获取文件类型限制

4. 检查文件是否存在

5. 处理 ZIP 文件

完整工作流示例

1. 获取配置列表

2. 获取文件类型限制

3. 检查文件是否存在

4. 处理文件

错误处理

错误码

常见错误

1. 配置索引错误

2. 文件名格式错误

3. ZIP 文件不存在

SDK 示例

JavaScript SDK

Python SDK

下一步