4. 核心概念对齐：用户、角色、权限、资源、策略的定义与关系

在IAM权限模型重构中，概念对齐是接口契约与数据契约能够协同工作的基础。不同团队（前端、后端、安全、运维）对同一术语的理解偏差，往往是权限错乱、接口冗余、数据不一致的根源。本节将严格定义五个核心实体——用户、角色、权限、资源、策略，并阐明它们之间的结构化关系。

4.1 核心概念定义

下表从业务语义、数据契约和接口契约三个维度对齐每个概念：

概念 业务语义 数据契约（核心字段） 接口契约（典型操作）
用户 (User) 系统的自然人/服务账号，是权限的最终主体 user_id, username, status, department_id POST /users, GET /users/{id}, PATCH /users/{id}/status
角色 (Role) 权限的逻辑分组，用于简化授权管理 role_id, role_name, role_type, description POST /roles, GET /roles/{id}, PUT /roles/{id}/permissions
权限 (Permission) 对某个资源执行特定操作的许可 perm_id, action, resource_type, effect POST /permissions, GET /permissions, DELETE /permissions/{id}
资源 (Resource) 被保护的对象，可以是API、数据、菜单、文件等 resource_id, resource_type, resource_path, parent_id POST /resources, GET /resources/tree, PATCH /resources/{id}
策略 (Policy) 一组权限规则的集合，支持条件、优先级和生效范围 policy_id, policy_name, statements[], effect, condition POST /policies, GET /policies/{id}, POST /policies/evaluate
对齐要点：在重构过程中，user_id 和 role_id 必须作为全局唯一标识符在接口与数据层保持一致；resource_path 建议采用 /v1/{resource_type}/{resource_id} 的规范格式，避免前端与后端对资源定位产生歧义。

4.2 概念关系模型

五个核心概念并非孤立存在，它们通过多对多关联和层级继承构成完整的权限模型。下图展示了标准RBAC（基于角色的访问控制）扩展模型中的实体关系：

核心概念关系模型（RBAC扩展） 用户 (User) user_id, username 角色 (Role) role_id, role_name 权限 (Permission) perm_id, action 资源 (Resource) resource_path 策略 (Policy) condition, effect N:N 关联 N:N 关联 作用于 绑定 引用 关系说明： • 用户与角色：多对多，一个用户可拥有多个角色，一个角色可被多个用户继承。 • 策略是高级抽象：可包含条件表达式（如时间、IP范围），覆盖多个权限和资源。

4.3 关系矩阵与约束规则

在接口契约与数据契约对齐过程中，以下关系矩阵定义了每个关联的基数和约束：

源实体 目标实体 关系类型 基数 关键约束
用户 角色 关联 (Assignment) M:N 同一用户不能重复关联同一角色；角色被禁用时，关联自动失效
角色 权限 包含 (Containment) M:N 权限变更后，所有关联角色的生效状态需重新计算
权限 资源 作用 (Target) M:1 一个权限只能作用于一个资源类型；资源删除时，关联权限需级联清理
策略 角色 绑定 (Binding) 1:N 策略可绑定多个角色；策略生效条件为 AND 逻辑
策略 权限 引用 (Reference) 1:N 策略引用权限时，可额外指定 condition 和 priority
数据契约对齐示例：在数据库层面，user_role 关联表必须包含 created_at 和 expired_at 字段，以支持临时授权和自动过期。接口契约中，POST /users/{id}/roles 请求体应包含 role_id 和 duration 参数，而非仅 role_id。

4.4 策略驱动的权限评估流程

当用户发起请求时，IAM系统需要按照以下评估流程确定是否放行。该流程直接映射到接口契约中的 POST /policies/evaluate 端点：

  1. 身份解析：根据请求中的 token 或 API Key 解析出 user_id。
  2. 角色加载：查询 user_role 关联表，加载用户所有有效角色。
  3. 策略聚合：根据角色加载绑定的策略列表，按 priority 降序排列。
  4. 条件匹配：逐条评估策略中的 condition（如时间窗口、来源IP、请求方法）。
  5. 权限裁决：匹配到第一条 effect=allow 的策略则放行；若全部为 deny 或未匹配，则拒绝。
常见陷阱：在接口契约设计中，POST /policies/evaluate 的响应必须包含 matched_policy_id 和 reason 字段，否则前端无法排查“为什么有角色权限但请求被拒”的问题。数据契约中，策略的 condition 字段建议使用 JSON Schema 格式存储，而非纯文本。

4.5 概念对齐的接口契约示例

以下是一个策略绑定与评估的完整接口契约示例，展示了五个核心概念如何在实际API中协同：

// 请求：为用户绑定角色并附加策略
POST /api/v1/users/1001/roles
Content-Type: application/json

{
  "role_id": "role_admin",
  "policy_bindings": [
    {
      "policy_id": "policy_time_restrict",
      "priority": 10,
      "parameters": {
        "allowed_hours": ["09:00", "18:00"],
        "timezone": "Asia/Shanghai"
      }
    }
  ],
  "duration": "P30D"
}

// 响应：返回绑定后的权限快照
HTTP/1.1 200 OK
Content-Type: application/json

{
  "user_id": "1001",
  "role_id": "role_admin",
  "effective_permissions": [
    {
      "resource_path": "/api/v1/orders/*",
      "actions": ["GET", "POST"],
      "effect": "allow",
      "source_policy": "policy_time_restrict"
    }
  ],
  "expired_at": "2025-08-01T09:00:00Z"
}

该接口同时涉及用户（user_id）、角色（role_id）、策略（policy_bindings）、权限（effective_permissions）和资源（resource_path），是五个核心概念对齐的典型体现。

← 上一章 📖 返回目录 下一章 →