作者： gzzhiyi

1. 音符时值

音符时值表示音符的持续时间，常见音符及其时值如下：

• 全音符：4拍
• 二分音符：2拍
• 四分音符：1拍
• 八分音符：0.5拍
• 十六分音符：0.25拍

2. 拍号

拍号决定每小节的拍数和每拍的时值，通常表示为分数，如4/4、3/4等。

• 分子：每小节的拍数
• 分母：每拍的音符类型（4代表四分音符，8代表八分音符）

3. 计算一拍的时值

以4/4拍为例：

• 拍号：4/4
• 每拍时值：四分音符（分母为4）
• 每拍时长：1拍

4. 不同拍号的时值计算

• 3/4拍：每拍为四分音符，每小节3拍。
• 6/8拍：每拍为八分音符，每小节6拍。

5. 示例

• 4/4拍：四分音符=1拍，二分音符=2拍，全音符=4拍。
• 6/8拍：八分音符=1拍，四分音符=2拍，附点四分音符=3拍。

6. 实际应用

• 4/4拍：四分音符=1拍，八分音符=0.5拍。
• 3/4拍：四分音符=1拍，二分音符=2拍。

总结

音符一拍的时值由拍号决定，分母指定每拍的音符类型，分子决定每小节的拍数。

一、前期准备：项目初始化与基础配置

1.1 项目创建与依赖安装

Laravel 内置API开发支持，无需额外引入前端脚手架，推荐使用纯净API项目初始化方式：

# 创建Laravel项目
composer create-project laravel/laravel laravel-api

# 进入项目目录
cd laravel-api

# 禁用前端相关依赖（可选，纯API无需前端）
rm -rf resources/js resources/css package.json vite.config.js

1.2 环境配置与数据库连接

修改根目录 .env 文件，配置核心环境变量，确保数据库、时区、接口响应格式适配后端API：

# 应用基础配置
APP_NAME=LaravelAPI
APP_ENV=local
APP_KEY=生成的密钥
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_TIMEZONE=Asia/Shanghai
APP_LOCALE=zh-CN

# 数据库配置（MySQL为例）
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_api
DB_USERNAME=root
DB_PASSWORD=

# 接口跨域配置（后续详解）
ALLOWED_ORIGINS=*

生成应用密钥（必填，保障加密安全）：

php artisan key:generate

二、路由：API路由定义与规范

2.1 API专属路由文件

Laravel 提供 routes/api.php 路由文件，专门用于定义后端接口，默认前缀 /api，无需手动添加，且不包含Session中间件，适配无状态API。

2.2 基础路由定义

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\UserController;
use App\Http\Controllers\Api\PostController;

// 单接口路由
Route::get('/test', function () {
    return response()->json([
        'code' => 200,
        'msg' => 'API接口正常',
        'data' => []
    ]);
});

// 控制器路由（推荐）
Route::get('/users', [UserController::class, 'index']); // 用户列表
Route::get('/users/{id}', [UserController::class, 'show']); // 单个用户
Route::post('/users', [UserController::class, 'store']); // 创建用户
Route::put('/users/{id}', [UserController::class, 'update']); // 更新用户
Route::delete('/users/{id}', [UserController::class, 'destroy']); // 删除用户

2.3 资源路由（RESTful规范）

针对标准CRUD接口，使用资源路由简化定义，自动映射RESTful风格接口：

// 完整资源路由
Route::apiResource('posts', PostController::class);

// 仅指定部分接口
Route::apiResource('posts', PostController::class)->only(['index', 'show']);

// 排除部分接口
Route::apiResource('posts', PostController::class)->except(['destroy']);

2.4 路由分组与中间件

对接口进行分组管理，统一添加前缀、中间件（如鉴权、跨域）：

Route::prefix('v1')->group(function () {
    // 公开接口
    Route::post('/login', [AuthController::class, 'login']);
    Route::post('/register', [AuthController::class, 'register']);

    // 需鉴权接口
    Route::middleware('auth:sanctum')->group(function () {
        Route::get('/user/info', [AuthController::class, 'userInfo']);
        Route::apiResource('posts', PostController::class);
    });
});

三、控制器：API业务逻辑处理

3.1 创建API专用控制器

推荐在 app/Http/Controllers/Api 目录下创建控制器，区分前后端，命令行创建：

# 创建基础控制器
php artisan make:controller Api/UserController

# 创建资源控制器（自带CRUD方法）
php artisan make:controller Api/PostController --api

3.2 控制器标准写法（API响应规范）

后端API统一返回JSON格式数据，遵循 code+msg+data 响应规范，避免直接返回原生数据：

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;

class UserController extends Controller
{
    /**
     * 用户列表
     */
    public function index(Request $request)
    {
        // 分页查询
        $users = User::query()->paginate(10);
        return $this->success('用户列表获取成功', $users);
    }

    /**
     * 单个用户详情
     */
    public function show($id)
    {
        $user = User::find($id);
        if (!$user) {
            return $this->fail('用户不存在', 404);
        }
        return $this->success('用户详情获取成功', $user);
    }

    /**
     * 统一成功响应
     */
    protected function success($msg = '操作成功', $data = [], $code = 200)
    {
        return response()->json([
            'code' => $code,
            'msg' => $msg,
            'data' => $data
        ]);
    }

    /**
     * 统一失败响应
     */
    protected function fail($msg = '操作失败', $code = 400)
    {
        return response()->json([
            'code' => $code,
            'msg' => $msg,
            'data' => []
        ]);
    }
}

四、请求验证：参数校验与异常处理

4.1 表单请求验证（推荐）

创建独立验证类，分离校验逻辑与业务逻辑，命令行创建：

php artisan make:request Api/UserStoreRequest

编写验证规则（app/Http/Requests/Api/UserStoreRequest.php）：

<?php

namespace App\Http\Requests\Api;

use Illuminate\Foundation\Http\FormRequest;

class UserStoreRequest extends FormRequest
{
    /**
     * 权限判断
     */
    public function authorize()
    {
        return true; // 开放接口直接返回true
    }

    /**
     * 验证规则
     */
    public function rules()
    {
        return [
            'username' => 'required|string|unique:users|max:20',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:6|confirmed',
        ];
    }

    /**
     * 自定义错误提示
     */
    public function messages()
    {
        return [
            'username.required' => '用户名不能为空',
            'email.unique' => '邮箱已被注册',
            'password.confirmed' => '两次密码不一致',
        ];
    }
}

4.2 控制器调用验证

public function store(UserStoreRequest $request)
{
    // 验证通过后获取安全参数
    $data = $request->validated();
    $data['password'] = Hash::make($data['password']);
    $user = User::create($data);
    return $this->success('用户创建成功', $user);
}

4.3 全局异常处理（API适配）

修改 app/Exceptions/Handler.php，将异常转为JSON响应，避免页面报错：

use Illuminate\Validation\ValidationException;

public function register()
{
    $this->renderable(function (ValidationException $e, $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'code' => 422,
                'msg' => '参数校验失败',
                'data' => $e->errors()
            ], 422);
        }
    });
}

五、数据库：迁移、模型与数据操作

5.1 数据迁移（表结构管理）

通过迁移文件管理数据库表，无需手动建表：

# 创建迁移文件
php artisan make:migration create_posts_table

# 执行迁移（建表）
php artisan migrate

# 回滚迁移
php artisan migrate:rollback

迁移文件示例（创建文章表）：

public function up()
{
    Schema::create('posts', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->text('content');
        $table->integer('user_id');
        $table->timestamps();
    });
}

5.2 模型定义与关联

# 创建模型
php artisan make:model Post

模型配置（app/Models/Post.php）：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasFactory;

    // 允许批量赋值字段
    protected $fillable = ['title', 'content', 'user_id'];

    /**
     * 关联用户（一对多）
     */
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

5.3 API常用数据操作

• 分页查询：Post::paginate(10)，自动返回分页元数据

• 条件筛选：Post::where('user_id', $userId)->get()

• 关联查询：Post::with('user')->paginate(10)（预加载避免N+1问题）

• 新增数据：Post::create($validatedData)

• 更新数据：Post::findOrFail($id)->update($validatedData)

• 删除数据：Post::findOrFail($id)->delete()

六、接口鉴权：Sanctum无状态认证

6.1 Sanctum安装与配置

Laravel官方推荐的轻量级API鉴权方案，无状态、适配纯后端接口：

# 安装Sanctum
composer require laravel/sanctum

# 发布配置文件
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

# 执行迁移（生成令牌表）
php artisan migrate

在 app/Models/User.php 引入令牌 trait：

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

6.2 登录签发令牌

public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required|string',
    ]);

    if (!Auth::attempt($credentials)) {
        return $this->fail('账号或密码错误', 401);
    }

    $user = Auth::user();
    // 签发令牌
    $token = $user->createToken('api_token')->plainTextToken;

    return $this->success('登录成功', [
        'token' => $token,
        'user' => $user
    ]);
}

6.3 鉴权中间件使用

在路由中添加 auth:sanctum 中间件，保护接口：

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user/profile', [AuthController::class, 'profile']);
    Route::apiResource('posts', PostController::class);
});

前端请求时，在请求头携带令牌：Authorization: Bearer 令牌值

6.4 退出登录（销毁令牌）

public function logout(Request $request)
{
    $request->user()->currentAccessToken()->delete();
    return $this->success('退出登录成功');
}

七、跨域处理：API接口跨域解决方案

纯后端API需解决跨域问题，Laravel 自带跨域中间件，修改配置文件 config/cors.php：

return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['*'], // 生产环境替换为具体域名
    'allowed_origins_patterns' => [],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => false,
];

修改后重启服务，跨域中间件自动生效。

八、API优化与进阶技巧

8.1 资源响应（格式化输出）

使用API资源类统一数据返回格式，避免字段冗余：

# 创建资源类
php artisan make:resource PostResource

资源类编写（app/Http/Resources/PostResource.php）：

public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'content' => $this->content,
        'author' => $this->user->username ?? '',
        'create_time' => $this->created_at->toDateTimeString(),
    ];
}

控制器调用：return $this->success('获取成功', PostResource::collection($posts));

8.2 接口限流（防恶意请求）

使用Laravel内置限流中间件，限制接口请求频率：

// 限制1分钟内最多60次请求
Route::middleware('throttle:60,1')->group(function () {
    Route::post('/login', [AuthController::class, 'login']);
});

8.3 软删除与数据恢复

迁移文件添加软删除字段，模型引入软删除trait，避免物理删除数据：

// 迁移文件
$table->softDeletes();

// 模型
use Illuminate\Database\Eloquent\SoftDeletes;
class Post extends Model
{
    use SoftDeletes;
}

九、接口调试与启动

• 启动服务：php artisan serve，默认地址 http://127.0.0.1:8000
• 路由查看：php artisan route:list，查看所有API路由详情
• 调试工具：使用Postman、ApiFox等接口工具调试，无需前端页面
• 日志查看：日志文件位于 storage/logs/laravel.log，排查后端异常