Django-Filter与DRF中filterset_fields设置方法及差异解析

差异原因 #

1. filterset_fields=["category_id"]（单下划线）的行为逻辑 #

这里的category_id是Django为外键字段category自动生成的数据库物理字段名。当用这个字段做过滤时，FilterSet会将其视为模型的直接字段，自动触发选项合法性校验：它会先查询关联的Category表，检查传入的ID是否存在于Category的主键集合中。如果不存在，就会抛出ValidationError，返回你看到的"选择有效选项，该选项不在可选范围内"错误。

2. filterset_fields=["category__id"]（双下划线）的行为逻辑 #

这是Django ORM的跨关联模型查询语法，表示通过SubCategory的category外键，关联到Category模型的id字段做过滤。此时FilterSet不会提前做合法性校验，而是直接向数据库发起WHERE category.id = [传入ID]的查询。当传入的ID不存在时，数据库自然返回空结果集，因此接口返回空数组[]。

正确设置方式 #

两种设置都是合法的，取决于你的业务需求：

• 若需要严格校验传入的分类ID必须是已存在的有效分类，选择["category_id"]，适合要求参数合法性的场景；
• 若只需要查询“属于该分类ID的子分类，即使分类不存在也返回空结果”，选择["category__id"]，适合不需要强校验的场景。

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