TP8.0 API接口字段级细粒度权限控制实现

字段级权限控制听起来是一项细致的工作，但实际落地时，它比接口级别的拦截复杂得多。TP8.0 的方案核心不在于“能否拦截”，而在于“放行后，响应数据中到底携带了什么”。ACL 在此的角色不是路由守卫，而是数据组装阶段的动态脱敏器——请求进入，但敏感字段在最后一步被悄然裁剪掉。

简单来说，ThinkPHP 的中间件或 AuthRule::check() 只能判断“能否进入这个门”，但无法控制“出门时口袋里装了什么”。字段级别的控制必须在模型数据转换为 JSON 之前介入——例如在资源类（Resource）、DTO 构造器或统一响应封装层中进行处理。

字段权限必须在数据组装阶段干预

• 不建议在控制器中手动 unset() 字段，因为容易遗漏、难以复用，且测试困难。
• 推荐在 Resource 层做字段白名单/黑名单：比如定义 $visible 或 $hidden，但必须结合当前用户上下文动态计算。
• 如果采用 DTO 模式，构造 DTO 实例时传入 $user，由 DTO 自己决定是否填充 salary、id_card 等敏感字段。

用 ACL 服务统一管理字段可读规则

字段权限不应硬编码到模型或 Resource 中，而应抽象出一个 AclFieldService，接收三个参数：user、resource_type（例如 'user'）、field_name（例如 'salary'），返回 true 或 false。

• 规则来源可以是数据库 permission_conditions 表，支持条件表达式，例如 role == 'hrbp' && dept_id == user.dept_id。
• 缓存策略：key 设为 field_acl_{$uid}_{$resource}_{$field}，TTL 10 分钟，权限变更时主动删除。
• 调用示例：if (! app(AclFieldService::class)->canRead($user, 'user', 'salary')) { $data['salary'] = null; }

资源标识与字段权限解耦设计

• 正确写法：user:profile:email（用户资料页的邮箱字段）、order:detail:refund_amount（订单详情中的退款金额）
• 错误写法：/api/users/123/email —— 路径含 ID，无法缓存复用；且与前端字段名耦合过紧
• 字段权限可继承：若 user:profile 整体不可读，则其下所有字段默认不可读，除非显式授权

API 响应明确反馈缺失字段权限

• 响应结构建议增加 missing_permissions 字段，值为字符串数组，如 ["user:profile:salary"]
• 开发环境开启该字段，生产环境可关闭以减少暴露面
• 日志中记录字段拦截事件，包含 user_id、resource_id、field、timestamp，供安全审计