依據 Laravel 12 官方文件 以及 Livewire 3 快速入門文件 調整後的開發標準指南，此文件旨在統一團隊在 Laravel 應用程式（含 Livewire 3 元件）上的開發風格與最佳實踐。文件中的各項規範可根據專案需求進行進一步調整與擴充。

1. 總則

  • 目標：
    • 統一程式碼撰寫風格，增進專案可讀性與維護性
    • 遵從 Laravel 12 與 Livewire 3 官方文件中的最佳實踐與建議
    • 提高團隊協作效率，降低因風格不一致而產生的錯誤與溝通成本
  • 參考文件：

2. 基本程式碼風格

2.1. 格式規範

  • PSR-12 與 Laravel 官方建議：
    • 每個 PHP 檔案以 <?php 開頭，無閉合標籤
    • 採用 4 個空白進行縮排，避免使用 Tab
    • 每行結尾不得有多餘空白，並維持統一行寬風格
  • 引號使用：
    • 根據是否需要變數解析來選擇單引號與雙引號，建議全專案內風格保持一致
  • 括號與空白：
    • 控制結構（if、foreach、while 等）應符合 PHP 與 Laravel 標準，例如控制結構與括號之間保持單一空白
    • 函式與方法定義、呼叫時內部參數列表應避免多餘空格

2.2. 文件與注釋

  • DocBlock 標註：
    • 每個類別、方法、屬性均建議撰寫 PHPDoc，明確標示參數、返回型別與可能的例外狀況
    • 針對複雜邏輯區塊，可加入區塊式注釋以提升可讀性

3. 命名慣例與目錄結構

3.1. 檔案與目錄命名

  • 目錄結構：
    • Laravel 核心程式碼放置在 app/ 目錄下，Livewire 相關元件則統一放置在 app/Http/Livewire
    • Blade 模板建議依照功能分類置於 resources/views 下，例如 resources/views/livewire
  • 檔案與類別命名：
    • 類別名稱採用 PascalCase（例如：UserController、OrderService、UserProfile）
    • Blade 模板檔案名稱採小寫加連字符分隔（例如：user-profile.blade.php）
    • 文件名稱與內容需對應，避免命名不一致

3.2. 命名細則

  • 方法與屬性：
    • 採用 camelCase（例如：getUserData()、orderId）
  • 常數：
    • 全部大寫，使用底線連接，例如：STATUS_ACTIVE

4. 控制器、服務與商業邏輯

4.1. 控制器實作

  • 精簡與職責單一：
    • 控制器應專注於請求處理與回傳結果，將複雜商業邏輯拆出放入 Service 或 Action 類別中
    • 採用依賴注入（Dependency Injection）以便於單元測試與維護
  • RESTful 與資源路由：
    • 儘量使用 Laravel 提供的 resource controllers 來管理 CRUD 操作
    • 使用路由群組與中介層（Middleware）統一管理權限驗證與請求前置處理

4.2. 表單驗證

  • Laravel Form Request 與 Livewire 驗證：
    • 對於複雜驗證邏輯，建議使用 Form Request 類別將驗證規則抽離至控制器之外
    • 在 Livewire 元件中，則可定義 $rules 屬性和利用 $this->validate() 或 $this->validateOnly() 驗證更新的欄位
    • 請參考 Laravel 表單驗證 與 Livewire 驗證指南

5. Blade 模板與前端資源

5.1. Blade 模板

  • 模板繼承與組件化：
    • 推薦使用 Blade 模板繼承機制（例如：layouts/app.blade.php）統一全站前端佈局
    • 利用 Blade Components 與 Slots 重用共用視圖片段，確保視圖邏輯簡單明瞭
    • 請參考 Laravel Blade 模板

5.2. Livewire 與前端整合

  • Livewire 標籤與資源：
    • 在主版面（layout）中引入 Livewire 必要的樣式與腳本：使用 @livewireStyles 與 @livewireScripts 指令
    • 於 Blade 中引入 Livewire 元件時，建議採用 <livewire:component-name /> 或 @livewire('component-name') 語法
  • 資料綁定與事件：
    • 儘量運用 Livewire 提供的雙向資料綁定（例如 wire:model、wire:model.defer）與事件（例如 wire:click、wire:submit）
    • 如需更複雜的前端互動，可搭配 Alpine.js（官方文件中亦有推薦做法）

6. Livewire 3 專屬標準

6.1. 元件結構與定義

  • 基本架構：
    • 每個 Livewire 元件應繼承自 Livewire\Component，並儘量使用 PHP 8 的屬性型別提示以提升程式明確性
    • 建議所有元件公開狀態僅限必須供前端綁定的屬性
  • 驗證與資料更新：
    • 在元件內定義驗證規則（例如：protected array $rules = []），並根據需要在 updated() 或具名更新方法中觸發局部驗證
    • Livewire 3 延續了自動執行元件生命週期（lifecycle hooks）與精簡狀態管理的優點，請參照 Livewire 3 快速入門 取得最新建議

Livewire 3 元件範例：

<?php

namespace App\Http\Livewire;

use Livewire\Component;

class UserProfile extends Component
{
    public string $name = '';
    public string $email = '';

    protected array $rules = [
        'name'  => 'required|string|min:3',
        'email' => 'required|email'
    ];

    // 當單一屬性更新時僅驗證該屬性，Livewire 3 建議使用具名事件（例如：updatedName）
    public function updatedName(): void
    {
        $this->validateOnly('name');
    }

    public function updateProfile(): void
    {
        $validatedData = $this->validate();
        // 執行後端更新邏輯，例如儲存至資料庫
    }

    public function render()
    {
        return view('livewire.user-profile');
    }
}

6.2. 元件溝通與事件處理

  • 事件發布與監聽：
    • 採用 Livewire 內建事件系統，在元件或元件與父母件之間傳遞必要事件
    • 命名規則需具意義，例如 userUpdated，確保其他團隊成員能迅速理解其用途
  • 元件拆分：
    • 若單個元件功能過於複雜，應進行拆分為多個專注於單一責任的子元件，以便維護與重用

7. 測試與品質保證

7.1. 單元測試與功能測試

  • 測試策略：
    • 使用 tests/Feature 與 tests/Unit 目錄分別存放功能與單元測試
    • Livewire 元件建議利用官方提供的測試工具進行整合與單元測試，確保前端與後端行為一致
  • 自動化測試整合：
    • 建議將測試納入 CI/CD 流程，定期執行測試以確保程式碼品質

7.2. 靜態分析

  • 程式碼檢查工具：
    • 使用 PHP CS Fixer、PHPStan、Psalm 等工具作為開發流程的一部分，確保程式碼符合規範與沒有潛在錯誤

8. 安全性、部屬與環境設定

8.1. 安全性

  • 資料輸出與防禦：
    • 在 Blade 中預設轉譯所有輸出（使用 {{ }}），對於需要非轉譯的情形使用 {!! !!} 並謹慎處理
    • 採用 Laravel 內建的 CSRF 保護機制，確保所有表單使用 @csrf
  • 權限管理：
    • 結合 Laravel Gate 與 Policy 機制進行權限驗證，避免在控制器中寫入過多授權邏輯

8.2. 部屬與環境設定

  • 環境管理：
    • 使用 .env 檔區分開發、測試與生產環境，並妥善保護敏感資訊
    • 定期更新依賴以確保安全性與相容性

9. 版本控管與團隊協作

  • Git 分支策略：
    • 採用 Git Flow 或類似流程，清楚區分 feature、bugfix 與 release 分支
    • 提交訊息需具描述性與意義，讓團隊成員能快速理解變更內容
  • Code Review 與文件維護：
    • 定期進行程式碼審查（Code Review），並確保團隊一致遵守上述規範
    • 持續更新技術文件與內部 Wiki，以反映最新的開發趨勢與實踐
最後修改日期: 2025 年 4 月 12 日

作者

留言

撰寫回覆或留言

發佈留言必須填寫的電子郵件地址不會公開。