跳至主要內容

文件模块

godo大约 24 分钟

桌面文件

接口方法: HandleDesktop

注意：如果路径不正确或者文件不存在，会导致错误。

描述: 该接口通过调用 HandleDesktop 方法来获取桌面文件信息。

  • URL: /file/desktop

  • 方法: GET

  • 请求参数: 无

  • 是否需要登录: false

  • 返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success"
codeinteger请求结果的状态码0
dataobject返回的数据对象见下表

data数据对象:

字段名类型描述示例值
updatetimestring数据的更新时间"2024-11-05T20:07:20.367891+08:00"
appsarray桌面应用程序列表见下表
menulistarray菜单项列表见下表

apps数据对象:

字段名类型描述示例值
isFileboolean是否是文件true
isDirectoryboolean是否是目录false
isSymlinkboolean是否是符号链接false
sizeinteger大小（字节）32
modTimestring最后修改时间"2024-10-29T23:07:45.895708+08:00"
atimestring最后访问时间"2024-10-29T23:07:45.895708+08:00"
birthtimestring创建时间"2024-10-29T23:07:45.895708+08:00"
modeinteger权限模式511
namestring名称"computer.exe"
pathstring路径"/C/Users/Desktop/computer.exe"
oldPathstring旧路径"/C/Users/Desktop/computer.exe"
parentPathstring父目录路径"/C/Users/Desktop"
contentstring内容描述或链接信息"link::Desktop:💻:diannao"
extstring扩展名"exe"
titlestring标题或显示名称"computer"
idinteger唯一标识符1
isPwdboolean是否是密码保护的false

menulist 数据对象:

字段名类型描述示例值
isFileboolean是否是文件true
isDirectoryboolean是否是目录false
isSymlinkboolean是否是符号链接false
sizeinteger大小（字节）32
modTimestring最后修改时间"2024-10-29T23:07:45.895708+08:00"
atimestring最后访问时间"2024-10-29T23:07:45.895708+08:00"
birthtimestring创建时间"2024-10-29T23:07:45.895708+08:00"
modeinteger权限模式511
namestring名称"computer.exe"
pathstring路径"/C/Users/Menulist/computer.exe"
oldPathstring旧路径"/C/Users/Menulist/computer.exe"
parentPathstring父目录路径"/C/Users/Menulist"
contentstring内容描述或链接信息"link::Desktop:💻:diannao"
extstring扩展名"exe"
titlestring标题或显示名称"computer"
idinteger唯一标识符1
isPwdboolean是否是密码保护的false

示例

请求示例

curl -X GET "http://api.example.com/file/desktop" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success",
  "code": 0,
  "data": {...}
}

失败响应示例

  1. 桌面路径不存在或文件读取失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "desktop.json not found",
  "code": -1
}
  1. JSON 解析失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "failed to parse desktop.json",
  "code": -1
}

获取系统信息

接口方法: HandleSystemInfo

注意：返回的系统信息被序列化为 JSON 字符串，并进行 Base64 编码。因此，客户端在接收数据后需要先进行 Base64 解码，再将其解析为 JSON 格式。

描述: 该接口通过调用 GetSystemInfo 函数来检索系统信息。

  • URL: /file/info

  • 方法: GET

  • 请求参数: 无

  • 是否需要登录: false

  • 返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File information retrieved successfully."
dataobject系统信息对象(base64编码的字符串)
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/info" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File information retrieved successfully.",
  "code": 0,
  "data": "eyJhcHBfbmFtZSI6ImdvZG9vcyIsImFyY2giOiJhcm02NCIsImhvc3RuYW1lIjoiMTkyLjE2OC4xMC4xOSIsIm1hYyI6IjkzNTExNjc4ZTAzZTA5MzI4OWY4ZjcyZWM0NTk1M2JiIiwib3MiOiJkYXJ3aW4iLCJzb3VyY2V0eXBlIjoib3BlbiIsInRvcHR5cGUiOiJ3ZWIiLCJ1c2V0eXBlIjoicGVyc29uIn0=" 
}

失败响应示例

  1. 获取系统信息失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve file information",
  "code": -1
}

读取目录

接口方法: HandleReadDir

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击 ../../）。如果文件内容以 "link::" 开头，则标记为符号链接。

描述: 该接口通过 HandleReadDir 方法读取指定目录下的所有文件和子目录。它首先获取操作系统的基本目录路径，然后读取指定路径下的目录内容。接口会过滤掉隐藏文件（以 . 开头的文件），并为每个文件或目录获取详细信息。如果是文件，还会读取其内容并检查是否为符号链接。最终，返回的文件信息按最后修改时间降序排列，并以 JSON 格式响应成功读取的目录信息。

  • URL: /file/read

  • 方法: GET

  • 是否需要登录: false

请求参数:

参数名类型必填描述示例值
pathstring是指定要读取的目录路径"/example"
  • 返回结果:
字段名类型描述示例值
messagestring请求结果的消息"Directory read successfully."
codeinteger请求结果的状态码（0 成功 -1 失败）0
dataarray返回的数据对象列表见下表

data 数据对象:

字段名类型描述示例值
isFileboolean是否是文件false
isDirectoryboolean是否是目录true
isSymlinkboolean是否是符号链接false
sizeinteger大小（字节）64
modTimestring最后修改时间"2024-10-29T23:07:45.894866315+08:00"
atimestring最后访问时间"2024-10-29T23:07:45.894866315+08:00"
birthtimestring创建时间"2024-10-29T23:07:45.894866315+08:00"
modeinteger权限模式2147484141
namestring名称"D"
pathstring路径"/D"
oldPathstring旧路径"/D"
parentPathstring父目录路径""
contentstring内容描述或链接信息""
extstring扩展名""
titlestring标题或显示名称"D"
isPwdboolean是否是密码保护的false

示例

请求示例

curl -X GET "http://api.example.com/file/read?path=/D" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "Directory read successfully.",
  "data": [
    {
      // OsFileInfo 的 JSON 表示
    }
  ],
  "code": 0
}

失败响应示例

  1. 读取目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 打开文件失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to open file: [error details]",
  "code": -1
}
  1. 读取文件内容失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to read file content: [error details]",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}

读取文件

接口方法: HandleStat

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击 ../../）。

描述: 该接口通过 HandleStat 方法根据请求中提供的路径检索单个文件或目录的详细信息。首先验证文件路径的有效性，然后获取操作系统的基本目录路径。接口会返回该文件的相关信息。

  • URL: /file/stat

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是指定要检索的文件路径"/example.txt"
  • 返回结果:
字段名类型描述示例值
codeinteger请求结果的状态码（0 成功 -1 失败）0
messagestring请求结果的消息"File information retrieved successfully."
dataobject返回的数据对象文件信息对象JSON 对象（见下表）

data 数据对象:

字段名类型描述示例值
isFileboolean是否是文件false
isDirectoryboolean是否是目录true
isSymlinkboolean是否是符号链接false
sizeinteger大小（字节）64
modTimestring最后修改时间"2024-10-29T23:07:45.894866315+08:00"
atimestring最后访问时间"2024-10-29T23:07:45.894866315+08:00"
birthtimestring创建时间"2024-10-29T23:07:45.894866315+08:00"
modeinteger权限模式2147484141
namestring名称"d"
pathstring路径"/d"
oldPathstring旧路径"/d"
parentPathstring父目录路径""
contentstring内容描述或链接信息""
extstring扩展名""
titlestring标题或显示名称"d"
isPwdboolean是否是密码保护的false

示例

请求示例

curl -X GET "http://api.example.com/file/stat?path=/d" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File information retrieved successfully.",
  "data": {
    // OsFileInfo 的 JSON 表示
  },
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
 {
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 文件信息检索失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "File not found.",
  "code": -1
}

文件权限

接口方法: HandleChmod

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击 ../../）。确保 mode 是有效的权限模式字符串。

描述: 该接口通过 HandleChmod 方法更改指定文件或目录的权限。将权限模式字符串解析为8进制格式，并获取操作系统的基本目录路径。然后更改文件权限。

  • URL: /file/chmod

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是要更改权限的文件或目录的路径。"/example.txt"
modestring是要设置的权限模式（八进制字符串，如 "0755"）"0775"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File permission changed successfully."
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/chmod" \
-H "Content-Type: application/json" \
-d '{"path":"/example.txt", "mode":"0755"}'

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File permission changed successfully.",
  "code": 0
}

失败响应示例

  1. 请求体解析失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Failed to parse request body",
  "code": -1
}
  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 无效的权限模式
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid mode: [error details]",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 更改文件权限失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to change file permissions.",
  "code": -1
}

文件是否存在

接口方法: HandleExists

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击 ../../）。

描述: 该接口通过 HandleExists 检查指定路径的文件或目录是否存在。用户通过查询参数提供路径，接口会返回该路径是否存在的结果。

  • URL: /file/exists

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是要检查的文件或目录路径"/example.txt"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File exists." 或 "File does not exist."
databoolean文件或目录存在状态true 或 false
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/exists?path=/example.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File exists.",
  "data": true,
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
    "message": "File does not exist.",
    "code": 0,
    "data": false
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1,
  "data": false
}

读取文件内容

接口方法: HandleReadFile

注意：对于加密文件，必须提供正确的 filePwd 才能读取内容。返回的文件内容为 Base64 编码，除非内容以 "link::" 开头。

描述: 该接口通过 HandleReadFile 方法读取指定文件的内容。首先验证文件路径的有效性，然后获取操作系统的基本目录路径。对于非加密文件，直接返回其 Base64 编码内容。对于加密文件，需验证请求头中的密码，验证成功后读取并解密文件内容，再返回 Base64 编码的解密内容。

  • URL: /file/readfile

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是要读取的文件路径"/example.txt"
  • 请求头:
参数名类型必填描述示例值
filePwdstring否文件密码（仅加密文件需要）"filePwd"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File read successfully."
datastring文件内容"Base64 编码的内容"
codeinteger请求结果的状态码0

示例

请求示例

  • 请求路径（普通文件，不需要密码）：
curl -X GET "http://api.example.com/file/readfile?path=./myfile.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success.",
  "data": "Base64 编码的内容",
  "code": 0
}
  • 请求路径（加密文件，需要提供密码）：
curl -X GET "http://api.example.com/file/readfile?path=./myfile.txt" -H "accept: application/json" -H "filePwd: my-secure-password"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success.",
  "data": "Base64 编码的内容",  //解密并编码后的内容
  "code": 0
}
  • 请求路径（链接文件，link:: 前缀的文件内容）：
curl -X GET "http://api.example.com/file/readfile?path=link::./myfile.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success.",
  "data": "link::http://example.com"
  "code": 0
}

失败响应示例

  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "data": null,
  "code": -1
}
  1. 文件未找到
  • HTTP 状态码: 400 Bad Request
{
  "message": "File not found.",
  "data": null,
  "code": -1
}
  1. 密码为空
  • HTTP 状态码: 400 Bad Request
{
  "message": "密码不能为空",
  "data": null,
  "code": -1
}
  1. 密码错误
  • HTTP 状态码: 400 Bad Request
{
  "message": "密码错误",
  "data": null,
  "code": -1
}
  1. 解密失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "解密失败",
  "data": null,
  "code": -1
}

删除文件

接口方法: HandleUnlink

注意：在删除文件前，可能需要检查文件是否在桌面上并进行相应处理。

描述: 该接口通过 HandleUnlink 删除指定路径的文件。用户通过查询参数提供文件路径，接口会尝试删除该文件。

  • URL: /file/unlink

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是要删除的文件路径"/example.txt"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File '/example.txt' successfully removed."
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/unlink?path=./myfile.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File '/example.txt' successfully removed.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 操作系统目录获取失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to get OS directory.",
  "code": -1
}
  1. 文件删除失败
  • HTTP 状态码: 409 Conflict
{
  "message": "Failed to remove file.",
  "code": -1
}

清除文件系统

接口方法: HandleClear

注意：此操作会删除指定路径下的所有文件和文件夹，操作具有破坏性，因此应谨慎调用。在执行此操作之前，建议进行数据备份。

描述: 该接口通过 HandleClear 方法清除文件系统。用于清除整个文件系统，通常是在需要重置或清理环境时使用。

  • URL: /file/clear

  • 方法: GET

  • 是否需要登录: false

  • 请求参数: 无

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File system cleared successfully."
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/clear" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "FileSystem successfully cleared.",
  "code": 0
}

失败响应示例

  1. 清除文件系统失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to clear file system",
  "code": -1
}

重命名文件或文件夹

接口方法: HandleRename

注意：路径验证：确保 oldPath 和 newPath 不包含恶意路径输入（如目录遍历攻击../../）。

描述: 该接口通过 HandleRename 方法重命名文件或文件夹，接收客户端传入的旧路径 (oldPath) 和新路径 (newPath) 并执行重命名操作。

  • URL: /file/rename

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
oldPathstring是旧路径"/D"
newPathstring是新路径"/D"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File renamed successfully."
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/rename?oldPath=./oldfile.txt&newPath=./newfile.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "File renamed successfully.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 获取根目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to get OS directory.",
  "code": -1
}
  1. 重命名文件失败
  • HTTP 状态码: 409 Conflict
{
  "message": "Error renaming file.",
  "code": -1
}

创建新目录

接口方法: HandleMkdir

注意：路径验证：确保 dirPath 不包含恶意路径输入（如目录遍历攻击../../）。

描述: 该接口通过 HandleMkdir 创建新目录，接收客户端传入的目录路径 (dirPath)，并在指定的文件系统路径下创建该目录。

  • URL: /file/mkdir

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
dirPathstring是目录路径"/D"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"Directory created successfully."
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/mkdir?dirPath=./newdir" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "Directory created successfully.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Invalid directory path.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 创建目录失败
  • HTTP 状态码：409 Conflict
{
  "message": "Error creating directory.",
  "code": -1
}

删除目录

接口方法: HandleRmdir

注意：删除操作是不可逆的，调用时需谨慎。

描述: 该接口通过 HandleRmdir 方法删除指定路径的目录。首先验证目录路径的有效性，然后获取操作系统的基本目录路径。接着，检查是否可以从桌面删除目录，并调用 Rmdir 函数删除目录。

  • URL: /file/rmdir

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
dirPathstring是目录路径"/D"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"Directory deleted successfully."
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/rmdir?dirPath=./mydir" -H "accept: application/json"

成功响应示例

{
  "message": "Directory './mydir' successfully removed.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Invalid directory path.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 删除目录失败
  • HTTP 状态码：409 Conflict
{
  "message": "Failed to remove directory './mydir'.",
  "code": -1
}

复制文件

接口方法: HandleCopy

注意：路径验证：确保 srcPath 和 dstPath 不包含恶意路径输入（如目录遍历攻击../../）。如果目标路径在桌面上，可能会有额外的添加限制或日志记录。

描述: 该接口通过 HandleCopy 方法复制文件，接收客户端传入的源路径 (srcPath) 和目标路径 (dstPath)，并执行复制操作。

  • URL: /file/copy

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
srcPathstring是源文件路径"/source.txt"
dstPathstring是目标文件路径"/dest.txt"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"File '/source.txt' successfully copied to '/dest.txt'."
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/copy?srcPath=./source.txt&dstPath=./dest.txt" -H "accept: application/json"

成功响应示例

{
  "message": "File './source.txt' successfully copied to './dest.txt'.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 复制文件失败
  • HTTP 状态码：409 Conflict
{
  "message": "Failed to copy file './source.txt' to './dest.txt'.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}

写入文件（可加密）

接口方法: HandleWriteFile

描述: 该接口通过 HandleWriteFile 方法写入文件，接收客户端传入的文件路径 (filePath) 和文件内容 (content)，并根据配置决定是否加密。首先获取操作系统的基本目录路径，然后从请求中获取文件内容。根据配置，决定是否加密文件内容并写入文件。如果加密，则在同级目录下创建一个同名隐藏文件。

  • URL: /file/writefile

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
filePathstring是文件路径"/example.txt"
contentfile是文件内容(文件数据)

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success"
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/write?filePath=./example.txt" -F "content=@/path/to/local/file.txt" -H "accept: application/json"

成功响应示例

{
  "message": "success",
  "code": 0
}

失败响应示例

  1. 获取操作系统目录失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}
  1. 文件内容读取失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Failed to read file content.",
  "code": -1
}
  1. 文件创建失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to create file.",
  "code": -1
}
  1. 加密失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "Failed to create file.",
  "code": -1
}
  1. 隐藏文件创建失败
  • HTTP 状态码：500 Internal Server Error
{
  "message": "创建隐藏文件失败",
  "code": -1
}

追加文件内容

接口方法: HandleAppendFile

注意：路径验证：确保 filePath 不包含恶意路径输入（如目录遍历攻击../../）。

描述: 该接口通过 HandleAppendFile 方法追加文件内容，接收客户端传入的文件路径 (filePath) 和文件内容 (content)，并追加到指定文件中。

  • URL: /file/append

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
filePathstring是文件路径"/example.txt"
contentfile是文件内容(文件数据)

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success"
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/append?filePath=./example.txt" -F "content=@/path/to/local/file.txt" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "Content appended to file '/example.txt'.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Invalid file path.",
  "code": -1
}
  1. 文件内容读取失败
  • HTTP 状态码：400 Bad Request
{
  "message": "Failed to read file content.",
  "code": -1
}
  1. 文件追加失败
  • HTTP 状态码: 409 Conflict
{
  "message": "Failed to append content to file.",
  "code": -1
}

压缩文件或文件夹

接口方法: HandleZip

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击../../），默认压缩格式为 zip，用户可以通过 ext 参数指定其他格式。

描述: 该接口通过 HandleZip 压缩指定路径的文件或文件夹。用户通过提供路径和可选的压缩文件扩展名，来指定压缩文件的输出路径。

  • URL: /file/zip

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是指定要压缩的文件或文件夹路径"/example"
extstring否指定压缩文件的扩展名，默认为 zip"zip"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success zip /example.zip."
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/zip?path=./example&ext=zip" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success zip /example.zip.",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid path.",
  "code": -1
}
  1. 压缩失败
  • HTTP 状态码: 409 Conflict
{
  "message": "Failed to compress /example.zip.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}

解压文件

接口方法: HandleUnZip

注意：路径验证：确保 path 不包含恶意路径输入（如目录遍历攻击../../），解压后的文件将放置在与压缩文件相同的目录中。

描述: 该接口通过 HandleUnZip 解压指定路径的压缩文件。用户通过提供路径，来指定解压文件的输出路径。

  • URL: /file/unzip

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是指定要解压的压缩文件路径"/example.zip"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success unzip /example.zip."
datastring解压后的路径"/example"
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/unzip?path=./example.zip" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success unzip /example.zip.",
  "data": "/example",
  "code": 0
}

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid path.",
  "code": -1
}
  1. 解压失败
  • HTTP 状态码: 409 Conflict
{
  "message": "Failed to unzip /example.zip.",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}

文件夹监控（SSE）

接口方法: WatchHandler

注意：SSE 流需要客户端支持，确保客户端能够处理 SSE 事件。

描述: 该接口通过 WatchHandler 监控指定路径的文件夹。用户通过提供文件夹路径，接口会启动服务器发送事件（SSE）流，以便实时监控文件夹的变化。成功时，启动 SSE 流；如果出现错误，则返回相应的错误信息。

  • URL: /file/watch

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
pathstring是指定要监控的文件夹路径"/example"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"filepath is not exist!"
codeinteger请求结果的状态码-1

示例

请求示例

curl -X GET "http://api.example.com/file/watch?filePath=/example" -H "accept: text/event-stream"

成功响应示例

  • HTTP 状态码: 200 OK

  • 响应内容: 启动 SSE 流，实时发送文件夹变化信息。

失败响应示例

  1. 路径验证失败
  • HTTP 状态码: 404 Not Found
{
  "message": "filepath is not exist!",
  "code": -1
}
  1. 获取操作系统目录失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to retrieve base directory.",
  "code": -1
}

设置文件密码

接口方法: HandleSetFilePwd

注意：确保请求头中包含有效的 filePwd。

描述: 该接口通过 HandleSetFilePwd 设置文件的密码，用户通过请求头提供文件密码，接口会对密码进行加盐哈希处理，并将结果存储在服务器上。

  • URL: /file/setpwd

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
filePwdstring是文件密码"mypassword"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"密码设置成功"
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/setpwd?filePwd=mypassword" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "密码设置成功",
  "code": 0
}

失败响应示例

  1. 获取盐值或密码为空
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Error message from GetSalt or empty password.",
  "code": -1
}
  1. 存储哈希密码失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to store hashed password.",
  "code": -1
}
  1. 存储盐值失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to store salt.",
  "code": -1
}

更改文件密码

接口方法: HandleChangeFilePwd

注意：确保请求头中包含有效的 filePwd。

描述: 该接口通过 HandleChangeFilePwd 更改文件的密码，用户通过请求头提供文件密码，接口会对密码进行加盐哈希处理，并将结果存储在服务器上。

  • URL: /file/changepwd

  • 方法: POST

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
filePwdstring是新的文件密码"newpassword"

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"The file password change success!"
codeinteger请求结果的状态码0

示例

请求示例

curl -X POST "http://api.example.com/file/changepwd?filePwd=newpassword" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "The file password change success!",
  "code": 0
}

失败响应示例

  1. 获取盐值或密码为空
  • HTTP 状态码: 400 Bad Request
{
  "message": "参数错误",
  "code": -1
}
  1. 存储哈希密码失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to store hashed password.",
  "code": -1
}

更改加密状态

接口方法: HandleSetIsPwd

注意：确保 ispwd 参数为有效的整数（0或1）。

描述: 该接口通过 HandleSetIsPwd 更改文件的加密状态，用户通过查询参数提供加密状态值，接口会将其转换为布尔值并存储在服务器上。

  • URL: /file/setispwd

  • 方法: GET

  • 是否需要登录: false

  • 请求参数:

参数名类型必填描述示例值
ispwdinteger是加密状态值0或1

返回结果:

字段名类型描述示例值
messagestring请求结果的消息"success"
codeinteger请求结果的状态码0

示例

请求示例

curl -X GET "http://api.example.com/file/setispwd?ispwd=1" -H "accept: application/json"

成功响应示例

  • HTTP 状态码: 200 OK
{
  "message": "success",
  "code": 0
}

失败响应示例

  1. 无效的加密状态值
  • HTTP 状态码: 400 Bad Request
{
  "message": "Invalid encryption status value.",
  "code": -1
}
  1. 存储加密状态失败
  • HTTP 状态码: 500 Internal Server Error
{
  "message": "Failed to store encryption status.",  
  "code": -1
}
copyright godoos.com
Copyright © 2024 godo