API Yanıtları İçin Projeksiyon En İyi Uygulamaları
Öğrenenler, REST API yanıt biçimleriyle uyumlu projeksiyonlar tasarlayarak veri yükünü küçültecek ve hassas alanları koruyacaktır.
API Yanıtları İçin Projeksiyon En İyi Uygulamaları, CoddyKit'te ücretsiz bir MongoDB Academy dersidir. Bu, 4 dersinin 4. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, MongoDB Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. MongoDB Academy kursu toplamda 4 dersten oluşur.
Projeksiyonları API Yanıt Şekilleriyle Uyumlu Hale Getirme
Uygulamanızın sunduğu her REST veya GraphQL uç noktasının tanımlı bir yanıt şekli vardır. İdeal MongoDB projeksiyonu, bu şeklin gerektirdiği alanları tam olarak döndürür; ne fazlasını ne de eksiğini. Projeksiyonunuz API yanıt sözleşmesini yansıttığında iki yaygın hatalı uygulamadan kaçınırsınız: uç noktanın hiç göndermediği alanları döndürmek (gereğinden fazla veri çekme) ve ikinci bir sorguyu zorunlu kılan alanları döndürmemek (yetersiz veri çekme).
Projeksiyon Sabitlerini Tanımlama
Her sorguda projeksiyon nesnelerini satır içinde sabit olarak tanımlamak, zamanla tekrara ve farklılaşmaya yol açar. Projeksiyon sabitlerini veri erişim işlevlerinizin veya veri depolarınızın yanında tanımlayın. API yanıt şekli değişirse, kod tabanındaki her sorguyu aramak yerine tek bir sabiti güncellersiniz.
// projections.js — centralised projection definitions
export const USER_PUBLIC = { _id: 0, username: 1, avatarUrl: 1, createdAt: 1 };
export const USER_PROFILE = { _id: 0, username: 1, email: 1, bio: 1, avatarUrl: 1 };
export const USER_ADMIN = { _id: 0, username: 1, email: 1, role: 1, lastLoginAt: 1, isActive: 1 };
// Usage
const user = await db.collection('users').findOne({ username: 'alice' }, { projection: USER_PROFILE });Hassas Alanları İstemcilere Asla Döndürmeyin
passwordHash, totpSecret, apiKey, ssn ve paymentMethodToken gibi alanlar API yanıtlarında asla görünmemelidir. Bunları varsayılan olarak hariç tutan güvenli bir temel projeksiyon tanımlayın ve bu alanları yalnızca özellikle gerektiren dahili hizmet çağrılarında alın. En az ayrıcalık ilkesini veri katmanında uygulayın.
// Always exclude sensitive fields from user queries
const SECURE_USER_BASE = {
passwordHash: 0,
totpSecret: 0,
resetToken: 0
};
// All user API responses go through this projection
const user = await db.collection('users').findOne(
{ _id: userId },
{ projection: SECURE_USER_BASE }
);
// Result never contains passwordHash or totpSecretListe Uç Noktaları: Yalnızca Özet Alanlarını Projeksiyona Dahil Etme
Liste uç noktaları (örneğin GET /products) genellikle belgenin tamamını değil, her öğenin özetini döndürür. Bir ürün listesinde name, price, thumbnailUrl ve rating gösterilebilir; tam description alanı, specifications dizisi veya reviews gösterilmez. Liste sorgularında dar kapsamlı bir projeksiyon kullanmak, belgelerin tamamı büyük metinler veya diziler içerdiğinde veri yükünün boyutunu %90 oranında azaltabilir.
const PRODUCT_SUMMARY = {
_id: 0,
slug: 1,
name: 1,
price: 1,
thumbnailUrl: 1,
rating: 1,
reviewCount: 1
};
// GET /products — lightweight list query
const products = await db.collection('products')
.find({ category: 'electronics', isActive: true })
.projection(PRODUCT_SUMMARY)
.sort({ rating: -1 })
.limit(20)
.toArray();Ayrıntı Uç Noktaları: Nesnenin Tamamını Projeksiyona Dahil Etme
Ayrıntı uç noktaları (örneğin GET /products/:slug) tek bir belgenin daha kapsamlı görünümünü döndürür. Ancak burada bile yalnızca dahili kullanıma ait alanları hariç tutmayı düşünün. Tüm herkese açık alanları projekte ederken istemcilerin görmemesi gereken dahili maliyet fiyatını, tedarikçi iletişim bilgilerini veya stok kaynağı sistem kimliklerini gizleyebilirsiniz.
const PRODUCT_DETAIL = {
supplierCost: 0, // internal — never expose to clients
warehouseLocation: 0, // internal
syncedFromErpAt: 0 // internal audit field
};
// GET /products/:slug — rich detail query
const product = await db.collection('products').findOne(
{ slug: req.params.slug, isActive: true },
{ projection: PRODUCT_DETAIL }
);Toplama İşlem Hatlarında da Projeksiyonları Kullanma
Projeksiyon en iyi uygulamaları toplama işlem hattı için de geçerlidir. Belge boyutunu azaltmak amacıyla $match aşamasından sonra ve $lookup veya $unwind gibi maliyetli aşamalardan önce bir $project aşaması yerleştirin. İşlem hattındaki daha küçük belgeler, sunucuda daha az bellek ve CPU kullanımı anlamına gelir.
db.orders.aggregate([
{ $match: { status: 'shipped', customerId: ObjectId('c1') } },
// Project early to reduce document size before $lookup
{ $project: { total: 1, createdAt: 1, customerId: 1, _id: 0 } },
{
$lookup: {
from: 'customers',
localField: 'customerId',
foreignField: '_id',
as: 'customer'
}
}
]);Projeksiyonlar ve API Sürümleme
MongoDB belgelerine yeni alanlar eklediğinizde eski API istemcileri bunları beklemiyor olabilir. Kesin dahil etme projeksiyonlarını (döndürülecek alanları tam olarak listeleyen projeksiyonlar) kullanmak, yeni belge alanlarının siz onları projeksiyona açıkça ekleyene kadar mevcut API tüketicileri tarafından görülmemesini sağlar. Bu, doğal bir sürümleme sınırı oluşturur: API sürümünü güncellediğinizde projeksiyonu da güncelleyin.
// v1 projection — stable contract for existing clients
export const USER_V1 = { _id: 0, username: 1, email: 1 };
// v2 projection — includes new avatarUrl and bio fields
export const USER_V2 = { _id: 0, username: 1, email: 1, avatarUrl: 1, bio: 1 };Projeksiyonların Yanıt Şemalarıyla Eşleştiğini Test Etme
MongoDB projeksiyon nesnesinin API yanıt şemanızla (örneğin bir Joi şeması veya TypeScript türüyle) eşleştiğini doğrulayan birim testleri yazın. Bu, geliştiricinin API yanıt türüne bir alan ekleyip bu alanı projeksiyona dahil etmeyi unuttuğu yaygın hatayı önler; alan, üretim ortamında undefined olarak dönerken TypeScript türü kontrollerinden geçer.
// Example test asserting projection covers all required response fields
const USER_RESPONSE_FIELDS = ['username', 'email', 'avatarUrl'];
const projection = { username: 1, email: 1, avatarUrl: 1, _id: 0 };
for (const field of USER_RESPONSE_FIELDS) {
if (projection[field] !== 1) {
throw new Error('Projection missing field: ' + field);
}
}
console.log('Projection covers all required response fields');Mongoose'da Projeksiyon Uyumsuzluğundan Kaçınma
Bir alanda select: false bulunan Mongoose şemaları, açıkça yeniden dahil edilmediği sürece bu alanın hiçbir sorgu sonucunda görünmesini engeller. Türetilmiş değerleri depolamadan hesaplamak için bunu şema düzeyindeki sanal alanlarla birleştirin. Bu araçlar birlikte, model düzeyinde güvenli bir varsayılan projeksiyon uygulamanızı sağlar ve eksik bir sorgu projeksiyonu nedeniyle verilerin yanlışlıkla sızdırılma olasılığını azaltır.
const userSchema = new mongoose.Schema({
username: String,
email: String,
// Excluded from all queries by default — must explicitly use +passwordHash
passwordHash: { type: String, select: false },
// Virtual — computed, not stored, never in DB
get displayName() { return this.username.toUpperCase(); }
});
userSchema.virtual('displayName').get(function() {
return this.username.toUpperCase();
});Projeksiyon Verimliliğini İzleme
Projeksiyonlarınızın amaçlandığı gibi çalıştığını doğrulamak için explain('executionStats')
nReturned ile keysExamined ve docsExamined oranlarına bakın. docsExamined eşleşen belge sayısına eşitse (sıfır değilse), projeksiyonunuz bir dizin tarafından kapsanmıyor ancak yine de doğrudur; kapsayan bir dizin eklemenin bakım maliyetine değip değmeyeceğini değerlendirebilirsiniz.const result = await db.collection('users').find(
{ role: 'admin' },
{ projection: { username: 1, email: 1, _id: 0 } }
).explain('executionStats');
console.log('Docs examined:', result.executionStats.totalDocsExamined);
console.log('Keys examined:', result.executionStats.totalKeysExamined);
console.log('Docs returned:', result.executionStats.nReturned);Özet: Projeksiyon En İyi Uygulamaları Denetim Listesi
Bu denetim listesini API'nizdeki her MongoDB sorgusuna uygulayın:
- Adlandırılmış projeksiyon sabitleri tanımlayın — uç nokta veya yanıt şekli başına bir sabit
- API yanıtları için dahil etme modunu kullanın — tam olarak ihtiyacınız olanları listeleyin
- Hassas alanları her zaman hariç tutun — passwordHash, belirteçler, dahili kimlikler
- Liste uç noktaları için dar kapsamlı projeksiyonlar kullanın — yalnızca özet, büyük içerikler olmadan
- $project aşamasını toplama işlem hatlarının başına yerleştirin — aşağı akışa aktarılan veriyi azaltın
Kısa Kontrol
Bu dersteki MongoDB ve NoSQL Databases kavramlarını anlayıp anlamadığınızı test edin.
Ders Özeti
Bu derste şunları öğrendiniz: farklılaşmayı önlemek için projeksiyon sabitleri her API uç noktası başına tanımlanmalıdır; hassas alanlar istemcilere yönelik sorgulardan her zaman hariç tutulmalıdır; $project aşamasını toplama işlem hatlarının başına yerleştirmek bellek baskısını azaltır. Sırada büyük sonuç kümelerini verimli bir şekilde sıralamak ve sayfalara bölmek için sıralama ve sayfalamayı inceleyeceğiz.
Yapay zeka eğitmeniyle JavaScript öğren — ücretsiz
Tarayıcında gerçek kod yaz ve çalıştır, 7/24 yapay zeka eğitmeninden anında yardım al; web'de ya da uygulamada kaldığın yerden devam et.
- Kurslar
- 30
- Dersler
- 120
Sıkça Sorulan Sorular
“API Yanıtları İçin Projeksiyon En İyi Uygulamaları” dersi ücretsiz mi?
Evet — “API Yanıtları İçin Projeksiyon En İyi Uygulamaları” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve MongoDB Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. MongoDB Academy kursu toplamda 4 dersten oluşur.
“API Yanıtları İçin Projeksiyon En İyi Uygulamaları” dersinde ne öğreneceğim?
Öğrenenler, REST API yanıt biçimleriyle uyumlu projeksiyonlar tasarlayarak veri yükünü küçültecek ve hassas alanları koruyacaktır. MongoDB Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.
MongoDB Academy öğrenmeye başlamak için deneyim gerekli mi?
Önceden deneyim gerekmez. CoddyKit'te MongoDB Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 4. dersidir.
“API Yanıtları İçin Projeksiyon En İyi Uygulamaları” dersi ne kadar sürer?
Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.
Bu MongoDB Academy dersinde kod yazıp çalıştırabilir miyim?
Evet. Her MongoDB Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.
Bu kursun tüm dersleri
- Dahil Etme ve Hariç Tutma Projeksiyonları
- İç İçe ve Dizi Alanlarını Projeksiyonla Alma
- $ ve $elemMatch Dizi Projeksiyonları
- API Yanıtları İçin Projeksiyon En İyi Uygulamaları