wx/hl-api-changelog

派生 0

API Changelog Bot 94fa5db42c docs: sync 13 services (0 breaking changes)

2026-03-17 09:27:35 +08:00

12 KiB

原始文件 Blame 文件历史

文件服务 API 文档

服务: hl-file-service 接口总数: 11

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`	响应消息

12 KiB 原始文件 Blame 文件历史 Unescape Escape

文件服务 API 文档

目录

C端文件上传

GET /mp/file/preview-by-url

POST /mp/file/upload

GET /mp/file/{fileId}/preview

文件管理

GET /admin/file/list

GET /admin/file/stats

POST /admin/file/upload/confirm

POST /admin/file/upload/token

GET /admin/file/{fileId}

DELETE /admin/file/{fileId}

GET /admin/file/{fileId}/preview

GET /admin/file/{fileId}/refs

12 KiB

原始文件 Blame 文件历史

`GET` /mp/file/preview-by-url

`POST` /mp/file/upload

`GET` /mp/file/{fileId}/preview

`GET` /admin/file/list

`GET` /admin/file/stats

`POST` /admin/file/upload/confirm

`POST` /admin/file/upload/token

`GET` /admin/file/{fileId}

`DELETE` /admin/file/{fileId}

`GET` /admin/file/{fileId}/preview

`GET` /admin/file/{fileId}/refs