REST后端文件上传接口设计：单端点双逻辑是否为最佳实践？

这不符合REST设计的最佳实践，主要问题和优化方案如下：

核心问题 #

• HTTP方法语义冲突：POST的标准语义是创建新资源，而查询上传状态属于读取已有资源的操作，应该对应GET方法。同一个端点混用POST实现两种完全不同语义的操作，会让API使用者混淆，也违背了HTTP协议的设计初衷。
• DTO职责混乱：同一个DTO既要承载创建请求的参数，又要返回查询状态的结果，字段选择性填充会导致DTO的职责不清晰，后续新增字段或修改逻辑时，容易出现字段遗漏或错误填充的问题，维护成本高。
• 可扩展性差：后续如果要对创建逻辑或查询逻辑单独扩展（比如创建时增加校验规则，查询时返回更多状态维度），两个逻辑耦合在同一个端点会互相影响，代码会越来越臃肿。

推荐的拆分方案 #

按操作语义拆分出独立端点，让每个端点的职责单一：

1. 新文件上传初始化：
   • 端点：POST /files
   • 逻辑：不需要传入file_id，接收上传配置参数后，创建新的上传任务资源，返回生成的file_id及初始化信息（如分片大小、允许的分片数量等）。
2. 查询上传状态：
   • 端点：GET /files/{file_id}
   • 逻辑：通过路径参数传入file_id，返回该上传任务的详细状态（已上传分片列表、最后成功上传的分片索引、错误信息等）。GET方法天然支持缓存，还能利用HTTP状态码（如404表示file_id不存在）更清晰地反馈结果。
3. 分片上传：
   • 额外补充端点：PUT /files/{file_id}/chunks/{chunk_index}
   • 逻辑：上传指定分片，PUT语义对应更新资源的一部分，符合分片上传的场景。

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