Laravel API 开发学习总结

发表于 分类于

学习日期：2026-07-09
项目：task-api（任务管理 API）
技术栈：Laravel 11 + Sanctum + SQLite

学习目标完成情况

原定学习目标：

  • Eloquent 高级查询
  • API 文档工具

完成进度：100% ✅

Eloquent 高级查询详解

1. 预加载（解决 N+1 查询问题）

N+1 问题示例

1
2
3
4
5
6
7
8
9
10
// ❌ 错误：N+1 问题（11 次查询）
$tasks = Task::where('user_id', $userId)->get();
foreach ($tasks as $task) {
    echo $task->user->name;  // 每次循环都查询数据库
}

// ✅ 正确：预加载（只有 2 次查询）
$tasks = Task::with('user:id,name,email')
    ->where('user_id', $userId)
    ->get();

预加载优化

  • with('user') - 预加载关联数据
  • user:id,name,email - 只选择需要的字段
  • 查询次数从 1+N 降低到 2

条件渲染（避免额外查询）

1
2
3
4
5
6
7
8
// TaskResource.php
'user' => $this->when($this->relationLoaded('user'), function () {
    return [
        'id' => $this->user->id,
        'name' => $this->user->name,
        'email' => $this->user->email,
    ];
}),

2. 关联统计（withCount）

基础用法

1
2
3
4
5
6
7
8
9
// 统计每个用户的任务数量
$users = User::withCount('tasks')->get();

// 返回结果
{
    "id": 1,
    "name": "用户A",
    "tasks_count": 5  // 自动添加统计字段
}

自定义字段名 + 筛选条件

1
2
3
4
5
6
7
8
$users = User::withCount('tasks')  // 总任务数
    ->withCount(['tasks as completed_tasks' => function ($query) {
        $query->where('status', 'completed');  // 已完成任务数
    }])
    ->withCount(['tasks as pending_tasks' => function ($query) {
        $query->where('status', 'pending');  // 未完成任务数
    }])
    ->get(['id', 'name', 'email']);

withCount vs count() 对比

方法 返回类型 适用场景 示例
withCount 模型列表 查询父模型 + 统计子模型 用户列表 + 每个用户的任务数
count() 数字 直接统计数量 总任务数、已完成数

3. 聚合函数

1
2
3
4
5
6
7
8
9
$stats = [
    'total_tasks' => Task::count(),  // 总任务数
    'completed_tasks' => Task::where('status', 'completed')->count(),  // 已完成
    'pending_tasks' => Task::where('status', 'pending')->count(),  // 未完成
    'avg_completion_rate' => round(
        Task::where('status', 'completed')->count() / max(Task::count(), 1) * 100, 
        2
    ),  // 完成率（保留2位小数）
];

API 文档工具（Scribe）

1. 安装 Scribe

1
2
3
4
5
6
7
cd ~/Herd/task-api

# 安装依赖
composer require knuckleswtf/scribe

# 发布配置文件
php artisan vendor:publish --tag=scribe-config

2. 配置认证

修改 config/scribe.php：

1
2
3
4
5
6
7
8
9
'auth' => [
    'enabled' => true,  // 启用认证
    'default' => false,
    'in' => AuthIn::BEARER->value,  // Bearer Token 认证
    'name' => 'Authorization',  // 认证头名称
    'use_value' => env('SCRIBE_AUTH_KEY'),
    'placeholder' => '{YOUR_TOKEN}',  // 占位符
    'extra_info' => '使用 Sanctum Token 认证，格式：Bearer YOUR_TOKEN',
],

3. 添加文档注解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
 * 获取任务列表
 * 
 * @group 任务管理
 * @title 获取任务列表
 * @description 获取当前用户的任务列表，支持按状态筛选、标题搜索、多字段排序
 * @authenticated
 * 
 * @queryParam status string optional 筛选状态（pending/completed）
 * @queryParam search string optional 搜索标题（模糊匹配）
 * @queryParam sort string optional 排序字段（created_at/title/status）
 * @queryParam order string optional 排序顺序（asc/desc）
 * @queryParam per_page integer optional 每页数量（默认5）
 */
public function index(Request $request)
{
    // ...
}

4. 常用注解标签

标签 作用
@group 分组名称
@title 接口标题
@description 接口描述
@authenticated 需要认证
@queryParam 查询参数说明
@bodyParam 请求体参数说明
@response 响应示例

5. 生成文档

1
php artisan scribe:generate

文档地址： http://task-api.test/docs

项目成果总结

项目信息

  • 项目名称： task-api
  • 技术栈： Laravel 11 + Sanctum + SQLite
  • API 数量： 9 个接口
  • 测试数量： 11 个测试（32 个断言）

实现功能

  • ✅ 用户认证（注册/登录/登出）
  • ✅ 任务 CRUD（创建/列表/删除）
  • ✅ 任务状态
  • ✅ 标题搜索（模糊匹配）
  • ✅ 多字段排序（created_at/title/status）
  • ✅ 分页查询（per_page 参数）
  • ✅ 预加载优化（避免 N+1 问题）
  • ✅ 管理员权限（中间件验证）
  • ✅ 全局统计（聚合函数）
  • ✅ 用户统计（关联统计）
  • ✅ API 文档（Scribe 自动生成）

技能掌握总结

已掌握的 Laravel API 技能

模块 掌握程度 核心知识点
✅ Sanctum 认证 ★★★★☆ Token 认证、注册/登录/登出
✅ Model 关系 ★★★★☆ 一对多关系、预加载优化
✅ Form Request ★★★☆☆ 验证规则、自定义错误消息
✅ API Resource ★★★☆☆ 数据格式化、条件渲染
✅ 分页查询 ★★★★☆ paginate、per_page 参数
✅ Feature Tests ★★★☆☆ 自动化测试、断言验证
✅ 异常处理 ★★★☆☆ 统一异常处理机制
✅ 中间件权限 ★★★☆☆ 自定义中间件、权限控制
✅ 复杂查询 ★★★☆☆ 筛选/搜索/排序/组合查询
✅ Eloquent 高级查询 ★★★☆☆ 预加载、关联统计、聚合函数
✅ API 文档工具 ★★★☆☆ Scribe 安装、配置、注解

总体掌握水平

当前水平：中级 Laravel API 开发者

可以独立完成：

  • ✅ 从零开始搭建 Laravel API 项目
  • ✅ 实现用户认证和权限控制
  • ✅ 设计 RESTful API 接口
  • ✅ 处理复杂的数据库查询
  • ✅ 编写自动化测试
  • ✅ 生成专业的 API 文档

核心知识点总结

1. 预加载优化

N+1 问题：

  • 查询主模型 + 循环访问关联模型
  • 导致 1 + N 次数据库查询

解决方案：

  • 使用 with() 预加载关联数据
  • 查询次数降低到 2 次
  • 指定字段：with('user:id,name,email')

2. withCount 的巧妙用法

1
2
3
'tasks as completed_tasks' => function ($query) {
    $query->where('status', 'completed');
}

分解：

  • tasks - 关联关系名
  • as completed_tasks - 自定义字段名
  • => function ($query) - 添加筛选条件

作用：

  • 一个查询完成多个统计
  • 避免循环查询
  • 性能优化

3. API 文档自动化

Scribe 优势：

  • 自动分析代码生成文档
  • 支持 PHPDoc 注解增强说明
  • 界面美观、易于测试
  • 导出 Postman 集合和 OpenAPI 规范

参考资源

总结

本次学习完成了 Eloquent 高级查询 和 API 文档工具 两个核心模块，从基础 CRUD 操作提升到了中级 API 开发水平。

关键收获：

  1. ✅ 理解了 N+1 查询问题及其解决方案
  2. ✅ 掌握了预加载和关联统计的用法
  3. ✅ 学会了聚合函数的实际应用
  4. ✅ 实现了 API 文档自动化生成
  5. ✅ 完成了完整的 Laravel API 项目开发

学习完成日期： 2026-07-09
项目地址： ~/Herd/task-api/