创建数据传输对象(DTO)或数据对象
何时使用
当数据跨越边界,或者必须被Web、API、Livewire、任务、命令或集成复用的时候,使用此技能。
所需输入
- 字段、类型、验证规则、源边界、输出消费者、默认值和序列化需求。
工作流程
- 检查已有的数据对象约定。
- 默认使用现已安装的Spatie Laravel Data。如果附近模块中存在不同的数据风格,请遵循本地约定。
- 对于不可变的DTO,优先使用
final readonly class和构造器属性提升。 - 在合适的属性上使用Spatie Data属性:
#[MapInputName]#[MapOutputName]#[WithCast]#[WithTransformer]#[Computed]#[ValidationAttribute]或包内的验证属性#[DataCollectionOf]#[Lazy]#[Hidden]#[LoadRelation]和#[LoadMissing]- 当包或项目约定使用时,使用
#[Inject]或属性注入属性
- 对于封闭集合使用枚举,对于可复用的标量约定使用类型化的类常量。
- 保持DTO与客户端无关。
- 仅在有用时添加命名构造函数,例如
fromArray、fromRequest或fromModel。 - 当项目约定支持时,将验证规则放在DTO附近。
- 避免持久化、授权或工作流逻辑。
- 为构造、验证规则、序列化和边界情况编写测试。
可能创建的文件
app/Data/*.php、app/DTOs/*.php或现有的本地等效文件。- DTO测试。
可能修改的文件
- 表单请求、动作、资源、Livewire组件、控制器、任务和测试。
架构规则
- DTO代表输入或输出契约。
- DTO支持API和UI的复用。
- DTO不得依赖Livewire、Blade、控制器或响应。
- 在实际可行的情况下,DTO应使用现代PHP类型,而不是非结构化数组。
- 当功能需要嵌套、转换或可复用的数据形状时,使用Spatie Data集合/资源。
- 优先使用Spatie Data验证属性,而非在可复用代码内进行临时数组验证。
测试要求
- 测试必填字段、类型转换、默认值、无效数据,以及暴露的序列化。
安全要求
- 不要将DTO构造视为授权。
- 除非明确需要,否则避免在输出DTO中包含敏感字段。
评审清单
- DTO是否稳定且与客户端无关?
- 字段是否已类型化?
- 验证规则是否足够接近以保持同步?
示例
好的示例
namespace App\Data;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Attributes\Validation\Max;
final readonly class RegisterUserData extends Data
{
public function __construct(
#[Required, Max(255)]
public string $name,
#[Required, Email]
public string $email,
) {}
}
不好的示例
// ❌ 类型安全性差,没有验证上下文,难以在后台任务中复用。
class RegisterController extends Controller
{
public function store(Request $request)
{
$this->action->handle($request->all());
}
}