REST API设计指南：筛选非null属性资源的最佳实践

你当前采用的min_date=1970-01-01T00:00:00.000Z方案不符合REST设计规范，核心问题有三点：

• 语义错位：min_date的参数语义是定义时间字段的取值下限，用Unix起始时间作为特殊占位值实现非空过滤，属于典型的参数语义滥用。调用方仅看参数名完全无法感知这个特殊约定，误用概率极高；后续如果业务需要支持1970年之前的历史时间数据，或者新增真实的min_date过滤需求，现有逻辑会直接出现兼容性问题。
• 实现泄露：这个方案本质是依赖"null值在排序比较中小于所有合法时间值"的内部实现逻辑，把服务端的实现细节暴露给了调用方，违反了REST要求接口契约与内部实现解耦的核心原则，后续服务端调整排序比较逻辑就会破坏现有调用。
• 隐式约定不可维护：这种靠特殊传值触发特殊逻辑的设计没有在接口层面明确表达过滤意图，没法通过接口文档工具自动生成准确的参数说明，后续迭代维护的隐患很大。

REST本身没有强制统一的过滤语法标准，但行业内已经形成了语义优先、约定统一的通用实践，按适用场景优先级排序如下：

• 显式字段存在性判断参数（通用场景首选）
  直接设计和字段绑定的显式参数，直白表达"字段非空"的过滤意图，完全不需要依赖特殊值取巧。最通用的写法是复用字段过滤的参数命名体系，比如：

  GET /resources?date[not_null]=true
  

  如果团队偏好更直白的命名，也可以用存在性判断的语义命名：

  GET /resources?date_exists=true
  

  这种方案的优势非常明显：语义完全无歧义，调用方一眼就能理解参数作用；可以复用到所有需要非空过滤的字段，不需要为每个字段单独设计特殊逻辑；和其他范围过滤参数完全不冲突，比如需要同时过滤date非空、且晚于2024年1月1日的资源，可以直接组合传参：

  GET /resources?date[not_null]=true&min_date=2024-01-01T00:00:00Z
  

• 统一结构化过滤参数（复杂查询场景适用）
  如果你的接口需要支持多字段组合、多条件嵌套的复杂查询，可以把所有过滤逻辑收敛到统一的filter参数中，用约定的表达式语法传递规则，比如：

  GET /resources?filter=date ne null
  

  这种方案的优势是参数收敛，不会出现查询参数过多过散的问题，适合查询逻辑复杂的中后台类接口，缺点是调用方需要提前学习约定的表达式语法，接入成本稍高。

• 专属业务端点（仅高频固定需求适用）
  如果"获取date字段非空的资源"是调用频率极高、且逻辑长期固定的强业务需求，也可以单独设计专属的业务端点：

  GET /resources/with-valid-date
  

  注意这个方案不能作为通用实现，否则每新增一个字段的过滤需求就要新增对应端点，接口数量会快速膨胀，维护成本极高。

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