数据 · XB 现场笔记

Redis hash 用一个键装多个字段

Thu, 24 Feb 2028 00:00:00 +0000

Redis hash 是一个键下面可按字段访问的记录，不是自动校验模式的对象，也不是天然支持嵌套路径的文档。当调用方只需要部分属性、又不想替换整条记录时，它很有用。但是否划算取决于访问模式、字段大小和返回值语义，而不是只要选择 hash 类型，就自动得到廉价读写或完整业务一致性。

只读取调用方真正需要的字段

HGET 获取一个字段，HMGET 按请求顺序获取选定字段，HGETALL 则返回整个映射。在 redis-py 的二进制响应模式下，缺失字段表示为 None，存在但为空的值表示为空字节串。直接判断真假会把这两种情况错误地合并；对不存在的键执行 HMGET，同样得到对应位置的缺失值，并不会自动创建 hash。

字段名和字段值本质上都是字节。名字中含点号仍是字面名称，Redis 不会把 name.first 解释为进入嵌套对象再找 first。同样，包含 JSON 文本的字符串键还是字符串，HGET 不会替你解析 JSON。序列化和内容校验属于应用职责，“没有提供属性”和“明确写入空值”也应保留区别。

更新操作有精确的返回语义

HSET 只修改指定字段，未指定的字段保持不变。一次多字段 HSET 是一个命令，但其整数回复统计新增字段数量，而不是成功修改的总数。替换已有 name 完全可能成功返回零；如果把零视为失败，就会制造多余重试、错误告警，甚至触发不必要的补偿动作。

HINCRBY 在一个命令内完成整数递增，字段不存在时从零开始，拒绝非整数值以及超出有符号六十四位范围的结果。它避免的是这一项递增的读改写竞争，并不把外围的业务检查也变为原子操作。分别执行 HGET、在客户端计算、再执行 HSET，仍可能覆盖其他客户端已完成的修改。

HDEL 的返回值统计实际删除的字段，删除最后一个字段会让整个键消失。因此，不能靠空 hash 长期占位，表示某条实体存在。键级过期同样会删除其字段；当前 Redis 还支持字段级截止时间，不能沿用“hash 字段绝对不能单独过期”的旧结论。下面的实验没有设置任何过期时间，也不把结果作为生命周期验证。

紧凑编码是实现选择

小 hash 可以用 listpack 表示，而不是普通哈希表。Redis 8.10.1 的标准阈值是五百一十二个字段，以及每个字段名或值六十四字节；实际部署可能改过这些设置。触发适用限制后，内部表示会改变，但公开的 hash 操作和已经存储的内容不会因此变成另一种数据类型。

紧凑存储用内部扫描工作换取更少的管理开销及较好的局部性。大幅提高阈值前需要测量，不能把命令说明中的复杂度理解为“任意长字段、任意配置下都没有额外成本”。排查时可用 OBJECT ENCODING 观察编码，但应用正确性不应依赖这个内部标签，也不能预设每个对象都必定节省相同倍数的内存。

坏掉的样子

HGETALL 的工作量随整个 hash 增长，响应还要携带字段名和值。调用方只需要两项，却每次读取数千项，即使它们都在同一个键里，也是在浪费传输和处理资源。HMGET 的工作量随请求字段数增长，同样不是免费操作；返回映射的迭代顺序更不应成为应用的排序约定。

WRONGTYPE 表示该键存放了另一种 Redis 类型，并不是普通的字段缺失。非整数计数器也需要明确的数据处理决定，而不是不断重试。一个巨大的 hash 仍只是一个键，不会自动把字段分散到多个集群节点。应围绕真实的访问边界和归属划分记录，不要为了减少键名数量而把无关数据都塞到一起。

快速验证

原有实验记录使用 macOS、Python 3.14.4、Redis 8.10.1 和 redis-py 8.1.0；本轮审阅没有重新执行服务实验，下面的结果说明保留原有观察范围。准备 POSIX 环境、C 编译器、make、curl、tar 与 Python 3.10 或更新版本。安装步骤仅用 libc 构建 Redis 核心，并把客户端装入临时虚拟环境。

redis_lab=$(mktemp -d)
curl --fail --location --output "$redis_lab/redis.tar.gz" https://download.redis.io/releases/redis-8.10.1.tar.gz
tar -xzf "$redis_lab/redis.tar.gz" -C "$redis_lab"
make -C "$redis_lab/redis-8.10.1" build redis -j2 MALLOC=libc
export REDIS_SERVER="$redis_lab/redis-8.10.1/src/redis-server"
python3 -m venv "$redis_lab/venv"
"$redis_lab/venv/bin/python" -m pip install redis==8.1.0

在同一个 shell 中，用 "$redis_lab/venv/bin/python" 执行下面代码。它创建私有 Unix socket，不开放 TCP，关闭持久化。为了用小数据触发转换，只对这个测试进程设置四个字段、八字节的低阈值。实验结束后关闭客户端、终止自己创建的进程并清理临时目录，不会连接默认的本机 Redis。

from contextlib import contextmanager
import os
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
import time

import redis
from redis.backoff import NoBackoff
from redis.retry import Retry


@contextmanager
def instance():
 with TemporaryDirectory(prefix="redis-hash-", dir="/tmp") as directory:
 endpoint = str(Path(directory) / "redis.sock")
 process = subprocess.Popen([
 os.environ["REDIS_SERVER"], "--port", "0",
 "--unixsocket", endpoint, "--unixsocketperm", "700",
 "--save", "", "--appendonly", "no", "--dir", directory,
 "--hash-max-listpack-entries", "4", "--hash-max-listpack-value", "8",
 ], stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
 client = redis.Redis(unix_socket_path=endpoint, decode_responses=False,
 socket_timeout=2, retry=Retry(NoBackoff(), 0))
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "Redis exited during startup"
 try:
 if client.ping():
 break
 except redis.ConnectionError:
 if time.monotonic() >= deadline:
 raise
 time.sleep(0.02)
 yield client
 finally:
 client.close()
 if process.poll() is None:
 process.terminate()
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors.decode()


with instance() as client:
 assert client.hset("profile", mapping={"name": "Ada", "visits": "0", "empty": b""}) == 3
 assert client.hset("profile", "name", "Ada L") == 0
 assert client.hmget("profile", ["visits", "name", "missing", "empty"]) == [
 b"0", b"Ada L", None, b"",
 ]
 assert client.hmget("absent", ["a", "b"]) == [None, None]
 assert client.hgetall("profile") == {b"name": b"Ada L", b"visits": b"0", b"empty": b""}
 assert client.hincrby("profile", "visits", 1) == 1
 assert client.hget("profile", "name") == b"Ada L"
 print("HSET counts new fields; HMGET preserves order and distinguishes missing from empty")

 client.set("json", '{"name":"Ada"}')
 try:
 client.hget("json", "name")
 except redis.ResponseError as error:
 assert "WRONGTYPE" in str(error)
 else:
 raise AssertionError("a JSON string is not a hash")
 client.hset("literal", "name.first", b"Ada")
 assert client.hget("literal", "name") is None
 assert client.hget("literal", "name.first") == b"Ada"
 client.hset("invalid", "counter", "3.5")
 try:
 client.hincrby("invalid", "counter", 1)
 except redis.ResponseError as error:
 assert "integer" in str(error)
 else:
 raise AssertionError("an integer counter cannot contain 3.5")
 assert client.hget("invalid", "counter") == b"3.5"
 client.hset("overflow", "counter", 2**63 - 1)
 try:
 client.hincrby("overflow", "counter", 1)
 except redis.ResponseError as error:
 assert "overflow" in str(error)
 else:
 raise AssertionError("signed 64-bit integer overflow must fail")
 assert client.hget("overflow", "counter") == str(2**63 - 1).encode()
 print("wrong types and invalid or overflowing counters fail; dotted fields are literal")

 assert client.object("ENCODING", "profile") == b"listpack"
 assert client.hset("profile", "fourth", "ok") == 1
 assert client.object("ENCODING", "profile") == b"listpack"
 assert client.hset("profile", "fifth", "ok") == 1
 assert client.object("ENCODING", "profile") == b"hashtable"
 client.hset("value-limit", "field", b"abcdefgh")
 assert client.object("ENCODING", "value-limit") == b"listpack"
 client.hset("value-limit", "field", b"abcdefghi")
 assert client.object("ENCODING", "value-limit") == b"hashtable"
 assert client.hget("profile", "visits") == b"1"
 assert client.hget("value-limit", "field") == b"abcdefghi"
 print("private 4-field and 8-byte thresholds each trigger listpack to hashtable conversion")

 assert client.hdel("value-limit", "absent") == 0
 assert client.hdel("value-limit", "field") == 1
 assert client.exists("value-limit") == 0
 print("deleting the last field removes the hash key")

断言区分了新增字段与替换字段，确认 HMGET 保留请求顺序，也保留缺失与空值的区别，并检查未修改的相邻字段。JSON 字符串触发 WRONGTYPE，点号字段名仍按字面查找；非整数和溢出递增都被拒绝，原来的计数器内容没有改变。

profile 有四个短字段时仍为 listpack，加入第五个后变为 hashtable；另一个 hash 在值从八字节增长到九字节时也发生转换。转换后的读取结果依旧正确，最后一个字段被删除后，其键不再存在。这些结果展示的是受控配置下的编码转换和命令语义，不是生产内存节约比例、延迟、并发负载或集群分布的测试。

来源

Redis hash，字段操作与当前版本的过期能力，已核验 2026-09-08。
Redis HSET，局部更新和新增字段计数，已核验 2026-09-08。
Redis HMGET，请求顺序与缺失字段响应，已核验 2026-09-08。
Redis HGETALL，完整 hash 读取及其复杂度，已核验 2026-09-08。
Redis HINCRBY，整数递增与支持范围，已核验 2026-09-08。
Redis HDEL，删除计数和最后一个字段的处理，已核验 2026-09-08。
Redis OBJECT ENCODING，内部表示及其转换，已核验 2026-09-08。
Redis 内存优化，紧凑编码阈值和测量建议，已核验 2026-09-08。
Redis 8.10.1 配置，hash 默认阈值，已核验 2026-09-08。
Redis 8.10.1 构建说明，仅构建核心与选择分配器，已核验 2026-09-08。

字节边界与解码规则一致，UTF-8 才能完整保留文本

Wed, 02 Dec 2026 00:00:00 +0000

UTF-8 用一到四字节编码 Unicode 标量值。ASCII 字符保持熟悉的单字节表示，许多其他字符则需要更长序列。它适合文本交换，却不会让任意字节自动成为有效文本，也不会让每个字节偏移都成为字符边界。正确处理需要编码约定、符合契约的有效性检查，以及对原始字节和已经解码文本的明确区分。

坏掉的样子

文件或网络读取可以停在多字节序列中间。每块独立解码，会拒绝原本完整且有效的整个字节流；如果每块都立即替换错误，还可能破坏本应与下一块组成字符的字节。流式解码器需要保留未完成输入，等后续数据到来再处理，并在流结束时检查是否仍有残缺序列。分块边界是传输细节，不是文本天然边界。

UTF-8 的起始与续字节具有可识别模式，但这不使任意切片安全。直接截断编码后的字节串，可能把一个序列切成两半。使用另一种编码成功解码，也不能证明解释正确。Latin-1 能映射每个字节，因此把 UTF-8 误解为 Latin-1，仍会得到合法 Unicode 字符串，却可能已经成为乱码。有效字符串和正确文本不是同一结论。

编码有效性还不同于文本等价与显示宽度。一个看起来带重音的字母，可以由单个码点表示，也可以由基础字母和组合标记表示。规范化能够让选定形式便于比较，但 UTF-8 解码不会自动完成规范化。同样，字节顺序标记可能成为字符串开头的实际字符，除非选定编解码器明确消费它。不能把这些处理都笼统称为“转换编码”。

快速验证

将脚本保存为 check-utf8.py，准备 Docker 后执行 python3 check-utf8.py。固定 Python 3.11.16 容器在无网络环境下运行标准库编码与 Unicode 操作，输入都是内存中明确给出的字节和字符串。实验不迁移数据库，也不转换现有文件；断言依赖字节和码点，不要求终端能够正确绘制某个表情图形：

import json,subprocess,uuid
image="python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84"
program=r"""
import codecs,json,unicodedata

text='A中🙂';encoded=text.encode('utf-8');assert len(text)==3 and len(encoded)==8
assert encoded.hex()=='41e4b8adf09f9982' and encoded.decode('utf-8')==text
pieces=[encoded[:2],encoded[2:5],encoded[5:]]
split_errors=0
for piece in pieces:
 try:piece.decode('utf-8')
 except UnicodeDecodeError:split_errors+=1
assert split_errors==3
decoder=codecs.getincrementaldecoder('utf-8')(errors='strict');decoded=[]
for piece in pieces:decoded.append(decoder.decode(piece,final=False))
decoded.append(decoder.decode(b'',final=True));assert ''.join(decoded)==text
rejected={}
for label,raw in {'overlong':bytes.fromhex('c0af'),'surrogate':bytes.fromhex('eda080'),
 'too_large':bytes.fromhex('f4908080'),'truncated':bytes.fromhex('e4b8')}.items():
 try:raw.decode('utf-8');raise AssertionError('invalid UTF-8 accepted')
 except UnicodeDecodeError as error:rejected[label]=error.reason
bad_tail=codecs.getincrementaldecoder('utf-8')();assert bad_tail.decode(bytes.fromhex('e4b8'),final=False)==''
try:bad_tail.decode(b'',final=True);raise AssertionError('incomplete final sequence accepted')
except UnicodeDecodeError:final_rejected=True
mojibake=encoded.decode('latin-1');assert mojibake!=text and mojibake.encode('latin-1')==encoded
decomposed='e\u0301';composed='é';assert decomposed!=composed and unicodedata.normalize('NFC',decomposed)==composed
bom=b'\xef\xbb\xbf'+encoded;assert bom.decode('utf-8').startswith('\ufeff') and bom.decode('utf-8-sig')==text
replacement=bytes.fromhex('ff41').decode('utf-8',errors='replace');assert replacement=='\ufffdA'
print(json.dumps({'text':text,'code_points':len(text),'bytes':len(encoded),'hex':encoded.hex(),
 'chunk_hex':[x.hex() for x in pieces],'independent_chunk_failures':split_errors,'incremental_output':decoded,
 'invalid_rejections':rejected,'final_incomplete_rejected':final_rejected,'latin1_code_points':[hex(ord(c)) for c in mojibake],
 'normalization_lengths':[len(decomposed),len(composed)],'bom_utf8_first':hex(ord(bom.decode('utf-8')[0])),
 'utf8_sig_strips_bom':bom.decode('utf-8-sig')==text,'replacement':replacement},ensure_ascii=False))
"""
name='xbcatm-socket-'+uuid.uuid4().hex[:10]
try:
 result=subprocess.run(['docker','run','--rm','-i','--name',name,'--network','none',
 '--memory','128m','--pids-limit','64',image,'python3','-'],input=program,
 capture_output=True,text=True,timeout=60)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),ensure_ascii=False,sort_keys=True))
finally:
 subprocess.run(['docker','rm','-f',name],capture_output=True,text=True,timeout=10)

字符串 A中🙂 在 Python 中具有三个对应码点的元素，编码后为八字节，十六进制是 41e4b8adf09f9982。ASCII 占一字节，汉字占三字节，表情占四字节；重新解码返回原文。编码字节数和这些码点数量回答不同问题，也都不能自动等同于屏幕列宽。限制字段长度前，必须先明确限制使用哪种单位。

程序把字节拆为 41e4、b8adf0、9f9982，每块当作完整 UTF-8 独立解码都会失败。增量解码器却依次输出 A、中、🙂，在调用之间保留部分序列，最后以 final=True 的空输入完成验证。另一个只持有 e4b8 的解码器，在结束时拒绝残缺序列，没有悄悄丢掉最后一段内容。

四个负向案例分别拒绝过长编码、代理码点、超出 Unicode 上限的值和不完整序列。即使部分字节看起来符合续字节模式，这些形式仍不属于有效 UTF-8。程序明确捕获 UnicodeDecodeError，不把无关异常当成校验成功，也没有使用允许代理码点的宽松模式。验证对象是标准编码规则，而不只是某个函数是否发生错误。

把有效 UTF-8 字节按 Latin-1 解码会成功，却产生不同码点。这个受控案例中，再按 Latin-1 编码错误字符串，可以恢复原字节，但它不是通用乱码修复算法。此前若经过替换、规范化或有损转换，信息可能已经消失。诊断编码不一致时，应先保留原始字节，再决定是否有证据支持某个逆向转换。

脚本还比较分解形式的字母与组合重音，以及组合形式 é。两者初始不相等，长度分别为二和一，NFC 规范化后相等。另外，普通 UTF-8 解码保留开头 BOM 为 U+FEFF，utf-8-sig 则消费它。这是两种独立转换，不能仅因文本看起来奇怪就同时应用。是否允许规范化或删除标记，需要依据字段和格式契约。

明确每个边界的字节契约

HTTP charset 声明或文件格式规范告诉消费者怎样解释字节，修改声明本身不会转码正文。生产端编码器、传输元信息、解析器和存储接口需要一致。应让包含多字节字符的样本经过真实边界，特别检查截断、分块缓冲和按字节计量的限制。只在程序入口看到 UTF-8 字样，并不能说明中途每一步都正确处理了内容。

按数据契约选择错误策略。实验展示 errors=‘replace’ 将非法输入变成 U+FFFD，结果是合法但有损的文本。这可能适合诊断显示，却不能证明标识符或签名数据得到保留。拒绝、替换、移除 BOM 和规范化，应作为具有不同可观察效果的独立决定，避免一个宽松解码动作掩盖本来需要向调用方报告的数据损坏。

限制已解码文本时，使用符合字符需求的操作；限制编码消息时，使用明确消息边界。增量解码解决被切开的字节序列，不定义字素簇、换行布局或数据库比较语义。应验证应用实际要求的属性，而不是把“统一使用 UTF-8”当成所有文本边界都正确的证明。编码一致只是完整文本处理契约的一部分。

来源

RFC 3629 UTF-8，有效字节序列、标量范围及非法编码，已核验 2026-09-12。
Unicode UTF and BOM FAQ，编码边界与字节顺序标记行为，已核验 2026-09-12。
Python 3.11 codecs，增量解码、结束校验与错误处理策略，已核验 2026-09-12。
Python 3.11 unicodedata，作为独立操作的 Unicode 规范化，已核验 2026-09-12。