CatchShop 商城

主题

CatchShop 商城系统 ​

CatchShop 是一款专业的商城系统，采用 PHP 语言开发，基于 Laravel 12 框架构建的模块化电商 API 系统。采用严格的三层架构设计，通过 Repository-Service-Controller 模式确保代码的可维护性和可扩展性，为企业提供完整的 Laravel 商城解决方案。

🏗️ 核心架构 ​

三层调用模式 ​

Controller → Service → Repository → Model
    ↓         ↓          ↓         ↓
  路由处理   业务逻辑    数据访问   数据模型

调用约定：

  • Controller：仅负责接收请求、调用 Service、返回响应，不包含业务逻辑
  • Service：聚合业务逻辑，处理复杂的业务规则，调用多个 Repository
  • Repository：专注数据访问，提供统一的数据操作接口，继承基础 Repository 类
  • Model：数据模型定义，关联关系配置

实际调用示例 ​

php
// Controller 层 - 仅做请求响应处理
class ProductController extends Controller
{
    public function search(Request $request)
    {
        $result = $this->productService->search($request->validated());
        return $this->success($result);
    }
}

// Service 层 - 业务逻辑聚合
class ProductService
{
    public function search(array $filters): mixed
    {
        $filters = $this->validateAndCleanFilters($filters);
        return $this->products->searchByFilters($filters);
    }
}

// Repository 层 - 数据访问
class ProductsRepository extends Repository
{
    public function model(): string
    {
        return Product::class;
    }

    public function searchByFilters(array $filters)
    {
        return $this->query()
            ->when($filters['keyword'], fn($q) => $q->whereLike('name', $filters['keyword']))
            ->orderBy($filters['sort'], $filters['order'])
            ->paginate($filters['limit']);
    }
}

🎯 设计模式 ​

1. 工厂模式 - 订单处理器 ​

php
// 根据订单类型动态选择处理器
$processor = OrderFactory::make(OrderSource::POINTS);
$order = $processor->create($orderData);

支持的订单类型：

  • NORMAL - 普通订单
  • POINTS - 积分订单
  • SECKILL - 秒杀订单
  • GROUP_BUY - 拼团订单

2. 模板方法模式 - 订单创建流程 ​

php
abstract class AbstractOrderService
{
    public function create(array $data): Order
    {
        $priceData = $this->prepare($data);           // 子类实现：验证/定价
        $order = $this->createOrderRecord($data);     // 公共逻辑
        $this->createOrderItems($order, $data);       // 公共逻辑
        $this->afterOrderCreated($order, $data);      // 子类可选实现
        return $order;
    }

    abstract protected function prepare(array &$data): array;
}

3. 事件订阅模式 ​

php
// 用户余额变动自动记录日志
Event::subscribe(UserEventSubscriber::class);

🌐 路由架构 ​

自动路由加载 ​

系统通过 MallServiceProvider 自动扫描并加载所有模块路由：

php
// 公开路由 (无需认证)
Route::prefix('api/mall/{module}')->group($module->getPublicRoutePath());

// 认证路由 (需要登录)
Route::middleware(['api', 'mall.auth:app'])
    ->prefix('api/mall/{module}')
    ->group($module->getAuthRoutePath());

URL 规范 ​

  • 公开接口：/api/mall/product/search
  • 认证接口：/api/mall/user/profile
  • 分类组织：/api/mall/points/user/daily/sign

📡 API 响应规范 ​

统一响应格式 ​

php
// 成功响应
{
    "code": 20000,
    "message": "success",
    "data": {...}
}

// 错误响应
{
    "code": 20001,
    "message": "参数错误"
}

// 分页响应
{
    "code": 20000,
    "message": "success",
    "data": [...],
    "total": 100,
    "limit": 15,
    "page": 1
}

状态码定义 ​

  • 20000 - 成功
  • 20001 - 失败
  • 20004 - 资源不存在
  • 20005 - 参数错误
  • 20006 - 权限不足
  • 20008 - 登录失败

🏪 业务模块 ​

Foundation - 基础设施 ​

CatchShop 商城系统提供完善的基础设施支持：

  • Repository 基类：提供统一的 CRUD 操作接口
  • Controller 基类：统一响应格式，用户认证获取
  • ApiResponse：标准化 API 响应处理
  • 枚举系统：类型安全的状态管理（Code、Module、Status 等）
  • 中间件：mall.auth 认证中间件
  • 异常处理：业务异常统一处理

核心业务模块 ​

CatchShop 商城系统包含 9 个核心业务模块：

  • User - 用户体系：注册登录、资料管理、地址、积分等级
  • Product - 商品体系：SPU/SKU、分类、规格、品牌、评论
  • Cart - 购物车：商品管理、结算逻辑
  • Order - 订单体系：多类型订单、状态流转、地址管理
  • Payment - 支付体系：多渠道支付、回调处理、退款
  • Points - 积分体系：积分商品、每日签到、积分记录
  • Marketing - 营销体系：优惠券、活动、满减规则
  • Distribution - 分销体系：分销商、佣金结算
  • GroupBuy - 拼团体系：拼团活动、订单处理

🔧 技术栈 ​

核心框架 ​

CatchShop 商城采用现代化技术栈：

  • Laravel 12 - 现代 PHP 框架
  • PHP 8.2+ - 强类型支持、枚举、属性等新特性

业务能力 ​

  • JWT Auth - 无状态认证
  • Yansongda Pay - 多渠道支付集成
  • Easy SMS - 短信服务
  • Captcha - 验证码生成

开发工具 ​

  • Pest - 现代化测试框架
  • Larastan - 静态代码分析
  • Laravel Pint - 代码格式化
  • Clockwork - 调试工具
  • Scribe - API 文档生成

性能优化 ​

  • Laravel Octane - 高性能应用服务器（可选）
  • Redis - 缓存与会话存储
  • 队列系统 - 异步任务处理

🚀 快速开始 ​

bash
# 安装依赖
composer install

# 初始化项目
php artisan catch:install

# 代码格式化
composer format

# 静态分析
composer analyse

# 运行测试
php artisan test

💡 最佳实践 aa ​

  1. 严格分层：Controller 不直接调用 Repository，Service 不处理 HTTP 相关逻辑
  2. 统一响应：所有 API 使用 ApiResponse 类统一响应格式
  3. 类型安全：充分利用枚举和类型声明，避免魔法字符串
  4. 事务管理：复杂业务操作使用数据库事务确保一致性
  5. 缓存策略：合理使用缓存提升性能，注意缓存失效
  6. 异常处理：使用业务异常类，提供清晰的错误信息

CatchShop - 基于真实业务场景设计，经过生产环境验证的现代化商城系统，采用 PHP 语言和 Laravel 框架开发，为企业提供专业的电商解决方案。