改造Restful搜索API：列表参数与NULL值过滤的最佳实践

核心需求 #

需要为SearchCriteria新增支持ID列表的过滤器，同时解决departmentId为NULL的员工检索问题，并严格处理以下四个请求场景：

场景处理细节 #

针对四个场景，后端需按以下逻辑处理：

• 场景1：请求跳过departmentId字段
  后端解析请求体时，若该字段不存在，不添加任何departmentId相关的过滤条件，直接返回所有员工记录。
• 场景2：请求中departmentId字段为null
  当字段值为null时，视为无过滤意图，不添加过滤条件，返回全量员工数据。
• 场景3：请求中departmentId为空列表
  空列表同样代表不需要按departmentId过滤，直接返回所有员工。
• 场景4：请求中departmentId列表包含"null"字符串
  此时需拆分条件：
  1. 对列表中除"null"外的其他ID值，用departmentId IN (...)匹配；
  2. 对"null"标记，用departmentId IS NULL匹配；
  3. 最终用OR连接这两类条件，返回匹配任一条件的员工。

最佳实践 #

1. 明确参数语义并文档化 #

在API文档中清晰定义每个场景的行为：

• 跳过字段/字段为null/空列表：无departmentId过滤，返回全量；
• 列表包含"null"：匹配数据库中departmentId为NULL的记录，同时匹配列表中其他ID值。
  避免模糊语义导致调用方误解。

2. 后端参数校验与安全处理 #

• 接收请求后先做参数校验，区分不同场景；
• 处理IN条件时使用预编译SQL语句，避免SQL注入风险；
• 统一将"null"字符串映射为数据库的NULL查询逻辑，不要混用其他特殊值（如空字符串）代表NULL。

3. 统一空值处理逻辑 #

所有类似的多值ID过滤器（如userId、roleId）遵循相同的空值规则，降低维护成本，避免逻辑不一致。

4. 覆盖全场景测试 #

针对四个场景分别编写测试用例：

• 测试跳过departmentId字段的请求，验证返回所有4条记录；
• 测试departmentId为null/空列表的请求，验证返回全量；
• 测试departmentId为["null"]的请求，验证仅返回departmentId为NULL的记录；
• 测试departmentId为["1", "null"]的请求，验证返回departmentId为1和NULL的记录。

后端处理示例（伪代码） #

def build_employee_query(search_criteria):
    base_query = "SELECT * FROM Employee"
    conditions = []
    params = []

    dept_ids = search_criteria.get("departmentId")
    # 仅当字段存在且列表非空时，才构建过滤条件
    if dept_ids is not None and len(dept_ids) > 0:
        normal_ids = [id_str for id_str in dept_ids if id_str != "null"]
        include_null = "null" in dept_ids

        sub_conditions = []
        if normal_ids:
            # 预编译IN条件，避免SQL注入
            placeholders = ", ".join(["%s"] * len(normal_ids))
            sub_conditions.append(f"departmentId IN ({placeholders})")
            params.extend(normal_ids)
        if include_null:
            sub_conditions.append("departmentId IS NULL")
        
        if sub_conditions:
            conditions.append(f"({' OR '.join(sub_conditions)})")
    
    if conditions:
        base_query += " WHERE " + " AND ".join(conditions)
    
    return base_query, params

内容的提问来源于stack exchange，提问作者Roopashree