尧图网页设计 
redis-py 贡献指南解读AI Agent 的开发命令体系、架构地图与代码规范【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py导读AGENTS.md 是 redis-py 仓库中面向 AI Agent 的唯一指导文件single source of guidance它同时承载了项目参考材料命令、架构、依赖说明与贡献流程规则。本文将逐层拆解这份文件从invoke驱动的测试/开发命令体系到同步与异步双栈镜像架构、命令 mixin 层、RESP 解析与集群路由的源码级地图再到 MUST/MUST NOT 硬性规范与强制自检循环。读完本文你将掌握在 redis-py 中定位模块、运行测试矩阵、遵循同步/异步一致性约束以及按仓库标准完成一次合规代码变更的完整方法。一、文档定位一份给 AI Agent 的仓库使用说明书AGENTS.md 在仓库中扮演双重角色项目参考材料汇总开发命令tasks.py 中的invoke任务、测试拓扑docker-compose.yml 的 profile、架构分层与依赖约束贡献流程规则规定 MUST / MUST NOT、类型提示、导入风格、同步/异步一致性、测试与 lint 要求以及提交前的强制检查循环。它面向在仓库中工作的 AI Agent但同样适用于任何想要高质量参与 redis-py 开发的人类贡献者。文档还提到两个配套技能文件/add-new-command技能仓库中存在 .claude/commands/add-new-command.md遵循项目预期工作流以及用于在项目结构变化时审计并刷新本文件的/sync-claude-md技能。二、开发命令体系invoke 驱动的测试与构建2.1 前置激活虚拟环境所有开发任务通过invoke参见 tasks.py驱动使用前需先激活.venv。2.2 核心 invoke 任务速查命令作用invoke devenv启动 docker-compose 测试环境standalone、replica、sentinel、cluster、redis-stack、stunnel。docker-compose.yml 中的 profiles 控制启动哪些容器--profile all为默认invoke clean停止所有 docker 容器并清理build/、dist/目录invoke tests依次运行fixed_client、standalone、cluster三套测试接受--uvloop、--protocol2\|3\|、--legacy-responsestrue\|false、--profile参数invoke standalone-tests/invoke cluster-tests只运行其中一套cluster 套件默认指向redis://localhost:16379/0TLS 为rediss://localhost:27379/0invoke fixed-client-tests仅运行标记为fixed_client的测试这些测试固定了客户端配置不能被全局--protocol/--legacy-responses参数重新配置invoke run-test-matrix运行完整的protocol×legacy_responses矩阵即 CI 所做的工作invoke linters/invoke linters-fixruff check、ruff format以及vulture redis whitelist.py --min-confidence 80用 whitelist.py 压制 vulture 误报invoke all-testslinters tests 全量执行invoke build-docs在docs/下生成 Sphinx HTML 文档从 tasks.py 的源码可以看到tests任务内部会依次调用fixed_client_tests、standalone_tests、cluster_tests且每个子任务都生成 JUnit XML 报告junit-results/与 coverage 报告并通过--ignoretests/test_scenario --ignoretests/test_asyncio/test_scenario排除需要外部基础设施的场景测试。run_test_matrix则以protocol ∈ {2, 3, }与legacy_responses ∈ {True, False}的笛卡尔积循环执行 standalone 与 cluster 套件。2.3 直接用 pytest 运行单个测试AGENTS.md 给出了绕过 invoke 直接运行单测的示例pytest tests/test_commands.py::TestRedisCommands::test_set -x pytest tests/test_asyncio/test_commands.py -k test_set and not cluster pytest --redis-urlredis://localhost:16379/0 -m onlycluster tests/test_cluster.pypytest 插件定义在 tests/conftest.py 的pytest_addoption中提供了也通过 invoke 封装暴露以下选项--redis-urlRedis 连接串默认redis://localhost:6379/0--redis-ssl-urlSSL 连接串默认rediss://localhost:6666--redis-mod-url带模块的 Redis 连接串默认redis://localhost:6479对应 redis-stack 容器--protocol表示使用库默认值当前为 RESP3--legacy-responsestrue|false|defaultdefault表示不覆盖客户端构造函数的默认值--redis-cluster-nodes测试启动前需要可用的集群节点数默认 6--uvloop使用 uvloop 运行 asyncio 测试--sentinels、--master-serviceSentinel 测试的节点列表与主服务名。三、pytest markers如何圈定测试作用域markers 定义在 pyproject.toml 的[tool.pytest.ini_options]中用于限定测试运行范围Marker含义onlycluster/onlynoncluster将测试限定在一种拓扑集群 / 非集群redismod需要 Redis 模块Stack 镜像针对集群运行时跳过fixed_client测试固定了自己的客户端/配置从 protocol/legacy 矩阵运行中排除experimental、replica、ssl、pipeline、cp_integration、no_mock_connections分别标记实验性、副本、SSL、管道、凭据提供方集成以及跳过自动mock_health_check_connectionsfixture 的测试multidb_integrationMultiDBClient 集成测试需要 docker 的multidbprofile两个集群 两个 standalonetests/test_scenario/与tests/test_asyncio/test_scenario/下的场景测试依赖外部基础设施Redis Enterprise、EntraID 等通过--ignore从默认的standalone-tests/cluster-tests中排除。四、架构地图理解 redis-py 的模块分层4.1 同步与异步镜像Sync and Async mirrors库提供两套必须保持同步的并行客户端栈同步顶层redis/client.py、redis/cluster.py、redis/connection.py、redis/sentinel.py、redis/lock.py、redis/retry.py异步镜像位于 redis/asyncio/ 下client.py、cluster.py、connection.py、sentinel.py等。核心约束改动其中一个栈的行为时几乎总是需要在另一个栈做等价改动。specs/sync_async_deduplication_analysis.md 记录了这种刻意为之的重复设计AGENTS.md 中的 Sync / Async Consistency 流程规则对触碰任一栈的改动都是强制性的。4.2 命令层mixin 组合命令面由 redis/commands/ 下的 mixin 类组合而成core.pyCoreCommands/AsyncCoreCommands覆盖每个标准 Redis 命令cluster.pyRedisClusterCommands/AsyncRedisClusterCommands并导出READ_COMMANDS可路由到副本的命令集合sentinel.pySentinel 专用命令redismodules.py聚合模块 mixinbf/Bloom、json/、search/、timeseries/、vectorset/每个模块子包拥有自己的命令面与响应解析policies.pyPolicyResolver/StaticPolicyResolver——集群客户端为每条命令解析的路由视图。其中STATIC_POLICIES已被弃用且无人读取它是 7.1.0 表格的冻结逐字副本仅为外部导入方保留刻意不与_STATIC_COMMAND_METADATA派生或同步。要改路由请改metadata.py绝不要改这里metadata.py命令元数据记录类型——RequestPolicy/ResponsePolicy、CommandPolicies/PolicyRecords、CommandMetadata/CommandMetadataRecordsCache以及元数据解析器。CommandMetadata是超集记录_to_command_policies将其投影为PolicyResolver服务的路由视图——当记录不提供路由策略时投影为None这是解析器告诉集群客户端自行解析目标节点的方式movablekeys命令需要此机制其 key 只存在于 key specs 中派生出的策略不含 key。CommandPolicies是 7.1.0 以可变类发布的CommandMetadata则是冻结的因此单个记录可被多个命令共享。redis/_parsers/commands.py出于向后兼容重新导出了策略类型但应统一从redis.commands.metadata导入。从 metadata.py 的源码可见RequestPolicy枚举包含ALL_NODES、ALL_SHARDS、ALL_REPLICAS、MULTI_SHARD、SPECIAL、DEFAULT_KEYLESS、DEFAULT_KEYED、DEFAULT_NODEResponsePolicy包含ONE_SUCCEEDED、ALL_SUCCEEDED、AGG_LOGICAL_AND、AGG_LOGICAL_OR、AGG_MIN、AGG_MAX、AGG_SUM、SPECIAL等聚合策略——这正是集群路由与响应聚合的语义基础。解析器是客户端级别的构造函数参数metadata_resolver作用于Redis、ConnectionPool、RedisCluster、NodesManager、ClusterPipeline构建一次并与每个节点客户端共享集群路由通过resolve_policies消费它客户端缓存CSC资格通过is_cacheable消费它。仅传入metadata_resolver时路由解析器由其派生显式传入policy_resolver时路由以显式值为准。异步客户端不接收metadata_resolver参数因为异步栈尚无客户端缓存作为第二个消费者——解析器类保持镜像待异步 CSC 落地时该参数再以增量的方式补充。helpers.py共享工具list_or_args、pubsub 订阅分区等。Redis同步与redis.asyncio.Redis通过继承这些 mixin 加上连接/连接池设施装配而成。新增命令 同时编辑同步与异步 mixin 类且若涉及集群路由可能要更新READ_COMMANDS与策略解析器。仓库中的/add-new-command技能.claude/commands/add-new-command.md遵循项目预期工作流。4.3 线上协议与响应解析redis/_parsers/ 负责 RESP 组帧与响应整形resp2.py、resp3.py纯 Python 解析器hiredis.py可选的 C 加速解析器安装hiredis3.2.0时自动启用redis/utils.py 中的HIREDIS_AVAILABLE检测逻辑与此一致response_callbacks.py按命令的响应后处理即库把原始协议输出重塑为 Python 类型的地方commands.pyCommandsParser集群客户端通过COMMAND INFO学习命令元数据返回的策略记录类型定义在 redis/commands/metadata.pyencoders.py请求编码。RESP3 现在是线上的默认协议两个开关互相配合protocol2|3选择线上协议legacy_responsesTrue|False选择Python 响应形状。True当前默认无论线上协议如何都保留 RESP2 时代的形状False返回新的统一形状。测试矩阵同时覆盖两个轴参见 specs/unified_responses_migration_guide.md。4.4 集群客户端redis/cluster.py异步redis/asyncio/cluster.py实现拓扑发现、slot 映射redis/crc.py 的key_slot、按节点的连接池、MOVED/ASK 重定向以及基于 redis/commands/metadata.py 的RequestPolicy/ResponsePolicy枚举、经由 redis/commands/policies.py 解析的路由。READ_COMMANDS控制读路由的副本资格。4.5 Multi-DatabaseActive-Active客户端redis/multidb/异步镜像在 redis/asyncio/multidb/实现前置多个 Redis 部署的客户端含健康检查、故障检测与故障转移。关键模块client.py、command_executor.py、database.py、failover.py、failure_detector.py、config.py同步侧另有circuit.pypybreaker与exception.py异步侧有healthcheck.py。这里同样要求同步/异步镜像改动。4.6 横切子系统redis/auth/凭据提供方与基于令牌的认证经redis-entraid的 EntraID、JWT 支持redis/cache.py客户端缓存配置。CacheConfig.is_allowed_to_cache是唯一资格决策点委托给配置持有的MetadataResolverredis/commands/metadata.py默认为静态表并由ConnectionPool.__init__从客户端级metadata_resolver注入。从源码看CacheProxy的实现is_allowed_to_cache会调用self._metadata_resolver.is_cacheable(command)未知命令、无法索引的记录、不完整元数据构建的记录全部 fail-closed 返回 False且判定按命令名记忆化命令执行路径上只是一次字典命中。DEFAULT_ALLOW_LIST已弃用且无人读取——改资格判定去metadata.py别改这里。CacheProxyConnection.send_command先询问该决策点然后要求调用携带keys不可缓存的命令缺少keys时绕过缓存而不是抛异常因此向命令方法传入keys是开始为其启用缓存的纯增量方式redis/maint_notifications.py服务端推送的维护通知及响应该通知的处理器redis/keyspace_notifications.pykeyspace/keyevent 订阅辅助同步与异步变体并存redis/observability/异步在 redis/asyncio/observability/OpenTelemetry 插桩。模块包括attributes.pyspan/metric 属性键、config.py、metrics.py、providers.py、recorder.py其余代码调用的 API——record_operation_duration、record_error_count、record_pubsub_message、record_streaming_lag_from_response、registry.py。可选由otelextra 门控异步栈只有recorder.py其余委托给同步包redis/event.pyEventDispatcher在连接生命周期事件上通知订阅者redis/http/部分认证流程与场景测试使用的 HTTP 客户端redis/retry.py、redis/backoff.py重试/退避策略ExponentialWithJitterBackoff是默认实现。4.7 Docker 测试镜像dockers/包含 standalone、cluster、sentinel、redis-stack 容器的配置。compose 文件拉取redislabs/client-libs-test:tag镜像tag 由CLIENT_LIBS_TEST_IMAGE_TAG/CLIENT_LIBS_TEST_STACK_IMAGE_TAG参数化CI 通过.github/workflows/integration.yaml中的CURRENT_REDIS_VERSION固定这些 tag。docker-compose.yml 中可见 standalone6379/6666 TLS、replica6380、cluster16379-16384 及 TLS 27379-27384、第二集群 cluster216385-16390专供multidbprofile、sentinel26379-26381、redis-stack6479等服务的端口与 profile 归属。五、Python 与依赖约束requires-python 3.10pyproject.toml 列出了受支持版本3.10 至 3.14含 PyPy可选 extrashiredis、xxhash、ocsp、jwt、circuit_breaker、otel均定义在[project.optional-dependencies]Ruff 是唯一格式化/lint 工具target-version py310、line-length 88。tests/*有放宽的命名规则模块命令包bf、timeseries、json、search选择退出 pep8 命名whitelist.py 是 vulture 的允许列表——扩展它而不是在代码内联静默 vulture。六、硬性规范MUST / MUST NOT 与通用原则MUST保持公共 API 兼容签名、参数名、默认值、返回类型尽可能让同步与异步实现完全对齐行为、签名、类型提示运行完整测试套件并修复所有失败运行 lint 并修复所有问题严格遵循现有代码模式与约定精确维持 Redis 命令语义与行为优化性能与内存效率MUST NOT无明确需求不得引入破坏性 API 变更不得修改无关代码不得改变 Redis 行为、边界情况或错误语义无充分理由不得引入新依赖不得添加多余抽象或新模式不得削弱或删除现有测试使其通过通用原则做最小、外科手术式的改动一致性优先于创新不确定时参考代码库中已有的实现先正确性后性能七、工程实践细则7.1 类型提示与重载使用 PEP 604X | Y语法遵循同步/异步类型提示重载约定保持同步与异步 API 类型提示一致非必要不改变公共类型签名7.2 导入所有类型在文件顶部导入除非绝对必要避免函数级导入导入保持最少且一致7.3 同步/异步一致性同步的任何改动必须在异步中镜像反之亦然确保签名、返回类型与行为一致确保重载保持对齐7.4 性能与内存先正确性再为性能与内存效率优化绝不为性能牺牲正确性避免热路径上的多余分配不需要时避免创建临时对象复用现有 helper/工具而非复制逻辑小心大型数据结构7.5 Redis 语义与 Redis 服务端行为精确匹配保留错误类型与消息不引入静默行为变更明确且正确地处理边界情况7.6 测试每次行为变更都添加或更新测试覆盖边界情况与失败场景保持测试确定性与稳定性不放松断言来让测试通过7.7 Lint 与代码质量运行所有 linter 并修复问题保证代码干净、可读、一致变更后做完整代码评审必要时重构以符合项目标准7.8 文档行为变化时更新 docstring保持 docstring 与类型提示一致避免冗余或过时的文档7.9 依赖除非绝对必要不引入新依赖优先使用项目内已有工具八、提交前强制流程8.1 Self-Check Loop强制最终确定变更前必须完成六步循环直到所有答案满意Correctness Check变更是否精确保留 Redis 语义边界情况是否处理正确API Check是否有公共函数签名变化若有回退或显式说明理由。Sync/Async Check两个实现是否都更新且行为一致类型提示与重载是否对齐Performance Check是否引入额外分配或不必要的工作能否简化或复用Consistency Check是否匹配代码库现有模式命名与结构是否一致Test Check是否为变更添加/更新了测试所有测试是否在未削弱断言的前提下通过8.2 Diff Validation强制提交前审查完整 diff只修改相关文件无无关行的改动无逻辑的意外删除无调试代码或残留注释导入未被不必要地改动公共 API 未被无意修改发现问题即修复并重新验证。8.3 Code Review强制实现完成后对最终代码做彻底评审核验正确性逻辑完整、边界处理、Redis 语义精确、API 稳定性签名、默认值、返回类型不变、同步/异步对等实现、类型提示、重载匹配、性能无多余分配、无冗余工作、一致性遵循现有模式、简洁性无多余抽象、测试覆盖充分、断言未削弱。任何问题都要先修复再重跑测试与 lint并重复评审。8.4 Final Checklist以下条件必须全部为真才算完成测试通过、lint 通过、同步/异步对等已验证、无 API 破坏、无多余分配引入、行为与 Redis 完全匹配、代码遵循现有模式、diff 最小且干净。结语从文档到代码的闭环AGENTS.md 的价值在于把如何正确地为 redis-py 做贡献沉淀成了可执行清单。它与仓库形成闭环命令体系对应 tasks.py 与 docker-compose.yml架构描述对应 redis/commands/ 的命令 mixin、redis/_parsers/ 的协议解析、redis/cluster.py 的集群路由与 redis/cache.py 的缓存资格判定规范与流程则直接约束每一次代码变更。对 AI Agent 与人类贡献者而言遵循这份指南意味着改动一处同步/异步双栈都要对齐改路由去metadata.py而非policies.py的冻结表提交前走完 Self-Check、Diff Validation 与 Code Review 三重校验——这正是 redis-py 保持 API 稳定、行为精确与双栈一致性的工程基石。【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 redis-py 贡献指南解读：AI Agent 的开发命令体系、架构地图与代码规范
redis-py 贡献指南解读AI Agent 的开发命令体系、架构地图与代码规范【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py导读AGENTS.md 是 redis-py 仓库中面向 AI Agent 的唯一指导文件single source of guidance它同时承载了项目参考材料命令、架构、依赖说明与贡献流程规则。本文将逐层拆解这份文件从invoke驱动的测试/开发命令体系到同步与异步双栈镜像架构、命令 mixin 层、RESP 解析与集群路由的源码级地图再到 MUST/MUST NOT 硬性规范与强制自检循环。读完本文你将掌握在 redis-py 中定位模块、运行测试矩阵、遵循同步/异步一致性约束以及按仓库标准完成一次合规代码变更的完整方法。一、文档定位一份给 AI Agent 的仓库使用说明书AGENTS.md 在仓库中扮演双重角色项目参考材料汇总开发命令tasks.py 中的invoke任务、测试拓扑docker-compose.yml 的 profile、架构分层与依赖约束贡献流程规则规定 MUST / MUST NOT、类型提示、导入风格、同步/异步一致性、测试与 lint 要求以及提交前的强制检查循环。它面向在仓库中工作的 AI Agent但同样适用于任何想要高质量参与 redis-py 开发的人类贡献者。文档还提到两个配套技能文件/add-new-command技能仓库中存在 .claude/commands/add-new-command.md遵循项目预期工作流以及用于在项目结构变化时审计并刷新本文件的/sync-claude-md技能。二、开发命令体系invoke 驱动的测试与构建2.1 前置激活虚拟环境所有开发任务通过invoke参见 tasks.py驱动使用前需先激活.venv。2.2 核心 invoke 任务速查命令作用invoke devenv启动 docker-compose 测试环境standalone、replica、sentinel、cluster、redis-stack、stunnel。docker-compose.yml 中的 profiles 控制启动哪些容器--profile all为默认invoke clean停止所有 docker 容器并清理build/、dist/目录invoke tests依次运行fixed_client、standalone、cluster三套测试接受--uvloop、--protocol2\|3\|、--legacy-responsestrue\|false、--profile参数invoke standalone-tests/invoke cluster-tests只运行其中一套cluster 套件默认指向redis://localhost:16379/0TLS 为rediss://localhost:27379/0invoke fixed-client-tests仅运行标记为fixed_client的测试这些测试固定了客户端配置不能被全局--protocol/--legacy-responses参数重新配置invoke run-test-matrix运行完整的protocol×legacy_responses矩阵即 CI 所做的工作invoke linters/invoke linters-fixruff check、ruff format以及vulture redis whitelist.py --min-confidence 80用 whitelist.py 压制 vulture 误报invoke all-testslinters tests 全量执行invoke build-docs在docs/下生成 Sphinx HTML 文档从 tasks.py 的源码可以看到tests任务内部会依次调用fixed_client_tests、standalone_tests、cluster_tests且每个子任务都生成 JUnit XML 报告junit-results/与 coverage 报告并通过--ignoretests/test_scenario --ignoretests/test_asyncio/test_scenario排除需要外部基础设施的场景测试。run_test_matrix则以protocol ∈ {2, 3, }与legacy_responses ∈ {True, False}的笛卡尔积循环执行 standalone 与 cluster 套件。2.3 直接用 pytest 运行单个测试AGENTS.md 给出了绕过 invoke 直接运行单测的示例pytest tests/test_commands.py::TestRedisCommands::test_set -x pytest tests/test_asyncio/test_commands.py -k test_set and not cluster pytest --redis-urlredis://localhost:16379/0 -m onlycluster tests/test_cluster.pypytest 插件定义在 tests/conftest.py 的pytest_addoption中提供了也通过 invoke 封装暴露以下选项--redis-urlRedis 连接串默认redis://localhost:6379/0--redis-ssl-urlSSL 连接串默认rediss://localhost:6666--redis-mod-url带模块的 Redis 连接串默认redis://localhost:6479对应 redis-stack 容器--protocol表示使用库默认值当前为 RESP3--legacy-responsestrue|false|defaultdefault表示不覆盖客户端构造函数的默认值--redis-cluster-nodes测试启动前需要可用的集群节点数默认 6--uvloop使用 uvloop 运行 asyncio 测试--sentinels、--master-serviceSentinel 测试的节点列表与主服务名。三、pytest markers如何圈定测试作用域markers 定义在 pyproject.toml 的[tool.pytest.ini_options]中用于限定测试运行范围Marker含义onlycluster/onlynoncluster将测试限定在一种拓扑集群 / 非集群redismod需要 Redis 模块Stack 镜像针对集群运行时跳过fixed_client测试固定了自己的客户端/配置从 protocol/legacy 矩阵运行中排除experimental、replica、ssl、pipeline、cp_integration、no_mock_connections分别标记实验性、副本、SSL、管道、凭据提供方集成以及跳过自动mock_health_check_connectionsfixture 的测试multidb_integrationMultiDBClient 集成测试需要 docker 的multidbprofile两个集群 两个 standalonetests/test_scenario/与tests/test_asyncio/test_scenario/下的场景测试依赖外部基础设施Redis Enterprise、EntraID 等通过--ignore从默认的standalone-tests/cluster-tests中排除。四、架构地图理解 redis-py 的模块分层4.1 同步与异步镜像Sync and Async mirrors库提供两套必须保持同步的并行客户端栈同步顶层redis/client.py、redis/cluster.py、redis/connection.py、redis/sentinel.py、redis/lock.py、redis/retry.py异步镜像位于 redis/asyncio/ 下client.py、cluster.py、connection.py、sentinel.py等。核心约束改动其中一个栈的行为时几乎总是需要在另一个栈做等价改动。specs/sync_async_deduplication_analysis.md 记录了这种刻意为之的重复设计AGENTS.md 中的 Sync / Async Consistency 流程规则对触碰任一栈的改动都是强制性的。4.2 命令层mixin 组合命令面由 redis/commands/ 下的 mixin 类组合而成core.pyCoreCommands/AsyncCoreCommands覆盖每个标准 Redis 命令cluster.pyRedisClusterCommands/AsyncRedisClusterCommands并导出READ_COMMANDS可路由到副本的命令集合sentinel.pySentinel 专用命令redismodules.py聚合模块 mixinbf/Bloom、json/、search/、timeseries/、vectorset/每个模块子包拥有自己的命令面与响应解析policies.pyPolicyResolver/StaticPolicyResolver——集群客户端为每条命令解析的路由视图。其中STATIC_POLICIES已被弃用且无人读取它是 7.1.0 表格的冻结逐字副本仅为外部导入方保留刻意不与_STATIC_COMMAND_METADATA派生或同步。要改路由请改metadata.py绝不要改这里metadata.py命令元数据记录类型——RequestPolicy/ResponsePolicy、CommandPolicies/PolicyRecords、CommandMetadata/CommandMetadataRecordsCache以及元数据解析器。CommandMetadata是超集记录_to_command_policies将其投影为PolicyResolver服务的路由视图——当记录不提供路由策略时投影为None这是解析器告诉集群客户端自行解析目标节点的方式movablekeys命令需要此机制其 key 只存在于 key specs 中派生出的策略不含 key。CommandPolicies是 7.1.0 以可变类发布的CommandMetadata则是冻结的因此单个记录可被多个命令共享。redis/_parsers/commands.py出于向后兼容重新导出了策略类型但应统一从redis.commands.metadata导入。从 metadata.py 的源码可见RequestPolicy枚举包含ALL_NODES、ALL_SHARDS、ALL_REPLICAS、MULTI_SHARD、SPECIAL、DEFAULT_KEYLESS、DEFAULT_KEYED、DEFAULT_NODEResponsePolicy包含ONE_SUCCEEDED、ALL_SUCCEEDED、AGG_LOGICAL_AND、AGG_LOGICAL_OR、AGG_MIN、AGG_MAX、AGG_SUM、SPECIAL等聚合策略——这正是集群路由与响应聚合的语义基础。解析器是客户端级别的构造函数参数metadata_resolver作用于Redis、ConnectionPool、RedisCluster、NodesManager、ClusterPipeline构建一次并与每个节点客户端共享集群路由通过resolve_policies消费它客户端缓存CSC资格通过is_cacheable消费它。仅传入metadata_resolver时路由解析器由其派生显式传入policy_resolver时路由以显式值为准。异步客户端不接收metadata_resolver参数因为异步栈尚无客户端缓存作为第二个消费者——解析器类保持镜像待异步 CSC 落地时该参数再以增量的方式补充。helpers.py共享工具list_or_args、pubsub 订阅分区等。Redis同步与redis.asyncio.Redis通过继承这些 mixin 加上连接/连接池设施装配而成。新增命令 同时编辑同步与异步 mixin 类且若涉及集群路由可能要更新READ_COMMANDS与策略解析器。仓库中的/add-new-command技能.claude/commands/add-new-command.md遵循项目预期工作流。4.3 线上协议与响应解析redis/_parsers/ 负责 RESP 组帧与响应整形resp2.py、resp3.py纯 Python 解析器hiredis.py可选的 C 加速解析器安装hiredis3.2.0时自动启用redis/utils.py 中的HIREDIS_AVAILABLE检测逻辑与此一致response_callbacks.py按命令的响应后处理即库把原始协议输出重塑为 Python 类型的地方commands.pyCommandsParser集群客户端通过COMMAND INFO学习命令元数据返回的策略记录类型定义在 redis/commands/metadata.pyencoders.py请求编码。RESP3 现在是线上的默认协议两个开关互相配合protocol2|3选择线上协议legacy_responsesTrue|False选择Python 响应形状。True当前默认无论线上协议如何都保留 RESP2 时代的形状False返回新的统一形状。测试矩阵同时覆盖两个轴参见 specs/unified_responses_migration_guide.md。4.4 集群客户端redis/cluster.py异步redis/asyncio/cluster.py实现拓扑发现、slot 映射redis/crc.py 的key_slot、按节点的连接池、MOVED/ASK 重定向以及基于 redis/commands/metadata.py 的RequestPolicy/ResponsePolicy枚举、经由 redis/commands/policies.py 解析的路由。READ_COMMANDS控制读路由的副本资格。4.5 Multi-DatabaseActive-Active客户端redis/multidb/异步镜像在 redis/asyncio/multidb/实现前置多个 Redis 部署的客户端含健康检查、故障检测与故障转移。关键模块client.py、command_executor.py、database.py、failover.py、failure_detector.py、config.py同步侧另有circuit.pypybreaker与exception.py异步侧有healthcheck.py。这里同样要求同步/异步镜像改动。4.6 横切子系统redis/auth/凭据提供方与基于令牌的认证经redis-entraid的 EntraID、JWT 支持redis/cache.py客户端缓存配置。CacheConfig.is_allowed_to_cache是唯一资格决策点委托给配置持有的MetadataResolverredis/commands/metadata.py默认为静态表并由ConnectionPool.__init__从客户端级metadata_resolver注入。从源码看CacheProxy的实现is_allowed_to_cache会调用self._metadata_resolver.is_cacheable(command)未知命令、无法索引的记录、不完整元数据构建的记录全部 fail-closed 返回 False且判定按命令名记忆化命令执行路径上只是一次字典命中。DEFAULT_ALLOW_LIST已弃用且无人读取——改资格判定去metadata.py别改这里。CacheProxyConnection.send_command先询问该决策点然后要求调用携带keys不可缓存的命令缺少keys时绕过缓存而不是抛异常因此向命令方法传入keys是开始为其启用缓存的纯增量方式redis/maint_notifications.py服务端推送的维护通知及响应该通知的处理器redis/keyspace_notifications.pykeyspace/keyevent 订阅辅助同步与异步变体并存redis/observability/异步在 redis/asyncio/observability/OpenTelemetry 插桩。模块包括attributes.pyspan/metric 属性键、config.py、metrics.py、providers.py、recorder.py其余代码调用的 API——record_operation_duration、record_error_count、record_pubsub_message、record_streaming_lag_from_response、registry.py。可选由otelextra 门控异步栈只有recorder.py其余委托给同步包redis/event.pyEventDispatcher在连接生命周期事件上通知订阅者redis/http/部分认证流程与场景测试使用的 HTTP 客户端redis/retry.py、redis/backoff.py重试/退避策略ExponentialWithJitterBackoff是默认实现。4.7 Docker 测试镜像dockers/包含 standalone、cluster、sentinel、redis-stack 容器的配置。compose 文件拉取redislabs/client-libs-test:tag镜像tag 由CLIENT_LIBS_TEST_IMAGE_TAG/CLIENT_LIBS_TEST_STACK_IMAGE_TAG参数化CI 通过.github/workflows/integration.yaml中的CURRENT_REDIS_VERSION固定这些 tag。docker-compose.yml 中可见 standalone6379/6666 TLS、replica6380、cluster16379-16384 及 TLS 27379-27384、第二集群 cluster216385-16390专供multidbprofile、sentinel26379-26381、redis-stack6479等服务的端口与 profile 归属。五、Python 与依赖约束requires-python 3.10pyproject.toml 列出了受支持版本3.10 至 3.14含 PyPy可选 extrashiredis、xxhash、ocsp、jwt、circuit_breaker、otel均定义在[project.optional-dependencies]Ruff 是唯一格式化/lint 工具target-version py310、line-length 88。tests/*有放宽的命名规则模块命令包bf、timeseries、json、search选择退出 pep8 命名whitelist.py 是 vulture 的允许列表——扩展它而不是在代码内联静默 vulture。六、硬性规范MUST / MUST NOT 与通用原则MUST保持公共 API 兼容签名、参数名、默认值、返回类型尽可能让同步与异步实现完全对齐行为、签名、类型提示运行完整测试套件并修复所有失败运行 lint 并修复所有问题严格遵循现有代码模式与约定精确维持 Redis 命令语义与行为优化性能与内存效率MUST NOT无明确需求不得引入破坏性 API 变更不得修改无关代码不得改变 Redis 行为、边界情况或错误语义无充分理由不得引入新依赖不得添加多余抽象或新模式不得削弱或删除现有测试使其通过通用原则做最小、外科手术式的改动一致性优先于创新不确定时参考代码库中已有的实现先正确性后性能七、工程实践细则7.1 类型提示与重载使用 PEP 604X | Y语法遵循同步/异步类型提示重载约定保持同步与异步 API 类型提示一致非必要不改变公共类型签名7.2 导入所有类型在文件顶部导入除非绝对必要避免函数级导入导入保持最少且一致7.3 同步/异步一致性同步的任何改动必须在异步中镜像反之亦然确保签名、返回类型与行为一致确保重载保持对齐7.4 性能与内存先正确性再为性能与内存效率优化绝不为性能牺牲正确性避免热路径上的多余分配不需要时避免创建临时对象复用现有 helper/工具而非复制逻辑小心大型数据结构7.5 Redis 语义与 Redis 服务端行为精确匹配保留错误类型与消息不引入静默行为变更明确且正确地处理边界情况7.6 测试每次行为变更都添加或更新测试覆盖边界情况与失败场景保持测试确定性与稳定性不放松断言来让测试通过7.7 Lint 与代码质量运行所有 linter 并修复问题保证代码干净、可读、一致变更后做完整代码评审必要时重构以符合项目标准7.8 文档行为变化时更新 docstring保持 docstring 与类型提示一致避免冗余或过时的文档7.9 依赖除非绝对必要不引入新依赖优先使用项目内已有工具八、提交前强制流程8.1 Self-Check Loop强制最终确定变更前必须完成六步循环直到所有答案满意Correctness Check变更是否精确保留 Redis 语义边界情况是否处理正确API Check是否有公共函数签名变化若有回退或显式说明理由。Sync/Async Check两个实现是否都更新且行为一致类型提示与重载是否对齐Performance Check是否引入额外分配或不必要的工作能否简化或复用Consistency Check是否匹配代码库现有模式命名与结构是否一致Test Check是否为变更添加/更新了测试所有测试是否在未削弱断言的前提下通过8.2 Diff Validation强制提交前审查完整 diff只修改相关文件无无关行的改动无逻辑的意外删除无调试代码或残留注释导入未被不必要地改动公共 API 未被无意修改发现问题即修复并重新验证。8.3 Code Review强制实现完成后对最终代码做彻底评审核验正确性逻辑完整、边界处理、Redis 语义精确、API 稳定性签名、默认值、返回类型不变、同步/异步对等实现、类型提示、重载匹配、性能无多余分配、无冗余工作、一致性遵循现有模式、简洁性无多余抽象、测试覆盖充分、断言未削弱。任何问题都要先修复再重跑测试与 lint并重复评审。8.4 Final Checklist以下条件必须全部为真才算完成测试通过、lint 通过、同步/异步对等已验证、无 API 破坏、无多余分配引入、行为与 Redis 完全匹配、代码遵循现有模式、diff 最小且干净。结语从文档到代码的闭环AGENTS.md 的价值在于把如何正确地为 redis-py 做贡献沉淀成了可执行清单。它与仓库形成闭环命令体系对应 tasks.py 与 docker-compose.yml架构描述对应 redis/commands/ 的命令 mixin、redis/_parsers/ 的协议解析、redis/cluster.py 的集群路由与 redis/cache.py 的缓存资格判定规范与流程则直接约束每一次代码变更。对 AI Agent 与人类贡献者而言遵循这份指南意味着改动一处同步/异步双栈都要对齐改路由去metadata.py而非policies.py的冻结表提交前走完 Self-Check、Diff Validation 与 Code Review 三重校验——这正是 redis-py 保持 API 稳定、行为精确与双栈一致性的工程基石。【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考