资源标识符为路径时，REST API URL设计的最佳实践

当资源标识符是文件路径（比如/folder_1/folder_2/a.sh）时，直接放到URL路径里会和后端文件系统冲突，你提出的三个方案各有优劣，下面逐一分析并给出实践建议：

方案1：将路径作为请求参数 #

这种方案完全符合REST规范。REST并没有强制要求资源标识符必须出现在URL路径中，请求参数也是合法的资源定位方式。对于文件路径这种包含特殊字符、层级结构的标识符，用请求参数传递反而更直观，也避免了URL路径解析的冲突问题。比如GET files?path=/folder_1/folder_2/a.sh，后端直接读取path参数即可定位到对应的文件资源，实现成本低，也容易维护。

方案2：对路径进行编码/解码 #

URL编码（比如把/转成%2F）确实能让文件路径合法地出现在URL路径中，比如GET files/%2Ffolder_1%2Ffolder_2%2Fa.sh。但这种方式有几个明显的弊端：一是编码后的URL可读性极差，不利于调试和用户理解；二是后端需要额外处理编码和解码逻辑，增加了复杂度；三是部分网关或代理服务器可能会对编码后的路径做额外解析，引发意想不到的问题。除非有强需求必须把资源ID放在路径里，否则不推荐这种方案。

方案3：新增ID映射关系 #

为每个文件路径分配独立的int/long型ID，存到数据库维护映射关系，这种方案适合需要对文件资源做权限控制、版本管理或统计分析的场景。但缺点也很明显：需要额外开发CRUD时的映射维护逻辑，增加了数据库存储和运维成本；用户无法通过URL直接推断资源路径，降低了API的直观性。如果你的业务不需要这些额外功能，这个方案的性价比很低。

最佳实践建议 #

如果只是单纯的文件资源访问，方案1是最优选择：它符合REST规范，实现简单，可读性好，也不会引入额外的维护成本。如果业务上要求必须把资源标识放在URL路径中，可以考虑方案2，但要做好编码解码的一致性测试，避免跨系统的解析问题。方案3只推荐在需要对文件资源做精细化管理（比如权限、版本、元数据跟踪）的场景下使用。

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