本文介绍如何在 laravel 中通过模型访问器（accessors）、修改器（mutators）结合自定义字段映射机制，实现数据库字段与前端字段的全自动双向转换，避免控制器中重复调用 transform()，提升大型遗留系统的可维护性。
在处理遗留数据库时，前后端字段命名不一致是常见痛点——例如数据库用 first_name，而前端期望 firstName；或需对数值做格式化（如金额存为分，返回为元）。若每次请求都在 Controller 或 Service 层手动转换，不仅冗余，还易出错、难维护。Laravel 原生提供的 访问器（Accessors）与修改器（Mutators） 是解决此问题的核心机制，再辅以轻量级字段映射逻辑，即可实现真正“模型层自治”的双向转换。
✅ 推荐方案：访问器 + 修改器 + 自定义 $maps 映射
Laravel 模型天然支持 get{Attribute}Attribute() 和 set{Attribute}Attribute() 方法，它们分别在读取和赋值属性时自动触发。结合一个简单的 $maps 配置数组，即可统一管理字段别名映射：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Person extends Model
{
// 【关键】声明数据库字段 → 前端字段的映射关系
protected $maps = [
'first_name' => 'firstName',
'last_name' => 'lastName',
'birth_date' => 'birthDate',
'salary_cents'=> 'salary', // 存储为分，对外显示为元
];
// 【访问器】将数据库值转为前端所需格式
public function getFirstNameAttribute($value)
{
return $value ? ucfirst(strtolower($value)) : null;
}
public function getSalaryAttribute($value)
{
return $value ? $value / 100 : 0.0;
}
public function getBirthDateAttribute($value)
{
return $value ? \Carbon\Carbon::parse($value)->format('Y-m-d') : null;
}
// 【修改器】将前端传入值转为数据库存储格式
public function setFirstNameAttribute($value)
{
$this->attributes['first_name'] = trim($value);
}
public function setSalaryAttribute($value)
{
$this->attributes['salary_cents'] = (int) round((float) $value * 100);
}
public function setBirthDateAttribute($value)
{
$this->attributes['birth_date'] = $value
? \Carbon\Carbon::parse($value)->format('Y-m-d')
: null;
}
}? 注意：$maps 本身不被 Laravel 自动识别，它仅作为开发者约定的配置项。真正的字段别名能力由 Eloquent 的 casts、appends、hidden 及访问器/修改器协同完成。
? 使用示例：零侵入式 API 开发
启用上述模型后，Controller 完全无需手动转换：
// 创建（自动转换输入 → 数据库格式）
public function store(Request $request)
{
$person = Person::create($request->only([
'firstName', 'lastName', 'birthDate', 'salary'
]));
return response()->json($person, 201); // 自动转换数据库值 → 前端格式
}
// 查询（自动转换数据库值 → 响应格式）
public function show($id)
{
$person = Person::findOrFail($id);
return response()->json($person); // 返回已格式化的 firstName、salary 等
}此时 $person-youjiankuohaophpcnfirstName 会触发 getFirstNameAttribute()，而 $person->firstName = 'john' 会触发 setFirstNameAttribute() —— 转换完全透明、不可绕过。
⚠️ 注意事项与进阶建议
- 不要滥用 $casts 替代逻辑转换：$casts = ['salary_cents' => 'integer'] 仅做类型转换，无法实现单位换算或字符串标准化，务必用修改器/访问器。
- 保持 fillable 与前端字段一致：若前端提交 firstName，请确保模型中 protected $fillable = ['firstName', 'lastName'];，Eloquent 会自动委托给对应修改器。
- 序列化控制：使用 protected $appends = ['fullName']; 配合 getFullNameAttribute() 可添加计算字段；用 protected $hidden = ['first_name', 'last_name']; 隐藏原始字段，避免混淆。
- 批量更新安全提示：Person::where(...)->update([...]) 不触发修改器！该方法直接执行 SQL。如需强一致性，请始终使用模型实例操作（如 save() 或 fill()->save()）。
- 扩展性增强（可选）：可封装为 Trait（如 HasFieldMapping），在多个模型中复用 $maps 解析与通用访问器逻辑，进一步解耦。
通过这种模型驱动的设计，你将告别散落在各处的 transform() 调用，让数据契约清晰固化在领域层——既符合 Laravel 的设计哲学，也显著提升了遗留系统在快速迭代中的健壮性与可读性。
