文件系统模拟场景REST API设计合理性评估及相关设计问题咨询

原设计功能匹配度说明 #

你现有的设计基本可以覆盖三个核心功能的需求，但不符合REST API的通用语义惯例，有优化空间。

疑问解答 #

1. GET接口路径参数选择与路径区分方案 #

优先选择路径变量，更符合REST通过URL定位资源的核心语义。
路径混淆的问题非常好解决：后端路由配置/v1/file-system/files/**通配符规则，直接截取/v1/file-system/files/之后的所有路径片段作为文件路径即可，比如请求v1/file-system/files/a/b/c.txt，截取得到的文件路径就是a/b/c.txt，完全不会和API自身的路由前缀冲突。
如果你的文件路径存在大量特殊字符（比如#、?这类会被URL解析器截断的字符），可以退而选择查询参数传递，传输前对路径做URL编码即可，兼容性更强。

2. createFile用PUT方法是否符合规范 #

完全符合规范。PUT方法的原生语义就是「客户端明确指定资源位置，上传内容覆盖该位置的现有资源，资源不存在则直接创建」，和你createFile的功能要求100%匹配，比POST更适合这个场景。

3. POST/PUT的path参数是否应该放在路径变量中 #

建议优先放在路径变量中，优势如下：

• 完全符合REST资源定位的设计原则，接口语义更清晰，调用方一看URL就知道操作的是哪个路径下的资源
• 避免参数拆分在路径和请求体中，降低接口对接的出错概率
  优化后的接口示例参考：

// 创建目录
POST v1/file-system/directories/{dir-path}
RESPONSE
{
  "id" : "",
  "path": "",
  "files": [...]
}

// 创建/覆盖文件
PUT v1/file-system/files/{file-path}
BODY {
  "content": ""
}
RESPONSE
{
  "id" : "",
  "content": "",
  "path": ""
}

// 读取文件
GET v1/file-system/files/{file-path}
RESPONSE
{
  "id" : "",
  "content": "",
  "path": ""
}

如果业务场景中存在大量带特殊字符的路径，不方便通过路径变量传递，再考虑将path参数放到请求体或者查询参数中。

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