laravel/api项目基础搭建、注册及登录api逻辑

前言

在数字化转型的浪潮中，高效、安全的API开发与管理成为了企业快速响应市场变化、提升用户体验的关键。本指南旨在通过一系列精心设计的步骤，引领您从零开始，逐步构建并优化一个基于dingo/api框架的API服务系统。从链接虚拟机创建新项目的基础搭建，到安装配置dingo/api环境，再到路由规划、控制器准备、API文档编写及注册认证等核心环节，每一步都力求详尽且实用。
我们不仅关注技术实现的细节，更重视用户体验与安全性，如通过细致的表单验证、灵活的token管理策略，确保API服务的健壮性与易用性。此外，本指南还涵盖了测试与文档编写的最佳实践，助力您轻松构建出既符合标准又易于维护的API服务。无论您是API开发的初学者还是寻求优化现有系统的专业人士，相信本指南都能为您提供宝贵的参考与帮助。

1、链接虚拟机创建新项目

1.1、链接虚拟机

sudo vagrant up：

1.2、创建新项目

进入到code文件夹下，运行命令composer create-project --prefer-dist laravel/laravel=8.4.4 shopProjectApi创建laravel项目：

1.3、修改配置

然后修改homestead.yaml：

运行命令vagrant reload --provision重启虚拟机：

然后再在/etc/host下写入域名映射：

2、安装dingo/api

安装dingo/api查看本篇博客。

3、api登陆认证配置

api登陆认证配置查看本篇博客。

4、路由

4.1 路由分层

在routes文件夹下复制两个api.php重命名：auth.php， admin.php，一个是权限相关的路由，一个是后台相关的路由：

4.2 路由注册

在app\Providers\Providers\RouteServiceProvider.php下进行注册刚刚创建的两个路由：

            /** 用户认证相关路由 */
            Route::prefix('api')
                ->middleware('api')
                ->namespace($this->namespace)
                ->group(base_path('routes/auth.php'));

            /** 后台路由 */
            Route::prefix('api')
                ->middleware('api')
                ->namespace($this->namespace)
                ->group(base_path('routes/admin.php'));

5、控制器准备

5.1 控制器分组

在app/Http/Controllers文件夹下创建3个文件夹Admin、Auth、Web分别用来管理后台、认证、前台控制器。

5.2 创建基础控制器

命令：php artisan make:controller BaseController

BaseController代码：

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Dingo\Api\Routing\Helpers;

class BaseController extends Controller
{
    use Helpers;
}

使用dingo/api的响应生成器，控制器需要使用 Dingo\Api\Routing\Helpers。以后创建的控制权都继承基础控制器。

6、api文档

api文档上我们使用showdoc，下载客户端

我们可以新建项目，在项目在分模块写文档，这部分就不在这里赘述了。

---

7、注册api

7.1 创建注册路由

注册路由我们把它归属到认证模块去，在routes/auth.php下去写：

<?php

use App\Http\Controllers\Auth\RegisterController;

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    // 路由组
    $api->group(['prefix' => 'auth'], function ($api) {
        // 注册
        $api->post('register', [RegisterController::class, 'store']);

        
    });
});

7.2 创建注册控制器

运行命令php artisan make:controller Auth/RegisterController，创建注册控制器。

7.3 创建表单验证类

运行命令php artisan make:request Auth/RegisterRequest


可以看到Http文件夹下就多了Requests文件夹以及验证文件。
效仿基础控制器，我们再建一个基础验证类。
运行命令：php artisan make:request BaseRequest

---

修改BaseRequest.php为如下：

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class BaseRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }
}

---

然后RegisterRequest.php继承BaseRequest类，并写入规则：

<?php
<?php

namespace App\Http\Requests\Auth;

use App\Http\Requests\BaseRequest;
use Illuminate\Foundation\Http\FormRequest;

class RegisterRequest extends BaseRequest
{
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'name' => 'required|max:16',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:6|max:16|confirmed',
        ];
    }
}

unique:users -> 邮箱在users表中唯一。
confirmed -> 表示必须要传一个password_confirmation确认密码字段并且和password字段值相等。

---

然后注册控制器不使用原始的request，而使用我们自己写的：

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\BaseController;
use App\Http\Requests\Auth\RegisterRequest;
use App\Models\User;
use Illuminate\Http\Request;

class RegisterController extends BaseController
{
    /**
     * 用户注册 
     */
    public function store(RegisterRequest $request) {
        $user = new User();
        $user->name = $request->input('name');
        $user->email = $request->input('email');
        $user->password = bcrypt($request->input('password'));
        $user->save();
        return $this -> response -> created();
    }
}

7.4 测试

测试：

7.4.1 配置语言包

可以看到我们的验证提示都是英文的，我们可以去下载中文包去配置。
laravel配置语言包请查看这篇文章

1、默认效果

配置完中文语言包的效果：

---

2、自定义提示消息

如果说我们不想要它默认的，想要自定义的，我们可以在RegisterRequest.php这样写（其他类似）：

public function messages() {
        return [
            'email.unique' => '邮箱已经存在，你还想注册？怎么不上天呢？'
        ];
    }

效果：

7.4.2 更改时区

在config/app.php修改：
'timezone' => 'Asia/Shanghai'：

---

8、登陆api

8.1、创建登陆api控制器

运行命令php artisan make:controller Auth/LoginController：

控制器写入一下方法，代码：

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\BaseController;
use Illuminate\Http\Request;

class LoginController extends BaseController
{
    /**
     * 登陆
     */
    public function login()
    {
        $credentials = request(['email', 'password']);

        if (!$token = auth('api')->attempt($credentials)) {
            return $this->response()->errorUnauthorized();
        }

        return $this->respondWithToken($token);
    }

    /**
     * Get the authenticated User.
     * 获取个人信息
     * @return \Illuminate\Http\JsonResponse
     */
    //public function me()
    //{
    //    return response()->json(auth('api')->user());
    //}

    /**
     * 退出登陆
     */
    public function logout()
    {
        auth('api')->logout();

        return response()->json(['message' => 'Successfully logged out']);
    }

    /**
     * Refresh a token.
     * 刷新token
     * @return \Illuminate\Http\JsonResponse
     */
    public function refresh()
    {
        return $this->respondWithToken(auth('api')->refresh());
    }

    /**
     * 格式化返回
     */
    protected function respondWithToken($token)
    {
    	// 方法一
        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
            'expires_in' => auth('api')->factory()->getTTL() * 60
        ]);
		// 方法二
        // return $this->response()->array([
        //     'access_token' => $token,
        //     'token_type' => 'Bearer',
        //     'expires_in' => auth('api')->factory()->getTTL() * 60
        // ]);
    }
}

---

8.2 修改token过期时间

在config/jwt.php中找到
再去.env配置环境中配置JWT_TTL，默认为一小时：

8.3、创建登陆路由

在routes\auth.php文件下创建登陆路由：

// 登陆
        $api->post('login', [LoginController::class, 'login']);

8.4、创建登陆表单验证

运行命令：php artisan make:request Auth/LoginRequest

在LoginRequest.php写入如下代码：

<?php

namespace App\Http\Requests\Auth;

use App\Http\Requests\BaseRequest;

class LoginRequest extends BaseRequest
{
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'email' => 'required|email ',
            'password' => 'required|min:6|max:16',
        ];
    }
}

修改LoginController.php中登陆控制器，使用我们验证的request：

效果：

9、退出登陆api

9.1 退出登陆路由

// 退出登陆，（前提在登陆后才需要退出登陆）
$api->post('logout', [LoginController::class, 'logout']); 

10、刷新token

10.1、刷新token路由

// 刷新token
$api->post('refresh', [LoginController::class, 'refresh']); 

11、编写文档

在showdoc里去编写我们写的接口文档：

##### 简要描述

- 用户注册接口

##### 请求URL
- `/api/auth/register `
  
##### 请求方式
- POST 

##### 参数

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|name |是  |string |用户名 最大长度16  |
|email     |是  |string | 邮箱  邮箱格式  |
|password |是  |string | 密码 最小长度6 最大长度16   |
|password_confirmation  |是  |string | 确认密码 和密码一样   |


##### 返回示例 
- 状态码 201 创建成功

- 状态码 422 参数错误
{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "名称 不能为空。"
        ],
        "email": [
            "邮箱 不能为空。"
        ],
        "password": [
            "密码 不能为空。"
        ]
    },
    "status_code": 422
}

以后写的其他接口也类似这样去写接口文档，接口文档是很重要的，方便前端去对接，也方便自己查阅，不要忽略了，这边写个例子，以后不在赘述。

在学习的php的路上，如果你觉得本文对你有所帮助的话，那就请关注点赞评论三连吧，谢谢，你的肯定是我写博的另一个支持。