Laravel ile AI Kod İnceleme Botu Oluşturma — Gerçek Dünya Kullanım Durumu

Daha önce sıklıkla karşılaştığım bir sorunun çözümüne dair fikrimi paylaşmak istiyorum. Takımımız PR incelemeleri yaparken, sürekli aynı yorumları yapıyordum, örneğin “bu N+1 sorununa neden olacak, lütfen eager loading kullanın.” Farklı geliştiriciler, farklı PR’ler ama aynı problem. İki hafta içinde üçüncü kez bu yorumu yaptığımda, bunu daha akıllı bir şekilde çözmenin yolu olmalı dedim.

İşte tam da bu noktada devreye giriyor. Bu bir yapay zeka ürünü değil; sadece PHP kod parçacığını alan ve OpenAI’ye gönderen, ardından yapılandırılmış geri bildirim veren pratik bir Laravel aracı. Amaç basit: belli başlı sorunları otomatik olarak yakalamak, böylece kıdemli geliştiriciler gerçek bir insan zekası gerektiren konulara odaklanabilsin.

Tüm bu süreci birlikte inceleyeceğiz. Sonunda, kod alan, önem dereceleriyle etiketlenmiş sorunlar, güvenlik bayrakları ve öneriler sunan, ayrıca bir kalite skoru veren çalışan bir Laravel uygulamanız olacak. Ayrıca, UI’nın API yanıtını beklerken donmaması için bir kuyruğa bağlayacağız.

Başlamadan önce ihtiyaç duyduğunuz şeyler: Laravel 10 veya 11, PHP 8.1+, Composer ve bir OpenAI API anahtarı. Bunlar yeterli.

PHPStan veya CodeSniffer Neden Değil?

Çünkü kural tabanlılar. Yalnızca kendilerine verilenleri yakalarlar, daha fazlasını değil.

PHPStan en yüksek seviyede gerçek anlamda iyi. Ben de kullanıyorum. Ancak, üretimdeki en kötü hatalardan bazıları hiçbir linting kuralını ihlal etmez. N+1 sorgu döngüsü sözdizimsel olarak mükemmeldir. Başarısız olduğunda sessizce null döndüren bir işlev herhangi bir uyarı tetiklemez. Bir rotada eksik yetkilendirme kontrolü statik analizde hiç görünecektir.

LLM bağlamı anlayabilir. Kodu inceleyebilir ve “yük altında bu çöker” ya da “bu doğrulama sessizce null geçecek” gibi yorumlar yapabilir. Bu, tamamen farklı bir geri bildirim kategorisidir. Her ikisini de kullanın, birbirleriyle rekabet etmiyorlar.

Tüm Bu Süreç Nasıl İşliyor?

Hiçbir kod parçasına dokunmadan önce, iş akışı şu şekildedir:

Developer submits PHP code via a form
        ↓
Laravel controller validates it
        ↓
CodeReviewService builds a structured prompt
        ↓
OpenAI GPT-4o analyses the code
        ↓
JSON response gets parsed
        ↓
Feedback renders back to the developer

Karmaşık soyutlamalar yok; OpenAI istemcisi dışında gereksiz paketler yok. Yapı, daha sonra özellik eklemek, inceleme geçmişini saklamak, GitHub webhook tetikleyicileri, Slack bildirimleri gibi şeyleri eklemek için yeterince temiz.

Adım 1: Laravel ve OpenAI Paketini Yükle

composer create-project laravel/laravel ai-code-reviewer
cd ai-code-reviewer
composer require openai-php/laravel

Yapılandırma dosyasını yayımlayın:

php artisan vendor:publish --provider="OpenAI\Laravel\ServiceProvider"

Sonra .env dosyanızı açın ve anahtarınızı ekleyin:

OPENAI_API_KEY=sk-your-key-here
OPENAI_ORGANIZATION=

Tek bir şeyi açıkça söylemek istiyorum. Git depolarına API anahtarlarının geçirilmesini çok fazla gördüm. Her şeyden önce, .env dosyanızın .gitignore içinde olduğundan emin olun.

Adım 2: Bir Hizmet Oluştur – CodeReviewService

Üçüncü parti API çağrıları bir hizmet sınıfında yer almalıdır. Ne bir kontrolörde, ne de bir modelde. Bu, test edilebilirliği artırır ve ileride GPT-4o’yu farklı bir modelle değiştirmek istediğinizde yalnızca bir dosyayı değiştirirsiniz.

Manuel olarak app/Services/CodeReviewService.php oluşturun:

create([
            'model'       => 'gpt-4o',
            'temperature' => 0.3,
            'messages'    => [
                [
                    'role'    => 'system',
                    'content' => 'You are a senior PHP developer and Laravel architect.
                                  Review PHP code and return feedback as valid JSON only.
                                  No markdown. No explanation outside the JSON object.',
                ],
                [
                    'role'    => 'user',
                    'content' => $this->buildPrompt($code),
                ],
            ],
        ]);

        return $this->parse($response->choices[0]->message->content);
    }

    private function buildPrompt(string $code): string
    {
        return  'Response could not be parsed. Try submitting again.',
                'score'          => null,
                'issues'         => [],
                'suggestions'    => [],
                'security_flags' => [],
            ];
        }

        return $data;
    }
}

temperature: 0.3 değeri bilinçli olarak seçilmiştir. Düşük sıcaklık, modelin daha az rastgele olmasını sağlar; yani daha tutarlı bir çıktı elde edersiniz. Yaratıcı yazım için bu değeri daha yüksek tutarsınız. Yapısal teknik analiz için ise öngörülebilir olmasını istersiniz.

Ayrıca parse metodunun markdown sınırlarını temizlediğini de dikkat edin. GPT-4o genellikle siz ona yalnızca temiz JSON vermesini istediğinizde, yalnızca temiz JSON döner, ancak bazen çıktıyı backtick sınırları içine alabilir. Bu, hiçbir şeyi bozmadan bu durumu ele alır.

Adım 3: Kontrolör ve Yollar

php artisan make:controller CodeReviewController

validate([
            'code' => 'required|string|min:10|max:5000',
        ]);

        $feedback = $this->reviewService->review($request->input('code'));

        return view('code-review.result', compact('feedback'));
    }
}

Yolları routes/web.php içine ekleyin:

use App\Http\Controllers\CodeReviewController;

Route::get('/code-review', [CodeReviewController::class, 'index'])
    ->name('code-review.index');

Route::post('/code-review', [CodeReviewController::class, 'review'])
    ->name('code-review.review');

Adım 4: Blade Görünümleri

Bunları minimal tutmak önemli. Stil, mevcut yapınızdan geliyor, ekstra bir şey eklemeye gerek yok.

resources/views/code-review/index.blade.php

    
    

    
PHP veya Laravel kodunu aşağıya yapıştırın ve anında yapılandırılmış geri bildirim alın.

    

        @csrf
        {{ old('code') }}

        @error('code')
            
{{ $message }}
        @enderror

        
Kodu İncele
    
    

resources/views/code-review/result.blade.php

    
    

    
{{ $feedback['summary'] ?? '' }}

    @isset($feedback['score'])
        
Kalite Skoru: {{ $feedback['score'] }} / 10
    @endisset

    @if(!empty($feedback['issues']))
        
Bulunan Sorunlar
        @foreach($feedback['issues'] as $issue)
            

                [{{ strtoupper($issue['severity']) }}]
                @if(!empty($issue['line_hint']))
                    , {{ $issue['line_hint'] }}
                @endif
                
{{ $issue['message'] }}
            
            

        @endforeach
    @else
        
Önemli sorun bulunamadı.
    @endif

    @if(!empty($feedback['security_flags']))
        
Güvenlik Bayrakları
        

            @foreach($feedback['security_flags'] as $flag)
                
{{ $flag }}
            @endforeach
        
    @endif

    @if(!empty($feedback['suggestions']))
        
Öneriler
        

            @foreach($feedback['suggestions'] as $s)
                
{{ $s }}
            @endforeach
        
    @endif

    
Başka bir kesiti incele
    

Adım 5: API Çağrısını Kuyruğa Al, UI’yi Engelleme

GPT-4o genellikle kısa parçalara 2 ila 4 saniye içinde yanıt verir, bazen daha uzun sürer. Bu, senkronize bir web isteği için iyi değildir ve bazı sunucu yapılandırmalarında yanıt gelmeden önce zaman aşımına ulaşabilir. Herhangi bir üretim kurulumunda bunu kuyruklayın.

php artisan make:job ProcessCodeReview

review($this->code);
        Cache::put($this->cacheKey, $result, now()->addMinutes(10));
    }
}

Kontrolörü güncelleyin ve işi yürütmek için bir anket yöntemi ekleyin:

public function review(Request $request)
    {
        $request->validate(['code' => 'required|string|min:10|max:5000']);

        $key = 'review_' . md5($request->input('code') . uniqid());

        ProcessCodeReview::dispatch($request->input('code'), $key);

        return view('code-review.waiting', ['cacheKey' => $key]);
    }

    public function poll(string $key)
    {
        $feedback = Cache::get($key);

        if (!$feedback) {
            return response()->json(['status' => 'pending']);
        }

        return response()->json(['status' => 'done', 'feedback' => $feedback]);
    }

Yerel geliştirme için, QUEUE_CONNECTION=sync ayarını .env dosyasında yapın; bu durumda işler hemen çalışır, işçi gerektirmez. Üretimde redis veya database kullanın.

Botun Gerçekten Yakaladığı: Bir Gerçek Örnek

Çeşitli projelerde farklı formlarda gördüğüm bir kod örneği. Bu kod çalışıyor. On siparişlik bir test veritabanında hiçbir sorun görünmüyor.

where('user_id', $userId)->get();

        foreach ($orders as $order) {
            $items = DB::table('order_items')->where('order_id', $order->id)->get();
            echo $order->id . ': ' . count($items) . ' items
';
        }
    }

Bu kodu 400 siparişli bir müşteri önüne koyun ve veritabanınıza ne olduğunu görün.

Kodu inceleyiciye yapıştırdığınızda gelen yanıt:

{
  "summary": "Kod işlevsel ancak kritik bir N+1 sorgu problemi var ve Eloquent'i tamamen geçiyor. Echo ile direkt çıktı almak, MVC ayrımını bozuyor ve bu kodu test edilemez hale getiriyor.",
  "score": 3,
  "issues": [
    {
      "severity": "critical",
      "line_hint": "foreach döngüsü, DB::table order_items",
      "message": "N+1 sorgu problemi. Her bir sipariş için döngü içinde bir veritabanı sorgusu gönderiliyor. 400 siparişle bu 401 sorgu haline geliyor. Eager loading kullanarak Eloquent ile: Order::with('items')->where('user_id', $userId)->get() yapın"
    },
    {
      "severity": "warning",
      "line_hint": "DB::table()",
      "message": "Hammade sorgu yapıcısı Eloquent model mantığını, erişimcileri ve ilişkileri atlıyor. Eloquent modellere geçmek, kodun bakımını ve test edilebilirliğini önemli ölçüde artırır."
    },
    {
      "severity": "info",
      "line_hint": "echo bildirimi",
      "message": "Kontrolör veya hizmet yönteminde doğrudan çıktı almak MVC'yi ihlal eder. Yapılandırılmış verileri döndürün ve görüntüleme katmanında işleyin."
    }
  ],
  "suggestions": [
    "Order'ın OrderItem'a işaret eden bir hasMany ilişkisini tanımlayın.",
    "DB::table çağrılarını Order::with('items')->where('user_id', $userId)->get() ile değiştirin.",
    "Bir koleksiyon döndürün ve çıktıyı Blade'in ele almasına izin verin, hizmet yöntemlerinden echo yapmayın."
  ],
  "security_flags": [
    "$userId, herhangi bir tür kontrolü veya doğrulama olmadan sorguya geçiyor. DB çağrısına ulaşmadan önce bunun doğrulandığını, yetki verilmiş bir tamsayı olduğunu doğrulayın."
  ]
}

3’lük bir puan, bir kritik sorun, bir uyarı, bir bilgi notu ve bir güvenlik bayrağı. Tümü doğru, uygulanabilir. Bu yanıt dört saniyeden az sürdü ve genellikle kıdemli bir geliştiricinin bu tür yorumları doğru bir şekilde yazması birkaç dakika alır.

Bu, Gerçek Bir İş Akışında Nerede Yer Alıyor?

Bu konuyu net bir şekilde belirtmek istiyorum çünkü böyle araçları kuran ama ya aşırı bağımlı olan ya da iki hafta sonra bırakan insanları gördüm. Burada doğru kullanım, bir ilk geçiş kapısı olarak işlev görmesi, peer review yerine geçmemesidir.

Gerçek anlamda mantıklı olan iş akışı: geliştirici bir PR açar, bot bir GitHub webhook’u aracılığıyla tetiklenir, geri bildirimi PR’de bir yorum olarak gönderir ve insan inceleyici temellere ilişkin geri bildirimin zaten yapıldığını bilir. Gerçek yargı, tasarım kararları, kenar durumları, yaklaşımın daha geniş mimariye uyup uymadığı gibi konulara hemen geçebilir.

İşte bu nedenle burası önemli. Gözden geçirmeyi değiştirmekle değil, tekrar eden ilk on dakikalık süreci kaldırmakla kazanç sağlıyor.

Bunu İnşa Etmeden Önce Bilinmesi Gerekenler:

Prompt yapısı, bu inşaatın her şeyinden daha önemlidir. İlk denemelerimde, serbest metin olarak geriye gelen sonuçlar alıyordum ki bu da bir kullanıcı arayüzüyle çalışmayı zorlaştırıyordu. Modelden yalnızca önceden belirlediğiniz alan adlarıyla JSON döndürmesini istemek, her zaman güvenilir şekilde ayrıştırma sağlar. Bu kısmı atlamayın.

GPT-4o, bu tür görevler için GPT-3.5’ten belirgin şekilde daha iyidir; sadece doğruluk açısından değil, sorunları açıklama şekli açısından. “Eager loading kullanın” ifadesinden “bu her döngüde bir sorgu gönderiyor, tam çözüm budur” ifadesi daha kullanışlıdır. API maliyeti farkı, bunu gerçekten bir kod tabanında kullanıyorsanız karşılığını verir.

Bir şey daha var. Tüm dosyaları bir kerede yüklemeyin, en azından başlarda. Girişi odaklanmış tutun: tek bir metod, bir sınıf, belirli bir özellik. Daha küçük, odaklı incelemeler daha iyi geri bildirim üretir. Çıkış kalitesinden memnun kaldıktan sonra giriş sınırını daha sonra genişletebilirsiniz.

Buradan doğal uzantılar, her bir PR üzerinde incelemeleri otomatik olarak tetiklemek için bir GitHub webhook entegrasyonu, kalite eğilimlerini takip etmek için bir inceleme geçmişi tablosu, botun özellikle takımınızın kurallarına göre inceleme yapması için proje başına özel sistem promptları ve bir inceleme tamamlandığında Slack bildirimleri gibi şeyler eklemektir. Bunların hiçbiri burada inşa ettiğimizin üzerine eklenmesi çok karmaşık değildir.

Bunu faydalı bulduysanız, yorumlarınızı bırakabilirsiniz.