如何构建符合DRY原则的Laravel资源API？方案优劣与优化方法

为什么不普遍采用单一路由/控制器/通用CRUD服务？ #

这种方案看似能减少重复代码，但实际落地会遇到诸多痛点，也是多数开发者不优先选择它的原因：

• 业务逻辑无法统一：多数资源的CRUD并非纯增删改查，比如用户资源需要密码加密、订单有状态流转校验、文章要生成slug，通用服务硬塞这些特殊逻辑会快速变得臃肿，后续维护难度指数级上升。
• 违背RESTful语义与可读性：单一路由如/api/{resource}/{id}虽然简洁，但无法直观体现资源的业务定位，其他开发者接手时要额外解析resource参数，调试、文档生成也不如独立路由清晰。
• 权限控制粒度不足：不同资源的权限规则差异大（比如普通用户只能修改自己的文章，管理员能操作所有资源），单控制器里做权限判断会堆满if-else，代码可读性极差。
• 扩展性受限：当某个资源需要新增特殊接口（比如/api/posts/{id}/publish），单控制器会越来越杂，而独立控制器可以轻松添加方法，保持职责单一。

两种方案的取舍对比 #

独立路由/控制器方案 #

• 适用场景：资源有独特业务逻辑、权限规则复杂、需要自定义端点、团队协作开发（分工明确）。
• 优势：职责单一、代码可读性高、调试定位问题快、符合Laravel生态常规实践，社区支持充足。
• 劣势：资源数量多会产生重复代码，文件数量较多。

通用路由/控制器/服务方案 #

• 适用场景：所有资源都是纯CRUD无特殊逻辑、资源数量极多且逻辑完全一致、快速搭建原型阶段。
• 优势：代码量少、文件数量少、上手快。
• 劣势：难以适配特殊业务逻辑、代码臃肿可读性差、权限控制繁琐、不符合RESTful规范，后期维护成本极高。

优化独立方案以遵循DRY原则的方法 #

1. 抽象通用基础控制器 #

创建BaseResourceController封装通用CRUD逻辑，其他资源控制器继承它，仅重写需要特殊处理的方法：

// app/Http/Controllers/Api/BaseResourceController.php
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;

abstract class BaseResourceController extends Controller
{
    protected $model;
    protected $resource;

    public function __construct(Model $model, $resource)
    {
        $this->model = $model;
        $this->resource = $resource;
    }

    public function index(Request $request)
    {
        $query = $this->model->query();
        // 通用分页、过滤逻辑
        return $this->resource::collection($query->paginate());
    }

    public function show($id)
    {
        $model = $this->model->findOrFail($id);
        return new $this->resource($model);
    }

    // 其他通用方法...
}

资源控制器继承示例：

// app/Http/Controllers/Api/PostController.php
namespace App\Http\Controllers\Api;

use App\Models\Post;
use App\Http\Resources\PostResource;

class PostController extends BaseResourceController
{
    public function __construct()
    {
        parent::__construct(Post::class, PostResource::class);
    }

    // 重写需要特殊处理的store方法
    public function store(Request $request)
    {
        $validated = $request->validate([
            'title' => 'required|string',
            'content' => 'required|string',
        ]);
        $post = $this->model->create($validated);
        // 新增业务逻辑：触发文章创建事件
        event(new PostCreated($post));
        return new $this->resource($post);
    }
}

2. 抽离通用CRUD服务类 #

将通用数据操作逻辑封装到BaseCrudService，资源专属服务类继承后仅处理特殊业务：

// app/Services/BaseCrudService.php
namespace App\Services;

use Illuminate\Database\Eloquent\Model;

class BaseCrudService
{
    protected $model;

    public function __construct(Model $model)
    {
        $this->model = $model;
    }

    public function getAll(array $filters = [])
    {
        $query = $this->model->query();
        foreach ($filters as $key => $value) {
            $query->where($key, $value);
        }
        return $query->paginate();
    }

    public function getById($id)
    {
        return $this->model->findOrFail($id);
    }

    // 其他通用方法...
}

3. 批量注册API资源路由 #

利用Laravel的apiResource或apiResources批量生成路由，减少重复代码：

// routes/api.php
use Illuminate\Support\Facades\Route;

// 批量注册资源路由
Route::apiResources([
    'posts' => \App\Http\Controllers\Api\PostController::class,
    'users' => \App\Http\Controllers\Api\UserController::class,
    'comments' => \App\Http\Controllers\Api\CommentController::class,
]);

4. 复用请求验证规则 #

创建基础请求类封装通用授权逻辑，资源请求类继承后仅定义专属验证规则：

// app/Http/Requests/BaseResourceRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

abstract class BaseResourceRequest extends FormRequest
{
    public function authorize()
    {
        return auth()->check();
    }
}

5. 用Traits封装共享逻辑 #

针对多个资源共享的非通用逻辑（比如生成slug、状态流转），用Traits封装后在Model中引入：

// app/Traits/HasSlug.php
namespace App\Traits;

trait HasSlug
{
    protected static function bootHasSlug()
    {
        static::creating(function ($model) {
            $model->slug = str_slug($model->title);
        });

        static::updating(function ($model) {
            if ($model->isDirty('title')) {
                $model->slug = str_slug($model->title);
            }
        });
    }
}

在Model中使用：

// app/Models/Post.php
namespace App\Models;

use App\Traits\HasSlug;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasSlug;
    // ...
}

内容的提问来源于stack exchange，提问作者jon