FastAPI中处理逗号分隔的列表查询参数
在FastAPI开发接口时，经常会遇到前端需要传递数组类型查询参数的场景。如果直接按照常规方式传递，可能会遇到参数解析不符合预期的问题。其中一种常见的传递方式是使用逗号分隔的字符串作为查询参数，后端再将其拆分为列表。本文将详细介绍在FastAPI中如何处理这类逗号分隔的列表查询参数。
基础场景：直接使用str类型接收后拆分
最直接的方式是在接口函数中将查询参数定义为str类型，然后在函数内部手动按照逗号拆分字符串，得到需要的列表。这种方式实现简单，适合简单的参数处理场景。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items")
async def get_items(ids: str = None):
# 如果参数不存在，返回空列表
if not ids:
return {"ids": []}
# 按照逗号拆分字符串，去除每个元素前后的空格
id_list = [item.strip() for item in ids.split(",")]
return {"ids": id_list}上述代码中，我们定义了ids参数为str类型，默认值为None。当请求路径为/items?ids=1,2,3,4时，ids参数的值为"1,2,3,4"，通过split(",")拆分后得到["1","2","3","4"]的列表。如果请求没有携带ids参数，会返回空列表。这种方式的好处是灵活性高，我们可以根据需求对拆分后的元素做进一步处理，比如类型转换。
进阶场景：使用自定义参数解析器自动转换
如果需要在多个接口中复用逗号分隔列表参数的解析逻辑，或者希望参数直接以列表形式在接口函数中接收，避免每个接口都写拆分逻辑，可以自定义参数解析器。FastAPI支持通过Query等类来自定义参数处理逻辑。
from typing import List, Optional
from fastapi import FastAPI, Query
from fastapi.exceptions import RequestValidationError
app = FastAPI()
def parse_comma_separated_list(value: Optional[str] = None) -> List[str]:
"""解析逗号分隔的字符串为列表"""
if value is None:
return []
# 拆分字符串，过滤空元素
return [item.strip() for item in value.split(",") if item.strip()]
@app.get("/users")
async def get_users(
roles: Optional[List[str]] = Query(default=None, alias="roles", description="逗号分隔的角色列表")
):
# 这里roles已经是解析后的列表，由自定义的解析逻辑处理
# 实际使用中需要结合参数解析的钩子，下面的示例是简化后的逻辑
# 更规范的实现可以通过自定义Query类或者依赖注入完成
return {"roles": roles}上面的代码定义了一个parse_comma_separated_list函数，专门用来处理逗号分隔字符串到列表的转换。不过这种方式需要结合FastAPI的参数解析机制进一步完善，比如通过依赖注入来统一处理，避免在每个接口中重复调用解析函数。
更优方案：使用依赖注入实现通用解析
利用FastAPI的依赖注入系统，我们可以将逗号分隔参数的解析逻辑封装成依赖项，所有需要该功能的接口直接注入即可，既减少重复代码，又让接口函数的参数更符合预期。
from typing import List, Optional
from fastapi import FastAPI, Depends, Query
app = FastAPI()
async def comma_separated_list_param(
param: Optional[str] = Query(default=None, description="逗号分隔的参数值")
) -> List[str]:
"""依赖项：解析逗号分隔的查询参数为列表"""
if param is None:
return []
return [item.strip() for item in param.split(",") if item.strip()]
@app.get("/products")
async def get_products(
categories: List[str] = Depends(comma_separated_list_param)
):
return {"categories": categories}
@app.get("/orders")
async def get_orders(
status: List[str] = Depends(comma_separated_list_param)
):
return {"status": status}在这个示例中，我们定义了comma_separated_list_param依赖项，它接收查询参数中的字符串，自动拆分为列表。/products和/orders两个接口都注入了这个依赖项，直接就能拿到解析后的列表，不需要在每个接口中写拆分逻辑。当请求/products?categories=电子,服饰,食品时，categories参数的值就是["电子","服饰","食品"]。
注意事项
- 拆分参数时建议过滤空元素，避免前端传递类似"1,,2,3"这样的参数时产生空字符串元素。
- 如果参数需要特定类型，比如整数列表，可以在解析后增加类型转换逻辑，同时做好异常处理，避免转换失败导致接口报错。
- 如果参数允许为空，记得设置默认值，避免请求没有携带参数时出现异常。
- 当参数需要同时支持数组形式（比如?ids=1&ids=2）和逗号分隔形式时，需要额外的判断逻辑，根据具体业务需求选择实现方式。
总结
处理FastAPI中的逗号分隔列表查询参数，有三种常用方式：手动拆分适合简单场景，自定义解析器适合需要复用的场景，依赖注入则是更优雅的通用方案。开发者可以根据项目的实际复杂度选择合适的方式，在保证功能正确的同时，让代码更易维护。