AccessPolicy Spec

表达访问控制策略的定义语义。当前实现优先使用结构化字段（subject + rules）；subjectType / subjectId / resourceRef / action / effect 为兼容展平字段，结构化字段缺失时才会回退使用。

写入服务会先把结构化字段归一化为展平字段，再按运行时语义键定位并 upsert。

AccessPolicySpecDTO

字段类型说明
namestring自然键。策略名称，写入运行态时作为 policyName，并用于通配符策略展开分组与按名称删除
subjectTypestring主体类型，例如 USER / ROLE / GROUP（展平兼容字段；subject 存在时忽略）
subjectIdstring主体标识（展平兼容字段；subject 存在时忽略）
resourceRefResourceRefDTO资源引用（展平兼容字段；rules 存在时忽略）。kind 归一化为 ObjectType，name 作为资源语义名
actionstring动作，例如 READ / WRITE / MANAGE（展平兼容字段；rules 存在时忽略）
effectstring策略效果，例如 ALLOW / DENY（展平兼容字段；rules 存在时忽略）
rowFilterObject行级过滤条件，可为对象或数组。rules 存在时取第一条规则的 rowFilter，否则取本字段
maskedColumnsObject字段脱敏配置，可为对象或数组
priorityinteger优先级。未指定时默认 0
subjectAccessPolicySubjectDTO推荐。结构化主体；设置时无需再写 subjectType / subjectId
rulesList<AccessPolicyRuleDTO>推荐。结构化规则列表；当前实现仅消费第一条规则

子结构消费说明

AccessPolicySubjectDTO

字段说明
roleCode角色编码。设置时主体类型推导为 ROLE，主体标识为该值
userCode用户编码。设置时主体类型推导为 USER，主体标识为该值
groupCode用户组编码。设置时主体类型推导为 GROUP，主体标识为该值

三者互斥，优先命中第一个非空字段（顺序：roleCode → userCode → groupCode）。

AccessPolicyRuleDTO

字段类型说明
objectRefResourceRefDTO资源引用。kind 归一化为 ObjectType；name 为语义名，* 表示匹配全部对象类型
actionstring动作，例如 READ / WRITE / MANAGE
effectstring策略效果，例如 ALLOW / DENY
rowFilterObject行级过滤条件，可为对象或数组
maskedColumnsObject字段脱敏配置，可为对象或数组
priorityinteger优先级。未指定时默认 0

消费位置

  • foundry-access-control-biz: AccessControlDefinitionWriteService.upsertAccessPolicy 将结构化字段归一化为展平字段后，按语义键定位并创建或更新策略。
  • foundry-access-control-biz: AccessPolicyDomainProjectionAdapter 调用 accessControlDefinitionApi.upsertAccessPolicy。

关键行为与约束

  1. 自然键为 name

    • 运行时 policyName 设置为该值。
    • 通配符策略展开时，按同一 policyName + 主体 + 动作/效果/优先级 分组管理。
    • deleteAccessPolicy(String policyName) 按 policyName 在工作空间内删除策略。

  2. 结构化 vs 展平字段

    • 推荐新定义统一使用 subject + rules。
    • subject 与 subjectType / subjectId 同时存在时，结构化优先。
    • rules 与展平字段同时存在时，仅读取 rules[0]，展平字段被忽略。

  3. 资源类型归一化

    • resourceRef.kind / objectRef.kind 为 OBJECT_TYPE（不区分大小写）时，运行时存储为 ObjectType。
    • 为空时默认按 ObjectType 处理。

  4. ObjectType 通配符展开

    • 当 objectRef.kind = ObjectType 且 objectRef.name = '*' 时，触发通配符策略。
    • 服务会按当前工作空间内的所有对象类型名称，展开为逐对象策略（每个 ObjectType 一条记录）。
    • 展开前会清理同一 policyName 下已不存在或多余的对象级记录，保证幂等。

  5. rowFilter 必填（ALLOW 场景）

    • effect = ALLOW 时必须提供 rowFilter。
    • 允许全部行时写： 
      rowFilter:
  operator: 'TRUE'

  6. 语义键与更新范围

    • 存在性判断语义键：subjectType + subjectId + resourceType + action + effect + priority（若解析出具体 resourceId，同时参与匹配）。
    • 已存在时：subjectType / subjectId / resourceType / action 语义键不可变，仅可更新 effect、priority、rowFilter、maskedColumns。
    • 不存在时创建新策略。

相关文档