Laravel通过routes/api.php定义API路由，使用Route::apiResource或HTTP动词方法声明端点，由RouteServiceProvider自动添加/api前缀和api中间件组，确保无状态处理。与web.php的Web路由不同，API路由不依赖Session和CSRF，返回JSON数据，适用于SPA或移动端。常用认证方式包括Laravel Sanctum（推荐用于Token认证）、Passport（支持OAuth2）和Basic Auth。异常处理在AppExceptionsHandler.php中统一管理，针对API请求返回标准化JSON错误响应，如422验证失败、404资源未找到等，提升API可用性。
在Laravel中，定义API路由的核心在于使用
routes/api.php
文件，通过
Route::apiResource
或
Route::get/post/put/delete
等方法来声明API端点，并由
RouteServiceProvider
确保这些路由应用了
api
中间件组，从而实现无状态的认证和处理。
Laravel API的路由定义其实蛮直接的，主要围绕
routes/api.php
这个文件展开。当你创建一个新的Laravel项目时，这个文件就躺在那里了。默认情况下，
RouteServiceProvider
会为
routes/api.php
中的所有路由加上一个
/api
的前缀，并且应用
api
中间件组。这个
api
中间件组很关键，它确保了你的API路由是无状态的，通常不使用session，而是依赖token进行认证。
定义路由的方式和Web路由类似，但侧重点不同：
单个路由定义：你可以像定义Web路由一样，使用
Route::get()
、
Route::post()
、
Route::put()
、
Route::delete()
等方法来定义具体的API端点。
// routes/api.phpRoute::get('/products', [ProductController::class, 'index']);Route::post('/products', [ProductController::class, 'store']);Route::get('/products/{product}', [ProductController::class, 'show']);// ...以此类推
这种方式灵活，适合定义非标准RESTful的接口，或者一些特殊的操作。
API资源路由：对于遵循RESTful规范的资源，Laravel提供了
Route::apiResource()
方法，它会自动生成一套标准的CRUD（创建、读取、更新、删除）路由，但与
Route::resource()
不同的是，它不会生成
create
和
edit
视图相关的路由，因为API通常不需要这些。
// routes/api.phpRoute::apiResource('posts', PostController::class);// 这会生成 /api/posts (GET, POST), /api/posts/{post} (GET, PUT, DELETE) 等路由
我个人非常喜欢
apiResource
，它能大幅减少样板代码，让路由定义看起来非常清晰。当然，如果你需要排除或只包含某些操作，也可以通过
except
或
only
方法来定制。
路由分组与版本控制：随着API的演进，你可能需要对路由进行分组，比如按版本来分。这时候
Route::prefix()
和
Route::middleware()
就派上用场了。
// routes/api.phpRoute::prefix('v1')->group(function () { Route::apiResource('users', UserController::class); Route::get('/dashboard-stats', [DashboardController::class, 'stats']);});Route::prefix('v2')->group(function () { // v2版本的路由 Route::apiResource('users', UserV2Controller::class);});
这种方式让不同版本的API共存，也方便管理。
认证中间件：别忘了，API通常需要认证。你可以在路由定义时直接应用认证中间件，比如使用Laravel Sanctum的
auth:sanctum
。
// routes/api.phpRoute::middleware('auth:sanctum')->group(function () { Route::get('/user', function (Request $request) { return $request->user(); }); Route::apiResource('orders', OrderController::class);});
这确保了只有经过认证的用户才能访问这些端点。
总的来说，Laravel在API路由方面提供了非常灵活且强大的工具集，你可以根据项目的具体需求，选择最适合的方式来定义和组织你的API。
Laravel API路由与Web路由有何不同？
这是个很基础但又经常被问到的问题，尤其对于刚接触Laravel API开发的朋友。简单来说，API路由和Web路由在Laravel中，虽然都定义在
routes
目录下，但它们的设计哲学和处理方式有着本质的区别。
最直观的区别在于它们各自的文件：API路由通常定义在
routes/api.php
，而Web路由则在
routes/web.php
。但这只是表象。
核心差异在于它们所使用的中间件组。
routes/web.php
中的路由默认应用
web
中间件组。这个中间件组包含了像
StartSession
（启动会话）、
ShareErrorsFromSession
（分享错误到会话）、
VerifyCsrfToken
（CSRF保护）等一系列为传统Web应用设计的中间件。这意味着Web路由是有状态的，它依赖Session来维护用户状态，并提供CSRF保护以防止跨站请求伪造攻击。当用户访问Web页面时，Laravel会返回HTML，并可能设置或读取Session数据。
而
routes/api.php
中的路由默认应用
api
中间件组。这个中间件组则轻量得多，它通常只包含
ThrottleRequests
（请求限流）和
SubstituteBindings
（路由模型绑定）等，最重要的是，它不包含Session和CSRF相关的中间件。这使得API路由是无状态的，它们不依赖Session来维护用户状态。API通常返回JSON或其他数据格式，供前端应用（如SPA、移动App）或第三方服务消费。认证机制也多采用基于Token的方式，比如JWT、OAuth2或Laravel Sanctum生成的API Token。
我个人的经验是，很多新手会不小心把API路由定义到
web.php
里，或者把
web
中间件组应用到API路由上。这虽然在某些情况下也能“跑起来”，但很快就会遇到问题，比如Session冲突、不必要的CSRF验证失败，或者性能下降。所以，保持API和Web路由的职责分离，用好各自的中间件组，是构建健壮Laravel应用的关键。API就应该纯粹地处理数据交互，Web就应该专注于用户界面和会话管理。
Laravel API路由中常用的认证方式有哪些？
在Laravel API的生态中，认证是确保API安全的关键一环。毕竟，你不会想让任何人都能随意访问你的数据。Laravel提供了几种非常流行且强大的认证方式，可以根据你的项目需求来选择。
Laravel Sanctum (最推荐的轻量级方案)这是我个人在大多数新项目中首选的API认证方案，因为它轻巧、易用，且功能强大。Sanctum主要解决了三种场景的认证需求：
SPA认证：当你的前端是独立的SPA（单页应用，如Vue、React）时，Sanctum通过Cookie来管理认证，但它与传统的Session认证不同，它会利用CSRF Token来保护API请求，并提供一个安全的认证流程。移动应用/简单API Token：对于移动应用或需要简单API Token的场景，Sanctum允许你为用户生成API Token。这些Token可以存储在客户端，并在每次请求时通过
Authorization: Bearer
头发送。Sanctum会验证这个Token的有效性。个人访问令牌：用户可以生成多个个人访问令牌，并为每个令牌分配特定的权限（Scopes）。这对于允许第三方应用访问用户数据，但又想精细控制权限的场景非常有用。
Sanctum的优势在于它的简洁性和灵活性，对于大多数API项目来说，它都是一个非常好的起点。
Laravel Passport (OAuth2完整实现)如果你的API需要支持OAuth2协议，或者你想构建一个为第三方应用提供服务的API，那么Passport就是你的不二之选。Passport是Laravel官方提供的OAuth2服务器实现，它能让你轻松地为你的API添加以下OAuth2特性：
授权码授权 (Authorization Code Grant)：用于第三方应用安全地获取用户授权。密码授权 (Password Grant)：适用于你自己的第一方客户端应用（如移动App）。客户端凭证授权 (Client Credentials Grant)：适用于机器对机器的通信。隐式授权 (Implicit Grant)：虽然安全性较低，但在某些特定场景下仍有使用。个人访问令牌 (Personal Access Tokens)：与Sanctum类似，但基于OAuth2标准。
Passport的功能非常强大，但相对Sanctum来说，配置和理解会稍微复杂一些。如果你的项目需要完整的OAuth2功能，或者你预计会有大量的第三方集成，那么投入时间学习Passport是值得的。
Basic Authentication (HTTP基本认证)虽然不太常见于生产环境的公共API，但HTTP基本认证在某些内部系统或特定场景下仍有应用。它通过在请求头中发送Base64编码的用户名和密码来认证。Laravel可以通过自定义中间件或利用
Auth::basic()
方法来支持。它的缺点是安全性相对较低，因为凭据是直接编码发送的，容易被截获。
选择哪种认证方式，真的取决于你的API服务对象和安全需求。对于大多数只需要简单API Token的移动App或SPA后端，Sanctum是极佳的选择。如果你的API是一个平台，需要让其他开发者构建应用，那么Passport的OAuth2能力会是必需品。
Laravel API路由中如何处理异常和错误响应？
处理API中的异常和错误响应，不仅仅是让程序不崩溃那么简单，它更是提供良好API用户体验的关键。一个设计糟糕的错误响应，比一个直接500的响应还要令人抓狂，因为它让调用者不知道如何处理。Laravel在这个方面做得非常出色，提供了强大的机制来统一处理异常并返回友好的JSON错误响应。
核心在于Laravel的
AppExceptionsHandler.php
文件。这个类是所有未捕获异常的“最终归宿”。你可以重写其中的
render
方法来定制不同类型异常的HTTP响应。
1. 统一的错误响应格式：我通常会定义一个统一的JSON错误响应结构。这样，无论出现什么错误，调用者都能预期接收到类似格式的数据，便于前端或客户端进行解析和处理。一个常见的格式可能包含
message
、
errors
（详细错误信息，通常是验证错误）、
code
（内部错误码，可选）和
status
（HTTP状态码）。
// AppExceptionsHandler.phpuse IlluminateValidationValidationException;use SymfonyComponentHttpKernelExceptionNotFoundHttpException;use Throwable;public function render($request, Throwable $exception){ if ($request->is('api/*')) { // 仅对API请求进行JSON错误响应 if ($exception instanceof ValidationException) { return response()->json([ 'message' => 'The given data was invalid.', 'errors' => $exception->errors(), ], 422); // 422 Unprocessable Entity } if ($exception instanceof NotFoundHttpException) { return response()->json([ 'message' => 'Resource not found.', ], 404); // 404 Not Found } // 更多自定义异常处理... // 默认的服务器错误 return response()->json([ 'message' => 'Server Error.', // 生产环境不应该暴露详细错误信息 // 'debug' => config('app.debug') ? $exception->getMessage() : null, ], 500); // 500 Internal Server Error } return parent::render($request, $exception);}
2. 利用HTTP状态码：正确使用HTTP状态码至关重要。它们是API与客户端之间沟通错误性质的通用语言。
200 OK
：请求成功。
201 Created
：资源创建成功。
400 Bad Request
：客户端发送的请求有语法错误，服务器无法理解。
401 Unauthorized
：请求需要用户认证。
403 Forbidden
：服务器理解请求，但拒绝执行。
404 Not Found
：请求的资源不存在。
405 Method Not Allowed
：请求方法不被允许。
422 Unprocessable Entity
：客户端发送的数据验证失败（Laravel的
ValidationException
默认会返回这个）。
500 Internal Server Error
：服务器内部错误。
3. 自定义异常类：对于应用程序特有的错误，创建自定义异常类是个好习惯。这样，你可以在业务逻辑中抛出这些异常，然后在
Handler.php
中捕获并返回特定的JSON响应。
// App/Exceptions/ProductNotFoundException.phpnamespace AppExceptions;use Exception;use IlluminateHttpJsonResponse;class ProductNotFoundException extends Exception{ public function render($request): JsonResponse { return response()->json([ 'message' => 'Product not found with the given ID.', 'code' => 'PRODUCT_001' ], 404); }}// 在控制器或服务中抛出throw new ProductNotFoundException();
4. 验证错误处理：Laravel的表单请求（Form Requests）在验证失败时，会自动抛出
ValidationException
。由于我们在
Handler.php
中处理了它，API请求会自动收到一个422状态码和详细的错误信息。这是Laravel非常方便的一个特性。
在我看来，错误处理是API开发中很容易被忽视，但又极其重要的一环。一个清晰、一致且富有信息的错误响应机制，能极大提升你的API的可用性和开发者的满意度。花时间设计好它，绝对是值得的。
以上就是Laravel API开发？API路由如何定义？的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/150045.html
微信扫一扫 
支付宝扫一扫 
