建立 DTO 或資料物件
使用時機
當資料跨越邊界,或必須被網頁、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());
}
}