Hyperf数据库字段加密解密方法

本文深入解析了在 Hyperf 框架中通过 Model 的 get/set mutator 实现数据库敏感字段（如手机号、身份证号）自动加解密的完整方案，强调轻量、低侵入的模型层拦截机制，并指出硬编码加密逻辑、忽略 null 处理、误用 $casts 等常见误区；同时重点提醒：mutator 无法覆盖 where/update/select 等原始查询场景，必须配套扩展查询构建器、重写批量操作逻辑、统一管理密钥与加解密服务，才能真正保障数据安全落地——这远不止是加两行方法，而是一套需全局设计的加密治理体系。

Hyperf Model 中如何用 getMutator 和 setMutator 拦截字段读写

Hyperf 的 Model 支持通过命名约定的 mutator 方法拦截字段访问，这是实现自动加解密最轻量、侵入性最小的方式。它不依赖中间件或全局事件，只在模型层面生效，适合敏感字段（如 id_card、phone、email）的按需加密。

关键点在于：Hyperf 会自动识别形如 get{Field}Attribute 和 set{Field}Attribute 的方法，并在 $model->field 读取或赋值时触发。

• 字段名需为小写下划线风格（如 user_phone），对应 mutator 方法名为 getUserPhoneAttribute / setUserPhoneAttribute
• 加密逻辑应放在 setXxxAttribute 中，解密放在 getXxxAttribute 中；数据库存的是密文，应用层看到的是明文
• 务必避免在 mutator 中调用 $this->attributes['xxx'] 直接读写，否则会触发无限递归
• 如果字段允许为 null，mutator 内需显式判断，否则 null 会被当成空字符串加密

加解密逻辑该放哪？推荐封装成独立 Service

把 AES 加解密逻辑硬写在 mutator 里会导致模型臃肿、难以测试，也违反单一职责。更合理的方式是抽离为一个可注入的 CryptService，通过构造函数或属性注入到 Model 中。

注意 Hyperf 的 Model 默认不是容器管理对象，不能直接 @Inject，需手动在构造函数中获取：

public function __construct(array $attributes = [])
{
    parent::__construct($attributes);
    $this->cryptService = ApplicationContext::getContainer()->get(CryptService::class);
}

• CryptService 应支持指定密钥、IV、算法（如 AES-128-CBC），并统一处理 padding 和 base64 编码
• 避免使用静态方法调用加密工具类，否则无法 mock 单元测试
• 生产环境密钥严禁写死，建议从 config/autoload/crypt.php 或 Vault 加载

为什么不能用 casts 实现自动加解密？

Hyperf（及 Laravel）的 $casts 属性仅支持基础类型转换（如 'created_at' => 'datetime'），底层调用的是 PHP 类型强制转换或 Carbon 构造，**不支持任意逻辑**。试图写 'phone' => PhoneCryptCast::class 会失败，因为框架不会实例化或调用自定义 cast 类的任何方法。

• $casts 是只读映射，仅影响 toArray()、jsonSerialize() 和属性赋值时的类型推导
• 即使继承 Castable 接口，Hyperf 当前版本（v3.0+）仍未实现对自定义 cast 的完整支持
• 强行绕过用 setAttribute + getAttribute 重写，会丢失批量赋值（fill()）、Eloquent 关系、JSON 序列化等行为的一致性

容易被忽略的边界问题：批量操作与原始查询

mutator 只在模型属性访问时生效，以下场景完全绕过加密逻辑，必须额外处理：

• User::where('user_phone', $plain)->first() —— 这里查的是明文，但数据库存的是密文，必然查不到；应改用 whereEncrypted('user_phone', $plain) 扩展查询方法
• User::query()->update(['user_phone' => $plain]) —— 直接执行 SQL，mutator 不触发；需配合 updating 事件或重写 update 方法
• User::select('user_phone')->get() —— 返回的是密文字符串，不会自动解密；需在 collection 上 map 或改用 selectRaw("AES_DECRYPT(user_phone, ?) as user_phone", [$key])
• 软删除字段（deleted_at）若参与加密，会导致 withTrashed() 查询异常，建议排除敏感字段的软删逻辑

真正落地时，加密字段往往需要配套的查询构建器扩展、迁移字段注释说明、以及 DB 备份前的解密脚本——这些都不是加两行 mutator 就能闭环的。

到这里，我们也就讲完了《Hyperf数据库字段加密解密方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！