如何正确使用SQLAlchemy的`one_or_none`查询方法？

嘿，我刚好踩过这个坑，来给你捋明白！

你之所以会报错，核心原因是：one_or_none()本身并不接受关键字参数——它的作用是对已经构建好过滤条件的Query对象执行查询，返回匹配的单条记录（如果有多条匹配会抛出异常）或者None。而filter_by()才是用来添加过滤条件的方法，你需要先调用它缩小查询范围，再链式调用one_or_none()。

正确用法示例 #

# 先通过filter_by传入关键字参数构建过滤条件，再调用one_or_none
user = db.session.query(User).filter_by(id=123, username="proton").one_or_none()

错误用法（就是你现在遇到的问题） #

# 直接给one_or_none传kwargs会触发参数错误
user = db.session.query(User).one_or_none(id=123)  # ❌ 这里会报错！

额外补充：复杂过滤条件的写法 #

要是你的查询条件不是简单的键值对，也可以用filter()配合表达式，再调用one_or_none()：

from sqlalchemy import or_
# 示例：查询id为123或者用户名包含"pro"的用户
user = db.session.query(User).filter(or_(User.id == 123, User.username.like("%pro%"))).one_or_none()

至于官方文档里没明确写参数的问题，其实one_or_none()属于Query对象的「执行类方法」，它的核心逻辑是基于前面已经构建好的Query去执行，所以文档重点说明的是它的返回行为（单条/None/多则抛异常），而不是参数——毕竟过滤参数都在前面的filter_by()或filter()里传递啦。

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