Laravel – API 的最佳命名约定

本文分享内容是大多数使用 PHP 的科技公司遵循的基本命名约定。这种命名约定符合 Laravel [PHP] 编码标准和PSR规范。

最佳方式是结合SOLID原则，并记住尽可能遵循KISS原则

命名标准：

对于类、接口 / 契约、特性：使用 大驼峰式「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';

    const WEB_SITE_URL = 'https://www.02405.com';

}

三、对于函数 / 方法、类属性和变量（小驼峰式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']);

});