Laravel Sanctum API using Postman

在当今前后端分离的开发浪潮中，Laravel Sanctum 凭借其轻量、安全、易于集成的 API 认证方案，迅速成为众多开发者构建单页应用、移动端及第三方 API 的首选工具。而 Postman 作为全球最流行的 API 调试平台，与 Sanctum 的组合堪称“黄金搭档”。本文将从实战角度出发，详细讲解如何利用 Postman 高效测试 Laravel Sanctum 构建的 API，助你快速掌握这一主流技术栈。

一、Laravel Sanctum 是什么？为何备受青睐？

Laravel Sanctum 是 Laravel 官方推出的轻量级 API 认证包，专为 SPA（单页应用）、移动应用和简单 API 而生。与传统的 Passport（基于 OAuth2）相比，Sanctum 无需繁琐的授权码流程，也不依赖外部数据库存储令牌，而是通过“API 令牌”或“Cookie 会话”两种模式实现认证。其最大优势在于：开箱即用、零复杂配置、完美兼容 Laravel 内置的认证系统。

核心特性包括： - 极简令牌管理：每个用户可生成多个纯文本令牌，过期时间灵活可控。 - SPA 友好：通过 Cookie 会话无缝对接前端 JS 应用，自动处理 CSRF 防护。 - 轻量级：不引入 OAuth2 的冗余功能，性能开销极小。 - 多平台支持：同样适用于移动端和第三方客户端。

二、为什么需要用 Postman 测试 Sanctum API？

在开发阶段，开发者无法依赖前端界面直接调用 API。Postman 作为强大的 HTTP 客户端，提供了： - 直观的请求构造界面（支持 GET/POST/PUT/DELETE 等） - 变量管理、环境切换、集合测试 - 令牌自动注入与预请求脚本 - 响应格式化与断言验证

通过 Postman，开发者可以独立模拟用户登录、令牌获取、受保护资源访问等全流程，快速定位认证问题。

三、实战步骤：在 Postman 中测试 Sanctum API

1. 环境准备

确保已安装 Laravel 项目并引入 Sanctum：

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

2. 创建 API 路由

在 routes/api.php 中定义示例接口：

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

该路由需要携带有效令牌才能访问。

3. 配置 Sanctum 令牌模式

在 User 模型中添加 HasApiTokens trait：

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

4. 在 Postman 中获取令牌

• 新建一个登录接口路由（例如 POST /api/login），返回令牌。
• 在 Postman 中设置请求：POST http://localhost:8000/api/login，Body 选择 x-www-form-urlencoded，填入 email 和 password。
• 发送请求后，从响应中复制返回的 token 值（通常是一个长的纯文本字符串）。

5. 测试受保护路由

• 新建请求 GET http://localhost:8000/api/user。
• 在 Headers 中手动添加 Authorization: Bearer <你的token>，或将 token 存入 Postman 的环境变量（推荐）。
• 发送请求，成功则返回当前用户信息；失败则返回 401 未授权。

6. 高级技巧：使用 Postman 脚本自动管理令牌

为避免每次手动复制粘贴，可在登录接口的 Tests 中编写预请求脚本：

var jsonData = pm.response.json();
pm.environment.set("token", jsonData.token);

然后在受保护接口的 Authorization 类型选择 Bearer Token，并在右侧 Token 输入框填入 {{token}}。这样登录后令牌会自动填充，极大提升效率。

四、常见问题与解决方案

五、总结与展望

Laravel Sanctum 以其简洁的设计理念，降低了 API 认证的门槛；而 Postman 则通过可视化的调试工具，让开发者能够专注于业务逻辑而非环境搭建。掌握这两者的结合使用，不仅是 Laravel 开发者的必备技能，更是现代 Web 应用高效迭代的关键。

未来，随着 Laravel 11 对 Sanctum 的深度集成（如默认 API 脚手架），以及 Postman 对 GraphQL 和 gRPC 的全面支持，这一组合将在微服务、移动端后端领域发挥更大价值。建议开发者在日常开发中建立标准化的 Postman 集合，结合 CI/CD 管道实现自动化 API 测试，从源头保障接口质量。

立即打开你的编辑器，开始用 Postman 助力 Sanctum API 开发吧！