Django(PostgreSQL)存储40位hashlib hexdigest的最优字段类型是什么

核心结论 #

针对Python hashlib生成的固定40字符十六进制摘要（典型为SHA1算法输出）、需要建立索引、兼顾存储效率与查询性能的场景，最优选择是自定义封装的BinaryField存储原始二进制哈希值；如果业务要求字段值直接可读、不想引入额外编解码逻辑，现有带长度约束的CharField是文本存储方案里的最优选择，不需要额外替换。

方案对比说明 #

• 现有CharField(max_length=40)方案
  PostgreSQL中varchar(40)类型存储40位十六进制字符串时，每个字符占1字节，单字段值占40字节（不含元数据），对应索引条目也为40字节级别，功能完全可用。注意不要为了“固定长度”换成PostgreSQL的char(40)类型，该类型会自动在值末尾补空格到指定长度，读写时需要额外处理截断，反而带来不必要的性能开销；也不要换成无长度约束的TextField，不会带来任何性能提升，还会丢失固定长度的校验能力。
• 最优BinaryField方案
  40位十六进制字符串解码后为固定20字节的原始二进制值，用BinaryField存储仅占20字节，比文本存储节省50%的存储空间，对应B树索引的体积也会缩小近一半。由于哈希值本身是随机分布的，更短的索引键可以降低B树索引的层级，大幅提升等值查询、索引扫描的性能，数据量越大优势越明显。
• 避坑提醒
  不要使用UUIDField，该字段对应PostgreSQL的uuid类型，仅支持16字节（对应32位十六进制）的值，无法容纳20字节长度的40位哈希摘要。

最优方案实现代码 #

可以通过自定义字段把十六进制和二进制的编解码逻辑封装在字段层，业务层和原来使用CharField一样直接传入、读取十六进制字符串即可，完全感知不到底层的二进制转换：

from django.db import models


class Fixed40HexHashField(models.BinaryField):
    """适配40位十六进制哈希摘要的高性能存储字段，自动处理编解码"""
    description = "40-char hex digest stored as 20-byte raw binary"

    def from_db_value(self, value, expression, connection):
        # 数据库读取时把二进制转为十六进制字符串返回
        if value is None:
            return value
        return value.hex()

    def get_prep_value(self, value):
        # 写入数据库时把输入的十六进制字符串转为二进制，做格式校验
        if value is None:
            return value
        if isinstance(value, bytes):
            if len(value) != 20:
                raise ValueError("Raw hash binary must be exactly 20 bytes long")
            return value
        if isinstance(value, str):
            processed_val = value.strip().lower()
            if len(processed_val) != 40:
                raise ValueError("Hex digest must be exactly 40 characters long")
            try:
                return bytes.fromhex(processed_val)
            except ValueError:
                raise ValueError("Invalid hex character in provided digest")
        raise TypeError("Hash value must be either 40-char hex string or 20-byte binary")


class MyModel(models.Model):
    # 其余业务字段...
    my_field = Fixed40HexHashField(null=True, db_index=True)
    # 直接通过db_index=True创建索引即可，不需要额外在Meta中重复定义

如果不想自定义字段，也可以直接使用原生BinaryField，只需要在写入时手动调用bytes.fromhex(hexdigest_str)转成二进制存入，读取时调用bin_value.hex()转回十六进制字符串即可，性能和自定义字段完全一致。

如果业务数据量在百万级以下，现有CharField方案的性能差异几乎感知不到，可以根据团队的开发习惯选择是否升级到二进制存储方案；如果数据量达到千万级以上，二进制存储的索引体积、查询性能优势会非常明显。

内容的提问来源于stack exchange，提问作者vestronge