FastAPI如何返回Content-Type为application/liquid的响应适配Shopify集成

核心实现逻辑 #

FastAPI默认使用JSONResponse作为响应类，默认返回application/json类型内容，你只需要自定义响应的媒体类型为application/liquid，直接返回渲染好的Liquid模板字符串即可，不需要额外安装第三方依赖。

方案1：单接口快速配置 #

适合仅单个接口需要返回Liquid内容的场景，无需额外封装，直接在接口逻辑中指定响应类型即可：

from fastapi import FastAPI
from fastapi.responses import Response

app = FastAPI()

# 你的自定义搜索接口，路径替换成你实际的接口路由
@app.get("/api/custom-search")
async def shopify_custom_search():
    # 保留你原有的搜索请求接收、结果处理逻辑
    # 最终生成符合Shopify Liquid语法的模板字符串
    liquid_rendered_content = """
    <div class="custom-search-results">
      {% for item in search_results %}
        <div class="search-item">
          <a href="{{ item.url }}">
            <img src="{{ item.featured_image }}" alt="{{ item.title }}">
            <p class="item-title">{{ item.title }}</p>
            <p class="item-price">{{ item.price | money }}</p>
          </a>
        </div>
      {% endfor %}
    </div>
    """

    # 直接返回指定媒体类型的响应
    return Response(
        content=liquid_rendered_content,
        media_type="application/liquid"
    )

方案2：封装可复用的Liquid响应类 #

如果项目中有多个接口需要返回Liquid格式内容，可以预先定义专用响应类，减少重复代码：

from fastapi import FastAPI
from fastapi.responses import Response

# 定义全局可复用的Liquid响应类
class LiquidResponse(Response):
    media_type = "application/liquid"

app = FastAPI()

# 接口装饰器直接指定响应类即可
@app.get("/api/custom-search", response_class=LiquidResponse)
async def shopify_custom_search():
    # 原有搜索处理逻辑
    liquid_rendered_content = "你的Liquid模板字符串"
    # 直接返回字符串内容，FastAPI会自动装配正确的响应头
    return liquid_rendered_content

校验&避坑要点 #

• 禁止使用默认JSON响应返回：不要将Liquid内容放到JSON结构中返回，否则会出现Content-Type不符合要求、Liquid语法被转义的问题，Shopify无法正常解析
• 响应内容校验：返回的内容必须是纯Liquid语法字符串，不要额外包裹JSON外层字段、不要做JSON序列化操作
• 响应头验证：接口部署后可以先本地调用，检查返回头中Content-Type字段值是否为application/liquid，如果Shopify对响应头校验严格不允许携带charset=utf-8后缀，可以在返回时手动指定响应头覆盖默认值：

  return Response(
      content=liquid_rendered_content,
      headers={"Content-Type": "application/liquid"}
  )
  

• 跨域配置：如果接口是给Shopify前端主题调用，记得配置FastAPI的CORS中间件，允许对应店铺的域名访问，避免浏览器拦截请求。

内容的提问来源于stack exchange，提问作者Can Jozef Saul