<h3>一、前期准备：项目初始化与基础配置</h3>
<h4>1.1 项目创建与依赖安装</h4>
<p>Laravel 内置API开发支持，无需额外引入前端脚手架，推荐使用纯净API项目初始化方式：</p>
<pre><code class="lang-bash language-bash bash"># 创建Laravel项目
composer create-project laravel/laravel laravel-api

# 进入项目目录
cd laravel-api

# 禁用前端相关依赖（可选，纯API无需前端）
rm -rf resources/js resources/css package.json vite.config.js</code></pre>
<h4>1.2 环境配置与数据库连接</h4>
<p>修改根目录 <strong>.env</strong> 文件，配置核心环境变量，确保数据库、时区、接口响应格式适配后端API：</p>
<pre><code class="lang-env language-env env"># 应用基础配置
APP_NAME=LaravelAPI
APP_ENV=local
APP_KEY=生成的密钥
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_TIMEZONE=Asia/Shanghai
APP_LOCALE=zh-CN

# 数据库配置（MySQL为例）
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_api
DB_USERNAME=root
DB_PASSWORD=

# 接口跨域配置（后续详解）
ALLOWED_ORIGINS=*</code></pre>
<p>生成应用密钥（必填，保障加密安全）：</p>
<pre><code class="lang-bash language-bash bash">php artisan key:generate</code></pre>
<h3>二、路由：API路由定义与规范</h3>
<h4>2.1 API专属路由文件</h4>
<p>Laravel 提供 <code>routes/api.php</code> 路由文件，专门用于定义后端接口，默认前缀 <code>/api</code>，无需手动添加，且不包含Session中间件，适配无状态API。</p>
<h4>2.2 基础路由定义</h4>
<pre><code class="lang-php language-php php">use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\UserController;
use App\Http\Controllers\Api\PostController;

// 单接口路由
Route::get(&#039;/test&#039;, function () {
    return response()-&gt;json([
        &#039;code&#039; =&gt; 200,
        &#039;msg&#039; =&gt; &#039;API接口正常&#039;,
        &#039;data&#039; =&gt; []
    ]);
});

// 控制器路由（推荐）
Route::get(&#039;/users&#039;, [UserController::class, &#039;index&#039;]); // 用户列表
Route::get(&#039;/users/{id}&#039;, [UserController::class, &#039;show&#039;]); // 单个用户
Route::post(&#039;/users&#039;, [UserController::class, &#039;store&#039;]); // 创建用户
Route::put(&#039;/users/{id}&#039;, [UserController::class, &#039;update&#039;]); // 更新用户
Route::delete(&#039;/users/{id}&#039;, [UserController::class, &#039;destroy&#039;]); // 删除用户
</code></pre>
<h4>2.3 资源路由（RESTful规范）</h4>
<p>针对标准CRUD接口，使用资源路由简化定义，自动映射RESTful风格接口：</p>
<pre><code class="lang-php language-php php">// 完整资源路由
Route::apiResource(&#039;posts&#039;, PostController::class);

// 仅指定部分接口
Route::apiResource(&#039;posts&#039;, PostController::class)-&gt;only([&#039;index&#039;, &#039;show&#039;]);

// 排除部分接口
Route::apiResource(&#039;posts&#039;, PostController::class)-&gt;except([&#039;destroy&#039;]);</code></pre>
<h4>2.4 路由分组与中间件</h4>
<p>对接口进行分组管理，统一添加前缀、中间件（如鉴权、跨域）：</p>
<pre><code class="lang-php language-php php">Route::prefix(&#039;v1&#039;)-&gt;group(function () {
    // 公开接口
    Route::post(&#039;/login&#039;, [AuthController::class, &#039;login&#039;]);
    Route::post(&#039;/register&#039;, [AuthController::class, &#039;register&#039;]);

    // 需鉴权接口
    Route::middleware(&#039;auth:sanctum&#039;)-&gt;group(function () {
        Route::get(&#039;/user/info&#039;, [AuthController::class, &#039;userInfo&#039;]);
        Route::apiResource(&#039;posts&#039;, PostController::class);
    });
});</code></pre>
<h3>三、控制器：API业务逻辑处理</h3>
<h4>3.1 创建API专用控制器</h4>
<p>推荐在 <code>app/Http/Controllers/Api</code> 目录下创建控制器，区分前后端，命令行创建：</p>
<pre><code class="lang-bash language-bash bash"># 创建基础控制器
php artisan make:controller Api/UserController

# 创建资源控制器（自带CRUD方法）
php artisan make:controller Api/PostController --api</code></pre>
<h4>3.2 控制器标准写法（API响应规范）</h4>
<p>后端API统一返回JSON格式数据，遵循 <strong>code+msg+data</strong> 响应规范，避免直接返回原生数据：</p>
<pre><code class="lang-php language-php php">&lt;?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;

class UserController extends Controller
{
    /**
     * 用户列表
     */
    public function index(Request $request)
    {
        // 分页查询
        $users = User::query()-&gt;paginate(10);
        return $this-&gt;success(&#039;用户列表获取成功&#039;, $users);
    }

    /**
     * 单个用户详情
     */
    public function show($id)
    {
        $user = User::find($id);
        if (!$user) {
            return $this-&gt;fail(&#039;用户不存在&#039;, 404);
        }
        return $this-&gt;success(&#039;用户详情获取成功&#039;, $user);
    }

    /**
     * 统一成功响应
     */
    protected function success($msg = &#039;操作成功&#039;, $data = [], $code = 200)
    {
        return response()-&gt;json([
            &#039;code&#039; =&gt; $code,
            &#039;msg&#039; =&gt; $msg,
            &#039;data&#039; =&gt; $data
        ]);
    }

    /**
     * 统一失败响应
     */
    protected function fail($msg = &#039;操作失败&#039;, $code = 400)
    {
        return response()-&gt;json([
            &#039;code&#039; =&gt; $code,
            &#039;msg&#039; =&gt; $msg,
            &#039;data&#039; =&gt; []
        ]);
    }
}
</code></pre>
<h3>四、请求验证：参数校验与异常处理</h3>
<h4>4.1 表单请求验证（推荐）</h4>
<p>创建独立验证类，分离校验逻辑与业务逻辑，命令行创建：</p>
<pre><code class="lang-bash language-bash bash">php artisan make:request Api/UserStoreRequest</code></pre>
<p>编写验证规则（app/Http/Requests/Api/UserStoreRequest.php）：</p>
<pre><code class="lang-php language-php php">&lt;?php

namespace App\Http\Requests\Api;

use Illuminate\Foundation\Http\FormRequest;

class UserStoreRequest extends FormRequest
{
    /**
     * 权限判断
     */
    public function authorize()
    {
        return true; // 开放接口直接返回true
    }

    /**
     * 验证规则
     */
    public function rules()
    {
        return [
            &#039;username&#039; =&gt; &#039;required|string|unique:users|max:20&#039;,
            &#039;email&#039; =&gt; &#039;required|email|unique:users&#039;,
            &#039;password&#039; =&gt; &#039;required|string|min:6|confirmed&#039;,
        ];
    }

    /**
     * 自定义错误提示
     */
    public function messages()
    {
        return [
            &#039;username.required&#039; =&gt; &#039;用户名不能为空&#039;,
            &#039;email.unique&#039; =&gt; &#039;邮箱已被注册&#039;,
            &#039;password.confirmed&#039; =&gt; &#039;两次密码不一致&#039;,
        ];
    }
}
</code></pre>
<h4>4.2 控制器调用验证</h4>
<pre><code class="lang-php language-php php">public function store(UserStoreRequest $request)
{
    // 验证通过后获取安全参数
    $data = $request-&gt;validated();
    $data[&#039;password&#039;] = Hash::make($data[&#039;password&#039;]);
    $user = User::create($data);
    return $this-&gt;success(&#039;用户创建成功&#039;, $user);
}</code></pre>
<h4>4.3 全局异常处理（API适配）</h4>
<p>修改 <code>app/Exceptions/Handler.php</code>，将异常转为JSON响应，避免页面报错：</p>
<pre><code class="lang-php language-php php">use Illuminate\Validation\ValidationException;

public function register()
{
    $this-&gt;renderable(function (ValidationException $e, $request) {
        if ($request-&gt;is(&#039;api/*&#039;)) {
            return response()-&gt;json([
                &#039;code&#039; =&gt; 422,
                &#039;msg&#039; =&gt; &#039;参数校验失败&#039;,
                &#039;data&#039; =&gt; $e-&gt;errors()
            ], 422);
        }
    });
}</code></pre>
<h3>五、数据库：迁移、模型与数据操作</h3>
<h4>5.1 数据迁移（表结构管理）</h4>
<p>通过迁移文件管理数据库表，无需手动建表：</p>
<pre><code class="lang-bash language-bash bash"># 创建迁移文件
php artisan make:migration create_posts_table

# 执行迁移（建表）
php artisan migrate

# 回滚迁移
php artisan migrate:rollback</code></pre>
<p>迁移文件示例（创建文章表）：</p>
<pre><code class="lang-php language-php php">public function up()
{
    Schema::create(&#039;posts&#039;, function (Blueprint $table) {
        $table-&gt;id();
        $table-&gt;string(&#039;title&#039;);
        $table-&gt;text(&#039;content&#039;);
        $table-&gt;integer(&#039;user_id&#039;);
        $table-&gt;timestamps();
    });
}</code></pre>
<h4>5.2 模型定义与关联</h4>
<pre><code class="lang-bash language-bash bash"># 创建模型
php artisan make:model Post</code></pre>
<p>模型配置（app/Models/Post.php）：</p>
<pre><code class="lang-php language-php php">&lt;?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasFactory;

    // 允许批量赋值字段
    protected $fillable = [&#039;title&#039;, &#039;content&#039;, &#039;user_id&#039;];

    /**
     * 关联用户（一对多）
     */
    public function user()
    {
        return $this-&gt;belongsTo(User::class);
    }
}</code></pre>
<h4>5.3 API常用数据操作</h4>
<ul>
<li>
<p><strong>分页查询</strong>：<code>Post::paginate(10)</code>，自动返回分页元数据</p>
</li>
<li>
<p><strong>条件筛选</strong>：<code>Post::where(&#039;user_id&#039;, $userId)-&gt;get()</code></p>
</li>
<li>
<p><strong>关联查询</strong>：<code>Post::with(&#039;user&#039;)-&gt;paginate(10)</code>（预加载避免N+1问题）</p>
</li>
<li>
<p><strong>新增数据</strong>：<code>Post::create($validatedData)</code></p>
</li>
<li>
<p><strong>更新数据</strong>：<code>Post::findOrFail($id)-&gt;update($validatedData)</code></p>
</li>
<li>
<p><strong>删除数据</strong>：<code>Post::findOrFail($id)-&gt;delete()</code></p>
</li>
</ul>
<h3>六、接口鉴权：Sanctum无状态认证</h3>
<h4>6.1 Sanctum安装与配置</h4>
<p>Laravel官方推荐的轻量级API鉴权方案，无状态、适配纯后端接口：</p>
<pre><code class="lang-bash language-bash bash"># 安装Sanctum
composer require laravel/sanctum

# 发布配置文件
php artisan vendor:publish --provider=&quot;Laravel\Sanctum\SanctumServiceProvider&quot;

# 执行迁移（生成令牌表）
php artisan migrate</code></pre>
<p>在 <code>app/Models/User.php</code> 引入令牌 trait：</p>
<pre><code class="lang-php language-php php">use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}</code></pre>
<h4>6.2 登录签发令牌</h4>
<pre><code class="lang-php language-php php">public function login(Request $request)
{
    $credentials = $request-&gt;validate([
        &#039;email&#039; =&gt; &#039;required|email&#039;,
        &#039;password&#039; =&gt; &#039;required|string&#039;,
    ]);

    if (!Auth::attempt($credentials)) {
        return $this-&gt;fail(&#039;账号或密码错误&#039;, 401);
    }

    $user = Auth::user();
    // 签发令牌
    $token = $user-&gt;createToken(&#039;api_token&#039;)-&gt;plainTextToken;

    return $this-&gt;success(&#039;登录成功&#039;, [
        &#039;token&#039; =&gt; $token,
        &#039;user&#039; =&gt; $user
    ]);
}</code></pre>
<h4>6.3 鉴权中间件使用</h4>
<p>在路由中添加 <code>auth:sanctum</code> 中间件，保护接口：</p>
<pre><code class="lang-php language-php php">Route::middleware(&#039;auth:sanctum&#039;)-&gt;group(function () {
    Route::get(&#039;/user/profile&#039;, [AuthController::class, &#039;profile&#039;]);
    Route::apiResource(&#039;posts&#039;, PostController::class);
});</code></pre>
<p>前端请求时，在请求头携带令牌：<code>Authorization: Bearer 令牌值</code></p>
<h4>6.4 退出登录（销毁令牌）</h4>
<pre><code class="lang-php language-php php">public function logout(Request $request)
{
    $request-&gt;user()-&gt;currentAccessToken()-&gt;delete();
    return $this-&gt;success(&#039;退出登录成功&#039;);
}</code></pre>
<h3>七、跨域处理：API接口跨域解决方案</h3>
<p>纯后端API需解决跨域问题，Laravel 自带跨域中间件，修改配置文件 <code>config/cors.php</code>：</p>
<pre><code class="lang-php language-php php">return [
    &#039;paths&#039; =&gt; [&#039;api/*&#039;],
    &#039;allowed_methods&#039; =&gt; [&#039;*&#039;],
    &#039;allowed_origins&#039; =&gt; [&#039;*&#039;], // 生产环境替换为具体域名
    &#039;allowed_origins_patterns&#039; =&gt; [],
    &#039;allowed_headers&#039; =&gt; [&#039;*&#039;],
    &#039;exposed_headers&#039; =&gt; [],
    &#039;max_age&#039; =&gt; 0,
    &#039;supports_credentials&#039; =&gt; false,
];</code></pre>
<p>修改后重启服务，跨域中间件自动生效。</p>
<h3>八、API优化与进阶技巧</h3>
<h4>8.1 资源响应（格式化输出）</h4>
<p>使用API资源类统一数据返回格式，避免字段冗余：</p>
<pre><code class="lang-bash language-bash bash"># 创建资源类
php artisan make:resource PostResource</code></pre>
<p>资源类编写（app/Http/Resources/PostResource.php）：</p>
<pre><code class="lang-php language-php php">public function toArray($request)
{
    return [
        &#039;id&#039; =&gt; $this-&gt;id,
        &#039;title&#039; =&gt; $this-&gt;title,
        &#039;content&#039; =&gt; $this-&gt;content,
        &#039;author&#039; =&gt; $this-&gt;user-&gt;username ?? &#039;&#039;,
        &#039;create_time&#039; =&gt; $this-&gt;created_at-&gt;toDateTimeString(),
    ];
}</code></pre>
<p>控制器调用：<code>return $this-&gt;success(&#039;获取成功&#039;, PostResource::collection($posts));</code></p>
<h4>8.2 接口限流（防恶意请求）</h4>
<p>使用Laravel内置限流中间件，限制接口请求频率：</p>
<pre><code class="lang-php language-php php">// 限制1分钟内最多60次请求
Route::middleware(&#039;throttle:60,1&#039;)-&gt;group(function () {
    Route::post(&#039;/login&#039;, [AuthController::class, &#039;login&#039;]);
});</code></pre>
<h4>8.3 软删除与数据恢复</h4>
<p>迁移文件添加软删除字段，模型引入软删除trait，避免物理删除数据：</p>
<pre><code class="lang-php language-php php">// 迁移文件
$table-&gt;softDeletes();

// 模型
use Illuminate\Database\Eloquent\SoftDeletes;
class Post extends Model
{
    use SoftDeletes;
}</code></pre>
<h3>九、接口调试与启动</h3>
<ul>
<li><strong>启动服务</strong>：<code>php artisan serve</code>，默认地址 <code>http://127.0.0.1:8000</code></li>
<li><strong>路由查看</strong>：<code>php artisan route:list</code>，查看所有API路由详情</li>
<li><strong>调试工具</strong>：使用Postman、ApiFox等接口工具调试，无需前端页面</li>
<li><strong>日志查看</strong>：日志文件位于 <code>storage/logs/laravel.log</code>，排查后端异常</li>
</ul>

Laravel 学习笔记