基于Deno的JSON-RPC v2 API适配HTTP状态码规范问询

核心原则 #

JSON-RPC 2.0本身通过响应 payload 中的error字段传递业务/RPC层面的错误，HTTP状态码应聚焦HTTP传输层问题或符合通用HTTP语义的场景，避免两者语义重叠。

常用状态码及适用场景 #

200 OK #

• 适用场景：
  • 所有成功处理的RPC请求（包括查询、更新成功等带返回结果的CRUD操作）
  • RPC请求格式合法，但业务层面返回error字段（比如参数校验失败、业务规则不满足）——因为HTTP传输本身是成功的，错误属于RPC层面

201 Created #

• 适用场景：仅当RPC调用是创建资源的操作（比如createUser、addPost），且确实在服务器端生成了新的持久化资源时使用。
• 注意：RPC payload里仍需返回创建后的资源信息或ID，状态码仅用于标识资源已被创建。

204 No Content #

• 适用场景：RPC调用成功，但没有任何数据需要返回（比如deleteUser成功且无需返回额外信息，或者clearCache这类无返回值操作）。
• 注意：此时响应payload可以为空，或者返回符合JSON-RPC规范的空结果响应：{"jsonrpc": "2.0", "id": "xxx"}

400 Bad Request #

• 适用场景：
  • HTTP请求本身格式错误（比如不是合法的JSON payload）
  • RPC请求格式不符合JSON-RPC 2.0规范（比如缺少jsonrpc字段、id格式错误）

401 Unauthorized #

• 适用场景：HTTP层面的身份验证失败（比如缺少JWT token、token无效/过期），此时RPC请求还没到业务处理阶段。
• 注意：如果是RPC层面的权限不足（比如已登录但无操作某资源的权限），应返回200 OK + payload中的error字段（code可设为-32001或自定义业务错误码）。

404 Not Found #

• 适用场景：HTTP请求的端点路径错误（比如用户访问了/api/rpc之外的路径），而非RPC方法不存在（方法不存在属于RPC层面错误，返回200 + error.code = -32601）。

403 Forbidden #

• 适用场景：HTTP层面的权限校验失败（比如IP被封禁、请求来源不允许），和401的区别是：401是未认证，403是已认证但无权限访问整个RPC端点。

500 Internal Server Error #

• 适用场景：服务器端在处理RPC请求时发生未捕获的异常（比如数据库连接失败、代码逻辑错误导致崩溃），此时无法返回合法的JSON-RPC响应。

501 Not Implemented #

• 适用场景：RPC方法已被定义，但尚未实现（比如batchUpdate方法在规划中但还没开发），此时返回200 + error.code = -32601也可，但用501更符合HTTP语义，前提是明确告知客户端该方法暂未实现。

关键区分示例 #

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