📚 课程目录第3章架构级权限矩阵定义

3、架构级权限矩阵定义

架构级权限矩阵是后端合规边界的核心数据模型，它决定了“谁”在“什么条件下”可以对“哪些资源”执行“何种操作”。在 CI/CD 部署中，该矩阵必须脱离硬编码，以可注入、可审计、可演化的形态存在。本节从矩阵的维度与粒度两个层面展开定义。

3.1 矩阵的四维模型

权限矩阵由四个核心维度构成：用户（User）、角色（Role）、资源（Resource）、动作（Action）。四者共同形成一张笛卡尔积约束表，任何一次 API 调用均可映射为矩阵中的一个交点。

维度	定义	示例值
用户（User）	发起请求的实体，可以是自然人、服务账号或系统进程	`user:zhang.san`、`svc:deploy-bot`
角色（Role）	用户与权限之间的逻辑分组，支持继承与组合	`role:admin`、`role:readonly`
资源（Resource）	被访问的对象，通常以 URI 模式或资源类型标识	`/api/v2/orders/{id}`、`type:invoice`
动作（Action）	对资源执行的操作，遵循 CRUD 或自定义语义	`create`、`read`、`update`、`delete`、`approve`

  合规要点： 四维模型必须支持 负向权限（Deny） 的显式声明。在矩阵中，Deny 规则的优先级应高于 Allow 规则，防止角色继承导致权限意外扩散。

3.2 矩阵的三层粒度

权限矩阵的粒度决定了合规边界的精细程度。粒度越细，安全控制越精确，但策略管理的复杂度也越高。在架构级定义中，我们通常将粒度划分为三个层次：API 级、字段级、数据行级。

3.2.1 API 级粒度

API 级粒度是最基础的权限控制层，以 HTTP 方法 + URI 路径为判定单元。例如：POST /api/v2/orders 仅允许 role:order_admin 执行。该粒度适用于大部分粗粒度场景，性能开销最低。

3.2.2 字段级粒度

字段级粒度控制对资源中特定属性的读写权限。例如：用户 A 可以读取订单的 status 和 amount 字段，但无权查看 customer_phone 字段。字段级权限通常在 API 网关或序列化层进行拦截。

3.2.3 数据行级粒度

数据行级粒度（Row-Level Security, RLS）是最精细的控制层，根据请求上下文动态过滤数据行。例如：销售经理只能查看自己管辖区域的订单记录。RLS 通常在数据库查询层通过 WHERE 子句注入实现。

粒度层级	控制单元	实现位置	性能影响	典型场景
API 级	HTTP 方法 + URI	API 网关 / 中间件	低	角色路由、功能开关
字段级	JSON 属性 / 列名	序列化层 / GraphQL Resolver	中	隐私数据脱敏、PII 保护
数据行级	数据行 / 记录	ORM 查询构建 / 数据库策略	高	多租户隔离、区域数据隔离

架构陷阱： 不要试图在单一位置实现所有粒度的权限控制。API 级权限应在网关层处理，字段级权限应在服务层处理，数据行级权限应在数据访问层处理。跨层混合会导致策略难以审计和调试。

3.3 矩阵的存储与注入策略

在 CI/CD 部署中，权限矩阵不应硬编码在代码仓库中，而应作为配置数据存储在外部策略引擎（如 OPA、Casbin、AWS Cedar）或配置中心（如 etcd、Consul）。部署流水线在构建阶段将矩阵序列化为 JSON/YAML 格式，并通过 Sidecar 或 Init Container 注入到目标服务中。

最佳实践： 权限矩阵的版本号应与应用版本号解耦。矩阵变更应走独立的审批与审计流程，避免因权限策略更新而触发全量应用部署。

// 权限矩阵 JSON 示例（简化）
{
  "matrix_version": "2025.03.01",
  "policies": [
    {
      "user": "*",
      "role": "order_admin",
      "resource": "/api/v2/orders/*",
      "action": ["create", "read", "update", "delete"],
      "effect": "Allow"
    },
    {
      "user": "*",
      "role": "order_viewer",
      "resource": "/api/v2/orders/*",
      "action": ["read"],
      "effect": "Allow",
      "field_restrictions": {
        "exclude": ["customer_phone", "internal_note"]
      }
    },
    {
      "user": "*",
      "role": "regional_manager",
      "resource": "/api/v2/orders/*",
      "action": ["read"],
      "effect": "Allow",
      "row_filter": "region == request.context.region"
    }
  ]
}

上述示例展示了三种粒度的策略共存于同一矩阵中：order_admin 拥有完整的 API 级权限；order_viewer 在 API 级权限基础上附加了字段级限制；regional_manager 则进一步叠加了数据行级过滤条件。CI/CD 流水线在部署时将此矩阵注入到服务的策略评估引擎中，实现运行时动态权限判定。