Laravel - API 的最佳命名約定

playmaker發表於2022-02-22
LaravelAPI

以下是大多數使用 PHP 的科技公司遵循的基本命名約定。
這種命名約定符合Laravel [PHP] 編碼標準和 PSR 規範。

最佳結合 SOLID 原則

並記住儘可能遵循 KISS 原則

Laravel - API 的最佳命名約定

以下列出了命名標準：

  • 對於類、介面/契約、特性：使用 大駝峰式「PascalCase」
  • 對於常量：使用「TITLE_CASE」
  • 對於函式/方法、類屬性和變數：使用 小駝峰式「camelCase」
  • 對於陣列索引/資料庫欄位名/模型可填充項/模型關係：使用 蛇形命名法「lower_snake_case」
  • 對於路由：使用 短橫線「lower-kebab-case」

以下是標準用法和示例：

一、對於類、介面/契約、特性（大駝峰式 PascalCase）

// 類
class AuthController extends Controller
{
    // ...
}

// 介面 / 契約
interface LoginInterface 
{
   // ...
}

// 特性
trait Audit
{
   // ...
}

二、對於常量（TITLE_CASE）

namespace App\Constants;

class AppConstant {
    const DEFAULT_PAGE = 1;
    const DEFAULT_PAGE_LIMIT = 10;
    const MAX_PAGE_LIMIT = 100;
    const ALPHANUMERIC_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    const NUMERIC_CHARACTERS = '0123456789';
    const ALPHA_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
    const UPPERCASE_ALPHA_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
    const LOWERCASE_ALPHA_CHARACTERS = 'abcdefghijklmnopqrstuvwxyz';
}

三、對於函式/方法、類屬性和變數（小駝峰式 camelCase）

// 函式 / 方法
public function refreshToken() : JsonResponse {
    return $this->loginService->refreshToken();
}

//類屬性
class AuthController extends Controller
{
    // these are the class properties
    protected $loginService;
    protected $logoutService;
}

//變數
public function __construct(LoginService $loginService, LogoutService $logoutService) {
    $this->loginService = $loginService;
    $this->logoutService = $logoutService;
}

四、對於陣列索引/資料庫欄位名/模型可填充項/模型關係（蛇形命名法 lower_snake_case）

//陣列索引
foreach($age as $x => $x_value) {
  return $x_value;
}

//資料庫欄位名
public function up()
{
    Schema::create('audits', function (Blueprint $table) {
        $table->id();
        $table->string('user_type')->nullable();
        $table->unsignedBigInteger('user_id')->nullable();
        $table->index(['user_id', 'user_type']);
    });
}

//模型可填充項
protected $fillable = [
    'first_name',
    'last_name',
    'username',
    'email',
    'password',
];

注意：模型可填充項需要與資料庫列匹配，這樣才能正常工作，但任何連線到資料庫的類（如 Eloquent 模型類），類屬性camelCase也需要與資料庫列lower_snake_case匹配。

五、對於路由（短橫線 lower-kebab-case）

Route::group(['middleware' => 'auth:api'], function() {
    Route::post('refresh-token', [AuthController::class, 'refreshToken']);
    Route::post('logout', [AuthController::class, 'logout']);
});

更多用法及使用案例可以積極評論。

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章