Save this content to: .claude/skills/jason-chen/SKILL.md

# Jason Chen PHP/Laravel 开发经验

## 1. 个人技术栈

### 1.1 核心技术
- **PHP 8.5+**：熟练掌握 PHP 8.x 新特性（构造器属性提升、命名参数、match 表达式、 fibers 等）
- **Laravel 13**：深度掌握 Laravel 架构，包括服务容器、门脸、事件系统、队列、通知等
- **Filament 5**：使用 Filament 快速构建后台管理系统
- **Livewire 4**：构建动态交互式界面
- **PostgreSQL 15+**：复杂查询优化、事务处理、主从复制
- **Redis 7+**：缓存策略、队列驱动、会话存储

### 1.2 偏好技术
- **Tailwind CSS 4**：实用优先的 CSS 框架
- **Alpine.js**：轻量级前端交互
- **Docker**：容器化部署
- **GitHub Actions**：CI/CD 自动化

## 2. 开发哲学

### 2.1 代码质量观
- **可读性优先**：代码是写给人看的，其次是给机器看的
- **约定大于配置**：遵循框架和团队的约定，减少自定义配置
- **单一职责**：每个类和方法只做一件事
- **DRY 原则**：不要重复自己，提取公共逻辑
- **KISS 原则**：保持简单，避免过度工程

### 2.2 性能观念
- **数据库是第一瓶颈**：优先优化数据库查询，使用索引和缓存
- **延迟加载**：按需加载，不提前加载不需要的数据
- **批量处理**：批量操作替代循环单条处理
- **异步处理**：耗时代码放入队列，避免阻塞

### 2.3 安全意识
- **零信任原则**：所有用户输入都不可信，必须验证
- **最小权限**：只授予必要的权限
- **防御性编程**：假设所有外部数据都可能是恶意的

## 3. Laravel 最佳实践

### 3.1 项目结构

详细项目结构规范请参考：[references/project-structure.md](references/project-structure.md)

关键目录组织：
- `app/Http/Controllers/` - 控制器（按业务模块组织）
- `app/Services/` - 业务逻辑服务（按业务模块组织）
- `app/Models/` - 数据模型（含 Traits 和 Observers）

### 3.2 模型设计
```php
// 使用 trait 组织公共逻辑
trait HasAvatar
{
    public function getAvatarUrlAttribute(): string
    {
        return $this->avatar
            ? Storage::url($this->avatar)
            : $this->defaultAvatarUrl();
    }
}

// 使用枚举管理状态
enum OrderStatus: string
{
    use HasLabel, HasColor;

    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Completed = 'completed';
    case Cancelled = 'cancelled';

    public static function getLabel(?self $status): string
    {
        return match ($status) {
            self::Pending => '待支付',
            self::Paid => '已支付',
            // ...
        };
    }
}
```

### 3.3 Traits 规范

详细 Traits 规范请参考：[references/model-traits.md](references/model-traits.md)

Traits 分类：
- **关联型** - 添加模型关联和设置器，如 `BelongsToUser`、`MorphToUser`
- **作用域型** - 添加查询作用域，如 `HasSortable`、`HasEasyStatus`、`HasRegion`
- **功能型** - 添加复杂业务功能，如 `HasCovers`、`AutoCreateOrderNo`

### 3.4 枚举规范

详细枚举规范请参考：[references/enums.md](references/enums.md)

枚举分类：
- **内联枚举** - 简单场景，直接放在模型文件中
- **独立枚举** - 复杂场景，放在 `app/Enums/` 目录

配合 Trait 使用：`HasLabel`（标签）、`HasColor`（颜色）。

### 3.5 服务层设计
```php
// 服务类处理业务逻辑
class InvoiceService
{
    public function __construct(
        protected InvoiceRepository $repository,
        protected InvoiceNotifier $notifier
    ) {}

    public function createForUser(User $user, array $data): Invoice
    {
        $invoice = $this->repository->create([
            'user_id' => $user->id,
            ...$data
        ]);

        $this->notifier->notifyAdmins($invoice);

        return $invoice;
    }
}
```

### 3.6 事件驱动设计
```php
// 领域事件
class InvoiceCreated
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public Invoice $invoice,
        public User $creator
    ) {}
}

// 监听器处理副作用
class SendInvoiceNotification
{
    public function handle(InvoiceCreated $event): void
    {
        Notification::send(
            $event->invoice->user,
            new InvoiceCreatedNotification($event->invoice)
        );
    }
}
```

### 3.7 API 响应规范

详细 API 响应规范请参考：[references/api-response.md](references/api-response.md)

使用 `ApiResponse` 类统一响应格式：
- `code = 0` 表示成功，非 0 表示失败
- 单个资源直接返回，不包裹 `data` 层
- 分页使用 `meta` + `links` 结构

## 4. 数据库经验

### 4.1 索引设计
```php
// 复合索引优化查询
$table->index(['tenant_id', 'status']);        // 租户+状态组合查询
$table->index(['tenant_id', 'created_at']);    // 租户+时间范围查询

// 唯一索引保证数据唯一性
$table->unique(['tenant_id', 'order_no']);

// 条件索引处理稀疏数据
$table->index('deleted_at')        // 软删除查询
    ->whereNotNull('deleted_at');

// 函数索引优化表达式查询
DB::statement('CREATE INDEX users_email_lower ON users (LOWER(email))');
```

### 4.2 查询优化
```php
// 避免 N+1 查询，使用预加载
$users = User::with(['profile', 'roles.permissions'])->get();

// 使用子查询优化聚合
$users = User::select('*')
    ->withCount(['posts' => fn($q) => $q->where('created_at', '>', now()->subMonth())])
    ->get();

// 使用 EXISTS 替代 IN
$users = User::whereHas('orders', fn($q) => $q->where('amount', '>', 1000))->get();
```

### 4.3 PostgreSQL 特性使用
```php
// JSONB 存储动态数据
$table->jsonb('metadata')->default('{}');

// 数组类型存储多值
$table->jsonb('tags')->default('[]');

// 事务处理
DB::transaction(function () use ($order, $payment) {
    $order->update(['status' => OrderStatus::Paid]);
    $payment->confirm();
});

// 乐观锁防止并发冲突
$version = $record->version;
$affected = DB::table('records')
    ->where('id', $record->id)
    ->where('version', $version)
    ->update(['data' => $newData, 'version' => $version + 1]);

if ($affected === 0) {
    throw new ConcurrentModificationException();
}
```

## 5. 性能优化经验

### 5.1 缓存策略
```php
// 多级缓存
$cache = Cache::store('redis');

// 带标签的缓存，方便批量清除
Cache::tags(['users', 'user_'.$user->id])->put('profile', $profile, 3600);

// 缓存穿透保护
return Cache::rememberOrFail('product_'.$id, 3600, fn() => Product::findOrFail($id));

// 缓存预热
class CacheWarmer
{
    public function warmPopularProducts(): void
    {
        $products = Product::popular()->limit(100)->get();
        foreach ($products as $product) {
            Cache::put('product_'.$product->id, $product, 86400);
        }
    }
}
```

### 5.2 队列优化
```php
// 优先处理紧急任务
$job = new ProcessOrder($order);
$job->onQueue('high');  // 高优先级队列

// 批量处理
ProcessPodcastJob::dispatchBatch($podcasts);

// 延迟任务处理峰值
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

// 失败任务重试配置
public int $tries = 3;
public int $backoff = 60;  // 60秒后重试
```

### 5.3 图片和文件优化
```php
// 使用 Flysystem 处理多存储
Storage::disk('s3')->url($path);

// 图片处理管道
Image::make($file)
    ->resize(800, null, fn($c) => $c->aspectRatio())
    ->quality(85)
    ->save();

// 生成响应式图片
<img srcset="
    {{ $image->url('small') }} 480w,
    {{ $image->url('medium') }} 800w,
    {{ $image->url('large') }} 1200w
">
```

## 6. 安全实践

### 6.1 输入验证
```php
// 始终验证用户输入
public function rules(): array
{
    return [
        'email' => ['required', 'email', 'max:255', 'unique:users,email'],
        'password' => ['required', 'confirmed', Password::min(8)->mixedCase()->numbers()],
        'amount' => ['required', 'numeric', 'min:0.01', 'max:999999.99'],
    ];
}

// 自定义验证规则
Rule::when($condition, fn() => ['required', 'numeric']);
```

### 6.2 授权策略
```php
// 模型策略控制权限
class InvoicePolicy
{
    public function view(User $user, Invoice $invoice): bool
    {
        return $user->isAdmin() || $invoice->tenant_id === $user->tenant_id;
    }

    public function update(User $user, Invoice $invoice): bool
    {
        return $user->isAdmin() && $invoice->isEditable();
    }
}

// 资源授权
Gate::define('view-invoice', fn(User $user, Invoice $invoice) => ...);
```

### 6.3 API 安全
```php
// 限流保护
Route::middleware('throttle:60,1')->group(function () {
    // 60 requests per minute
});

// CORS 配置
'middleware' => [
    'cors' => [
        'allowedOrigins' => ['https://example.com'],
        'allowedMethods' => ['GET', 'POST', 'PUT', 'DELETE'],
        'allowedHeaders' => ['Content-Type', 'Authorization'],
    ],
];

// 使用 Sanctum 进行 API 认证
Sanctum::authenticateAsUser(User::find($userId));
```

## 7. 调试和问题排查

### 7.1 日志策略
```php
// 结构化日志
Log::info('User purchased', [
    'user_id' => $user->id,
    'order_id' => $order->id,
    'amount' => $order->amount,
    'payment_method' => $order->payment_method,
]);

// 性能日志
Log::channel('performance')->info('Slow query', [
    'query' => $query->toSql(),
    'bindings' => $query->getBindings(),
    'time' => $executionTime,
]);
```

### 7.2 问题排查流程
1. **查看日志**：先看 Laravel 日志，再看服务器日志
2. **定位问题**：确定是前端、后端、数据库还是缓存问题
3. **复现问题**：找到最小复现步骤
4. **分析原因**：使用 Xdebug 或 Ray 进行调试
5. **验证修复**：确保修复后问题不再出现

### 7.3 常用调试技巧
```php
// 使用 Ray 进行调试
ray($variable, $another)->purple();

// 使用 Laravel Tinker 测试
php artisan tinker

// 数据库查询分析
DB::listen(fn($query) => logger($query->sql, $query->bindings));

// 检查队列状态
php artisan queue:monitor
```

## 8. 工具链偏好

### 8.1 开发环境
- **IDE**：PHPStorm（深度定制，使用 Laravel 插件）
- **终端**：Windows Terminal + PowerShell 7
- **API 测试**：Postman 或 Insomnia
- **数据库**：TablePlus 或 DBeaver

### 8.2 代码质量
- **格式化**：Laravel Pint（基于 PSR-12）
- **静态分析**：PHPStan（严格模式）
- **依赖检查**：Composer Audit
- **代码审查**：GitHub PR + StyleCI

### 8.3 监控和日志
- **应用监控**：Sentry（错误追踪）
- **服务器监控**：Prometheus + Grafana
- **日志管理**：Laravel Horizon（队列监控）
- **性能分析**：Laravel Telescope

## 9. 架构设计思维

### 9.1 分层架构
```
┌─────────────────────────────────────┐
│         Presentation Layer          │
│    (Controllers, Resources)         │
├─────────────────────────────────────┤
│          Service Layer             │
│   (Business Logic, Validation)      │
├─────────────────────────────────────┤
│        Repository Layer             │
│      (Data Access Abstraction)      │
├─────────────────────────────────────┤
│           Model Layer               │
│      (Eloquent, Database)           │
└─────────────────────────────────────┘
```

### 9.2 领域驱动设计
- **聚合根**：Invoice 是发票聚合的根
- **值对象**：Money、Address、PhoneNumber
- **领域事件**：InvoiceSubmitted、InvoiceApproved
- **仓储模式**：InvoiceRepository 接口和实现分离

### 9.3 微服务思维
- **独立部署**：每个模块可以独立部署
- **松耦合**：通过事件或消息队列通信
- **清晰边界**：每个服务有明确的职责
- **数据隔离**：每个服务有自己的数据库

## 10. 团队协作经验

### 10.1 代码审查要点
- **功能性**：代码是否实现了需求
- **可读性**：代码是否清晰易懂
- **健壮性**：是否有错误处理和边界情况
- **性能**：是否有性能问题
- **安全性**：是否有安全隐患

### 10.2 Git 工作流
- **特性分支**：每个功能一个分支
- **PR 先行**：所有代码通过 PR 合并
- **squash 合并**：保持历史清晰
- **提交规范**：遵循 Conventional Commits，详细规范见 [references/git-commit.md](references/git-commit.md)

### 10.3 文档习惯
- **代码即文档**：通过清晰的变量和方法命名
- **README**：每个项目都有 README
- **API 文档**：使用 OpenAPI/Swagger
- **变更记录**：保持 CHANGELOG

## 11. 职业成长

### 11.1 持续学习
- **关注官方文档**：Laravel、PHP、PostgreSQL 新版本特性
- **阅读源码**：理解框架内部原理
- **社区参与**：Stack Overflow、Laracasts、GitHub
- **技术博客**：关注优质技术博客和 newsletter

### 11.2 技术视野
- **全栈能力**：不只是后端，了解前端和运维
- **架构思维**：从业务角度思考技术选型
- **业务理解**：深入理解业务逻辑才能写出好代码
- **技术分享**：输出是最好的学习方式

### 11.3 软技能
- **沟通能力**：清晰表达技术问题
- **时间管理**：合理评估任务时间
- **问题分解**：大问题拆分成小任务
- **自我驱动**：主动发现问题而不是等待

## 12. 个人规范

详细规范文档存放于 `references/` 目录：

### 12.1 Git Commit 规范
- 文件：[references/git-commit.md](references/git-commit.md)
- 内容：Commit 消息格式、类型说明、最佳实践、工作流程、常见问题解决等

### 12.2 项目结构规范
- 文件：[references/project-structure.md](references/project-structure.md)
- 内容：目录组织原则、各目录职责、枚举放置、资源类文件组织等

### 12.3 规范原则
- **一致性**：所有团队成员遵循相同规范
- **可执行**：规范可以自动化检查和验证
- **持续改进**：根据实际情况调整规范

## 13. 总结

### 核心理念
1. **代码是为人写的**：可读性、可维护性优先
2. **简单是终极的复杂**：避免过度设计
3. **测量而非猜测**：用数据指导优化
4. **安全是每个人的责任**：从一开始就要考虑安全
5. **团队比个人更重要**：代码是协作的艺术

### 技术信条
- 用 Laravel 的方式解决问题
- 数据库不是无限的，优化查询是永恒的主题
- 缓存是银弹，但也要小心缓存一致性
- 异步处理是提升性能的关键
- 测试是代码质量的保障

### 人生信条
- 保持好奇心，永远学习
- 代码改变世界
- 分享知识，共同成长

---

**技能版本**：1.0.0
**创建者**：Jason Chen
**最后更新**：2026-04-24