Laravel 提供了强大的功能来帮助开发 RESTful API，能够处理 HTTP 请求、返回 JSON 数据、验证输入、身份验证等操作。本文将详细介绍如何使用 Laravel 开发 RESTful API，包括路由、控制器、资源、验证、身份验证和测试。

1. 什么是 RESTful API？

RESTful API（表述性状态转移应用程序编程接口）是一种常用的 Web 服务架构风格，基于 HTTP 协议，用于在客户端和服务器之间进行数据交换。RESTful API 使用标准的 HTTP 动作，如 GET、POST、PUT、DELETE 等，通过 URL 和 HTTP 请求的方式访问和操作资源。

2. 在 Laravel 中创建 RESTful API

2.1 创建 API 路由

在 Laravel 中，API 路由通常定义在 routes/api.php 文件中。与 web 路由不同，API 路由通常没有会话状态，它们是无状态的，适合处理 API 请求。

// routes/api.php

use App\Http\Controllers\Api\PostController;

Route::get('/posts', [PostController::class, 'index']);  // 获取所有帖子
Route::get('/posts/{id}', [PostController::class, 'show']);  // 获取单个帖子
Route::post('/posts', [PostController::class, 'store']);  // 创建新帖子
Route::put('/posts/{id}', [PostController::class, 'update']);  // 更新帖子
Route::delete('/posts/{id}', [PostController::class, 'destroy']);  // 删除帖子

2.2 创建 API 控制器

Laravel 提供了一个命令来快速生成控制器，特别是 API 控制器，可以使用 --api 选项生成只处理 API 请求的控制器。控制器通常会返回 JSON 格式的数据。

php artisan make:controller Api/PostController --api

生成的控制器示例如下：

// app/Http/Controllers/Api/PostController.php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    // 获取所有帖子
    public function index()
    {
        $posts = Post::all();
        return response()->json($posts);  // 返回 JSON 格式的所有帖子
    }

    // 获取单个帖子
    public function show($id)
    {
        $post = Post::find($id);

        if (!$post) {
            return response()->json(['message' => 'Post not found'], 404);
        }

        return response()->json($post);  // 返回 JSON 格式的单个帖子
    }

    // 创建新帖子
    public function store(Request $request)
    {
        $validatedData = $request->validate([
            'title' => 'required|string|max:255',
            'content' => 'required|string',
        ]);

        $post = Post::create($validatedData);
        return response()->json($post, 201);  // 返回新创建的帖子并返回 201 状态码
    }

    // 更新帖子
    public function update(Request $request, $id)
    {
        $post = Post::find($id);

        if (!$post) {
            return response()->json(['message' => 'Post not found'], 404);
        }

        $validatedData = $request->validate([
            'title' => 'sometimes|required|string|max:255',
            'content' => 'sometimes|required|string',
        ]);

        $post->update($validatedData);
        return response()->json($post);  // 返回更新后的帖子
    }

    // 删除帖子
    public function destroy($id)
    {
        $post = Post::find($id);

        if (!$post) {
            return response()->json(['message' => 'Post not found'], 404);
        }

        $post->delete();
        return response()->json(['message' => 'Post deleted successfully']);
    }
}

2.3 API 响应

Laravel 提供了便捷的 response()->json() 方法来返回 JSON 数据。可以指定状态码和消息：

return response()->json($data, 200);  // 返回成功响应
return response()->json(['message' => 'Not found'], 404);  // 返回失败响应

3. 请求验证

在 API 中处理用户提交的数据时，验证请求是非常重要的一步。Laravel 提供了强大的验证功能，可以确保数据的正确性和安全性。验证逻辑可以放在控制器中，使用 Request 对象的 validate 方法。

public function store(Request $request)
{
    $validatedData = $request->validate([
        'title' => 'required|string|max:255',
        'content' => 'required|string',
    ]);

    $post = Post::create($validatedData);
    return response()->json($post, 201);
}

如果验证失败，Laravel 会自动返回 422 响应和详细的错误信息。

4. 身份验证与授权

4.1 使用 API 令牌身份验证（Passport）

Laravel 提供了 Passport 包，简化了 API 身份验证过程。Passport 允许你通过 OAuth2 实现 API 令牌身份验证。

安装 Passport：

composer require laravel/passport
php artisan migrate
php artisan passport:install

在 config/auth.php 中设置 API 驱动为 Passport：

// config/auth.php

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

在用户模型中，使用 HasApiTokens 特性：

// app/Models/User.php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Laravel\Passport\HasApiTokens;

class User extends Model
{
    use HasApiTokens;
}

生成和使用 API 令牌：

$user = User::find(1);
$token = $user->createToken('MyApp')->accessToken;

4.2 保护 API 路由

你可以通过 auth:api 中间件来保护需要身份验证的 API 路由：

// routes/api.php

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

5. API 资源（API Resources）

在开发 RESTful API 时，通常需要对返回的模型进行格式化。Laravel 提供了 API 资源（API Resources）来轻松转换模型为 JSON 格式。你可以生成资源类来处理这些转换。

php artisan make:resource PostResource

生成的资源类示例如下：

// app/Http/Resources/PostResource.php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'content' => $this->content,
        ];
    }
}

在控制器中使用资源：

use App\Http\Resources\PostResource;

public function show($id)
{
    $post = Post::find($id);

    if (!$post) {
        return response()->json(['message' => 'Post not found'], 404);
    }

    return new PostResource($post);  // 使用资源返回格式化后的数据
}

6. API 测试

Laravel 提供了强大的测试功能，可以帮助你测试 API 的各个方面。你可以使用 php artisan make:test 命令生成 API 测试类。

php artisan make:test PostApiTest

在生成的测试类中，你可以编写针对 API 路由的测试：// tests/Feature/PostApiTest.php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;

class PostApiTest extends TestCase
{
use RefreshDatabase;

/** @test */
public function it_can_create_a_post()
{
$response = $this->postJson(‘/api/posts’, [
‘title’ => ‘New Post’,
‘content’ => ‘Post content.’,
]);

$response->assertStatus(201)
->assertJsonStructure([
‘id’,
‘title’,
‘content’,
]);
}

/** @test */
public function it_can_get_all_posts()
{
$response = $this->getJson(‘/api/posts’);
$response->assertStatus(200);
}
}