MongoDB聚合管道$redact如何基于权限过滤文档？

MongoDB聚合管道中的$redact阶段提供了一种按文档内容动态裁剪字段的机制。它并不是简单地过滤整篇文档，而是递归遍历文档的每一个层级，根据条件表达式返回的系统变量决定保留、删除或继续向下检查。这种能力最常见的用途就是基于权限过滤嵌套文档：当一份文档同时包含公开字段、部门私有字段以及仅管理员可见的字段时，$redact可以在一次聚合查询中根据当前访问者的角色返回不同深度的数据。不过，$redact的条件表达式只能访问当前文档以及与管道相关的系统变量，并不能自动感知当前登录用户，因此在使用前必须通过$set、$addFields等方式将用户权限注入到文档中。

一、$redact阶段的工作机制与系统变量

$redact作为聚合管道中的一个独立阶段，需要接收一个表达式，该表达式最终求值为三个特殊系统变量之一：$$KEEP、$$PRUNE或$$DESCEND。实际开发中，最常用的表达式是$cond或$switch，因为权限判断通常包含多个条件分支。下面是一个最简单的基础语法示例，它会对集合中的每个文档判断accessLevel字段是否大于等于private，满足条件则继续向下遍历，否则整篇文档被裁剪。

db.collection.aggregate([
  {
    $redact: {
      $cond: {
        if: { $gte: [ "$accessLevel", "private" ] },
        then: "$$DESCEND",
        else: "$$PRUNE"
      }
    }
  }
])

三个系统变量的含义必须区分清楚。$$KEEP表示保留当前文档，并且不再递归检查该文档内的子文档或数组元素。这意味着一旦当前层级返回$$KEEP，所有更深层的内容都会无条件保留，无论其中是否包含权限级别更低的字段。$$PRUNE表示删除当前文档，同样不再继续向下遍历。$$DESCEND则保留当前层级文档本身，但会继续递归检查它的每个子文档和数组元素，让权限判断落到更细的粒度上。理解这一点对避免越权至关重要：如果对根文档直接返回$$KEEP，就等于放弃了所有子文档级别的权限控制。

递归行为是$redact的核心特性。当当前层级返回$$DESCEND时，MongoDB会进入该文档的嵌套字段继续执行同样的条件表达式。例如一个根文档没有accessLevel字段，但它的某个子文档有accessLevel字段，那么根文档的表达式结果需要返回$$DESCEND而不是$$PRUNE，否则子文档根本没有机会被评估。很多初学者在根文档条件判断失败后直接裁剪，导致所有嵌套内容被意外删除。因此在实际权限设计中，根文档和各级子文档都必须明确设置访问级别，并且条件表达式要能够处理字段缺失的情况。

二、基于角色权限过滤嵌套文档的完整示例

假设有一个员工信息集合，每份文档都包含员工基本信息、薪资信息和绩效信息，但不同字段的敏感程度不同。基本信息对所有角色公开，薪资信息仅HR和直接经理可见，绩效评语仅经理可见。为了用$redact实现这一需求，可以先给每个层级加上accessLevel字段来标明访问级别，分别使用public、private和manager三个值。示例数据如下：

db.employees.insertMany([
  {
    _id: 1,
    name: "Alice",
    department: "Engineering",
    accessLevel: "public",
    salary: { base: 80000, bonus: 12000, accessLevel: "private" },
    performance: { rating: 4.5, managerNote: "excellent", accessLevel: "manager" }
  },
  {
    _id: 2,
    name: "Bob",
    department: "Sales",
    accessLevel: "public",
    salary: { base: 65000, bonus: 8000, accessLevel: "private" },
    performance: { rating: 3.8, managerNote: "needs coaching", accessLevel: "manager" }
  }
])

由于$redact无法直接读取当前登录用户的信息，需要先在管道中通过$set或$addFields阶段把用户角色注入到每个文档中。下面的示例将角色硬编码为hr，然后使用$switch构建完整的分支判断。每一个分支都返回$$DESCEND表示继续向下检查，都不满足时返回$$PRUNE进行裁剪。

db.employees.aggregate([
  { $set: { currentUserRole: "hr" } },
  {
    $redact: {
      $switch: {
        branches: [
          {
            case: { $eq: [ "$accessLevel", "public" ] },
            then: "$$DESCEND"
          },
          {
            case: {
              $and: [
                { $eq: [ "$accessLevel", "private" ] },
                { $in: [ "$currentUserRole", ["hr", "manager"] ] }
              ]
            },
            then: "$$DESCEND"
          },
          {
            case: {
              $and: [
                { $eq: [ "$accessLevel", "manager" ] },
                { $eq: [ "$currentUserRole", "manager" ] }
              ]
            },
            then: "$$DESCEND"
          }
        ],
        default: "$$PRUNE"
      }
    }
  }
])

当currentUserRole为hr时，根文档的accessLevel为public，因此根文档保留并继续深入。随后薪资子文档的accessLevel为private，HR属于允许角色，因此保留；绩效子文档的accessLevel为manager，HR不满足该分支，所以被裁剪。最终输出中只会保留基本信息和薪资信息，而绩效评语不会出现。如果把角色改为manager，则薪资和绩效都会保留，因为经理同时满足两个受限级别。

需要特别注意的是，如果某个子文档缺少accessLevel字段，$eq比较会返回false，导致该分支落空，最终进入default被裁剪。为避免误删，可以在每个分支的case中先判断字段存在，例如使用{ $ifNull: [ "$accessLevel", "public" ] }给缺省值，或者在文档写入时强制要求所有层级都带有accessLevel字段。实际项目中建议采用后者，通过Schema校验或应用层写入逻辑保证权限字段完整。

三、$redact与$match、视图方案的对比与性能权衡

从功能角度看，$match只能过滤顶层文档，它基于条件决定整篇文档是否保留，而无法根据文档内部某个字段的值有选择地裁剪嵌套内容。例如只凭$match无法在保留员工基本信息和薪资的同时删除绩效评语，因为同一篇文档中不同字段的可见性不能由$match实现。$redact则专门解决这种文档内部动态裁剪的问题，但它的代价也非常明显：$redact会在文档被读取后递归遍历每个子文档和数组元素，无法使用索引进行预过滤。因此通常建议将$match放在管道前面，先利用索引缩小文档数量，再对剩余文档执行$redact，这样既保证正确性又能降低性能开销。

视图是另一个常见的替代方案。如果权限规则相对固定，可以把包含$set和$redact的聚合管道定义为数据库视图，应用层直接查询视图即可。这样做的好处是权限逻辑集中管理，不会因为客户端漏写过滤条件而导致数据泄露。但视图同样无法获取当前认证用户信息，仍然需要通过客户端传入角色或使用其他手段写入文档。另外，视图中的聚合管道每次查询都会重新执行，如果数据量大，$redact的递归成本依然存在，因此视图并不能消除性能问题。

除了$redact，开发者还可以考虑应用层裁剪或字段级加密。应用层裁剪灵活，但权限逻辑分散，容易遗漏；字段级加密适合高度敏感字段，但会增加解密开销和密钥管理复杂度。$redact适合读取场景下的动态文档过滤，不适合更新或删除场景。对于权限层次简单且字段固定的情况，普通投影（projection）可能更高效，但投影只能指定固定的包含或排除字段，无法根据字段值动态判断。因此选择$redact前需要评估集合规模、嵌套深度以及权限复杂度。

四、常见错误与调试技巧

使用$redact时最容易犯的错误之一是误将$$KEEP用于根文档。因为$$KEEP会保留整个文档并停止递归，即使子文档中包含更高级别的权限限制也会被一并返回。例如根文档的accessLevel为public，条件设计者可能认为公开可见就返回$$KEEP，结果薪资和绩效子文档全部泄露。正确的做法是根文档返回$$DESCEND，让子文档继续接受权限判断。另一个常见错误是表达式返回了普通字符串DESCEND而不是$$DESCEND，或者把系统变量写成没有美元符号的变量，导致$redact无法识别。

数组处理也是需要留意的地方。$redact会递归遍历数组中的每个元素，并把每个元素当作文档来评估。如果数组元素本身是标量而非文档，它没有字段可供条件表达式比较，这时基于字段存在的条件很可能会使其被裁剪。如果希望保留数组中的标量元素，需要在条件逻辑中单独处理数组元素类型，比如通过$type判断当前元素是否为object，只有文档类型才执行权限判断，其他类型直接保留。

调试$redact管道时，建议先只运行$set阶段确认注入的角色字段是否正确，再分步加上$redact查看裁剪结果。对于复杂条件，可以临时将$switch的返回值输出到一个字段中，例如用{ $set: { decision: { $switch: ... } } }观察每个文档最终得到的决策是$$KEEP、$$PRUNE还是$$DESCEND，这样可以快速定位条件分支设计错误。最后再将该表达式迁移到$redact中执行。使用explain查看执行计划时，重点观察$redact前面的阶段是否有效利用了索引，以及被$redact处理的文档数量是否已经大幅减少，这有助于评估整体查询是否高效。

MongoDB的$redact为基于文档内容的权限过滤提供了一种原生且灵活的方案。正确使用它需要理解递归语义、精心设计权限字段和条件表达式，并结合$match、视图等手段控制性能。一旦掌握了这些要点，$redact能够在多租户、多角色系统中显著降低数据越权风险，同时保持聚合管道的简洁性。

MongoDB聚合管道$redact权限过滤修改时间：2026-08-27 18:48:20