字典参数构造RESTful API查询字符串教程

时间：2026-07-03 06:50

本文详细讲解如何利用 Python 字典结构安全地将嵌套逻辑（如 eq()、ne() 等函数式查询参数）转换为符合后端要求的 URL 查询字符串，彻底规避因 requests 自动编码而引发的 500 错误。在调用部分 RESTful API 时，后端期望接收的查询参数并非传统的 key=valu

本文详细讲解如何利用 Python 字典结构安全地将嵌套逻辑（如 eq()、ne() 等函数式查询参数）转换为符合后端要求的 URL 查询字符串，彻底规避因 requests 自动编码而引发的 500 错误。

在调用部分 RESTful API 时，后端期望接收的查询参数并非传统的 key=value 格式，而是类似函数调用的语法——例如 eq(group,337)、ne(custom.field_28,R-404A)、select(id,name,...)。如果你直接将这种结构作为字典传递给 requests.get(url, params=...)，就会遇到麻烦：requests 会按照常规规则对参数进行 URL 编码，将 eq(group,337) 拆解为 eq%28group%2C337%29，但更关键的是——它根本不理解这种嵌套逻辑，也无法正确展开多值的 ne 或 select 参数，最终服务器端解析失败，直接返回 500 Internal Server Error。

问题究竟出在哪里？requests 的 params 参数仅支持扁平的键值对（字符串或列表），无法处理自定义函数语法或嵌套结构。因此，唯一可行的解决方案是：手动构造符合 API 规范的查询字符串。

✅ 正确做法：自定义查询字符串生成器

下面这个 makeQueryString() 函数，健壮且可复用，能够将结构化的字典精准地转换为目标格式：

def makeQueryString(params_dict):
    """
    将嵌套字典转换为 GET 查询字符串（支持 eq/ne/select/sort 等函数式语法）
    示例输入：
        {
            "eq": {"group": 337, "instock": 1},
            "ne": {"custom.field_28": ["R-404A", "R-407C"]},
            "select": ["id", "name", "custom.field_28"],
            "sort": "+name"
        }
    输出：eq(group,337)&eq(instock,1)&ne(custom.field_28,R-404A)&ne(custom.field_28,R-407C)&select(id,name,custom.field_28)&sort(+name)
    """
    parts = []
    for key, value in params_dict.items():
        if isinstance(value, dict):
            # 处理 eq(), ne() 等键对应字典的情况
            for subkey, subval in value.items():
                if isinstance(subval, list):
                    # 多值：ne(field,[a,b]) → ne(field,a)&ne(field,b)
                    for item in subval:
                        parts.append(f"{key}({subkey},{item})")
                else:
                    # 单值：eq(field,val) → eq(field,val)
                    parts.append(f"{key}({subkey},{subval})")
        elif isinstance(value, list):
            # 处理 select([...])、sort([...]) 等列表型参数
            items_str = ",".join(str(v) for v in value)
            parts.append(f"{key}({items_str})")
        else:
            # 基础字符串/数字：sort(+name) → sort(+name)
            parts.append(f"{key}({value})")
    return "&".join(parts)

✅ 完整可运行示例

import requests

url = "https://www.produktdatenbank-get.at/api/products"
headers = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0",
    "Accept": "application/json",
    "Accept-Encoding": "identity",
    "Accept-Language": "en-US,en;q=0.9",
    "Host": "www.produktdatenbank-get.at",
    "Referer": "https://www.produktdatenbank-get.at/",
    "X-Requested-With": "XMLHttpRequest",
}

# 结构化定义参数（语义清晰、易于维护）
params_dict = {
    "eq": {
        "group": 337,
        "instock": 1,
        "custom.field_133": 1,
    },
    "ne": {
        "custom.field_28": ["R-404A", "R-407C", "R-417A", "R-410A"],
    },
    "select": [
        "id",
        "name",
        "custom.field_22",
        "custom.field_28",
        "custom.field_133",
        "subsidable",
        "custom.field_78",
    ],
    "sort": "+name",
}

# 转换为合法查询字符串
query_string = makeQueryString(params_dict)

# 发送请求（注意：params 是字符串，非字典！）
response = requests.get(url, params=query_string, headers=headers)

print("Status Code:", response.status_code)
if response.status_code == 200:
    data = response.json()
    print(f"Received {len(data.get('data', []))} products.")
else:
    print("Error response:", response.text[:200])

⚠️ 关键注意事项

切勿将字典直接传给 params=：requests 会把 {"eq(group,337)": ""} 这类键名当作普通字段处理，完全违背 API 的预期。
URL 编码由 requests 自动完成：你生成的 query_string 必须是纯 ASCII 字符串（不含中文或特殊符号），requests 会在发送前自动进行编码，无需手动调用 urllib.parse.quote()。
字段名必须严格遵循 API 文档：例如 custom.field_28 中的下划线和点号不可更改；大小写同样敏感。
select 字段的顺序可能影响响应结构：部分 API 对 select 中字段的顺序有特定要求，建议按照文档推荐的顺序排列。
调试技巧：打印 query_string，并与浏览器开发者工具 Network 标签页中捕获的真实请求进行对比，确保完全一致。