PartialResultException是受检异常，因其继承自NamingException，JNDI规范要求开发者显式处理分布式目录查询中的部分成功场景，如LDAP分页超限或网络中断导致结果截断，必须try-catch或throws，以保障对已返回有效数据的正确消费与容错决策。
Java中PartialResultException是JNDI（Java Naming and Directory Interface）规范定义的受检异常，用于标识分布式目录检索操作中“部分成功”——即查询返回了部分结果，但因超时、网络中断、权限不足或后端服务限制等原因未能获取全部数据。
为什么PartialResultException是受检异常
它继承自NamingException，而NamingException本身是受检异常（checked exception）。JNDI设计上要求开发者显式处理这类可预期的中间态失败，避免静默丢弃部分结果。例如LDAP分页查询或大型目录遍历时，服务端常主动截断响应以保障性能，此时抛出该异常而非直接失败。
- 必须用
try-catch捕获或在方法签名中声明throws - 不处理会导致编译错误，强制关注分布式场景下的容错逻辑
- 区别于
CommunicationException等完全失败类异常，它暗示“已有有效数据”
如何正确处理PartialResultException
核心是区分“可恢复的部分失败”与真正错误。典型做法是在捕获后检查已返回的结果集，并决定是否重试、降级或告警。
- 从
PartialResultException中提取已获取的NamingEnumeration（如DirContext.search()返回的枚举），逐条消费已有结果 - 检查异常的
getRootCause()判断根本原因：若为TimeLimitExceededException，可调高超时；若为SizeLimitExceededException，需改用分页（如LDAP的PagedResultsControl） - 避免简单吞掉异常——忽略它等于放弃部分数据，违背分布式系统“尽力交付”原则
分布式检索中触发PartialResultException的常见场景
该异常多出现在跨网络、多节点的目录服务访问中，不是代码缺陷，而是协议和基础设施的正常反馈。
立即学习“Java免费学习笔记（深入）”；
- LDAP服务器配置了单次查询最大返回条目数（如OpenLDAP的
slapd.conf中sizelimit），实际结果超限时抛出 - JNDI Context设置了
java.naming.ldap.derefAliases或java.naming.ldap.referral，而下游服务链中某节点不可达 - AD（Active Directory）域控制器负载过高，主动终止长查询，返回已收集到的OU或用户子集
替代方案与最佳实践
若业务无法接受部分结果，应主动规避而非被动捕获。
- 使用分页控件（
PagedResultsControl）代替一次性大查询，将“部分成功”转化为可控的多次小请求 - 设置合理的
java.naming.ldap.timeout和java.naming.ldap.maxsize，让异常更早暴露、更易定位 - 在服务治理层面，对JNDI调用做熔断和降级——例如缓存最近一次完整结果，异常时返回缓存+告警
