urlencode 是 Python 标准库 urllib.parse 模块中的一个核心函数，它的主要作用是将一个 Python 字典或由元组组成的序列转换成 URL 查询字符串（Query String）。

什么是 URL 编码？

URL 编码（也称为百分比编码）是一种将 URL 中不允许的字符转换为 加上两位十六进制数格式的机制，URL 只能使用 ASCII 字符集中的特定子集。

空格字符在 URL 中是不允许直接出现的，所以它通常被编码为 %20 或 （在查询字符串的键值对中），中文字符、特殊符号等也需要进行编码，以确保 URL 的有效性和可靠性。

urlencode 的基本用法

urlencode 函数最常见的用法是处理字典。

编码 Python 字典

当你有一个包含键值对的字典,并想将其转换为查询字符串时，urlencode 非常方便。

语法： urllib.parseurlencode(query, doseq=False, safe='', encoding='utf-8', errors='replace')

参数说明：

• query: 要编码的数据，通常是字典或由 (key, value) 元组组成的序列。
• doseq: 这是一个非常重要的参数。
  • 如果为 False（默认值），值可以是单个字符串。
  • 如果为 True，值可以是序列（如列表、元组），序列中的每个元素都会被单独编码，并为同一个键生成多个 key=value 对。
• safe: 指定不应该被编码的额外字符，默认是 。
• encoding: 指定字符串的编码格式，默认是 'utf-8'。
• errors: 指定如何处理编码错误，默认是 'replace'。

示例：

from urllib.parse import urlencode
# 1. 基本字典编码
params = {'name': '张三', 'age': '30', 'city': '北京'}
query_string = urlencode(params)
print(f"基本编码: {query_string}")
# 输出: 基本编码: name=%E5%BC%A0%E4%B8%89&age=30&city=%E5%8C%97%E4%BA%AC
# 解释: '张三' 和 '北京' 被编码成了 %E5%BC%A0%E4%B8%89 和 %E5%8C%97%E4%BA%AC
# 2. 使用 doseq=True 处理多值参数
# 比如一个用户选择了多个爱好
params_with_list = {'name': '李四', 'hobbies': ['reading', 'music', 'sports']}
query_string_doseq = urlencode(params_with_list, doseq=True)
print(f"\n使用 doseq=True: {query_string_doseq}")
# 输出: 使用 doseq=True: name=%E6%9D%8E%E5%9B%BD&hobbies=reading&hobbies=music&hobbies=sports
# 解释: 'hobbies' 列表中的每个值都生成了一个独立的键值对
# doseq=False (默认), 结果会是这样的
query_string_no_doseq = urlencode(params_with_list, doseq=False)
print(f"\n使用 doseq=False (默认): {query_string_no_doseq}")
# 输出: 使用 doseq=False (默认): name=%E6%9D%8E%E5%9B%BD&hobbies=%5B%27reading%27%2C+%27music%27%2C+%27sports%27%5D
# 解释: 整个列表被转换成了字符串形式，这通常不是我们想要的结果

urlencode 与 quote 的区别

初学者经常会混淆 urlencode 和 quote，它们是解决不同问题的工具。

简单总结：

• 当你只想让一个字符串（比如一个搜索词）在 URL 中安全时，用 quote 或 quote_plus。
• 当你有多个键值对需要拼接到 URL 的查询部分时，用 urlencode。

完整构建带查询参数的 URL

在实际应用中,我们通常会将 urlencode 与另一个函数 urlunparse 或 urljoin 结合使用，来构建一个完整的、合法的 URL。

urlunparse 用于将一个 URL 的各个部分（协议、域名、路径、参数、查询、片段）重新组合成一个完整的 URL。

示例：

from urllib.parse import urlencode, urlunparse, urlparse
# 目标基础 URL
base_url = "https://www.example.com/search"
# 要编码的参数
params = {
    'q': 'Python 教程',
    'page': '1',
    'sort': 'relevance'
}
# 1. 使用 urlencode 生成查询字符串
query_string = urlencode(params)
print(f"生成的查询字符串: {query_string}")
# 输出: 生成的查询字符串: q=Python+%E6%95%99%E7%A8%8B&page=1&sort=relevance
# 2. 使用 urlunparse 构建完整的 URL
# urlunparse 需要一个包含 6 个元素的元组: (scheme, netloc, path, params, query, fragment)
# 注意：'params' 和 'query' 是不同的，'params' 用于路径后的分号参数，较少使用。
parsed_url = urlparse(base_url)
full_url = urlunparse((
    parsed_url.scheme,  # 'https'
    parsed_url.netloc,  # 'www.example.com'
    parsed_url.path,    # '/search'
    '',                 # params (我们这里不用)
    query_string,       # 刚才生成的查询字符串
    ''                  # fragment (锚点，我们这里不用)
))
print(f"\n完整的 URL: {full_url}")
# 输出: 完整的 URL: https://www.example.com/search?q=Python+%E6%95%99%E7%A8%8B&page=1&sort=relevance

Python 3.x vs. Python 2.x

如果你在维护旧的 Python 2 代码，可能会看到 from urllib import urlencode，在 Python 3 中，为了更好地组织代码，所有与 URL 解析相关的函数都被移到了 urllib.parse 子模块中。

Python 2 (已不推荐使用):

# Python 2
from urllib import urlencode
params = {'name': '张三'}
print urlencode(params)

Python 3 (推荐):

# Python 3
from urllib.parse import urlencode
params = {'name': '张三'}
print(urlencode(params))

• urlencode 是将 Python 字典或元组列表转换为 URL 查询字符串（key=value&...）的标准方法。
• 它能自动处理字符编码（默认为 UTF-8），将非 ASCII 字符（如中文）和特殊字符（如 &, , ）转换为 编码格式。
• 使用 doseq=True 可以正确处理值为列表的参数，生成多个同名的键值对。
• 它与 quote 的区别在于：quote 用于单个字符串，urlencode 用于键值对集合。
• 在构建完整 URL 时，通常将 urlencode 的结果与 urlunparse 结合使用。