在 RESTful API 设计中，需明确区分 null（数据库空值）与字符串 "None" 或未传参场景；推荐使用小写 null 作为查询参数值，并在后端解析时将其映射为 SQL 的 IS NULL 条件，从而精准获取未知状态的数据行。
在 restful api 设计中，需明确区分 `null`（数据库空值）与字符串 `"none"` 或未传参场景；推荐使用小写 `null` 作为查询参数值，并在后端解析时将其映射为 sql 的 `is null` 条件，从而精准获取未知状态的数据行。
在实际开发中，当数据库某字段（如 is_impounded）存在三态语义——True（已扣押）、False（未扣押）、NULL（状态未知）——前端需提供一种无歧义的方式请求“未知”数据。直接使用 /cars?is_impounded=None 是无效的：一方面，None 是 Python 特有对象，在 HTTP 请求中会被编码为字符串 "None"，无法被后端自动识别为 SQL NULL；另一方面，多数 Web 框架（如 Flask、FastAPI、Django REST Framework）默认将空或未识别参数视为忽略条件，导致全量返回。
✅ 正确做法是约定一个语义清晰、格式规范的字符串标识符 —— 小写的 null：
GET /cars?is_impounded=null
该请求应被后端明确识别为「查询 is_impounded IS NULL」，而非等同于未传参。以下是一个 FastAPI 示例实现：
from fastapi import Query, Depends
from sqlalchemy import select, or_
from sqlalchemy.orm import Session
@app.get("/cars")
def list_cars(
is_impounded: str | None = Query(None),
db: Session = Depends(get_db)
):
stmt = select(Car)
if is_impounded == "null":
stmt = stmt.where(Car.is_impounded.is_(None))
elif is_impounded == "true":
stmt = stmt.where(Car.is_impounded.is_(True))
elif is_impounded == "false":
stmt = stmt.where(Car.is_impounded.is_(False))
# 若未提供 is_impounded 参数，则不加过滤条件
return db.execute(stmt).scalars().all()⚠️ 注意事项：
-
大小写敏感：统一使用
null（全小写），避免Null、NULL或None，防止解析歧义； -
参数优先级：确保
null的判断逻辑早于布尔值转换，避免被误转为bool("null") → True； -
文档同步：在 OpenAPI 文档（如 Swagger UI）中显式说明
is_impounded支持值为"true"、"false"或"null"； -
安全性：切勿拼接原始参数构造 SQL，始终使用 ORM 参数化查询或
is_()等安全方法。
这种设计兼顾语义准确性与协议兼容性，无需修改数据库结构（如改用字符串枚举），也避免了客户端对 'unknown' 这类非标准值的理解成本，是处理三值逻辑（True/False/Unknown）在 REST API 中的推荐实践。
