response_status

User 69e88e27

发布于：2026-01-13

概述

response_status 标签用于设置模板响应的 HTTP 状态码。默认情况下，模板响应状态码为 200（成功），当需要返回其他状态码（如 404、403、422 等）时，可以使用此标签。

语法

{% response_status 状态码 %}

支持的状态码范围

支持的状态码范围：200-599

2xx - 成功响应（200, 201, 204 等）
3xx - 重定向响应（301, 302, 304 等）
4xx - 客户端错误（400, 401, 403, 404, 422 等）
5xx - 服务器错误（500, 502, 503 等）

使用示例

1. 成功创建资源（201）

{% response_status 201 %}
{% response_type "json" %}
{% layout none %}

{
  "status": "created",
  "id": 123,
  "message": "资源创建成功"
}

2. 页面未找到（404）

{% response_status 404 %}
{% layout none %}

<div class="error-page">
  <h1>404 - 页面未找到</h1>
  <p>抱歉，您访问的页面不存在。</p>
</div>

3. 禁止访问（403）

{% response_status 403 %}
{% layout none %}

<div class="error-page">
  <h1>403 - 禁止访问</h1>
  <p>您没有权限访问此页面。</p>
</div>

4. 验证失败（422）

常用于表单提交验证失败的情况。

{% response_status 422 %}
{% response_type "json" %}
{% layout none %}

{
  "status": "error",
  "message": "验证失败",
  "errors": {
    "email": ["邮箱格式不正确"],
    "password": ["密码长度至少8位"]
  }
}

5. 使用 Turbo Stream 返回错误状态

{% response_status 422 %}
{% response_type "turbo_stream" %}
{% layout none %}

<turbo-stream action="replace" target="form-errors">
  <template>
    <div id="form-errors">
      <ul>
        {% for error in errors %}
          <li>{{ error }}</li>
        {% endfor %}
      </ul>
    </div>
  </template>
</turbo-stream>

6. 服务器错误（500）

{% response_status 500 %}
{% layout none %}

<div class="error-page">
  <h1>500 - 服务器错误</h1>
  <p>服务器遇到了一个错误，请稍后再试。</p>
</div>

实际应用场景

场景 1：自定义 404 页面

在静态模板中创建自定义 404 页面。

{%# statics/404.liquid %}
{% response_status 404 %}
{% layout none %}

<!DOCTYPE html>
<html>
<head>
  <title>404 - 页面未找到</title>
  <style>
    .error-container {
      text-align: center;
      padding: 50px;
    }
  </style>
</head>
<body>
  <div class="error-container">
    <h1>404</h1>
    <p>抱歉，您访问的页面不存在。</p>
    <a href="/">返回首页</a>
  </div>
</body>
</html>

场景 2：表单验证错误

表单提交后，如果验证失败，返回 422 状态码和错误信息。

{%# templates/create_comment_turbo_stream.liquid %}
{% response_status 422 %}
{% response_type "turbo_stream" %}
{% layout none %}

{%# 显示验证错误 %}
<turbo-stream action="replace" target="comment-form">
  <template>
    <form id="comment-form">
      {% if errors %}
        <div class="errors">
          <ul>
            {% for error in errors %}
              <li>{{ error }}</li>
            {% endfor %}
          </ul>
        </div>
      {% endif %}
      {% render 'comment_form', comment: comment %}
    </form>
  </template>
</turbo-stream>

场景 3：API 错误响应

创建 API 接口，返回错误状态码和错误信息。

{%# statics/api/error.liquid %}
{% response_status 400 %}
{% response_type "json" %}
{% layout none %}

{
  "status": "error",
  "code": 400,
  "message": "请求参数错误",
  "details": {
    "field": "email",
    "reason": "邮箱格式不正确"
  }
}

场景 4：资源创建成功

创建资源后返回 201 状态码。

{% response_status 201 %}
{% response_type "json" %}
{% layout none %}

{
  "status": "created",
  "id": {{ article.id }},
  "title": {{ article.title | json }},
  "created_at": {{ article.created_at | date: "%Y-%m-%d %H:%M:%S" | json }}
}

场景 5：权限不足

当用户没有权限访问资源时，返回 403 状态码。

{% response_status 403 %}
{% layout none %}

<div class="error-page">
  <h1>403 - 禁止访问</h1>
  <p>您没有权限访问此资源。</p>
  {% if current_user %}
    <a href="/">返回首页</a>
  {% else %}
    <a href="/sign_in">登录</a>
  {% endif %}
</div>

常见 HTTP 状态码说明

2xx 成功

200 OK - 请求成功（默认）
201 Created - 资源创建成功
204 No Content - 请求成功，但没有返回内容

3xx 重定向

301 Moved Permanently - 永久重定向
302 Found - 临时重定向
304 Not Modified - 资源未修改

4xx 客户端错误

400 Bad Request - 请求参数错误
401 Unauthorized - 未授权，需要登录
403 Forbidden - 禁止访问，权限不足
404 Not Found - 资源未找到
422 Unprocessable Entity - 验证失败

5xx 服务器错误

500 Internal Server Error - 服务器内部错误
502 Bad Gateway - 网关错误
503 Service Unavailable - 服务不可用

注意事项

状态码范围：只接受 200-599 范围内的整数，超出范围的值会被忽略，使用默认的 200 状态码
必须为整数：状态码必须是整数类型，不能是字符串或其他类型
配合其他标签使用：通常与 response_type 和 layout 标签配合使用，实现完整的响应控制
优先级：布局（layout）中设置的 response_status 会覆盖模板中的设置
标签顺序：将 response_status 标签放在模板的最前面，与其他控制标签一起
浏览器行为：某些状态码（如 404、500）可能会触发浏览器的默认错误页面，需要确保返回的内容格式正确

常见错误

错误 1：状态码超出范围

{%# ❌ 错误示例 %}
{% response_status 100 %}  <!-- 超出范围 -->
{% response_status 600 %}  <!-- 超出范围 -->

问题：超出 200-599 范围的状态码会被忽略，使用默认的 200 状态码。

解决：

{%# ✅ 正确示例 %}
{% response_status 404 %}

错误 2：使用字符串而不是数字

{%# ❌ 错误示例 %}
{% response_status "404" %}  <!-- 字符串 -->

问题：字符串类型的状态码会被忽略，使用默认的 200 状态码。

解决：

{%# ✅ 正确示例 %}
{% response_status 404 %}  <!-- 整数 -->

错误 3：忘记配合 layout none

{%# ❌ 错误示例 %}
{% response_status 404 %}
<!-- 没有设置 layout none，如果返回非 HTML 格式会有问题 -->

问题：如果使用非 HTML 响应类型，布局的 HTML 结构会影响响应格式。

解决：

{%# ✅ 正确示例 %}
{% response_status 404 %}
{% layout none %}

<div>404 错误页面</div>

最佳实践

状态码选择：根据实际情况选择合适的状态码，遵循 HTTP 标准
错误信息：返回错误状态码时，提供清晰的错误信息，帮助用户理解问题
配合 response_type：根据响应格式选择合适的 response_type（如 JSON、HTML）
禁用布局：当使用非 HTML 响应类型时，配合 {% layout none %} 禁用布局
标签顺序：将 response_status 标签放在模板的最前面，与其他控制标签一起
测试验证：在浏览器开发者工具中检查响应的状态码，确保符合预期

总结

response_status 标签用于设置模板响应的 HTTP 状态码，支持 200-599 范围内的状态码。正确使用此标签可以实现适当的 HTTP 响应，如错误处理、资源创建确认、权限控制等。通常需要与 response_type 和 layout 标签配合使用，以实现完整的响应控制。

提交反馈

response_type

layout