PHP 接口开发：RESTful API 设计与实战

// 用户API路由
Route::prefix('v1')->group(function () {
    Route::get('/users', [\App\Http\Controllers\Api\UserController::class, 'index']); // 列表
    Route::post('/users', [\App\Http\Controllers\Api\UserController::class, 'store']); // 创建
    Route::get('/users/{id}', [\App\Http\Controllers\Api\UserController::class, 'show']); // 详情
    Route::put('/users/{id}', [\App\Http\Controllers\Api\UserController::class, 'update']); // 更新
    Route::delete('/users/{id}', [\App\Http\Controllers\Api\UserController::class, 'destroy']); // 删除
});

<?php
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;

class UserController extends Controller
{
    /**
     * 获取用户列表
     * @return JsonResponse
     */
    public function index(): JsonResponse
    {
        $users = User::paginate(10); // 分页
        return response()->json([
            'code' => 200,
            'message' => 'success',
            'data' => $users
        ]);
    }

    /**
     * 创建用户
     * @param Request $request
     * @return JsonResponse
     * @throws ValidationException
     */
    public function store(Request $request): JsonResponse
    {
        // 参数验证
        $this->validate($request, [
            'username' => 'required|string|min:3',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:6'
        ]);

        // 创建用户
        $user = User::create([
            'username' => $request->username,
            'email' => $request->email,
            'password' => bcrypt($request->password)
        ]);

        return response()->json([
            'code' => 201,
            'message' => '创建成功',
            'data' => $user
        ], 201);
    }

    /**
     * 获取用户详情
     * @param int $id
     * @return JsonResponse
     */
    public function show(int $id): JsonResponse
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json([
                'code' => 404,
                'message' => '用户不存在'
            ], 404);
        }

        return response()->json([
            'code' => 200,
            'message' => 'success',
            'data' => $user
        ]);
    }

    /**
     * 更新用户
     * @param Request $request
     * @param int $id
     * @return JsonResponse
     * @throws ValidationException
     */
    public function update(Request $request, int $id): JsonResponse
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json([
                'code' => 404,
                'message' => '用户不存在'
            ], 404);
        }

        // 参数验证
        $this->validate($request, [
            'username' => 'string|min:3',
            'email' => 'email|unique:users,email,' . $id
        ]);

        // 更新用户
        $user->update($request->only(['username', 'email']));

        return response()->json([
            'code' => 200,
            'message' => '更新成功',
            'data' => $user
        ]);
    }

    /**
     * 删除用户
     * @param int $id
     * @return JsonResponse
     */
    public function destroy(int $id): JsonResponse
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json([
                'code' => 404,
                'message' => '用户不存在'
            ], 404);
        }

        $user->delete();
        return response()->json([
            'code' => 200,
            'message' => '删除成功'
        ]);
    }
}
?>

composer require tymon/jwt-auth:^1.0

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

php artisan jwt:secret

use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    // ...

    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    public function getJWTCustomClaims()
    {
        return [];
    }
}

public function login(Request $request)
{
    $credentials = $request->only('email', 'password');
    if (!$token = auth()->attempt($credentials)) {
        return response()->json(['code' => 401, 'message' => '账号或密码错误'], 401);
    }

    return response()->json([
        'code' => 200,
        'message' => '登录成功',
        'data' => [
            'token' => $token,
            'expires_in' => auth()->factory()->getTTL() * 60
        ]
    ]);
}

Route::middleware('auth:api')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    // 其他需要认证的接口
});

composer require darkaonline/l5-swagger

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

/**
 * @OA\Get(
 *     path="/api/v1/users",
 *     summary="获取用户列表",
 *     tags={"用户管理"},
 *     @OA\Response(
 *         response=200,
 *         description="成功",
 *         @OA\JsonContent(
 *             @OA\Property(property="code", type="integer", example=200),
 *             @OA\Property(property="message", type="string", example="success"),
 *             @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/User"))
 *         )
 *     )
 * )
 */
public function index()
{
    // ...
}