在Laravel中使用API Platform实现只读模型属性的最佳实践

问题背景

在API开发中，我们经常需要定义一些只读属性，这些属性只能通过GET请求访问，而不能通过POST、PUT或PATCH等写入操作修改。典型的例子包括ID字段、创建时间(created_at)和更新时间(updated_at)等系统自动管理的字段。

解决方案探索

1. 使用ApiProperty注解

API Platform提供了ApiProperty注解来定义属性的读写权限。在Laravel模型中，我们可以通过以下两种方式应用这个注解：

方法一：直接定义属性

#[ApiProperty(writable: false)]
protected string $email;

这种方式简单直接，但需要注意Laravel的魔术属性访问机制。

方法二：使用属性访问器

#[ApiProperty(writable: false)]
public function email(): Attribute
{
    return Attribute::make(
        get: fn(string $value) => $value
    );
}

这是Laravel推荐的方式，更符合Eloquent模型的设计模式。

2. 处理系统默认字段

对于Laravel自动管理的字段(如id、created_at、updated_at)，我们需要特别注意：

在具体模型中定义

#[ApiProperty(writable: false, property: 'created_at')]
class Tenant extends Model
{
    // ...
}

在抽象基类中定义

abstract class AbstractModel extends Model
{
    #[ApiProperty(writable: false)]
    public \DateTime $created_at;
}

但要注意，直接定义属性可能会影响Laravel的自动填充机制。

3. 利用Laravel的fillable属性

API Platform可以考虑与Laravel的fillable属性集成，自动将不在fillable数组中的字段设为只读。这种方案更符合Laravel的习惯用法，也能减少重复配置。

最佳实践建议

1. 对于自定义字段：优先使用属性访问器方式配合ApiProperty注解
2. 对于系统字段：在抽象基类中统一定义，保持一致性
3. 考虑fillable集成：等待API Platform未来版本可能提供的原生支持
4. 命名规范：注意Laravel使用snake_case命名惯例，确保属性名正确

实现示例

abstract class AbstractModel extends Model
{
    use HasUuids;

    #[ApiProperty(writable: false)]
    public function id(): Attribute
    {
        return Attribute::make(get: fn(string $value) => $value);
    }

    #[ApiProperty(writable: false, property: 'created_at')]
    #[ApiProperty(writable: false, property: 'updated_at')]
}

#[ApiResource]
class Tenant extends AbstractModel
{
    #[ApiProperty(writable: false)]
    public function slug(): Attribute
    {
        return Attribute::make(get: fn(?string $value) => $value);
    }

    protected $fillable = [
        'company_name',
        'firstname',
        'lastname',
    ];
}

通过这种方式，我们可以确保系统字段和自定义只读字段都得到正确处理，同时保持代码的整洁和可维护性。