332 行
12 KiB
Markdown
332 行
12 KiB
Markdown
# 文件服务 API 文档
|
||
|
||
**服务**: `hl-file-service`
|
||
**接口总数**: 11
|
||
|
||
## 目录
|
||
|
||
- **C端文件上传** (3 个接口)
|
||
- **文件管理** (8 个接口)
|
||
|
||
---
|
||
|
||
## C端文件上传
|
||
|
||
### `GET` /mp/file/preview-by-url
|
||
|
||
**文件在线预览**
|
||
|
||
返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 示例 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `url` | `string` | | 文件完整URL | |
|
||
|
||
---
|
||
|
||
### `POST` /mp/file/upload
|
||
|
||
**上传文件（C端用户）**
|
||
|
||
小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 示例 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `groupKey` | `string` | | 文件分组标识 | |
|
||
|
||
**响应** `统一响应结果«文件信息»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `文件信息` | | 响应数据 |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileHash` | `string` | | 文件MD5哈希 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `fileName` | `string` | | 文件名 |
|
||
| `fileSize` | `long` | | 文件大小(字节) |
|
||
| `fileType` | `string` | | 文件类型 |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
| `mimeType` | `string` | | MIME类型 |
|
||
| `ossUrl` | `string` | | OSS地址 |
|
||
| `previewUrl` | `string` | | 预览地址 |
|
||
| `refCount` | `int` | | 引用次数 |
|
||
| `status` | `string` | | 文件状态 |
|
||
| `thumbnailUrl` | `string` | | 缩略图地址 |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `GET` /mp/file/{fileId}/preview
|
||
|
||
**文件内容流式预览**
|
||
|
||
流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `integer` | | 文件ID |
|
||
|
||
---
|
||
|
||
## 文件管理
|
||
|
||
### `GET` /admin/file/list
|
||
|
||
**文件列表（分页）**
|
||
|
||
支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回
|
||
|
||
**关联字典**：
|
||
- file_type：文件类型（列表筛选+显示）
|
||
- file_status：文件状态（显示）
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 示例 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `endDate` | `string` | | 结束日期 | 2026-12-31 |
|
||
| `fileType` | `string` | | 文件类型 | image |
|
||
| `groupKey` | `string` | | 业务分组 | scenic |
|
||
| `keyword` | `string` | | 搜索关键词 | 风景 |
|
||
| `page` | `integer(int32)` | | 页码 | 1 |
|
||
| `pageSize` | `integer(int32)` | | 每页条数 | 20 |
|
||
| `startDate` | `string` | | 开始日期 | 2026-01-01 |
|
||
|
||
**响应** `统一响应结果«IPage«文件信息»»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `IPage«文件信息»` | | 响应数据 |
|
||
| `current` | `long` | | |
|
||
| `pages` | `long` | | |
|
||
| `records` | `文件信息[]` | | |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileHash` | `string` | | 文件MD5哈希 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `fileName` | `string` | | 文件名 |
|
||
| `fileSize` | `long` | | 文件大小(字节) |
|
||
| `fileType` | `string` | | 文件类型 |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
| `mimeType` | `string` | | MIME类型 |
|
||
| `ossUrl` | `string` | | OSS地址 |
|
||
| `previewUrl` | `string` | | 预览地址 |
|
||
| `refCount` | `int` | | 引用次数 |
|
||
| `status` | `string` | | 文件状态 |
|
||
| `thumbnailUrl` | `string` | | 缩略图地址 |
|
||
| `size` | `long` | | |
|
||
| `total` | `long` | | |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `GET` /admin/file/stats
|
||
|
||
**存储统计**
|
||
|
||
返回文件总数、总存储空间、各类型文件占比等统计信息
|
||
|
||
**响应** `统一响应结果«文件统计信息»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `文件统计信息` | | 响应数据 |
|
||
| `countByGroup` | `object` | | 按分组统计文件数量 |
|
||
| `countByType` | `object` | | 按类型统计文件数量 |
|
||
| `sizeByType` | `object` | | 按类型统计文件大小 |
|
||
| `totalCount` | `long` | | 文件总数 |
|
||
| `totalSize` | `long` | | 文件总大小(字节) |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `POST` /admin/file/upload/confirm
|
||
|
||
**确认上传完成**
|
||
|
||
上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储
|
||
|
||
**请求体** `上传确认请求`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `string` | 是 | 文件ID |
|
||
|
||
**响应** `统一响应结果«文件信息»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `文件信息` | | 响应数据 |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileHash` | `string` | | 文件MD5哈希 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `fileName` | `string` | | 文件名 |
|
||
| `fileSize` | `long` | | 文件大小(字节) |
|
||
| `fileType` | `string` | | 文件类型 |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
| `mimeType` | `string` | | MIME类型 |
|
||
| `ossUrl` | `string` | | OSS地址 |
|
||
| `previewUrl` | `string` | | 预览地址 |
|
||
| `refCount` | `int` | | 引用次数 |
|
||
| `status` | `string` | | 文件状态 |
|
||
| `thumbnailUrl` | `string` | | 缩略图地址 |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `POST` /admin/file/upload/token
|
||
|
||
**请求上传凭证**
|
||
|
||
上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求
|
||
|
||
**请求体** `上传令牌请求`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileHash` | `string` | 是 | 文件MD5哈希 |
|
||
| `fileName` | `string` | 是 | 文件名 |
|
||
| `fileSize` | `long` | 是 | 文件大小(字节) |
|
||
| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
|
||
**响应** `统一响应结果«上传令牌信息»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `上传令牌信息` | | 响应数据 |
|
||
| `bucket` | `string` | | OSS Bucket名称 |
|
||
| `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） |
|
||
| `expireAt` | `string` | | 过期时间 |
|
||
| `file` | `文件信息` | | 秒传文件信息 |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileHash` | `string` | | 文件MD5哈希 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `fileName` | `string` | | 文件名 |
|
||
| `fileSize` | `long` | | 文件大小(字节) |
|
||
| `fileType` | `string` | | 文件类型 |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
| `mimeType` | `string` | | MIME类型 |
|
||
| `ossUrl` | `string` | | OSS地址 |
|
||
| `previewUrl` | `string` | | 预览地址 |
|
||
| `refCount` | `int` | | 引用次数 |
|
||
| `status` | `string` | | 文件状态 |
|
||
| `thumbnailUrl` | `string` | | 缩略图地址 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `ossKey` | `string` | | OSS对象Key |
|
||
| `presignedUrl` | `string` | | 预签名上传URL |
|
||
| `region` | `string` | | OSS Region |
|
||
| `stsToken` | `STS临时凭证信息` | | STS临时凭证 |
|
||
| `accessKeyId` | `string` | | AccessKey ID |
|
||
| `accessKeySecret` | `string` | | AccessKey Secret |
|
||
| `expiration` | `string` | | 过期时间 |
|
||
| `securityToken` | `string` | | 安全令牌 |
|
||
| `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `GET` /admin/file/{fileId}
|
||
|
||
**文件详情**
|
||
|
||
**关联字典**：
|
||
- file_type：文件类型（显示）
|
||
- file_status：文件状态（显示）
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `integer` | | 文件ID |
|
||
|
||
**响应** `统一响应结果«文件信息»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `文件信息` | | 响应数据 |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileHash` | `string` | | 文件MD5哈希 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `fileName` | `string` | | 文件名 |
|
||
| `fileSize` | `long` | | 文件大小(字节) |
|
||
| `fileType` | `string` | | 文件类型 |
|
||
| `groupKey` | `string` | | 业务分组 |
|
||
| `mimeType` | `string` | | MIME类型 |
|
||
| `ossUrl` | `string` | | OSS地址 |
|
||
| `previewUrl` | `string` | | 预览地址 |
|
||
| `refCount` | `int` | | 引用次数 |
|
||
| `status` | `string` | | 文件状态 |
|
||
| `thumbnailUrl` | `string` | | 缩略图地址 |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|
||
|
||
### `DELETE` /admin/file/{fileId}
|
||
|
||
**删除文件**
|
||
|
||
软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `integer` | | 文件ID |
|
||
|
||
**响应** `统一响应结果«Void»`
|
||
|
||
---
|
||
|
||
### `GET` /admin/file/{fileId}/preview
|
||
|
||
**文件内容流式预览**
|
||
|
||
流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `integer` | | 文件ID |
|
||
|
||
---
|
||
|
||
### `GET` /admin/file/{fileId}/refs
|
||
|
||
**文件引用列表**
|
||
|
||
查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `integer` | | 文件ID |
|
||
|
||
**响应** `统一响应结果«List«文件引用信息»»`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `code` | `int` | | 状态码 |
|
||
| `data` | `文件引用信息[]` | | 响应数据 |
|
||
| `bizId` | `string` | | 业务ID |
|
||
| `bizType` | `string` | | 业务类型 |
|
||
| `createdAt` | `string` | | 创建时间 |
|
||
| `fileId` | `string` | | 文件ID |
|
||
| `refId` | `string` | | 引用ID |
|
||
| `message` | `string` | | 响应消息 |
|
||
|
||
---
|