laravel-debugging-prompts

调试提示词

使用 AI 调试需要完整的信息。缺少上下文只会得到无法解决具体问题的泛泛建议。

错误消息和堆栈跟踪

信息不完整

“支付控制器报错了”

信息完整

“处理付款时发生错误：

错误：

Illuminate\Database\QueryException: SQLSTATE[23000]:
Integrity constraint violation: 1452 Cannot add or update a child row:
a foreign key constraint fails (`app`.`payments`, CONSTRAINT `payments_order_id_foreign`
FOREIGN KEY (`order_id`) REFERENCES `orders` (`id`) ON DELETE CASCADE)

堆栈跟踪：

#0 app/Services/PaymentService.php(45): Payment::create()
#1 app/Http/Controllers/PaymentController.php(28): PaymentService->process()
#2 vendor/laravel/framework/src/Illuminate/Routing/Controller.php(54)

上下文：

• Laravel 11.x、MySQL 8.0
• 当 order_id 在 orders 表中不存在时发生
• 付款数据：['order_id' => 999, 'amount' => 5000, 'status' => 'pending']
• 数据库中不存在订单 999”

**为什么有效：**提供了完整的错误、堆栈跟踪、上下文，以及导致问题的具体数据。

预期行为与实际行为

含糊

“API 返回的数据不对”

具体

“产品 API 返回的数据不正确：

预期行为：

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": "29.99",
    "category": {
      "id": 5,
      "name": "Tools"
    }
  }
}

实际行为：

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": 2999,
    "category": null
  }
}

问题：

1. 价格以分（2999）为单位，而不是格式化后的美元金额（"29.99"）
2. 尽管产品有 category_id = 5，但分类为 null

代码：

// ProductController@show
return new ProductResource($product);

数据库中的产品有 category_id = 5，但关联未加载。”

**为什么有效：**展示了预期与实际输出的确切差异，指出具体问题，并附上相关代码。

日志条目和状态

信息不足

“队列好像出问题了”

信息充分

“队列中的任务执行失败：

日志条目：

[2024-01-15 10:30:15] local.ERROR: Job failed: ProcessOrderJob
{"order_id":123,"exception":"Stripe\\Exception\\InvalidRequestException:
No such customer: cus_invalid","attempts":3}

[2024-01-15 10:30:15] local.INFO: Order state before job
{"id":123,"status":"pending","stripe_customer_id":"cus_invalid"}

任务代码：

public function handle()
{
    $customer = $this->stripe->customers->retrieve(
        $this->order->stripe_customer_id
    );
    // ...
}

状态：

• 订单 123 的 stripe_customer_id = "cus_invalid"
• Stripe 中不存在该客户
• 任务已重试 3 次，现在位于 failed_jobs 表中
• 使用 Laravel 11.x 和 Horizon”

**为什么有效：**包含日志、状态信息、相关代码，以及重试相关的上下文。

假设和证据

薄弱

“我觉得是缓存问题”

有力

“怀疑 Redis 缓存已过期：

**假设：**产品价格已缓存，但更新时没有使缓存失效。

证据：

1. 更新数据库中的产品价格：UPDATE products SET price = 3999 WHERE id = 1
2. 数据库显示：SELECT price FROM products WHERE id = 1 → 3999
3. API 返回旧价格：GET /api/products/1 → "price": "29.99"
4. 执行 php artisan cache:clear 后，API 返回正确价格："price": "39.99"

缓存代码：

public function show(Product $product)
{
    $cached = Cache::remember("product.{$product->id}", 3600, function () use ($product) {
        return new ProductResource($product);
    });
    return $cached;
}

**问题：**产品更新时缓存键不会失效。需要在 ProductObserver 中使缓存失效，或从 show 方法中移除缓存。”

**为什么有效：**提供了清晰的假设、具体证据、相关代码和建议的解决方案。

已尝试的解决方案

没有帮助

“我试了一些办法，但都没用”

有帮助

“已尝试的解决方案及结果：

**尝试 1：**添加预加载

$products = Product::with('category')->get();

**结果：**仍然出现 N+1 查询。Debugbar 显示 101 次查询（1 次查询产品，100 次查询分类）。

**尝试 2：**获取数据后使用 load()

$products = Product::all();
$products->load('category');

**结果：**问题未变，仍然有 101 次查询。

**尝试 3：**检查关联定义

// In Product model
public function category()
{
    return $this->belongsTo(Category::class);
}

**结果：**关联看起来正确。products 表中存在外键 category_id。

**当前状态：**预加载语法看起来正确，但没有生效。使用 Laravel 11.x。我漏了什么？”

**为什么有效：**展示了已尝试的方法、所用的确切代码和观察到的结果，避免建议已尝试过的解决方案。

调试模板

模板：错误报告

**Error:** [Full error message]
**Stack trace:** [Complete stack trace]
**File/Line:** [Where error occurs]
**Context:** [Laravel version, packages, environment]
**Data:** [Input data causing error]
**Expected:** [What should happen]

模板：意外行为

**Expected:** [Describe expected behavior with example]
**Actual:** [Describe actual behavior with example]
**Code:** [Relevant code snippet]
**State:** [Database state, variable values]
**Environment:** [Laravel version, Sail/host, packages]

模板：性能问题

**Problem:** [Describe slow operation]
**Metrics:** [Response time, query count, memory usage]
**Query log:** [Slow queries from Debugbar/Telescope]
**Code:** [Code causing performance issue]
**Dataset size:** [Number of records involved]
**Attempted:** [Optimizations already tried]

快速参考

使用 AI 高效调试：

• 完整错误信息——完整消息、堆栈跟踪、文件和行号
• 展示两方面情况——预期行为与实际行为
• 附上日志——错误日志、信息日志、状态转储
• 提供证据——数据库查询、API 响应、变量转储
• 记录尝试过程——尝试过什么、确切代码、结果
• 提供上下文——Laravel 版本、环境、软件包

信息越多，解决问题越快。调试时，尽可能提供更多信息。