在 RESTful API 设计中，需明确区分 null（表示缺失/未知）与空值、布尔值或字符串，推荐使用小写 null 作为查询参数值来精确筛选数据库中的 NULL 字段。

在 restful api 设计中，需明确区分 `null`（表示缺失/未知）与空值、布尔值或字符串，推荐使用小写 `null` 作为查询参数值来精确筛选数据库中的 null 字段。

在构建支持三态逻辑（如 True / False / Unknown）的 API 时，直接将数据库中的 NULL 值映射为语义清晰的查询参数至关重要。常见误区是使用 None（Python 对象）、null（首字母大写）、undefined 或 'unknown' 字符串——这些要么被 HTTP 客户端自动忽略或标准化（如 None 在 URL 编码后常被丢弃），要么引入冗余数据建模（如将 NULL 强制存为 'unknown' 字符串），违背范式且增加维护成本。

✅ 正确做法：统一约定小写 null 作为特殊字符串标记，服务端显式识别并转换为 SQL IS NULL 条件。

例如，对字段 is_impounded 发起如下请求：

DrugBank 数据库

访问并分析来自 DrugBank 数据库的全面药物信息，包括药物属性、相互作用、靶点、通路、化学结构和药理学数据。用于药物数据、药物发现研究、药理学研究、药物-

下载

GET /cars?is_impounded=null

服务端（以 Python Flask + SQLAlchemy 为例）应这样处理：

from flask import request
from sqlalchemy import or_

@app.route('/cars')
def get_cars():
    is_impounded = request.args.get('is_impounded')

    query = Car.query
    if is_impounded == 'null':
        query = query.filter(Car.is_impounded.is_(None))  # 注意：SQLAlchemy 中用 is_(None) 表示 IS NULL
    elif is_impounded == 'true':
        query = query.filter(Car.is_impounded.is_(True))
    elif is_impounded == 'false':
        query = query.filter(Car.is_impounded.is_(False))
    # 若未提供该参数，则不加过滤（返回全部）

    return jsonify([car.to_dict() for car in query.all()])

⚠️ 注意事项：

• 不要依赖 JavaScript 或 Python 的 None/null 字面量直接拼接 URL（如 ?is_impounded=None），因为 None 在 URL 编码中可能被省略或转为 None 字符串，导致服务端无法区分；
• 避免将数据库 NULL 存为 'unknown' 等魔法字符串——这会污染数据类型、影响索引效率，并使 COUNT(*) 与 COUNT(is_impounded) 语义混淆；
• 建议在 API 文档中明确定义：is_impounded=null 表示“值为数据库 NULL”，而非 JSON null；同时提供 OpenAPI 规范示例，增强客户端可发现性；
• 若需支持多值过滤（如 ?is_impounded=null,true），可进一步扩展解析逻辑，但基础场景优先保证单值语义清晰。

综上，采用小写 null 作为保留字是最轻量、兼容性强且符合 Web 惯例的解决方案——它不侵入数据模型，不增加存储开销，同时让 API 行为可预测、易测试、易文档化。