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']);
});