laravel:using-examples-in-prompts

在提示词中使用示例

示例比描述更能明确意图。向 AI 展示你想要什么，而不只是告诉它。

引用现有代码

抽象

“创建一个类似支付服务的服务”

具体

“按照 app/Services/PaymentService.php 中的模式创建 OrderService：

class PaymentService
{
    public function __construct(
        private PaymentGateway $gateway,
        private PaymentRepository $repository
    ) {}
    
    public function charge(Order $order): Payment
    {
        // Implementation
    }
}

使用构造函数注入，返回领域对象，让方法各司其职。”

**为什么有效：**展示了要遵循的结构、命名和模式。

展示期望的风格

模糊

“使用一致的命名”

具体

“遵循 app/Models/Product.php 中的命名约定：

// Relationships: camelCase, descriptive
public function orderItems(): HasMany
public function primaryCategory(): BelongsTo

// Scopes: scope prefix, descriptive
public function scopeActive(Builder $query): void
public function scopePublishedAfter(Builder $query, Carbon $date): void

// Accessors: get prefix, Attribute suffix
public function getFormattedPriceAttribute(): string

将相同模式应用于新的 Subscription 模型。”

**为什么有效：**通过具体示例展示约定的实际应用。

输入/输出示例

不明确

“转换产品数据”

明确

“为 API 转换产品数据：

输入（来自数据库）：

[
    'id' => 1,
    'name' => 'Widget',
    'price_cents' => 2999,
    'created_at' => '2024-01-15 10:30:00',
    'category' => ['id' => 5, 'name' => 'Tools']
]

预期输出：

{
    "id": 1,
    "name": "Widget",
    "price": "29.99",
    "category": "Tools",
    "created_at": "2024-01-15T10:30:00Z"
}

使用 ProductResource 处理此转换。”

**为什么有效：**展示了确切的输入和预期输出格式。

具体与抽象

抽象

“妥善处理错误”

具体

“按照 app/Services/PaymentService.php 中的方式处理错误：

try {
    $charge = $this->gateway->charge($amount);
} catch (PaymentGatewayException $e) {
    Log::error('Payment failed', [
        'order_id' => $order->id,
        'amount' => $amount,
        'error' => $e->getMessage(),
    ]);
    
    throw new PaymentFailedException(
        'Unable to process payment: ' . $e->getMessage(),
        previous: $e
    );
}

使用具体的异常，记录上下文，保留原始异常。”

**为什么有效：**展示了要复现的确切错误处理模式。

抽象

“添加测试”

具体

“按照 tests/Feature/ProductTest.php 中的模式添加测试：

test('user can create product with valid data', function () {
    $user = User::factory()->create();
    $category = Category::factory()->create();
    
    $response = $this->actingAs($user)
        ->postJson('/api/products', [
            'name' => 'New Product',
            'price' => 29.99,
            'category_id' => $category->id,
        ]);
    
    $response->assertCreated()
        ->assertJsonStructure(['data' => ['id', 'name', 'price']]);
    
    $this->assertDatabaseHas('products', [
        'name' => 'New Product',
    ]);
});

使用工厂，测试成功路径和验证失败，并检查数据库状态。”

**为什么有效：**展示了要遵循的测试结构、断言和模式。

编写示例文档

建立新模式时，请将其记录下来：

“为外部 API 集成创建一种新的服务模式。模板如下：

// app/Services/External/BaseApiClient.php
abstract class BaseApiClient
{
    protected string $baseUrl;
    protected int $timeout = 30;
    protected int $retries = 3;
    
    abstract protected function authenticate(): array;
    
    protected function request(string $method, string $endpoint, array $data = []): array
    {
        // Retry logic, error handling, logging
    }
}

// app/Services/External/StripeClient.php
class StripeClient extends BaseApiClient
{
    protected string $baseUrl = 'https://api.stripe.com/v1';
    
    protected function authenticate(): array
    {
        return ['Authorization' => 'Bearer ' . config('services.stripe.secret')];
    }
    
    public function createCharge(int $amount): array
    {
        return $this->request('POST', '/charges', ['amount' => $amount]);
    }
}

所有外部 API 客户端都使用此模式。将其记录在 docs/patterns/external-apis.md 中。”

**为什么有效：**通过文档创建了可供日后参考的可复用模式。

快速参考

让示例为你所用：

• 展示现有代码 - 引用项目中的实际文件
• 演示风格 - 展示命名、结构和模式的实际应用
• 提供输入/输出 - 用具体数据明确转换方式
• 使用真实代码 - 使用代码库中的片段，而非通用示例
• 记录模式 - 将优秀示例转化为可复用模板

示例胜过解释。展示，而不只是告诉。