Communitygithub.com

AlizHarb/agent-skills

一個持續增長的高品質 AI 助手技能集合,專門為 Laravel、軟體架構、除錯、測試、安全、程式碼品質、文件及工程最佳實務,強化 Codex、Claude Code、Cursor、Gemini CLI 及相容的 AI 代理。

agent-skills 是什麼?

這個技能是關於「建立 DTO 或資料物件」,專門為 AI 輔助編碼助手(如 Codex、Claude Code、Cursor、Gemini CLI 等)設計。它提供了一個標準化的工作流程,指導開發人員在資料跨越邊界或需在網頁、API、Livewire、工作、命令或整合中重複使用時,建立不可變的資料傳輸物件 (DTO)。此技能優先使用 Spatie Laravel Data 套件,並強調使用 `final readonly class` 搭配建構子屬性提升、豐富的 Spatie Data 屬性(如 `#[MapInputName]`、`#[WithCast]` 等),以及枚舉和型別常數來確保型別安全。它明確禁止在 DTO 中包含持久化、授權或工作流程邏輯,並要求針對建構、驗證規則、序列化及邊界情況編寫測試,確保 DTO 穩定、客戶端無關且可安全重用。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

建立 DTO 或資料物件

使用時機

當資料跨越邊界,或必須被網頁、API、Livewire、工作、命令或整合重複使用時,使用此技能。

需要的輸入

  • 欄位、型別、驗證規則、來源邊界、輸出消費者、預設值及序列化需求。

工作流程

  1. 檢查現有的資料物件慣例。
  2. 由於 Spatie Laravel Data 已安裝,預設使用它。如果附近模組中存在不同的資料風格,請遵循當地慣例。
  3. 對於不可變的 DTO,優先使用 final readonly class 搭配建構子屬性提升。
  4. 在屬性適合的地方使用 Spatie Data 屬性:
    • #[MapInputName]
    • #[MapOutputName]
    • #[WithCast]
    • #[WithTransformer]
    • #[Computed]
    • #[ValidationAttribute] 或套件驗證屬性
    • #[DataCollectionOf]
    • #[Lazy]
    • #[Hidden]
    • #[LoadRelation] 和 #[LoadMissing]
    • #[Inject] 或屬性注入屬性(當套件或專案慣例使用它們時)
  5. 使用枚舉表示封閉集合,使用型別類別常數表示可重複使用的純量協定。
  6. 保持 DTO 與客戶端無關。
  7. 僅在有用時添加命名建構子,例如 fromArray、fromRequest 或 fromModel。
  8. 當專案慣例支援時,將驗證規則放在 DTO 附近。
  9. 避免持久化、授權或工作流程邏輯。
  10. 針對建構、驗證規則、序列化及邊界情況添加測試。

可能建立的檔案

  • 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());
    }
}

相關技能