MongoDB在分片集群中通过zone机制可以将指定范围的数据路由到特定的分片上，这种能力在数据本地化、合规存储等场景中非常实用。而要查看当前分片集合上已经配置了哪些zone，除了传统的listZones命令之外，从MongoDB 6.0.3开始，还可以在聚合管道中使用$listShardZones阶段来获取分片区域的详细信息。本文将围绕这个聚合阶段的语法、返回结构、权限要求和实际用法展开讲解。
一、$listShardZones的基本语法与返回结构
$listShardZones是一个聚合管道阶段，语法非常简单，它不接受任何参数，直接附加在aggregate命令后面即可。需要注意的是，它必须作用于分片集合，如果在非分片集合上执行，会返回空结果或报错提示集合未分片。
基本写法如下：
db.orders.aggregate([
{ $listShardZones: {} }
])执行后返回的是一个文档数组，每个文档代表一个zone的配置信息，典型结构如下：
{
_id: ObjectId("64a1b2c3d4e5f67890123456"),
zone: "zone_california",
min: { region: "west", zip: MinKey },
max: { region: "west", 90210 },
shard: "shard0001"
}其中各字段含义分别是：zone表示区域名称；min和max定义了该zone覆盖的分片键范围，是一个前缀闭区间，即包含min但不包含max；shard表示该zone关联到的分片名称。理解min和max的边界语义非常关键，因为zone的范围必须与分片键的前缀匹配，否则在添加zone时会直接报错。
二、使用前提与权限要求
使用$listShardZones有几个前提条件需要满足。第一，MongoDB版本必须是6.0.3及以上，低版本中不存在这个聚合阶段，会抛出无法识别的管道阶段错误。第二，执行的集合必须是分片集合，通常会在admin数据库上通过聚合命令运行，或者直接对目标分片集合执行。
在权限方面，该阶段要求用户具备listZones权限动作，内置角色clusterManager或hostManager包含了这一权限。如果使用普通读写账号执行，会收到未授权的错误提示。示例授权语句如下：
use admin
db.createRole({
role: "zoneViewer",
privileges: [
{ resource: { cluster: true }, actions: [ "listZones" ] }
],
roles: []
})此外还要注意，$listShardZones返回的是配置服务器上元数据中的zone信息，它反映的是配置时刻的静态信息，如果并发地执行addShardToZone或updateZoneKeyRange操作，读到的结果可能存在短暂的不一致，这在自动化运维脚本中需要做好容错处理。
三、实际操作示例与常见问题排查
下面通过一个完整流程演示如何创建zone并查询。首先给分片添加zone，然后为集合的某个分片键范围绑定zone，最后用$listShardZones验证结果。
// 1. 将zone关联到分片
sh.addShardToZone("shard0001", "zone_california")
// 2. 为集合的分片键范围绑定zone
sh.updateZoneKeyRange(
"shop.orders",
{ region: "west", zip: MinKey },
{ region: "west", zip: 90210 },
"zone_california"
)
// 3. 查看分片集合上的zone配置
db.getSiblingDB("shop").orders.aggregate([
{ $listShardZones: {} }
])返回结果中可以看到zone_california对应的最小值和最大值范围，以及它所绑定的分片shard0001。通过这个结果，运维人员可以快速核对数据路由是否符合预期，比如确认美国西部订单确实被写入到了位于西海岸机房的分片上。
常见问题方面，如果查询结果为空，可以从三个方向排查：一是确认集合是否真的已经分片，可用sh.status()查看；二是确认zone范围是否绑定到了正确的命名空间，命名空间由库名加点号加集合名组成；三是检查版本是否满足要求。如果报错提示管道阶段不存在，多半是版本过低，建议升级或改用db.adminCommand({ listZones: 1 })作为替代方案。
与listZones命令相比，$listShardZones的优势在于它可以与其他聚合阶段组合使用，例如配合$match过滤特定分片的zone，或配合$sort按zone名称排序，这在管理大量zone的集群中更加灵活。不过要注意，它只能作为管道的第一个阶段使用，不能出现在其他阶段之后。