PyJWT：Python 项目的 JWT 处理库

jpadilla 维护的 PyJWT 在 GitHub 上收获了 5,670 个 Star，是 Python 生态中处理 JSON Web Token 的代表性工具：

PyJWT 按照 RFC 7519 标准实现，提供了在 Python 中生成和验证 JWT 的基础能力。这个项目由 jpadilla 维护，最初的原型由 progrium 编写。接口设计简单，开发者用少量代码就能完成 token 的签发与解析。

JWT 是一种开放标准，用于在各方之间安全地传输信息。token 由头部、载荷和签名三部分组成，各部分用点号分隔，形成形如 xxxxx.yyyyy.zzzzz 的字符串。头部声明 token 类型和签名算法，载荷存放实际数据，签名用于验证 token 未被篡改。PyJWT 负责把 Python 字典编码成符合标准的 token 字符串，也能反向解析和验证签名。

这个库在 Web 开发中应用广泛。服务端签发 token 后返回给客户端，客户端在后续请求中携带 token，服务端通过解析 token 确认用户身份。这种方式避免了服务端维护会话状态，适合分布式系统和微服务架构。

安装

PyJWT 通过 PyPI 分发，支持 Python 3.8 及以上版本。安装命令如下：

$ pip install PyJWT

安装完成后，在 Python 脚本中导入 jwt 模块即可开始使用。如果需要特定版本的 Python 支持，建议查看文档中的兼容性说明。

编码与解码

生成 token 使用 jwt.encode 方法：

>>> import jwt
>>> encoded = jwt.encode({"some": "payload"}, "secret", algorithm="HS256")
>>> print(encoded)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzb21lIjoicGF5bG9hZCJ9.4twFt5NiznN84AWoo1d7KO1T_yoc0Z6XOpOVswacPZg

这个方法接收三个参数。第一个是 payload 字典，存放需要传输的数据。第二个是密钥，用于生成签名。第三个是算法名称，示例中使用 HS256，即 HMAC 配合 SHA256。密钥和算法的选择取决于具体的安全需求。

解析 token 使用 jwt.decode：

>>> jwt.decode(encoded, "secret", algorithms=["HS256"])
{'some': 'payload'}

解码时需要传入 token 字符串、验证密钥和允许的算法列表。algorithms 参数是必填项，开发者需要明确指定可接受的签名算法。这项设计是为了防范算法混淆攻击，攻击者可能通过篡改头部中的算法声明来绕过验证。

文档与测试

PyJWT 的完整文档托管在 Read the Docs，内容涵盖支持的算法列表、密钥格式说明和各类验证选项的详细配置。文档中还包含了处理非对称加密算法的示例，这类算法使用公钥和私钥对进行签名和验证，适合需要分离签名和验证角色的场景。

项目测试基于 tox 构建。克隆仓库后在项目根目录执行：

$ tox

即可运行完整测试套件，覆盖多种 Python 版本和算法组合。测试套件的覆盖面较广，有助于保证核心编码解码逻辑在不同环境下的稳定性。

PyJWT 的代码量不大，核心功能集中在 token 的编码和解码上。对于需要在 Python 项目中集成 JWT 认证的开发者来说，这个库提供了一个轻量且直接的方案。几行代码就能实现 token 的签发和验证，学习成本较低。无论是小型项目还是大型应用，PyJWT 都能满足基础的 JWT 处理需求。

现 token 的签发和验证，学习成本较低。无论是小型项目还是大型应用，PyJWT 都能满足基础的 JWT 处理需求。