Trait Mutator 

pub trait Mutator: Accessor {
    // Required method
    fn mutator_for(
        &mut self,
        field: &str,
        value: &Value,
        merged_data: &HashMap<String, Value>,
    ) -> Option<MutatorResult>;

    // Provided methods
    fn set_attr(
        &mut self,
        name: &str,
        value: Value,
        data: Option<&HashMap<String, Value>>,
    ) { ... }
    fn set_attrs(&mut self, data: &HashMap<String, Value>) { ... }
}

修改器 trait — 对齐 PHP setAttr / setXxxAttr

PHP 对齐

PHP 方法	Rust 等价	说明
setAttr($name, $value, $data)	Self::set_attr()	入口方法
setXxxAttr($value, $data)	Self::mutator_for()	业务模型按字段派发
setAttrs($data)	Self::set_attrs()	批量赋值

修改器第二参数 merged_data

PHP setXxxAttr($value, $data) 中 $data = array_merge($this->data, $data)， 即「当前模型数据 + 外部批量数据」的合并。Rust 中 Self::mutator_for() 第三参数 merged_data 保留此语义。

优先级

1. 方法修改器 mutator_for → 若返回 Some 则使用其结果
2. 无修改器 → 原样写入 data_map

$type 类型转换 / 关联属性 / __toString 由各功能模块分别实现，当前阶段仅支持方法修改器。

Required Methods

fn mutator_for( &mut self, field: &str, value: &Value, merged_data: &HashMap<String, Value>, ) -> Option<MutatorResult>

业务模型重写：按字段名派发到具体修改器

参数

• field：归一化后的字段名
• value：被设置的值（引用，修改器按需 clone）
• merged_data：data_map + 外部 data 的合并（对应 PHP array_merge）

返回

• None：无修改器，原样写入 data
• Some(MutatorResult::Value(v))：写入 v 到 data
• Some(MutatorResult::Skip)：跳过默认赋值（对应 PHP null + data modified 提前返回）

Provided Methods

fn set_attr( &mut self, name: &str, value: Value, data: Option<&HashMap<String, Value>>, )

入口方法 — 对应 PHP setAttr($name, $value, $data)

执行流程（对齐 Attribute.php 第 367-395 行）：

1. 字段名归一化
2. 构造 merged_data（data_map + 外部 data）
3. 派发到 mutator_for
4. 处理 Skip / Value / None 三种结果
5. 失效同名字段访问器缓存（对应 PHP unset($this->get[$name])）

fn set_attrs(&mut self, data: &HashMap<String, Value>)

批量赋值 — 对应 PHP setAttrs($data)

对每个字段调用 set_attr，第三参数传完整 data（使修改器能感知批量上下文）。

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors