Great question—this is a common point of confusion when building file-handling APIs, and both approaches have their place depending on your use case. Let’s break this down clearly:

方案1：返回元数据+Base64文件字段 #

这种方式的适用场景非常有限，主要适合：

• 处理极小的文本/配置文件（几KB级别）
• 客户端需要一次性获取文档元数据和文件内容，且不会有性能问题的场景

但它存在不少明显的缺点：

• Base64编码会让文件体积增加约30%，大幅降低传输效率，大文件场景下极易导致超时或内存溢出
• 不符合REST的资源定位原则：文档元数据和文件本身是两个不同的资源，强行合并会让接口职责模糊
• 客户端需要额外处理Base64解码，增加了前端/客户端的复杂度

方案2：单独的/download端点（推荐） #

这是更符合REST规范和工业界最佳实践的方案，优势非常明显：

• 清晰的资源语义：/documents/{id}专注返回文档元数据（名称、上传时间、大小、类型等），/documents/{id}/download专门负责提供文件内容，职责单一，符合REST的资源隔离原则
• 更好的性能与可靠性：直接返回二进制流，无需编码损耗；支持HTTP Range请求头实现断点续传，大文件传输更稳定
• 更友好的客户端体验：可以设置精准的HTTP响应头，比如：
  • Content-Type: application/pdf（告诉客户端文件类型）
  • Content-Disposition: attachment; filename="invoice-2024.pdf"（控制浏览器直接下载而非打开）
• 更强的扩展性：后续可以轻松扩展功能，比如支持不同格式下载（/documents/{id}/download?format=zip）、添加权限校验、统计下载次数等，都不会影响原有的元数据接口

总结建议 #

• 仅在处理极小文件且客户端有一次性获取所有数据的需求时，才考虑方案1
• 绝大多数场景（尤其是大文件、二进制文件），优先采用方案2，这也是主流API平台（比如云存储服务、文档管理系统）的通用做法

内容的提问来源于stack exchange，提问作者Heinrich