一、前期准备：项目初始化与基础配置
1.1 项目创建与依赖安装
Laravel 内置API开发支持，无需额外引入前端脚手架，推荐使用纯净API项目初始化方式：
# 创建Laravel项目
composer create-project laravel/laravel laravel-api
# 进入项目目录
cd laravel-api
# 禁用前端相关依赖（可选，纯API无需前端）
rm -rf resources/js resources/css package.json vite.config.js1.2 环境配置与数据库连接
修改根目录 .env 文件，配置核心环境变量，确保数据库、时区、接口响应格式适配后端API：
# 应用基础配置
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=*生成应用密钥（必填，保障加密安全）：
php artisan key:generate二、路由：API路由定义与规范
2.1 API专属路由文件
Laravel 提供 routes/api.php 路由文件，专门用于定义后端接口，默认前缀 /api，无需手动添加，且不包含Session中间件，适配无状态API。
2.2 基础路由定义
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\UserController;
use App\Http\Controllers\Api\PostController;
// 单接口路由
Route::get('/test', function () {
return response()->json([
'code' => 200,
'msg' => 'API接口正常',
'data' => []
]);
});
// 控制器路由（推荐）
Route::get('/users', [UserController::class, 'index']); // 用户列表
Route::get('/users/{id}', [UserController::class, 'show']); // 单个用户
Route::post('/users', [UserController::class, 'store']); // 创建用户
Route::put('/users/{id}', [UserController::class, 'update']); // 更新用户
Route::delete('/users/{id}', [UserController::class, 'destroy']); // 删除用户
2.3 资源路由（RESTful规范）
针对标准CRUD接口，使用资源路由简化定义，自动映射RESTful风格接口：
// 完整资源路由
Route::apiResource('posts', PostController::class);
// 仅指定部分接口
Route::apiResource('posts', PostController::class)->only(['index', 'show']);
// 排除部分接口
Route::apiResource('posts', PostController::class)->except(['destroy']);2.4 路由分组与中间件
对接口进行分组管理，统一添加前缀、中间件（如鉴权、跨域）：
Route::prefix('v1')->group(function () {
// 公开接口
Route::post('/login', [AuthController::class, 'login']);
Route::post('/register', [AuthController::class, 'register']);
// 需鉴权接口
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user/info', [AuthController::class, 'userInfo']);
Route::apiResource('posts', PostController::class);
});
});三、控制器：API业务逻辑处理
3.1 创建API专用控制器
推荐在 app/Http/Controllers/Api 目录下创建控制器，区分前后端，命令行创建：
# 创建基础控制器
php artisan make:controller Api/UserController
# 创建资源控制器（自带CRUD方法）
php artisan make:controller Api/PostController --api3.2 控制器标准写法（API响应规范）
后端API统一返回JSON格式数据，遵循 code+msg+data 响应规范，避免直接返回原生数据：
<?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()->paginate(10);
return $this->success('用户列表获取成功', $users);
}
/**
* 单个用户详情
*/
public function show($id)
{
$user = User::find($id);
if (!$user) {
return $this->fail('用户不存在', 404);
}
return $this->success('用户详情获取成功', $user);
}
/**
* 统一成功响应
*/
protected function success($msg = '操作成功', $data = [], $code = 200)
{
return response()->json([
'code' => $code,
'msg' => $msg,
'data' => $data
]);
}
/**
* 统一失败响应
*/
protected function fail($msg = '操作失败', $code = 400)
{
return response()->json([
'code' => $code,
'msg' => $msg,
'data' => []
]);
}
}
四、请求验证：参数校验与异常处理
4.1 表单请求验证（推荐）
创建独立验证类，分离校验逻辑与业务逻辑，命令行创建：
php artisan make:request Api/UserStoreRequest编写验证规则（app/Http/Requests/Api/UserStoreRequest.php）：
<?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 [
'username' => 'required|string|unique:users|max:20',
'email' => 'required|email|unique:users',
'password' => 'required|string|min:6|confirmed',
];
}
/**
* 自定义错误提示
*/
public function messages()
{
return [
'username.required' => '用户名不能为空',
'email.unique' => '邮箱已被注册',
'password.confirmed' => '两次密码不一致',
];
}
}
4.2 控制器调用验证
public function store(UserStoreRequest $request)
{
// 验证通过后获取安全参数
$data = $request->validated();
$data['password'] = Hash::make($data['password']);
$user = User::create($data);
return $this->success('用户创建成功', $user);
}4.3 全局异常处理（API适配）
修改 app/Exceptions/Handler.php，将异常转为JSON响应，避免页面报错：
use Illuminate\Validation\ValidationException;
public function register()
{
$this->renderable(function (ValidationException $e, $request) {
if ($request->is('api/*')) {
return response()->json([
'code' => 422,
'msg' => '参数校验失败',
'data' => $e->errors()
], 422);
}
});
}五、数据库：迁移、模型与数据操作
5.1 数据迁移（表结构管理）
通过迁移文件管理数据库表，无需手动建表：
# 创建迁移文件
php artisan make:migration create_posts_table
# 执行迁移（建表）
php artisan migrate
# 回滚迁移
php artisan migrate:rollback迁移文件示例（创建文章表）：
public function up()
{
Schema::create('posts', function (Blueprint $table) {
$table->id();
$table->string('title');
$table->text('content');
$table->integer('user_id');
$table->timestamps();
});
}5.2 模型定义与关联
# 创建模型
php artisan make:model Post模型配置（app/Models/Post.php）：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
use HasFactory;
// 允许批量赋值字段
protected $fillable = ['title', 'content', 'user_id'];
/**
* 关联用户（一对多）
*/
public function user()
{
return $this->belongsTo(User::class);
}
}5.3 API常用数据操作
-
分页查询：
Post::paginate(10)，自动返回分页元数据 -
条件筛选：
Post::where('user_id', $userId)->get() -
关联查询：
Post::with('user')->paginate(10)（预加载避免N+1问题） -
新增数据：
Post::create($validatedData) -
更新数据：
Post::findOrFail($id)->update($validatedData) -
删除数据：
Post::findOrFail($id)->delete()
六、接口鉴权：Sanctum无状态认证
6.1 Sanctum安装与配置
Laravel官方推荐的轻量级API鉴权方案，无状态、适配纯后端接口：
# 安装Sanctum
composer require laravel/sanctum
# 发布配置文件
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
# 执行迁移（生成令牌表）
php artisan migrate在 app/Models/User.php 引入令牌 trait：
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, HasFactory, Notifiable;
}6.2 登录签发令牌
public function login(Request $request)
{
$credentials = $request->validate([
'email' => 'required|email',
'password' => 'required|string',
]);
if (!Auth::attempt($credentials)) {
return $this->fail('账号或密码错误', 401);
}
$user = Auth::user();
// 签发令牌
$token = $user->createToken('api_token')->plainTextToken;
return $this->success('登录成功', [
'token' => $token,
'user' => $user
]);
}6.3 鉴权中间件使用
在路由中添加 auth:sanctum 中间件，保护接口：
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user/profile', [AuthController::class, 'profile']);
Route::apiResource('posts', PostController::class);
});前端请求时，在请求头携带令牌：Authorization: Bearer 令牌值
6.4 退出登录（销毁令牌）
public function logout(Request $request)
{
$request->user()->currentAccessToken()->delete();
return $this->success('退出登录成功');
}七、跨域处理：API接口跨域解决方案
纯后端API需解决跨域问题，Laravel 自带跨域中间件，修改配置文件 config/cors.php：
return [
'paths' => ['api/*'],
'allowed_methods' => ['*'],
'allowed_origins' => ['*'], // 生产环境替换为具体域名
'allowed_origins_patterns' => [],
'allowed_headers' => ['*'],
'exposed_headers' => [],
'max_age' => 0,
'supports_credentials' => false,
];修改后重启服务，跨域中间件自动生效。
八、API优化与进阶技巧
8.1 资源响应（格式化输出）
使用API资源类统一数据返回格式，避免字段冗余：
# 创建资源类
php artisan make:resource PostResource资源类编写（app/Http/Resources/PostResource.php）：
public function toArray($request)
{
return [
'id' => $this->id,
'title' => $this->title,
'content' => $this->content,
'author' => $this->user->username ?? '',
'create_time' => $this->created_at->toDateTimeString(),
];
}控制器调用：return $this->success('获取成功', PostResource::collection($posts));
8.2 接口限流（防恶意请求）
使用Laravel内置限流中间件，限制接口请求频率：
// 限制1分钟内最多60次请求
Route::middleware('throttle:60,1')->group(function () {
Route::post('/login', [AuthController::class, 'login']);
});8.3 软删除与数据恢复
迁移文件添加软删除字段，模型引入软删除trait，避免物理删除数据：
// 迁移文件
$table->softDeletes();
// 模型
use Illuminate\Database\Eloquent\SoftDeletes;
class Post extends Model
{
use SoftDeletes;
}九、接口调试与启动
- 启动服务：
php artisan serve，默认地址http://127.0.0.1:8000 - 路由查看：
php artisan route:list，查看所有API路由详情 - 调试工具：使用Postman、ApiFox等接口工具调试，无需前端页面
- 日志查看：日志文件位于
storage/logs/laravel.log，排查后端异常