response_status
User 69e88e27
发布于：2026-01-13
# response_status 标签使用指南
## 概述
`response_status` 标签用于设置模板响应的 HTTP 状态码。默认情况下，模板响应状态码为 200（成功），当需要返回其他状态码（如 404、403、422 等）时，可以使用此标签。
## 语法
```liquid
{% response_status 状态码 %}
```
## 支持的状态码范围
支持的状态码范围：**200-599**
- **2xx** - 成功响应（200, 201, 204 等）
- **3xx** - 重定向响应（301, 302, 304 等）
- **4xx** - 客户端错误（400, 401, 403, 404, 422 等）
- **5xx** - 服务器错误（500, 502, 503 等）
## 使用示例
### 1. 成功创建资源（201）
```liquid
{% response_status 201 %}
{% response_type "json" %}
{% layout none %}
{
"status": "created",
"id": 123,
"message": "资源创建成功"
}
```
### 2. 页面未找到（404）
```liquid
{% response_status 404 %}
{% layout none %}
<div class="error-page">
<h1>404 - 页面未找到</h1>
<p>抱歉，您访问的页面不存在。</p>
</div>
```
### 3. 禁止访问（403）
```liquid
{% response_status 403 %}
{% layout none %}
<div class="error-page">
<h1>403 - 禁止访问</h1>
<p>您没有权限访问此页面。</p>
</div>
```
### 4. 验证失败（422）
常用于表单提交验证失败的情况。
```liquid
{% response_status 422 %}
{% response_type "json" %}
{% layout none %}
{
"status": "error",
"message": "验证失败",
"errors": {
"email": ["邮箱格式不正确"],
"password": ["密码长度至少8位"]
}
}
```
### 5. 使用 Turbo Stream 返回错误状态
```liquid
{% 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）
```liquid
{% response_status 500 %}
{% layout none %}
<div class="error-page">
<h1>500 - 服务器错误</h1>
<p>服务器遇到了一个错误，请稍后再试。</p>
</div>
```
## 实际应用场景
### 场景 1：自定义 404 页面
在静态模板中创建自定义 404 页面。
```liquid
{%# 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 状态码和错误信息。
```liquid
{%# 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 接口，返回错误状态码和错误信息。
```liquid
{%# statics/api/error.liquid %}
{% response_status 400 %}
{% response_type "json" %}
{% layout none %}
{
"status": "error",
"code": 400,
"message": "请求参数错误",
"details": {
"field": "email",
"reason": "邮箱格式不正确"
}
}
```
### 场景 4：资源创建成功
创建资源后返回 201 状态码。
```liquid
{% 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 状态码。
```liquid
{% 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** - 服务不可用
## 注意事项
1. **状态码范围**：只接受 200-599 范围内的整数，超出范围的值会被忽略，使用默认的 200 状态码
2. **必须为整数**：状态码必须是整数类型，不能是字符串或其他类型
3. **配合其他标签使用**：通常与 `response_type` 和 `layout` 标签配合使用，实现完整的响应控制
4. **优先级**：布局（layout）中设置的 `response_status` 会覆盖模板中的设置
5. **标签顺序**：将 `response_status` 标签放在模板的最前面，与其他控制标签一起
6. **浏览器行为**：某些状态码（如 404、500）可能会触发浏览器的默认错误页面，需要确保返回的内容格式正确
## 常见错误
### 错误 1：状态码超出范围
```liquid
{%# ❌ 错误示例 %}
{% response_status 100 %} <!-- 超出范围 -->
{% response_status 600 %} <!-- 超出范围 -->
```
**问题**：超出 200-599 范围的状态码会被忽略，使用默认的 200 状态码。
**解决**：
```liquid
{%# ✅ 正确示例 %}
{% response_status 404 %}
```
### 错误 2：使用字符串而不是数字
```liquid
{%# ❌ 错误示例 %}
{% response_status "404" %} <!-- 字符串 -->
```
**问题**：字符串类型的状态码会被忽略，使用默认的 200 状态码。
**解决**：
```liquid
{%# ✅ 正确示例 %}
{% response_status 404 %} <!-- 整数 -->
```
### 错误 3：忘记配合 layout none
```liquid
{%# ❌ 错误示例 %}
{% response_status 404 %}
<!-- 没有设置 layout none，如果返回非 HTML 格式会有问题 -->
```
**问题**：如果使用非 HTML 响应类型，布局的 HTML 结构会影响响应格式。
**解决**：
```liquid
{%# ✅ 正确示例 %}
{% response_status 404 %}
{% layout none %}
<div>404 错误页面</div>
```
## 最佳实践
1. **状态码选择**：根据实际情况选择合适的状态码，遵循 HTTP 标准
2. **错误信息**：返回错误状态码时，提供清晰的错误信息，帮助用户理解问题
3. **配合 response_type**：根据响应格式选择合适的 `response_type`（如 JSON、HTML）
4. **禁用布局**：当使用非 HTML 响应类型时，配合 `{% layout none %}` 禁用布局
5. **标签顺序**：将 `response_status` 标签放在模板的最前面，与其他控制标签一起
6. **测试验证**：在浏览器开发者工具中检查响应的状态码，确保符合预期
## 总结
`response_status` 标签用于设置模板响应的 HTTP 状态码，支持 200-599 范围内的状态码。正确使用此标签可以实现适当的 HTTP 响应，如错误处理、资源创建确认、权限控制等。通常需要与 `response_type` 和 `layout` 标签配合使用，以实现完整的响应控制。