如何在Rails中为API定义带说明文档的自定义错误码？

没问题，我来一步步教你在Rails API里实现自定义错误响应格式，同时规范错误码管理和文档说明：

1. 定义全局错误码常量 #

首先咱们把所有自定义错误码集中管理，避免硬编码数字带来的维护麻烦。在config/initializers/error_codes.rb文件中添加以下内容：

# 全局自定义错误码映射
ERROR_CODES = {
  authentication_issue: 1000,
  # 后续新增错误码直接在这里扩展即可，比如：
  # invalid_request_params: 1001,
  # resource_not_found: 1002
}.freeze

# 单独定义认证错误的常量，使用时更直观
AUTHENTICATION_ERROR_CODE = ERROR_CODES[:authentication_issue]

这样整个应用的任何地方都能直接引用这些常量，不用再记数字。

2. 创建自定义异常类 #

为了让错误处理逻辑更清晰，咱们给认证问题创建一个专属的异常类。在app/exceptions/authentication_error.rb中写入：

class AuthenticationError < StandardError
  def initialize(message = "Authentication issue")
    super(message)
  end
end

这里默认的错误消息就是你需要的内容，也可以在抛出异常时自定义消息（比如raise AuthenticationError.new("无效的登录凭证")）。

3. 配置全局异常捕获与响应格式 #

在app/controllers/application_controller.rb中，添加全局异常捕获逻辑，把自定义异常转换成你想要的JSON响应格式：

class ApplicationController < ActionController::API
  # 捕获AuthenticationError异常，统一返回格式
  rescue_from AuthenticationError do |exception|
    render json: {
      status: 401,
      message: exception.message,
      code: AUTHENTICATION_ERROR_CODE
    }, status: :unauthorized
  end

  # 如果你需要统一处理其他内置异常，比如404，也可以在这里扩展：
  # rescue_from ActiveRecord::RecordNotFound do |exception|
  #   render json: {
  #     status: 404,
  #     message: "请求的资源不存在",
  #     code: ERROR_CODES[:resource_not_found]
  #   }, status: :not_found
  # end
end

这样只要在业务逻辑中抛出AuthenticationError，就会自动返回符合要求的响应。

4. 在业务逻辑中抛出异常 #

比如在需要认证的控制器里，添加认证校验的前置动作，失败时抛出异常：

class Api::V1::PostsController < ApplicationController
  before_action :authenticate_request

  private

  def authenticate_request
    # 这里替换成你的实际认证逻辑，比如检查请求头的token
    token = request.headers['Authorization']&.split(' ')&.last
    unless valid_token?(token)
      raise AuthenticationError # 或者自定义消息：raise AuthenticationError.new("Token无效或缺失")
    end
  end
end

5. 添加错误码说明文档 #

为了让团队成员或API使用者清楚每个错误码的含义，咱们可以维护一份明确的文档：

方式一：在README.md中添加章节 #

## API错误码说明
| 错误码 | HTTP状态码 | 消息说明 | 常见触发场景 |
|--------|------------|----------|--------------|
| 1000   | 401        | Authentication issue | 用户未登录、Token无效/过期、缺少认证凭证 |
| 1001   | 400        | Invalid input | 请求参数格式错误、必填字段缺失 |
| ...    | ...        | ...      | ...          |

方式二：单独创建文档文件 #

在项目根目录下新建docs/error_codes.md，写入上述表格内容，适合大型项目的文档管理。

这样一套流程下来，你就完美实现了自定义错误响应格式，同时统一管理了错误码和对应的说明文档。

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