Laravel 12 中现代 API 开发的完整指南

Source: Dev.to

介绍

随着应用规模的扩大，对健壮、安全且易于维护的 API 的需求迅速增长。本文阐述了 Laravel 12 的独特之处、其架构为何重要，以及如何利用其最新特性构建现代 API。

为什么 Laravel 12 相较于 Laravel 11 更特别

Laravel 12 不仅仅是一次版本升级；它专注于安全性、可观测性和可扩展性。关键亮点包括：

• secureValidate() 用于更严格的输入和密码验证
• ddBody() 用于改进的请求调试
• 原生 UUIDv7 支持，提升 API 标识符的表现
• 更简洁的 API‑first 开发模式

这些特性使 Laravel 12 成为生产级 API 的理想选择。

项目设置

要启动一个 Laravel 12 项目，请运行：

composer create-project laravel/laravel:^12.0 my-api

这将确保您的应用程序基于 Laravel 12 构建，并使用最新的默认设置。

为什么要把 API 路由和 Web 路由分开？

Laravel 通过设计将路由分为 web.php 和 api.php。

这很重要的原因

• API 路由是无状态的
• 会话、CSRF 等中间件被排除
• API 更轻量、性能更佳

这种分离提升了基于 API 系统的可扩展性和安全性。

定义 API 路由 (routes/api.php)

Laravel 12 鼓励使用资源路由进行 RESTful 路由。

use App\Http\Controllers\Api\UserController;
use Illuminate\Support\Facades\Route;

Route::apiResource('users', UserController::class);

为什么使用 apiResource？

apiResource 会自动创建典型的 index、store、show、update 和 destroy 路由，遵循 REST 约定。

数据库设计与 UUIDv7 支持

Laravel 12 原生支持 UUIDv7，非常适合 API。

为什么选择 UUIDv7？

• 时间有序（比 UUIDv4 更好的索引）
• 全局唯一
• 比自增 ID 更安全

示例迁移

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateUsersTable extends Migration
{
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->uuid('id')->primary();
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('users');
    }
}

此模式非常适合分布式系统和公共 API。

为什么在 API 中使用控制器？

控制器将请求处理与业务逻辑分离。

好处

• 代码更简洁
• 更易于测试
• 更好的可维护性

Laravel 12 控制器仍然轻量且富有表现力。

使用 secureValidate() 进行请求验证

Laravel 12 引入了 secureValidate()，用于更严格的验证规则，特别适用于密码和敏感数据。

public function store(Request $request)
{
    $data = $request->secureValidate([
        'name'     => ['required', 'string', 'max:255'],
        'email'    => ['required', 'email', 'unique:users'],
        'password' => ['required', 'strong_password'],
    ]);

    $user = User::create($data);

    return response()->json([
        'message' => 'User created successfully',
        'data'    => $user,
    ], 201);
}

为什么使用 secureValidate()？

它开箱即用地强制更严格的规则，降低不安全输入的风险。

使用 ddBody() 调试请求

Laravel 12 引入了 ddBody() 用于请求调试。

$request->ddBody();

为什么这很有用

• 只转储请求体
• 比 dd($request->all()) 更简洁
• 在 API 开发期间更快的调试

这显著提升了开发者的生产力。

Consistent API Responses with Resources

一致性是 REST API 的关键原则。

Create a resource

php artisan make:resource UserResource

Example resource class

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id'         => $this->id,
            'name'       => $this->name,
            'email'      => $this->email,
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}

Returning a resource response

return new UserResource($user);

使用 API 资源可以让响应保持简洁、可预测且专业。

Laravel 12 API 的最佳实践

• 对面向公众的 ID 使用 UUIDv7
• 始终使用 secureValidate() 验证输入
• 响应使用 API Resources
• 控制器保持精简
• 为 API 设定版本（例如 /api/v1）

这些实践使您的 API 可扩展且具备未来兼容性。

结论

Laravel 12 为现代 API 开发设定了更高的标准。通过 secureValidate()、ddBody() 和原生 UUIDv7 支持等特性，它在安全性、调试和可扩展性方面优于 Laravel 11。遵循 Laravel 12 的 API‑first 设计原则，开发者可以自信地构建干净、安全、可投入生产的 API。