Rails 7中Turbo Stream未按标准执行，被迫转为HTML的问题

环境 #

• Rails 7
• turbo-rails 1.4

表单代码与渲染结果 #

模板代码 #

<%= form_with url: search_loop_results_individuals_path do |form| %>
   <%= form.text_field 'q', style: 'display: inline-block; width: 75%' %>
   <%= form.submit t('search') %>
 <% end %>

<div id="search_results">

</div>

渲染后的HTML #

<form action="/individuals/search_loop_results?locale=en" accept-charset="UTF-8" method="post"><input type="hidden" name="authenticity_token" value="blurb" autocomplete="off" />
        <input style="display: inline-block; width: 75%" type="text" name="q" id="q" />
        <input type="submit" name="commit" value="search" data-disable-with="search" />
</form>
<div id="search_results">

</div>

请求日志 #

Started POST "/individuals/search_loop_results?locale=en" for 127.0.0.1 at 2023-09-15 11:55:32 +0200
Processing by IndividualsController#search_loop_results as TURBO_STREAM

控制器代码 #

def search_loop_results
  @individuals = Individual.where("name_last ILIKE ?", "%" + params[:q] + "%").or(Individual.where("name_first ILIKE ?", "%" + params[:q] + "%")).page params[:page]
end

异常现象 #

1. 当模板命名为search_loop_results.turbo_stream.erb时，Rails报错：

   ActionController::UnknownFormat (IndividualsController#search_loop_results is missing a template for this request format and variant.
   

2. 当模板命名为search_loop_results.html.erb时，请求流程完成但不符合预期：
   • 日志显示渲染了完整HTML布局：

     Rendering individuals/search_loop_results.html.erb within layouts/application
     Individual Count (1.1ms)  SELECT COUNT(*) FROM "individuals" WHERE (name_last ILIKE '%ludi%' OR name_first ILIKE '%ludi%')
     ↳ app/views/individuals/_index_for_assignment.html.erb:5
     

   • 浏览器控制台报错：

     XHR  POST http://localhost:3000/individuals/search_loop_results?locale=en
     [HTTP/1.1 200 OK 129ms]
     
     Error: Form responses must redirect to another location
     

尝试过的操作 #

在控制器中直接指定Turbo Stream渲染：

# respond_to do |format|
#   format.turbo_stream do
     render turbo_stream: turbo_stream.replace('search_results', partial: 'individuals/index_for_assignment', class: 'fade-in-div') 
#   end
# end

• 注释respond_to块是因为提示重复响应
• 仅保留render语句时，返回了正确响应，但DOM元素未被替换，浏览器仍提示需重定向

原因分析 #

1. POST请求的Turbo限制：Turbo默认要求POST表单（对应创建/更新/删除等状态变更操作）的响应必须是重定向，而非直接返回HTML或Turbo Stream，这是浏览器报错的核心原因。
2. 模板匹配问题：若控制器未显式声明支持TURBO_STREAM格式，Rails无法正确匹配对应的模板文件，导致UnknownFormat错误。
3. 请求方法不匹配场景：搜索属于纯查询操作，本质应使用GET请求；Turbo Stream的设计初衷偏向处理有状态变更的POST请求，GET请求结合Turbo Frame才符合框架预期。

解决方法 #

方案1：改用GET请求 + Turbo Frame（推荐） #

完全符合Rails/Turbo设计理念：

1. 修改表单为GET方法并绑定Turbo Frame：

   <%= form_with url: search_loop_results_individuals_path, method: :get, data: { turbo_frame: "search_results" } do |form| %>
     <%= form.text_field 'q', style: 'display: inline-block; width: 75%' %>
     <%= form.submit t('search') %>
   <% end %>
   
   <%= turbo_frame_tag "search_results" do %>
     <!-- 搜索结果将在此处更新 -->
   <% end %>
   

2. 确保search_loop_results.html.erb仅渲染结果内容（不含完整布局）：

   <!-- app/views/individuals/search_loop_results.html.erb -->
   <%= render 'index_for_assignment', individuals: @individuals %>
   

方案2：强制POST请求返回Turbo Stream（不推荐，不符合REST规范） #

若必须使用POST，需明确声明响应格式：

1. 控制器中处理Turbo Stream格式：

   def search_loop_results
     @individuals = Individual.where("name_last ILIKE ?", "%#{params[:q]}%").or(Individual.where("name_first ILIKE ?", "%#{params[:q]}%")).page params[:page]
     respond_to do |format|
       format.turbo_stream
       format.html { redirect_to individuals_path, notice: "搜索完成" } # 提供HTML降级方案
     end
   end
   

2. 创建search_loop_results.turbo_stream.erb模板：

   <%= turbo_stream.replace "search_results", partial: "individuals/index_for_assignment", locals: { individuals: @individuals } %>
   

3. 表单中添加data-turbo-stream="true"确保请求格式正确：

   <%= form_with url: search_loop_results_individuals_path, data: { turbo_stream: true } do |form| %>
     <!-- 表单内容不变 -->
   <% end %>
   

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