调用MS SQL存储过程时SqlAlchemy绑定参数异常问题（ODBC v17）

我正在开发一个API端点服务，从Postman请求的JSON负载中提取数据，作为参数传入后端MS SQL存储过程。执行代码如下：

query = (
  "exec dbo.usp_SaveRisk @exposure_json=:risk_request_data, @inundation_json=:inundation_data_json"
)
result_list = conn.execute_query(
  query, {"@exposure_json": risk_request_data, "@inundation_json": inundation_data_json}
)

出现错误：

sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'risk_request_data'

调试时已确认risk_request_data是格式正确的字符串，为何参数值未被捕获并绑定到存储过程？

问题核心是参数命名不匹配：

• SQL语句中使用的绑定占位符是:risk_request_data和:inundation_data_json
• 但传入的参数字典键却是@exposure_json和@inundation_json

SQLAlchemy会严格按照SQL语句里的占位符名称（冒号后的部分）匹配参数字典的键，两者必须完全一致。修改参数字典的键，与SQL中的占位符名称对应即可：

query = (
  "exec dbo.usp_SaveRisk @exposure_json=:risk_request_data, @inundation_json=:inundation_data_json"
)
result_list = conn.execute_query(
  query, {"risk_request_data": risk_request_data, "inundation_data_json": inundation_data_json}
)

额外说明：MS SQL存储过程的@是SQL端的参数标识，而SQLAlchemy的绑定占位符用:参数名格式，二者不要混淆。只需保证SQL里的:xxx与参数字典的xxx键一致，无需在字典键中添加@。

内容的提问来源于stack exchange，提问作者B. Youngman