📥 文件下载接口

功能概述

文件下载接口提供了三种下载方式：

• 业务类型路径下载：/download/{业务类型}/{文件路径}
• 业务类型参数下载：/download/{业务类型}?filePath=文件路径
• 默认下载：/download?filePath=文件路径

下载流程

接口规格

1. 业务类型路径下载

推荐使用

此接口通过URL路径指定业务类型和文件路径，更加简洁直观。

接口信息

• 路径: /download/{业务类型}/{文件路径}
• 方法: GET
• 说明: 通过URL路径指定业务类型和文件路径进行下载

请求参数

参数名	位置	类型	必填	说明	示例值
业务类型	Path	String	是	业务类型代码	demo
文件路径	Path	String	是	文件存储路径	2024/08/25/file.pdf
fileName	Query	String	否	自定义下载文件名	示例文档.pdf

请求示例

基础下载

GET /download/demo/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf
Host: 127.0.0.1:9830

自定义文件名

GET /download/demo/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf?fileName=示例文档.pdf
Host: 127.0.0.1:9830

2. 业务类型参数下载

接口说明

此接口通过查询参数指定文件路径，适合复杂路径场景。

接口信息

• 路径: /download/{业务类型}
• 方法: GET
• 说明: 通过查询参数指定文件路径进行下载

请求参数

参数名	位置	类型	必填	说明	示例值
业务类型	Path	String	是	业务类型代码	demo
filePath	Query	String	是	文件存储路径	/2024/08/25/file.pdf
fileName	Query	String	否	自定义下载文件名	示例文档.pdf

请求示例

基础下载

GET /download/demo?filePath=/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf
Host: 127.0.0.1:9830

自定义文件名

GET /download/demo?filePath=/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf&fileName=示例文档.pdf
Host: 127.0.0.1:9830

3. 默认下载接口

安全提醒

默认下载接口不进行业务类型校验，建议在内网环境使用或增加额外的安全控制。

接口信息

• 路径: /download
• 方法: GET
• 说明: 不区分业务类型的通用下载接口

请求参数

参数名	位置	类型	必填	说明	示例值
filePath	Query	String	是	文件存储路径	/2024/08/25/file.pdf
fileName	Query	String	否	自定义下载文件名	示例文档.pdf

请求示例

基础下载

GET /download?filePath=/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf
Host: 127.0.0.1:9830

自定义文件名

GET /download?filePath=/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.pdf&fileName=示例文档.pdf
Host: 127.0.0.1:9830

最佳实践

接口选择建议

1. 业务类型路径下载

   • 适用于标准的文件下载场景
   • URL更简洁，便于分享和缓存
   • 推荐作为主要下载方式

2. 业务类型参数下载

   • 适用于文件路径包含特殊字符的场景
   • 适用于动态拼接文件路径的场景
   • 便于前端处理和参数拼接

3. 默认下载接口

   • 适用于内部系统或测试环境
   • 需要自行控制访问权限
   • 不建议在生产环境直接暴露

安全建议

1. 访问控制

   • 实施适当的认证和授权机制
   • 对敏感文件增加访问权限校验
   • 限制可下载的文件类型

2. 性能优化

   • 对大文件启用断点续传
   • 配置合适的超时时间
   • 考虑使用CDN加速

3. 监控告警

   • 记录异常下载行为
   • 监控文件访问频率
   • 设置下载量阈值告警

错误处理

错误码	说明	解决方案
404	文件不存在	检查文件路径是否正确
403	无访问权限	确认业务类型和权限配置
400	参数错误	检查请求参数格式
500	服务器错误	查看服务器日志定位问题

开发建议

1. 总是使用 fileName 参数指定下载文件名
2. 文件路径使用标准的日期格式组织
3. 合理使用文件类型和扩展名
4. 注意URL编码，特别是中文文件名