REST的几个常见错误

最新推荐文章于 2025-10-03 11:40:24 发布
转载 最新推荐文章于 2025-10-03 11:40:24 发布 · 6.5k 阅读 · 1

过去几年我的工作和学习一直围绕RESTful API，我在不同的项目和社区中见过很多相同的错误，于是我就决定，将我在网上读到的和我自身的经验整理一下。下面这些，是常见的一些设计错误、解释以及例子。

URI不够RESTful

你的URI没有反应相应资源的用途。

RESTful的API是基于资源的，当我们设计URI的时候，要时刻铭记我们应该通过URI正确反映资源，要让用户一看到URI，就能明白这是什么资源，是什么地方的，它的标志符是什么，它有什么可选项。

比如说，我们有种资源叫“account”，我们现在要关闭这个账户，那么相应的URI应该设计成什么呢？

下面分别是错误的和正确的例子，你认为哪一个更合理？

错误的：

  • POST /accounts/close
  • POST /closeAccount

正确的：

  • POST /accounts/4402278/close

错误的用法没有给出URI的具体信息，也许我们需要在请求中加入一些查询的变量或主体，但是光从名字来看，并不能看到查询的参数，或需要的主体。

正确的用法明确地表达出“account” 4402278可以被关闭，从URI我们就可以推断出这一点。

使用了错误的HTTP方法

HTTP的方法必须根据请求意图的不同正确使用。例如，如果你要返回信息，就必须使用GET方法。

下面就是一些动作的类型和相应的HTTP方法：

  • GET - 取回记录
  • POST - 创建记录
  • PUT - 更新整个记录
  • PATCH - 更新其中一些记录
  • DELETE - 删除记录

话虽如此，下面这种错误时常发生：

错误：

  • POST /accounts/4402278/delete

正确：

  • DELETE /accounts/4402278/delete

错误的例子企图在“accounts”上使用POST方法，通过在URI标注ID删除一个账户。

虽然这样做也可以达到目的，但却是不恰当的。应为HTTP提供了明确的方法来删除资源，即DELETE。

还有很多错误的例子，展开说又可以写一篇文章了，在这里只是简单提一下。

打破了幂等

无论你对相同的资源调用多少次GET，返回的信息应该不变。

  • 应该维持幂等的方法：GET，PUT，OPTIONS
  • 不维持幂等的方法：POST

那么DELETE方法呢？如果你删除/accounts/4402278两次会发生什么？

  • 账户不应该允许被删除多次……想象一下如果维持幂等将会什么样子。
  • 第二次删除操作不会找到该资源，应该返回404

https://www.youtube.com/watch?v=6dVNdFwqeKs

忽略状态码

图片描述

如果你的API返回200（ok）或500（内部服务器错误），就违背了返回状态码的原则。

状态码的目的是给用户对请求状态的总体判断。

这意味着，我们应该慎重选择代表状态的状态码，它需要准确反应最后结果的状态。

错误的：

  • GET /accounts/123456（没有对应记录）返回：HTTP状态200（ok），body中说没有找到

正确的：

  • GET /accounts/123456（没有对应记录）返回：404（not found）

如果你需要get一个如例子所示的资源，但是没有相应的记录，那么应该返回404，因为这是not found。如果反悔200（ok）然后在body中说“not found”，这是不合适的。这种做法非常多余。

状态码也能帮助你的API更清楚地描述状态。在很多情况下，用户只处理状态码就能知道发生了什么，这比处理大型字符串更加简单。

HTTP状态码

下面是最常用的一些状态码。

  • 2xx - Success
  • 200 OK
  • 201 Created
  • 203 Partial Information
  • 204 No response
  • 3xx - Redirection
  • 301 Moved
  • 302 Found
  • 304 Not Modified
  • 4xx / 5xx - Error
  • 400 Bad Request
  • 401 Unauthorized
  • 402 Payment Required
  • 403 Forbidden
  • 404 Not Found
  • 500 Internal Server Error
  • 503 Service Unavailable

忽略缓存

忽略缓存很简单，只要在API调用的头部加入”Cache-control: no-cache”就可以了。

HTTP定义了很多强大的缓存机制，包括ETag，If-Modified-Since header，和304 Not Modified返回码。

这可以让你的客户端和服务器能通过缓存或代理保持一份资源的副本，来提高应用的扩展性和性能。

忽略超链接

如果你的调用发送的描述不包含任何链接，那么你就打破了REST的HATEOAS原则。

超链接的概念指的是一些链接资源，可以让应用通过链接在不同的状态之间跳转。

如果你忽略了超链接，就意味着URI必须在客户端通过很难的编程原理实现。

更多有关HATEOAS原则

  • 客户端通过链接与应用的交互应提供动态API
  • 应用现在的状态由你部署的数据和链接定义
  • 客户端应该对链接有一定的理解
  • 服务器应该可以独立升级
  • 应该通过链接来交互，而不是外带的信息

例子

在下面的例子中，我们有一个叫做“accounts”的资源，一共有一百条。

{
    "accounts": [
        {
            "accountNumber": "4502278",
            "balance": 100.00,
            "links": [
              {"rel": "deposit", href: "/account/4502278/deposit"},
              {"rel": "withdraw", href: "/account/4502278/withdraw"},
              {"rel": "transfer", href: "/account/4502278/transfer"},
              {"rel": "close", href: "/account/4502278/close"}
            ]
        }
    ]
}

如果现在账户出现了异常，用户只能进行其中一些操作，那么API应该如下部署：

{
    "accounts": [
        {
            "accountNumber": "4502278",
            "balance": -60.55,
            "links": [
                {"rel": "deposit", href: "/account/4502278/deposit"}
            ]
        }
    ]
}

忽略MIME类型

如果你的API返回的资源只有一种单一的表示形式，那么可能你服务的客户端很少，而且都能理解这种形式。

如果你未来想要支持更多客户端，那么应该使用HTTP内容协商。

它可以让你指定特定的资源类型，如XML，JSON或YAML。

总结

当你设计API的时候……

  • 条理清楚
  • 需要头部
  • 使用标准（JSON-API）
  • URI设计合理
  • 返回正确的状态码
  • 注意幂等
  • 使用正确的HTTP方法

我希望这篇文章能让你了解一下常见的错误，并且在你设计API的时候设法避免他们。

2016年9月22日-23日，[SDCC 2016大数据技术&架构实战峰会](http://bss.youkuaiyun.com/m/topic/sdcc_invite/hangzhou /)将在杭州举行，两场峰会大牛讲师来自阿里、京东、苏宁、唯品会、美团点评、游族、饿了么、有赞、Echo等知名互联网公司，共同探讨海量数据下的应用监控系统建设、异常检测的算法和实现、大数据基础架构实践、敏捷型数据平台的构建及应用、音频分析的机器学习算法应用，以及高可用/高并发/高性能系统架构设计、电商架构、分布式架构等话题与技术。
9月5日~18日是八折优惠票价阶段，5人以上团购或者购买两场峰会通票更有特惠，限时折扣，预购从速。（票务详情链接）。

互联网应用主流框架整合【构建REST风格的系统】
一块大洋
06-15 1万+
REST风格设计(附源码)
PHP程序员常见的40个陋习,你中了几个？
12-19
23. 不了解SQL注入和XSS攻击：学习防范这些常见安全问题的方法。 24. 不支持参数化配置：使用构造函数、set/get方法，定义常量。 25. 不能理解OOP优缺点：理解OOP的封装、继承、多态特性及其适用场景。 26. 过度...
RESTful Service API 常见问题解决方案
05-24 1092
REST 风格的优秀设计应该像下面这些： - GET /users 获取所有用户 - GET /users/1234 获取ID为1234的用户 - POST /users 创建一个新用户 - PUT /users/1234 更新ID为1234的用户 - PATCH /users/1234 更新ID为1234的用户的部分内容 - DELETE /users/1234 删除I...
REST API
最新发布
2502_92141759的博客
10-03 939
REST（Representational State Transfer，表现层状态转移）是一种软件架构风格，用于设计网络应用程序接口（API）。REST API 是遵循 REST 原则的 API，它使用 HTTP 协议进行通信，通常以 JSON 或 XML 格式传输数据。REST 不是一种协议或标准，而是一组设计原则，使 API 更加简洁、可扩展和易于理解。REST API 是一种灵活、可扩展的接口设计风格，通过使用标准 HTTP 方法和状态码，使不同系统之间的通信变得简单。
【规范】Restful学习
常徜的博客
04-13 417
文章目录RESTful（本文为API 仅供查阅）一、何为RESTful二、接口规范1.GET2.POST3.DELETE4.PUT三、安全和幂等 RESTful （本文为API 仅供查阅） 一、何为RESTful RESTful架构，就是目前最流行的一种互联网软件架构。 它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。 REST这个词，是Roy ThomasFieldin...
restful 常见的返回错误码总结
臣本布衣，躬耕于南阳
03-09 8753
HTTP 400 - 请求错误:bad_request HTTP 406 错误 – 无法接受 (Not acceptable) 422 Unprocessable Entity - 请求格式正确 附：对照表 Response Class HTTP Status Code Symbol 消息 100 :continue 101 :switching...
RESTful
我的博客
05-09 697
REST = Representational State Transfer 表述性状态转移，是web服务的一种架构风格 总之就是一种风格 REST基于HTTP,URI,XML,JSON,HTML这些广泛流行的协议和标准 REST架构的主要原则： --网络上的所有事物都可以被抽象为资源（Resource） --每个资源都有唯一的资源标识符（Resource Identifier） -
【VSCode REST Client脚本编写】：避免这些10个常见陷阱与错误，提升你的编码效率
[【VSCode REST Client脚本编写】：避免这些10个常见陷阱与错误，提升你的编码效率](http://blog.kevinyang.net/2023/09/02/vscode-rest-client-note/image-20230902223304534.png) # 1. VSCode REST Client简介 ...
REST API教程.zip_zip压缩包
01-10
在RESTful API的设计中，有以下几个关键知识点： 1. **资源（Resource）**：REST API的核心是资源，每个URL代表一个特定的资源。例如，`/users/{userId}`表示一个用户资源，其中`{userId}`是资源的标识符。 2. **...
REST ful接口规范事项
weixin_42067697的博客
07-13 186
正确：post /api/transaction?from=1&to=2&money=500 ---->还是放body体中 不外泄。course_is=A --服务端解析token 从而知道是哪个用户。错误：post /api/accounts/1/transfer/500/to2。错误设计：/create /delete /show。3.从1号用户，转账500，给2号用户。---》url中不要带敏感信息。
HTTP的REST服务简介和最佳实践
05-16
一说到REST，我想大家的第一反应就是“啊，就是那种前后台通信方式。”但是在要求详细讲述它所提出的各个约束，以及如何开始搭建REST服务时，却很少有人能够清晰地说出它到底是什么，需要遵守什么样的准则。 博文地址：https://blog.youkuaiyun.com/adparking/article/details/52278794 此PDF文档，只为方便阅读查看
.net Rest服务访问
闲暇余客
06-30 1232
趁热打铁,记录一下访问rest服务的过程以及中间遇到的坑
理解 RESTful API 面向资源 幂等性
许恒的博客
12-07 3076
  如何理解RESTful的幂等性  我来答 分享 举报浏览 3612 次 1个回答 #再见，2018！# 2018要结束了，你还有哪些心愿没完成？？ 最佳答案 热心网友  2017-07-02 等幂性（Idempotence） 等幂性简单点说就是一次请求和多次请求，资源的状态是一样。比如GET和HEAD，不论你请求多少次，资源还是在那里。请注意，DELETE和PUT也是等幂的，...
谈对RESTFUL api的理解
weixin_44465584的博客
03-13 1669
前言：restful出现的环境，什么是rest?以及出现的意义 1.REST的由来 全称：REST，全称是Resource Representational State Transfer，即：资源在网络中以某种形式进行状态转移。————所谓状态的转移，它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到：“我这篇文章的...
关于Restful风格使用的一些误区
干勾鱼的优快云博客
10-12 6105
网上对Restful风格的介绍有很多，比如阮一峰老师的理解RESTful架构，RESTful API 设计指南等，大家可以参考。这里主要说说Restful使用中的一些误区。 1 URI包含动词。 这是在使用Restful风格开发时最常见的一种设计错误。Restful认为客户端访问服务器时，其实是在访问资源（Resources），什么是资源（Resources）？所谓"资源"，就是网络上的一个实体，...
关于RESTful一些注意事项，和自己整理的接口开发规范
热门推荐
哈库桑的博客
02-21 4万+
最近在研究restful，公司开发要使用，所以自己就去网上找了好些资料，并整理了一套公司开发的接口规范。当然，我也只是刚刚入坑。还不是很全面。但是这就是一个过程。一点点，总会好起来的。以下是就是RESTful接口规范： 一、   URI URI规范 1.不用大写； 2.用中杠 - 不用下杠 _ ； 3.参数列表要encode； 4.URI中的名词表示资源集合，使用复数形式。 5.在R
http访问服务器rest格式请求
08-18 6093
例子如下：StringBuffer tokenurl = new StringBuffer(); tokenurl.append(Functions.fldUrl()).append("/"); tokenurl.append("token").append("/"); tokenurl.append("get").append("/");
rest接口访问404问题
hoho_12
08-27 3139
问题描述：项目中使用了rest接口，大概是使用RestController、RequestMapping、GetMapping等注解来开发。在参照已有的代码写了一个简单的查询接口之后，使用maven打成jar包之后发布，始终是访问不了这个接口，一直报404找不到。 解决方案：在经过反复调试与分析，在同事的帮助下，发现web-inf下的classes目录下有同名的class文件，就是这个class文件在打的jar包中也有，两个重复了。但是访问的时候一直走的是classes下的class文件，不是走的我打的j
REST API返回701错误时如何自动修复？
08-28
<think>我们正在处理的是IoTDB的REST API返回的错误代码701。根据之前的讨论，701错误通常表示路径不存在或元数据访问失败。现在用户希望了解当REST API返回701错误时，如何实现自动修复。 自动修复701错误的方法可以分为几个层次： 1. 预检查：在发送请求前，对路径进行校验和修正（如转义特殊字符） 2. 错误处理：在收到701错误后，根据可能的错误原因进行修复重试 3. 自动化元数据管理：在路径不存在时自动创建（需要谨慎，因为可能涉及权限和业务逻辑） 参考引用[4]中提到的“为常见错误提供自动化修复建议”，我们可以为701错误设计一个自动修复流程。 具体步骤： 一、预检查（预防性修复） - 对用户输入的路径进行规范化处理，确保特殊字符被正确转义（使用反引号） - 检查路径是否在元数据中存在（通过元数据查询API） 二、错误后自动修复（反应式修复） 当收到701错误时，自动执行以下步骤： 1. 路径转义修正：检查路径中是否有特殊字符，如果有，则用反引号转义后重试。 2. 元数据刷新：调用元数据刷新API（/rest/v1/refresh），然后重试原请求。 3. 路径创建：如果路径确实不存在，且当前用户有创建权限，则自动创建路径（需要根据业务需求决定是否开启此功能）。 三、自动修复流程设计（伪代码） ```python def auto_fix_701(original_sql, max_retry=3): retry_count = 0 while retry_count < max_retry: response = execute_sql(original_sql) if response.status_code != 200 or response.json().get("code") != 701: return response # 成功或其它错误，直接返回 # 分析错误原因 error_message = response.json().get("message", "") if "Path does not exist" in error_message: # 尝试1：路径转义修正 fixed_sql = escape_special_characters(original_sql) response = execute_sql(fixed_sql) if response.status_code == 200 and response.json().get("code") != 701: return response # 尝试2：刷新元数据 refresh_metadata() # 调用刷新元数据的API response = execute_sql(fixed_sql) # 再次用修正后的SQL执行 if response.status_code == 200 and response.json().get("code") != 701: return response # 尝试3：自动创建路径（需要配置是否允许自动创建） if config.allow_auto_create_path: path = extract_path_from_sql(original_sql) # 从SQL中提取路径 create_timeseries(path) # 创建时间序列 # 创建后需要等待元数据刷新（或主动刷新） refresh_metadata() # 然后用修正后的SQL重试 response = execute_sql(fixed_sql) if response.status_code == 200 and response.json().get("code") != 701: return response retry_count += 1 # 重试次数用尽，返回最后一次错误 return response ``` 四、注意事项 - 自动创建路径（create_timeseries）需要谨慎，因为它可能改变系统状态，且需要知道数据类型、编码等，通常需要从上下文推断或使用默认值。 - 刷新元数据操作在分布式环境下可能不会立即生效（需要等待集群同步），因此可能需要延迟重试。 - 参考引用[1]中强调不要混合HTTP错误码和业务错误码，因此701是业务错误码，我们应在HTTP 200响应的业务体中处理。 五、错误码处理原则 - 在REST API设计中，业务错误（如701）应该在HTTP 200响应中通过业务错误码表示，而不是使用HTTP状态码（如404）。这样客户端可以统一处理业务逻辑错误。 六、高级设计 - 参考引用[4]中提到的“实现错误中心，将错误代码映射到详细的故障排除指南”，我们可以为701错误建立知识库，记录可能的原因和修复方法，并在自动修复失败时提供详细的错误诊断报告。 七、示例：路径转义函数 ```python import re def escape_special_characters(sql): # 匹配路径中的非字母数字字符（不包括点），并用反引号转义 # 注意：避免转义已经转义的部分 pattern = r'([a-zA-Z0-9_]+[\.\-][a-zA-Z0-9_\.\-]+)' def escape_match(match): path = match.group(0) # 如果已经被反引号包围，则不处理 if path.startswith('`') and path.endswith('`'): return path return f'`{path}`' return re.sub(pattern, escape_match, sql) ``` 八、自动创建路径的默认策略 - 数据类型：默认为FLOAT（可根据路径中的关键词调整，如包含'temp'则用FLOAT，包含'status'则用BOOLEAN） - 编码：SNAPPY - 压缩器：LZ4 九、分布式环境下的元数据刷新 - 在集群环境下，刷新元数据可能需要调用集群级别的API，或者等待一段时间（例如5秒）让元数据同步。 十、自动修复的配置开关 - 提供配置项，允许用户选择开启或关闭某些自动修复步骤（如自动创建路径）。 十一、监控与日志 - 记录自动修复的过程，便于后续审计和问题排查。 十二、相关问题 - 如何设计一个通用的REST API错误自动修复框架？ - 在分布式IoTDB中，元数据同步的延迟如何影响自动修复？ - 如何避免自动创建路径导致的安全问题？ 以上为针对701错误的自动修复方法，具体实现时需要根据实际环境和业务需求进行调整。</think>### IoTDB REST API 701错误的自动修复方法 #### 一、701错误自动修复框架 根据引用[4]的自动化修复建议，设计分层修复策略： ```mermaid graph TD A[701错误触发] --> B{错误类型分析} B --> C1[路径语法错误] B --> C2[元数据未同步] B --> C3[存储组缺失] B --> C4[权限不足] C1 --> D1[自动路径转义] C2 --> D2[强制元数据刷新] C3 --> D3[自动创建存储组] C4 --> D4[权限提升请求] D1 --> E[重试查询] D2 --> E D3 --> E D4 --> E ``` #### 二、核心自动修复技术 1. **路径自动转义**（解决引用[1]的HTTP与业务错误分离问题） ```python def auto_escape_path(sql): """自动转义特殊字符路径""" pattern = r"(root\.[\w-]+\.?[\w-]+)" return re.sub(pattern, r"`\1`", sql) # 示例转换 # 输入: SELECT device-1.sensor FROM root.sg # 输出: SELECT `device-1`.`sensor` FROM `root.sg` ``` 2. **元数据同步自动化**（实现引用[2]的调试自动化） ```python def refresh_metadata(api_endpoint): """触发元数据刷新""" requests.post(f"{api_endpoint}/rest/v1/refresh") time.sleep(1) # 等待元数据加载 ``` 3. **存储组自动创建** ```python def ensure_storage_group(api_endpoint, sg_path): """确保存储组存在""" check_sql = f"SHOW STORAGE GROUP LIKE '{sg_path}.*'" if not execute_query(api_endpoint, check_sql).get("results"): create_sql = f"SET STORAGE GROUP TO {sg_path}" execute_query(api_endpoint, create_sql) ``` #### 三、完整自动修复流程 ```python def auto_fix_701(api_endpoint, original_sql, max_retry=3): """701错误自动修复管道""" for attempt in range(max_retry): response = execute_query(api_endpoint, original_sql) if response.get("code") != 701: return response # 成功或其它错误 # 错误类型诊断 error_msg = response.get("message", "") if "Path does not exist" in error_msg: # 路径修复 fixed_sql = auto_escape_path(original_sql) response = execute_query(api_endpoint, fixed_sql) if response.get("code") != 701: return response if "metadata not found" in error_msg.lower(): # 元数据刷新 refresh_metadata(api_endpoint) response = execute_query(api_endpoint, original_sql) if response.get("code") != 701: return response # 提取存储组路径 (root.sg) sg_path = re.search(r"root\.\w+", original_sql).group(0) ensure_storage_group(api_endpoint, sg_path) return {"status": "FAIL", "message": "Auto-fix failed after retries"} ``` #### 四、生产环境增强措施（实现引用[4]的建议） 1. **安全控制** ```python # 配置白名单控制自动创建行为 AUTO_CREATE_WHITELIST = ["root.sensor_temp", "root.device_log"] def is_safe_to_create(path): return any(p in path for p in AUTO_CREATE_WHITELIST) ``` 2. **修复验证** ```python def validate_fix(effected_path): """验证修复后路径存在""" check_sql = f"SHOW TIMESERIES {effected_path}" return bool(execute_query(api_endpoint, check_sql).get("results")) ``` 3. **监控集成** ```python def log_auto_fix(event): """发送修复事件到监控系统""" metrics.increment("iotdb.701_auto_fix.count") logging.info(f"AUTO_FIX_EVENT: {json.dumps(event)}") ``` #### 五、高级修复策略 1. **分布式环境修复**（引用[4]的批量处理扩展） ```python def cluster_metadata_sync(nodes): """集群元数据同步""" for node in nodes: requests.post(f"http://{node}:18080/rest/v1/refresh") ``` 2. **权限自动化**（引用[3]的OAuth2集成） ```python def auto_elevate_permissions(user_token, path): """自动申请路径权限""" payload = {"user": user_token, "path": path, "permission": "READ"} requests.post("/auth/elevate", json=payload) ``` 3. **修复策略配置** ```json // config/auto_fix_rules.json { "701": { "max_retry": 3, "enable_auto_create": true, "allowed_paths": ["root.sg.*"], "metadata_refresh_delay": 1500 } } ``` #### 六、最佳实践建议 1. **修复策略选择**： - 开发环境：启用全自动修复（包含路径创建） - 生产环境：仅启用路径转义和元数据刷新 2. **性能优化**： ```python # 元数据缓存预热 def preload_metadata(common_paths): for path in common_paths: execute_query(f"COUNT TIMESERIES {path}") ``` 3. **错误分析增强**（实现引用[2]的调试建议）： ```python def analyze_701_error(sql): """错误根因分析""" return { "unescaped_chars": bool(re.search(r"[.-]", sql)), "storage_group_exists": check_storage_group_exists(sql), "last_metadata_refresh": get_metadata_refresh_time() } ``` > 关键提示：自动修复后需验证数据一致性，建议添加`$$ \text{ConsistencyCheck} = \sum_{i=1}^{n} |\text{RepairedValue}_i - \text{ActualValue}_i| < \epsilon $$`[^4]
评论 1
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值