处理接口

处理接口提供 ZIP 文件的处理功能，包括文件检查、格式限制获取和文件处理。

接口概览

接口	方法	描述
`/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": "测试成功"
}

用途：

检查服务是否启动
测试网络连接
健康检查

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	输出根目录

用途：

获取可用的配置选项
显示给用户选择
获取配置索引

注意事项：

数组的下标即为配置索引（config_index）
索引从 0 开始
配置顺序由 config.toml 决定

3. 获取文件类型限制

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

请求：

http

GET /process/limits?config_index=0

查询参数：

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

响应：

json

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

响应字段：

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

用途：

验证文件名格式
显示允许的文件类型
前端表单验证

错误响应：

json

{
  "success": false,
  "message": "选择的配置文件不存在",
  "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` 表示文件已存在

用途：

防止文件覆盖
提示用户确认
前端表单验证

检查逻辑：

系统会检查所有配置的输出目录中是否存在同名文件：

base_path / format[0] / name
base_path / format[1] / name
base_path / format[2] / name
...

只要任何一个目录中存在同名文件，就返回 false。

错误响应：

json

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

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 结尾
不能包含路径分隔符
建议使用小写字母和下划线

正确示例：

icon.png
app_logo.png
header_image.png

错误示例：

icon.png.png（重复后缀）
images/icon.png（包含路径）
icon.jpg（错误后缀）

path

ZIP 文件的绝对路径
服务器必须有读取权限
文件必须存在

示例：

/home/user/icons.zip
/tmp/downloads/design_assets.zip
C:\Users\user\Downloads\icons.zip（Windows）

config_index

配置索引，从 /process/configs 获取
从 0 开始
必须在有效范围内

响应（成功）：

json

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

响应（失败）：

json

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

处理流程：

1. 验证文件名格式
   ↓
2. 验证 ZIP 文件存在
   ↓
3. 检查文件是否已存在
   ↓
4. 打开 ZIP 文件
   ↓
5. 根据 zip_format 匹配文件
   ↓
6. 验证匹配结果
   ↓
7. 创建输出目录
   ↓
8. 提取文件到指定目录
   ↓
9. 记录处理历史
   ↓
10. 返回处理结果

常见错误：

错误信息	说明	解决方法
文件名格式不正确: icon.jpg	文件名不以 .png 结尾	修改文件名为 .png
ZIP 文件不存在: /path/to/file.zip	指定的 ZIP 文件不存在	检查文件路径是否正确
文件已存在: ./android/mdpi/icon.png	目标文件已存在	删除已存在文件或使用不同文件名
ZIP 文件内容格式与配置文件不符合	ZIP 内部结构与配置不匹配	检查 ZIP 文件结构和配置规则
选择的配置文件不存在	配置索引超出范围	检查配置索引是否正确

文件匹配规则：

系统根据 zip_format 配置匹配 ZIP 中的文件：

目录映射模式（以 / 结尾）
toml
```
zip_format = ["mipmap-mdpi/", "mipmap-hdpi/"]
```
- 匹配：mipmap-mdpi/icon.png
- 匹配：a/b/mipmap-mdpi/icon.png
- 不匹配：mipmap-mdpi.png
同级通配模式（使用 **）
toml
```
zip_format = ["./**.png", "./**@2x.png"]
```
- 匹配：icon.png
- 匹配：icon@2x.png
- 匹配：images/icon.png
精确文件匹配
toml
```
zip_format = ["icon.png", "icon@2x.png"]
```
- 匹配：icon.png
- 不匹配：images/icon.png

输出路径计算：

输出路径由以下公式计算：

output_path = base_path / format[i] / name

示例：

toml

base_path = "./android"
format = ["mdpi", "hdpi", "xhdpi"]
name = "icon.png"

输出路径：

./android/mdpi/icon.png
./android/hdpi/icon.png
./android/xhdpi/icon.png

安全检查：

系统会进行以下安全检查：

文件名验证
- 检查文件名是否以允许的扩展名结尾
- 防止路径遍历攻击
文件类型限制
- 根据 format_limit 检查文件类型
- 防止恶意文件注入
目录验证
- 确保 base_path 存在
- 防止写入系统敏感目录

使用示例：

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"]}')

完整工作流

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

javascript

async function fullWorkflow(zipPath, fileName) {
  // 1. 获取配置列表
  const configs = await fetch('http://127.0.0.1:9999/process/configs')
    .then(res => res.json());

  console.log('可用配置:', configs.data);

  // 2. 选择配置（这里选择第一个）
  const configIndex = 0;

  // 3. 获取文件类型限制
  const limits = await fetch(
    `http://127.0.0.1:9999/process/limits?config_index=${configIndex}`
  ).then(res => res.json());

  console.log('允许的文件类型:', limits.data);

  // 4. 检查文件是否存在
  const check = await fetch('http://127.0.0.1:9999/process/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: fileName,
      config_index: configIndex
    })
  }).then(res => res.json());

  if (!check.data) {
    console.log('文件已存在，无法处理');
    return;
  }

  // 5. 处理文件
  const result = 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
    })
  }).then(res => res.json());

  if (result.success) {
    console.log('处理成功');
  } else {
    console.error('处理失败:', result.message);
  }
}

// 使用示例
fullWorkflow('/home/user/icons.zip', 'icon.png');

错误处理

错误响应格式

所有错误响应都遵循统一格式：

json

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

错误类型

1. 参数错误

json

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

原因： 文件名不以 .png 结尾

解决： 修改文件名为 .png 结尾

2. 文件不存在

json

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

原因： 指定的 ZIP 文件不存在

解决： 检查文件路径是否正确

3. 文件已存在

json

{
  "success": false,
  "message": "文件已存在: ./android/mdpi/icon.png",
  "data": null
}

原因： 目标文件已存在

解决： 删除已存在文件或使用不同文件名

4. 配置错误

json

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

原因： 配置索引超出范围

解决： 检查配置索引是否正确

5. 格式不匹配

json

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

原因： ZIP 内部结构与配置不匹配

解决： 检查 ZIP 文件结构和配置规则

下一步

查看配置说明了解如何配置输出规则
查看插件使用了解浏览器插件的集成方式

处理接口 ​

接口概览 ​

1. 测试接口 ​

2. 获取配置列表 ​

3. 获取文件类型限制 ​

4. 检查文件是否存在 ​

5. 处理 ZIP 文件 ​

name ​

path ​

config_index ​

完整工作流 ​

错误处理 ​

错误响应格式 ​

错误类型 ​

1. 参数错误 ​

2. 文件不存在 ​

3. 文件已存在 ​

4. 配置错误 ​

5. 格式不匹配 ​

下一步 ​

处理接口

接口概览

1. 测试接口

2. 获取配置列表

3. 获取文件类型限制

4. 检查文件是否存在

5. 处理 ZIP 文件

name

path

config_index

完整工作流

错误处理

错误响应格式

错误类型

1. 参数错误

2. 文件不存在

3. 文件已存在

4. 配置错误

5. 格式不匹配

下一步