Django REST ModelViewSet 带查询参数返回404 无参数正常响应

核心触发逻辑 #

Django的URL路由匹配仅识别路径部分，完全不解析查询串（即URL中?后面的内容），因此404异常并非路由匹配规则失效导致。结合复现场景（无参数访问正常、任意参数触发404），绝大多数场景下问题出在自定义过滤后端的实现逻辑：
DRF的过滤链执行规则是：只要配置在filter_backends列表中的类，无论请求是否携带该后端对应的专属参数，都会按顺序执行其filter_queryset方法。你当前配置的过滤链中包含自定义实现的DistanceFilterBackend，这类自定义距离过滤的常见实现逻辑为：

检查请求中是否存在任意查询参数，如果存在，就判定用户要使用距离筛选能力，要求请求必须携带经纬度参数；如果经纬度参数缺失，就直接抛出Http404异常表示资源不存在。
这种逻辑完全匹配当前的复现现象：不带任何查询参数时，后端的参数检查分支不触发，过滤逻辑正常通过；只要传入任意一个查询参数（哪怕是和距离筛选无关的search=a），就会触发该分支的参数校验，因为缺失经纬度参数抛出404。
剩余小概率原因是路由空注册带来的匹配冲突：你将ViewSet注册到r''空路径下，配合DefaultRouter的默认尾随斜杠规则生成的路由存在边缘匹配问题，容易被全局中间件误判为无效路径返回404。

分步排查流程 #

• 定位自定义过滤后端问题
  临时将filter_backends配置调整为[SearchFilter, DjangoFilterBackend]，移除DistanceFilterBackend后重新发起带查询参数的请求：
  • 如果此时接口可以正常返回200结果，说明异常完全来自DistanceFilterBackend的实现逻辑，打开该类的filter_queryset方法源码，找到类似if request.query_params: ... raise Http404()的分支逻辑。
  • 如果调整过滤后端后依然返回404，进入下一步排查。
• 修复路由空注册问题
  将当前空路径注册的代码router.register(r'', BusinessViewSet, basename="business")修改为带固定前缀的注册规则，比如router.register(r'businesses', BusinessViewSet, basename="business")，确认根路由挂载路径为/api/，保证列表接口的完整路径为/api/businesses/，规避空路径注册带来的斜杠匹配冲突。
• 栈追踪定位异常抛出点
  开启Django调试模式后复现请求，查看报错日志的栈追踪信息，明确404的抛出位置：如果是路由层抛出的，调整反向代理或中间件的路径识别规则；如果是业务代码内部抛出的，直接修改对应异常的类型即可。

对应修复方案 #

• 修改自定义DistanceFilterBackend的校验逻辑：只有当请求实际携带经纬度专属参数时，才启动参数校验流程，不要把“请求存在任意查询参数”作为启动距离筛选的判定条件。同时将原本抛出的Http404替换为DRF内置的ValidationError，让参数类错误返回400状态码，和路由不存在的404状态做明确区分。
• 所有ViewSet路由注册时必须配置明确的路径前缀，禁止直接注册到空路径下，减少DefaultRouter生成规则的边缘匹配问题。
• 统一全链路的尾随斜杠处理规则，保证路由配置、反向代理、中间件的斜杠识别逻辑一致，避免路径识别偏差。

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