Kemal框架中自定义404 JSON响应的正确方式

在构建基于Kemal框架的RESTful API时，开发者经常需要为不存在的资源返回404状态码和自定义JSON响应。本文将深入探讨如何正确实现这一功能，避免常见的陷阱。

常见错误做法

许多开发者会尝试直接在路由处理中设置状态码和响应体：

get "/job_run/:id" do |env|
  env.response.content_type = "application/json"
  
  job_id = env.params.url["id"]
  job = Mosquito::Api::JobRun.new(job_id)

  if job.found?
    job.to_json
  else
    env.response.status = HTTP::Status::NOT_FOUND
    {
      error: "Job not found",
      see_other: "/job_runs"
    }.to_json
  end
end

这种方法看似合理，但实际上会导致Kemal框架渲染默认的错误页面，而不是开发者期望的JSON响应。这是因为Kemal对错误状态码有特殊的处理逻辑。

正确解决方案：使用halt方法

Kemal提供了halt方法，专门用于中断当前请求并返回自定义响应。这是处理错误响应的推荐方式：

get "/job_run/:id" do |env|
  env.response.content_type = "application/json"
  
  job_id = env.params.url["id"]
  job = Mosquito::Api::JobRun.new(job_id)

  if job.found?
    job.to_json
  else
    err = {
      error: "Job not found",
      see_other: "/job_runs"
    }.to_json
    
    halt env, status_code: 404, response: err
  end
end

为什么halt方法更优

1. 内容类型保持：halt方法会保留之前设置的content_type，确保响应始终是JSON格式
2. 立即中断执行：调用halt后，请求处理会立即终止，不会继续执行后续中间件
3. 状态码明确：通过status_code参数明确指定HTTP状态码，代码可读性更高
4. 框架集成：这是Kemal框架推荐的处理方式，能确保与框架其他部分良好协作

进阶技巧：全局错误处理

虽然上述方法适用于特定路由的错误处理，但对于大型API，可以考虑结合全局错误处理器：

error 404 do |env|
  env.response.content_type = "application/json"
  { error: "Not Found" }.to_json
end

这种方式适合处理未匹配任何路由的请求，而特定资源不存在的错误仍建议在路由内部使用halt处理，以提供更具体的错误信息。

总结

在Kemal框架中处理404错误时，直接设置状态码和响应体是不够的。使用halt方法可以确保响应符合预期，同时保持代码的清晰和可维护性。对于RESTful API开发，这是返回错误响应的最佳实践。