微服务文件下载导出
一句话说明：微服务生成文件并返回二进制流，通过服务API调用组件（ServiceCall）代理，由平台接口自动转换为文件下载。
业务场景
业务方需要在自建微服务中生成自定义文件（Excel、Word、PDF、ZIP 等），并让用户在 Chameleon 页面上点击后直接下载该文件。
适用场景
- 复杂格式文档生成：微服务内使用 NPOI、OpenXML、iText 等文档库生成 Excel / Word / PDF，平台侧无需集成任何文档生成能力
- 已有服务能力复用：文件生成逻辑已存在于业务微服务中，只想通过平台页面触发下载
- 大文件导出：在异步任务（TinyTask）中调用微服务生成文件，平台自动上传文件服务并交付下载
平台内置的数据导出组件面向对象数据的通用列表导出；需要完全自定义文件内容时，使用本文的微服务文件下载方式。
配置方法
上游微服务要求
微服务 API 需满足以下条件（请求方法固定为 POST）：
| 要素 | 要求 | 说明 |
|---|---|---|
| 响应内容 | 二进制文件内容 | 非文件内容（JSON）会被平台按普通接口数据处理 |
Content-Type 响应头 | 必须为文件的 MIME 类型 | 如 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/pdf；不能是 application/json |
Content-Disposition 响应头 | 建议提供 | 用于确定下载文件名，如 attachment; filename=report.xlsx；支持 RFC 5987 编码的 filename* |
平台侧配置
配置一个服务API调用组件，关键配置：
| 配置项 | 配置值 | 说明 |
|---|---|---|
| 服务名称 | SystemSlave（或其他已注册微服务） | 见服务名称取值 |
| API地址 | 微服务的文件生成接口地址 | 例：api/Report/ExportExcel |
| 请求体行为模式 | 按业务需要选择 | 通常选「前端请求穿透」（缺省）或「传递上游组件结果」 |
| 输出到最终结果 | 开启 | 必须开启，否则平台不会把文件流作为下载返回 |
无需任何额外配置项，平台按响应 Content-Type 自动识别：JSON 按接口数据返回，非 JSON 一律按文件流代理下载。
使用示例
以下为微服务侧的示例（ASP.NET Core）：
[HttpPost("exportText")]
public IActionResult ExportText()
{
var content = $"Export test file. Generated at {DateTime.Now:yyyy-MM-dd HH:mm:ss}.{Environment.NewLine}";
// File(...) automatically sets Content-Type and Content-Disposition headers
return File(Encoding.UTF8.GetBytes(content), "text/plain", "export-test.txt");
}
平台侧只需配置服务API调用组件指向 DownloadFile/exportText，用户执行流程后浏览器即自动下载 export-test.txt。
生成 Excel 的示例（微服务内使用 NPOI）：
[HttpPost("exportExcel")]
public IActionResult ExportExcel()
{
using var workbook = new XSSFWorkbook();
var sheet = workbook.CreateSheet("sheet1");
// ... write data rows ...
using var stream = new MemoryStream();
workbook.Write(stream, leaveOpen: true);
stream.Position = 0;
return File(stream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "report.xlsx");
}
注意事项
文件名确定规则
平台按以下 顺序确定下载文件名：
- 响应头
Content-Disposition的filename*/filename（优先） - 流程上下文中的
DownloadFileName（上游组件写入，适用于组件链路场景） - 兜底：
download+ 时间戳（如download20261108120000）
文件名必须带扩展名：平台按扩展名推断响应的 Content-Type。若文件名无扩展名，平台会按响应 Content-Type 自动补全；无法识别的 Content-Type 会提示「文件类型识别错误」。
适用边界
- 同步下载路径建议文件大小 小于 50MB：响应内容会整体缓存在内存中
- 更大文件请在异步任务中调用：平台自动将文件上传文件服务（阅后即焚存储）并交付下载，不占用请求内存
- 上游接口返回
510/401时，平台按业务异常处理并弹出错误信息，不会当作文件下载