URL、HTTP请求、网站服务设计原则

原文：https://stackoverflow.com/a/1619677

作者：Bob Aman

翻译：DarcJC

原文并未遵循任何协议，因此本文作者拥有一切解释权。在原作者授权后，本文可以基于知识共享署名-相同方式共享 4.0 国际许可协议转载。

良好的URI一般设计原则：

• 不要利用查询参数来改变状态
• 如果能控制的话，不要使用混合大小写的路径；小写是最好的
• 不要在URI中使用特定实现的拓展名（.php, .py, .pl, etc.）
• 不要为RPC而设计URI
• 请尽可能地限制URI中的空格
• 请保持路径简短
• 请在 /resource 和 /resource/ 间做出选择；将不使用的那个使用301重定向到另一个
• 在对一个资源的子项进行查询时，请使用查询参数；比如分页、搜索查询
• 当内容可以存在于请求头（主体）时，请不要将其放在URI中

（注意：我没有说这是“RESTFul URI设计”；URI在REST中基本是不透明的）

良好的HTTP方法选择原则：

• 不要用GET来改变状态；这倒是一个让搜索引擎爬虫毁掉你一天的好方法
• 不要使用PUT，除非你要更新整个资源
• 不要使用PUT，除非你也可以合法地在同一个URI使用GET请求
• 不要使用POST来拉取长时间存在或可以被合理地缓存的信息
• 不要用PUT执行一个不等幂的操作；（译注：可以将PUT看做一个一元运算，用其返回结果再进行运算一次后，得到的结果相同）
• 尽可能多地使用GET
• 请在难以抉择时优先使用POST而不是PUT
• 请对更大或者层次化的资源类使用PUT
• 请尽可能在删除资源时使用DELETE而不是POST
• 请在需要计算的环境下使用GET，要是你的输入实在很大，那就使用POST

基于http的web服务设计的一般原则：

• 不要将应当在响应头中的元数据放在响应体中
• 不要将元数据放在单独的资源中，除非将其包括在内会产生很大的开销
• 请使用适当的状态码：
  • 201 Created 创建一个资源后；该资源必须在发送响应时存在
  • 202 Accepted 成功执行操作或异步创建资源
  • 400 Bad Request 有人使用明显伪造的数据进行操作；对于你的应用来说，这可能是一个(参数)校验错误；通常将 500 保留给未捕获的异常
  • 401 Unauthorized 有人访问API而未提供必须的授权验证头或凭据无效；如果你不希望通过授权验证头获取凭据，请不要使用此代码
  • 403 Forbidden 有人恶意访问API或访问者未被授权
  • 405 Method Not Allowed 例如，在应当用POST时使用PUT
  • 413 Request Entity Too Large 有人尝试发送一个不可接受的大文件时
  • 418 I'm a teapot 当你想用一个茶壶煮咖啡时 (这个规范发布于1 April 1998 滑稽)
• 尽可能使用缓存类的头：
  • ETag 头在当你可以很容易地将资源转换成HASH值时是很好的
  • Last-Modified 说明在文件更新时更新时间戳是个好主意
  • Cache-Control 和 Expire 应当设置为一个合理的值
• 尽可能接受请求中的缓存头（If-None-Modified, If-Modified-Since）：
• 请仅在有意义时使用重定向，但是对于web服务来说使用重定向的场景应该较少

记住，在没必要的时候不要在POST中使用 Content-Type: application/x-www-form-urlencoded，用JSON或CSV可能更加简单。