laravel-quality

Laravel 质量

测试、静态分析和代码质量约束。

相关指南：

• code-style.md - Laravel Pint 配置和编码风格
• type-safety.md - 严格类型和类型提示
• Testing - 全面的测试指南

质量工具链

# composer.json scripts
{
    "test": "pest",
    "analyse": "phpstan analyse",
    "format": "pint",
    "quality": [
        "@analyse",
        "@test"
    ]
}

所有文件顶部都必须包含 declare(strict_types=1)。每次提交前都要运行质量检查。

架构测试（Pest）

设置

tests/Pest.php

pest()->extend(Tests\TestCase::class)->in('Feature', 'Unit');

核心架构测试

tests/Architecture/ActionsTest.php

<?php

declare(strict_types=1);

arch('actions are invokable')
    ->expect('App\Actions')
    ->toHaveMethod('__invoke');

arch('actions live in Actions namespace')
    ->expect('App\Actions')
    ->toBeClasses()
    ->toOnlyBeUsedIn('App\Actions', 'App\Http', 'App\Jobs', 'App\Listeners');

arch('actions do not use models directly')
    ->expect('App\Actions')
    ->not->toUse('Illuminate\Database\Eloquent\Model');

tests/Architecture/DataTest.php

<?php

declare(strict_types=1);

arch('data objects extend base Data class')
    ->expect('App\Data')
    ->toExtend('App\Data\Data')
    ->ignoring('App\Data\Data');

arch('data objects use constructor property promotion')
    ->expect('App\Data')
    ->toHaveConstructor();

tests/Architecture/StrictTypesTest.php

<?php

declare(strict_types=1);

arch('app files declare strict types')
    ->expect('App')
    ->toUseStrictTypes();

arch('test files declare strict types')
    ->expect('Tests')
    ->toUseStrictTypes();

tests/Architecture/ControllersTest.php

<?php

declare(strict_types=1);

arch('controllers do not use DB facade')
    ->expect('App\Http')
    ->not->toUse('Illuminate\Support\Facades\DB');

arch('controllers do not use models directly')
    ->expect('App\Http\Web\Controllers')
    ->not->toUse('App\Models');

tests/Architecture/NamingTest.php

<?php

declare(strict_types=1);

arch('actions end with Action suffix')
    ->expect('App\Actions')
    ->toHaveSuffix('Action');

arch('data objects end with Data suffix')
    ->expect('App\Data')
    ->toHaveSuffix('Data')
    ->ignoring('App\Data\Data', 'App\Data\Concerns');

arch('exceptions end with Exception suffix')
    ->expect('App\Exceptions')
    ->toHaveSuffix('Exception')
    ->ignoring('App\Exceptions\Concerns');

tests/Architecture/ModelsTest.php

<?php

declare(strict_types=1);

arch('models use custom query builders')
    ->expect('App\Models')
    ->toHaveMethod('newEloquentBuilder');

arch('models do not use local scopes')
    ->expect('App\Models')
    ->not->toHaveMethod('scope*');

静态分析（PHPStan）

安装

composer require phpstan/phpstan --dev
composer require phpstan/phpstan-strict-rules --dev
composer require larastan/larastan --dev

配置

phpstan.neon

includes:
    - vendor/larastan/larastan/extension.neon
    - vendor/phpstan/phpstan-strict-rules/rules.neon

parameters:
    level: 8
    paths:
        - app
        - tests
    excludePaths:
        - app/Providers/TelescopeServiceProvider.php
    checkMissingIterableValueType: true
    checkGenericClassInNonGenericObjectType: true
    reportUnmatchedIgnoredErrors: false

运行

./vendor/bin/phpstan analyse

代码风格（Laravel Pint）

安装

composer require laravel/pint --dev

配置

pint.json

{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true,
        "no_unused_imports": true,
        "ordered_imports": {
            "sort_algorithm": "alpha"
        }
    }
}

运行

./vendor/bin/pint
./vendor/bin/pint --test  # Check only

测试覆盖率

启用覆盖率（Pest）

phpunit.xml

<coverage>
    <report>
        <html outputDirectory="coverage"/>
        <text outputFile="php://stdout"/>
    </report>
</coverage>

运行并生成覆盖率

./vendor/bin/pest --coverage
./vendor/bin/pest --coverage --min=80  # Enforce minimum

CI/CD 检查

GitHub Actions 示例

.github/workflows/tests.yml

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite
          coverage: xdebug

      - name: Install Dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Code Style
        run: ./vendor/bin/pint --test

      - name: Static Analysis
        run: ./vendor/bin/phpstan analyse

      - name: Run Tests
        run: ./vendor/bin/pest --coverage --min=80

提交前钩子

安装

composer require brainmaestro/composer-git-hooks --dev

配置

composer.json

{
    "extra": {
        "hooks": {
            "pre-commit": [
                "./vendor/bin/pint",
                "./vendor/bin/phpstan analyse",
                "./vendor/bin/pest"
            ]
        }
    },
    "scripts": {
        "post-install-cmd": "vendor/bin/cghooks add --ignore-lock",
        "post-update-cmd": "vendor/bin/cghooks update"
    }
}

质量指标

跟踪内容

• 测试覆盖率 - 目标为 80% 以上
• PHPStan 级别 - 级别 8（最高）
• 架构测试通过率 - 100%
• 代码风格违规数 - 0

定期审查

• 每周 - 检查测试覆盖率趋势
• 每个 PR - 运行所有质量检查
• 每月 - 审查架构规范符合情况
• 发布前 - 全面质量审计

需要留意的常见问题

反模式

• 在控制器中编写领域逻辑
• 使用作用域而非构建器
• 缺少严格类型声明
• 传递基本类型而非 DTO
• 在任务 / 监听器中编写领域逻辑

类型安全

• 缺少返回类型
• 缺少参数类型
• 缺少属性类型
• 数组 / 集合未指定类型

测试

• 端点缺少功能测试
• 操作缺少单元测试
• 关键路径的覆盖率过低
• 脆弱的测试（模拟对象过多）

执行策略

1. 架构测试 - 自动化检查
2. PR 审查 - 人工核验
3. CI/CD 门禁 - 阻止未通过的构建
4. 团队标准 - 编写文档并开展培训
5. 结对编程 - 分享知识