在Django项目开发中，当ORM提供的查询接口无法满足复杂业务需求时，开发者通常会使用Raw Queryset执行原生SQL语句。但在参数绑定环节，一个常见的误区是误用Python内置的id函数，导致参数传递异常，最终引发查询错误。
Raw Queryset参数绑定的基本用法
Django的Raw Queryset支持两种参数绑定方式，分别是位置参数和命名参数，这两种方式都能有效避免SQL注入问题，同时保证参数传递的正确性。
位置参数绑定
使用位置参数时，需要将参数放在一个元组中传递给raw方法的params参数，SQL语句中用%s作为占位符。
from myapp.models import User
# 正确用法：使用位置参数传递查询条件
users = User.objects.raw(
"SELECT * FROM myapp_user WHERE age > %s AND status = %s",
params=(18, 1)
)
for user in users:
print(user.username)
命名参数绑定
命名参数则使用%(key)s作为占位符，参数以字典形式传递，可读性更强。
from myapp.models import Order
# 正确用法：使用命名参数传递查询条件
orders = Order.objects.raw(
"SELECT * FROM myapp_order WHERE user_id = %(user_id)s AND total_price > %(min_price)s",
params={"user_id": 5, "min_price": 100.0}
)
for order in orders:
print(order.order_no)
id内置函数引发的参数绑定陷阱
Python内置的id函数用于返回对象的唯一标识，很多开发者在编写代码时，会不小心将变量名命名为id，或者误将id作为字段名直接用在参数绑定的占位符中，从而引发错误。
常见错误场景一：变量名覆盖id内置函数
如果将查询参数变量命名为id，会覆盖Python内置的id函数，导致后续如果误用id函数时得到错误结果，同时也会让参数传递的逻辑变得混乱。
from myapp.models import Article
# 错误用法：变量名使用id，覆盖内置函数
id = 10 # 这里id已经不是内置函数，而是整数变量
# 如果后续需要调用内置id函数获取对象标识，就会得到错误结果
obj_id = id # 实际得到的是10，而不是对象的唯一标识
# 错误的参数绑定写法，容易混淆
articles = Article.objects.raw(
"SELECT * FROM myapp_article WHERE category_id = %s",
params=(id,) # 这里虽然能查到结果，但变量名不规范，容易引发后续问题
)
常见错误场景二：占位符误用id作为键名
在使用命名参数时，如果占位符的键名使用id，同时又将内置id函数传入参数，会导致参数值不符合预期。
from myapp.models import Comment
# 错误用法：命名参数键名用id，传入内置id函数
user_obj = User.objects.get(pk=3)
# 误将内置id函数作为值传入，实际传递的是id函数的内存地址标识，不是用户ID
comments = Comment.objects.raw(
"SELECT * FROM myapp_comment WHERE user_id = %(id)s",
params={"id": id(user_obj)} # 这里得到的是对象的内存标识，不是user_obj.id
)
# 上述查询会返回错误结果，因为参数值不是预期的用户ID
正确的解决方案
要避免这些陷阱，需要遵循以下规范：
- 不要使用
id作为变量名，尤其是存储数据库记录ID的变量，建议使用obj_id、user_id、article_id这类有明确含义的名称。 - 在使用命名参数时，占位符的键名要和传递的字典键名完全一致，且不要使用
id作为键名，避免和内置函数混淆。 - 如果需要获取数据库记录的ID，直接使用对象的
id属性，不要调用内置id函数。
修正后的示例代码
from myapp.models import User, Comment
# 正确用法：变量名使用明确的user_id
user_id = 3
user_obj = User.objects.get(pk=user_id)
# 位置参数绑定，使用明确的变量名
comments = Comment.objects.raw(
"SELECT * FROM myapp_comment WHERE user_id = %s",
params=(user_id,)
)
# 命名参数绑定，键名使用user_id，和变量名对应
comments = Comment.objects.raw(
"SELECT * FROM myapp_comment WHERE user_id = %(user_id)s",
params={"user_id": user_obj.id} # 直接使用对象的id属性，不调用内置id函数
)
for comment in comments:
print(comment.content)
错误排查技巧
如果遇到Raw Queryset参数绑定错误，可以按照以下步骤排查：
- 先打印
params参数的值，确认传递的参数内容是否符合预期，是否误传了内置id函数的返回值。 - 检查SQL语句中的占位符和
params的参数类型是否匹配，位置参数的数量是否和%s的数量一致，命名参数的键名是否完全对应。 - 查看Django抛出的错误信息，确认是参数数量不匹配、类型错误还是SQL语法错误，针对性调整代码。
注意：Raw Queryset执行的是原生SQL，需要确保SQL语句的语法符合当前使用的数据库规范，不同数据库的占位符和语法可能存在差异。
通过规范变量命名和参数传递方式，就能有效避免Django Raw Queryset参数绑定中的id内置函数陷阱，减少不必要的调试时间。
DjangoRaw_Queryset参数绑定id内置函数修改时间：2026-06-13 06:15:36