cute http file server 开发API

### cute http file server (CHFS) API开发指南 #### 一、引言 `cute http file server`（简称 CHFS）是一款轻量级的HTTP文件服务器，它提供了丰富的API接口来实现对文件的管理与操作。通过这些API，开发者可以轻松地在自己的应用程序中集成文件管理功能，如用户认证、文件的增删查改等。 本文档将详细介绍CHFS的API接口，包括用户认证和文件操作两个主要方面，并针对每个接口提供详细的参数说明、请求方法、响应格式等内容，以便开发者能够快速理解和使用。 #### 二、用户认证 用户认证模块主要负责用户的登录与登出操作，确保数据的安全性和完整性。 ##### 2.1 用户登录 **请求方式**：`POST /session` **描述**：用于用户登录。 **参数**： | 类型 | 名称 | 数据类型 | 必填 | 默认值 | 描述 | |-----------|--------|----------|------|--------|------------| | formData | pwd | string | Y | - | 用户密码 | | formData | user | string | Y | - | 用户名 | **响应**： | HTTPCode | 描述 | 数据示例 | |----------|------------------|-------------------------| | 500 | 服务器内部错误 | `{error: "xxxxxx"}` | | 201 | 成功 | `{token: "xxxxxx"}`<br>`Cookie: "JWT"+"user"` | | 400 | 参数错误 | `{error: "xxxxxx"}` | | 404 | 账号或密码错误 | `{error: "xxxxxx"}` | **说明**：登录成功后，系统会返回一个JWT Token，该Token用于后续的API调用验证身份。 ##### 2.2 用户登出 **请求方式**：`DELETE /session` **描述**：用于退出登录状态。 **参数**： | 类型 | 名称 | 数据类型 | 必填 | 默认值 | 描述 | |--------|------|----------|------|--------|-----------------| | header | JWT | Cookie | Y | - | 登录后获取的Token | **响应**： | HTTPCode | 描述 | 数据示例 | |----------|------------|--------------------| | 401 | 无效Token | `{error: "xxxxxx"}` | | 204 | 成功 | `Cookie: "JWT"+"user"` | | | (无数据) | | **说明**：登出成功后，应清除客户端的JWT Token，确保安全性。 #### 三、文件操作 文件操作模块提供了对文件和目录的基本管理功能，包括获取文件列表、删除文件或目录、新建目录等。 ##### 3.1 获取文件列表 **请求方式**：`GET /files` **描述**：获取指定目录下的文件列表。 **参数**： | 类型 | 名称 | 数据类型 | 必填 | 默认值 | 描述 | |-----------|---------|----------|------|--------|--------------------| | querystring | filepath | Y | - | 要查询的目录 | | header | JWT | Cookie | Y | - | 登录后获取的Token | **响应**： | HTTPCode | 描述 | 数据示例 | |----------|------------------|------------------------------------------------| | 500 | 服务器内部错误 | `{error: "xxxxxx"}` | | 200 | 成功 | JSON：<br>{<br>"currentMask": "string",<br>"files": [{<br>"name": "string", // 文件名<br>"dir": bool, // 是否是目录<br>"size": int, // 文件大小<br>"modified": "string", // 修改时间<br>"icon": "url", // 某些文件的缩略图<br>"mask": "string", // 当前用户的访问权限<br>"guestMask": "string" // 匿名用户的访问权限<br>}]<br>} | | 400 | 参数无效 | `{error: "xxxxxx"}` | | 401 | 无效Token | `{error: "xxxxxx"}` | | 403 | 无访问权限 | `{error: "xxxxxx"}` | **说明**：返回的JSON数据包含了当前目录下的所有文件和目录信息，包括文件名、是否为目录、文件大小、修改时间等。 ##### 3.2 删除文件或目录 **请求方式**：`DELETE /rmfiles` **描述**：删除指定的文件或目录。 **参数**： | 类型 | 名称 | 数据类型 | 必填 | 默认值 | 描述 | |-----------|---------|----------|------|--------|--------------------| | formData | filepath | Y | - | 要删除的文件或目录 | | header | JWT | Cookie | Y | - | 登录后获取的Token | **响应**： | HTTPCode | 描述 | 数据示例 | |----------|------------------|------------------------------------| | 204 | 成功 | | | 400 | 参数无效 | `{error: "xxxxxx"}` | | 401 | 无效Token | `{error: "xxxxxx"}` | | 500 | 服务器内部错误 | `{error: "xxxxxx"}` | | 403 | 无访问权限 | `{error: "xxxxxx"}` | **说明**：如果操作成功，则不会返回任何数据；若出现错误，则会返回相应的错误信息。 ##### 3.3 新建目录 **请求方式**：`POST /newdir` **描述**：新建一个目录。 **参数**： | 类型 | 名称 | 数据类型 | 必填 | 默认值 | 描述 | |-----------|---------|----------|------|--------|--------------| | formData | filepath | Y | - | 要创建的目录 | | header | JWT | Cookie | Y | - | 登录后获取的Token | **响应**： | HTTPCode | 描述 | 数据示例 | |----------|------------------|-----------------------------------| | 500 | 服务器内部错误 | `{error: "xxxxxx"}` | | 201 | 成功 | | | 400 | 参数错误 | `{error: "xxxxxx"}` | | 401 | 无效Token | `{error: "xxxxxx"}` | **说明**：新建目录成功时，不返回任何数据；如果出现错误则返回错误信息。 #### 四、总结 通过以上介绍，我们可以看到CHFS提供了非常全面的API接口，涵盖了用户认证及文件操作两大核心功能。这些API接口的设计遵循RESTful风格，使得开发者可以轻松地将其集成到自己的应用中。无论是对于想要快速构建文件管理系统的企业还是个人开发者来说，CHFS都是一个不错的选择。