fastapi 如何让单个 endpoint 支持多种响应格式（json/csv）

FastAPI可通过Accept头内容协商实现JSON/CSV多格式响应：匹配"json"或"csv"子串，JSON直接返回Pydantic模型或dict，CSV则用StreamingResponse配合StringIO生成流式响应并设置对应Content-Type及Content-Disposition头。

FastAPI 本身不直接内置多格式响应（如 JSON/CSV）的自动切换，但可以通过 内容协商（Content Negotiation） —— 即解析请求头中的 Accept 字段，结合手动构造不同响应体来实现。核心思路是：同一个 endpoint 根据客户端期望的格式，返回对应结构的数据（JSON 或 CSV 流），同时设置正确的 Content-Type 和 Content-Disposition（尤其对 CSV 下载有用）。

1. 基于 Accept 头判断格式

读取 request.headers.get("accept")，粗略匹配 application/json 或 text/csv（或通配符 */*）。注意：浏览器通常发 Accept: text/html,application/xhtml+xml...，所以别只依赖精确匹配，可做子串判断或用标准库 email.message.Message 解析更严谨（但多数场景简单判断够用）。

• 推荐写法：检查 "

  

  json" in accept.lower() 或 "csv" in accept.lower()
• 若未明确指定，可设默认格式（如 JSON），或按业务定优先级

2. 返回 JSON：直接用 Pydantic 模型或 dict

这是 FastAPI 默认行为。只要函数返回一个可序列化的对象（dict、Pydantic model、list），且未显式设置响应类型，FastAPI 自动转为 JSON 并设 Content-Type: application/json。

• 无需额外操作，保持原样返回即可
• 若需自定义 JSON 响应结构（如加 {"data": ...} 包裹），直接 return 字典

3. 返回 CSV：用 StreamingResponse + StringIO

CSV 不适合用普通 JSON 响应，要用 StreamingResponse 流式输出，并设置正确头部：

• 导入：from fastapi import Response 和 from starlette.responses import StreamingResponse
• 用 io.StringIO 构建 CSV 内容，再用 StringIO.getvalue().encode("utf-8") 转 bytes
• 响应 headers 至少包含：{"Content-Type": "text/csv; charset=utf-8"}；若希望浏览器下载，加 "Content-Disposition": 'attachment; filename="data.csv"'
• 示例片段：

import io
import csv
from starlette.responses import StreamingResponse

def generate_csv(data: list[dict]):
    output = io.StringIO()
    if data:
        writer = csv.DictWriter(output, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)
    output.seek(0)
    return StreamingResponse(
        iter([output.getvalue().encode("utf-8")]),
        media_type="text/csv; charset=utf-8",
        headers={"Content-Disposition": 'attachment; filename="report.csv"'}
    )

4. 完整 endpoint 示例

把以上逻辑组合进一个路由：

• 接收 query 参数（如 format=json）或仅靠 Accept 头均可；建议两者都支持，更灵活
• 数据源统一获取（比如从 DB 或 mock），再分支处理格式
• 注意：CSV 不支持嵌套结构，需扁平化字段（如把 {"user": {"name": "a"}} 展开为 {"user_name": "a"}）