orjson：Python 最快的 JSON 库

orjson 是一款高性能 Python JSON 库，目前获得 8,098 个 Star。

orjson 的核心优势在于速度。它的序列化速度比 Python 标准库 json 快约 10 倍，反序列化速度约 2 倍。同时，orjson 对 UTF-8 和 RFC 8259 的兼容性比标准库更严格。

在类型支持上，orjson 原生序列化 dataclass、datetime、numpy.ndarray 和 UUID 等实例，不需要自定义转换函数。对于常规类型如 str、dict、list、tuple、int、float、bool 和 None 也都直接支持。

orjson 通过 Rust 实现底层逻辑，并提供多种序列化选项控制输出格式。用户可以通过 option 参数组合多个标志位，常用的包括 OPT_NAIVE_UTC（将无时区 datetime 视为 UTC）、OPT_SERIALIZE_NUMPY（原生序列化 numpy 数组）、OPT_INDENT_2（输出格式化缩进）、OPT_SORT_KEYS（按键排序）、OPT_NON_STR_KEYS（允许非字符串字典键）等。

序列化失败时，orjson 抛出 JSONEncodeError，提示不可序列化的具体类型。该异常继承自 TypeError，与标准库行为保持一致。循环引用、超深递归（超过 254 层）、无效 UTF-8 字符串、以及不支持的 tzinfo 时区信息都会触发此异常。

安装 orjson 直接通过 pip 即可：

pip install orjson

在 requirements.txt 中建议指定版本范围：

orjson >= 3.10,<4

基本用法与标准库 json 类似：

import orjson, datetime

data = {
    "type": "job",
    "created_at": datetime.datetime(1970, 1, 1),
}

# 序列化
result = orjson.dumps(data, option=orjson.OPT_NAIVE_UTC)
# 反序列化
parsed = orjson.loads(result)

orjson.dumps 返回 bytes 对象而非 str，这是与标准库 json 的主要差异。需要字符串时可自行解码。

对于自定义类型，orjson 提供 default 参数。该参数接收一个可调用对象，返回 orjson 支持的类型即可：

import orjson, decimal

def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

orjson.dumps(decimal.Decimal("0.084"), default=default)

orjson 支持 CPython 3.10 到 3.15，提供多平台预编译 wheel。Linux 支持 amd64、i686、aarch64、arm7、ppc64le 和 s390x 架构；macOS 支持 amd64 和 aarch64；Windows 支持 amd64、i686 和 aarch64。amd64 wheel 在 x86-64-v1 及以上平台运行，并在支持 AVX-512 的硬件上获得额外性能提升。

从标准库 json 迁移到 orjson 时需要注意几个差异点。orjson.dumps 返回 bytes 对象而非 str，若需要字符串需手动解码。标准库的 sort_keys 参数在 orjson 中替换为 OPT_SORT_KEYS，indent 替换为 OPT_INDENT_2，且 orjson 仅支持 2 空格缩进。ensure_ascii 在 orjson 中不存在，UTF-8 字符不会被转义为 ASCII。

orjson 不兼容 PyPy、Android 和 iOS 嵌入式 Python 构建。该项目遵循语义化版本发布，代码采用 MPL 2.0、Apache 2.0 和 MIT 多许可证分发。

嵌入式 Python 构建。该项目遵循语义化版本发布，代码采用 MPL 2.0、Apache 2.0 和 MIT 多许可证分发。