PricingLoginStart free
MongoDB Academy · Pelajaran

Amalan Terbaik Unjuran untuk Respons API

Pelajar akan mereka bentuk unjuran yang selaras dengan bentuk respons REST API, sekali gus mengurangkan saiz muatan dan melindungi medan sensitif.

Pelajaran 4 daripada 413 langkah

Amalan Terbaik Unjuran untuk Respons API ialah pelajaran MongoDB Academy percuma di CoddyKit. Ini ialah pelajaran 4 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran MongoDB Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus MongoDB Academy merangkumi sejumlah 4 pelajaran.

Selaraskan Unjuran Dengan Bentuk Respons API

Setiap titik akhir REST atau GraphQL yang didedahkan oleh aplikasi anda mempunyai bentuk respons yang ditetapkan. Unjuran MongoDB yang ideal mengembalikan tepat medan yang diperlukan oleh bentuk tersebut—tidak lebih dan tidak kurang. Apabila unjuran anda mencerminkan kontrak respons API, anda mengelakkan dua anti-corak biasa: pengambilan berlebihan (mengembalikan medan yang tidak pernah dihantar oleh titik akhir) dan pengambilan tidak mencukupi (mengembalikan medan yang memaksa pertanyaan kedua).

Takrifkan Pemalar Unjuran

Menulis objek unjuran secara terus dalam setiap pertanyaan menyebabkan penduaan dan perbezaan yang tidak selaras dari semasa ke semasa. Takrifkan pemalar unjuran bersama fungsi capaian data atau repositori anda. Jika bentuk respons API berubah, anda hanya perlu mengemas kini satu pemalar dan tidak perlu mencari setiap pertanyaan dalam pangkalan kod.

// 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 });

Jangan Sesekali Kembalikan Medan Sensitif kepada Klien

Medan seperti passwordHash, totpSecret, apiKey, ssn, dan paymentMethodToken hendaklah jangan sesekali muncul dalam respons API. Takrifkan unjuran asas yang selamat untuk mengecualikannya secara lalai, dan hanya ambil medan tersebut dalam panggilan perkhidmatan dalaman yang benar-benar memerlukannya. Gunakan prinsip keistimewaan minimum pada lapisan data.

// 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 totpSecret

Titik Akhir Senarai: Proyeksikan Hanya Medan Ringkasan

Titik akhir senarai (contohnya, GET /products) biasanya mengembalikan ringkasan setiap item, bukan dokumen penuh. Senarai produk mungkin memaparkan name, price, thumbnailUrl, dan rating—bukan description penuh, tatasusunan specifications, atau reviews. Menggunakan unjuran yang padat untuk pertanyaan senarai boleh mengurangkan saiz muatan sebanyak 90% apabila dokumen penuh mengandungi teks atau tatasusunan yang besar.

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();

Titik Akhir Terperinci: Proyeksikan Objek Penuh

Titik akhir terperinci (contohnya, GET /products/:slug) mengembalikan paparan yang lebih kaya bagi satu dokumen. Walaupun begitu, pertimbangkan untuk mengecualikan medan dalaman sahaja. Anda boleh memproyeksikan semua medan awam sambil menyembunyikan harga kos dalaman, butiran hubungan pembekal, atau ID sistem sumber inventori yang tidak sepatutnya dilihat oleh klien.

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 }
);

Gunakan Unjuran dalam Saluran Agregasi Juga

Amalan terbaik unjuran turut terpakai pada saluran agregasi. Letakkan peringkat $project selepas $match dan sebelum peringkat mahal seperti $lookup atau $unwind untuk mengurangkan saiz dokumen yang mengalir melalui saluran tersebut. Dokumen yang lebih kecil dalam saluran bermakna penggunaan memori dan CPU yang lebih rendah pada pelayan.

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'
    }
  }
]);

Unjuran dan Pensirian Versi API

Apabila anda menambah medan baharu pada dokumen MongoDB, klien API lama mungkin tidak menjangkakannya. Menggunakan unjuran kemasukan ketat (menyenaraikan tepat medan yang hendak dikembalikan) bermakna medan dokumen baharu tidak kelihatan kepada pengguna API sedia ada sehingga anda menambahnya secara jelas pada unjuran. Ini memberikan sempadan pensirian versi secara semula jadi: kemas kini unjuran apabila anda mengemas kini versi API.

// 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 };

Uji Padanan Unjuran Dengan Skema Respons

Tulis ujian unit yang mengesahkan objek unjuran MongoDB sepadan dengan skema respons API anda (contohnya, skema Joi atau jenis TypeScript). Ini mencegah pepijat biasa apabila pembangun menambah medan pada jenis respons API tetapi terlupa memasukkannya dalam unjuran—medan itu kembali sebagai undefined dalam pengeluaran walaupun lulus semakan jenis TypeScript.

// 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');

Mengelakkan Ketidakpadanan Unjuran dalam Mongoose

Skema Mongoose dengan select: false pada sesuatu medan menghalang medan itu daripada muncul dalam sebarang hasil pertanyaan melainkan dimasukkan semula secara jelas. Gabungkan ini dengan virtual peringkat skema untuk mengira nilai terbitan tanpa menyimpannya. Bersama-sama, alat ini membolehkan anda menguatkuasakan unjuran lalai yang selamat pada peringkat model, sekali gus mengurangkan kemungkinan data terbocor secara tidak sengaja akibat unjuran pertanyaan yang tiada.

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();
});

Memantau Kecekapan Unjuran

Gunakan explain('executionStats')

untuk mengesahkan bahawa unjuran anda berfungsi seperti yang dirancang. Lihat nisbah nReturned berbanding keysExamined dan docsExamined. Jika docsExamined sama dengan bilangan dokumen yang sepadan (bukan sifar), unjuran anda tidak diliputi oleh indeks tetapi masih betul—anda boleh menilai sama ada penambahan indeks liputan berbaloi dengan kos penyelenggaraannya.

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);

Ringkasan: Senarai Semak Amalan Terbaik Unjuran

Gunakan senarai semak ini pada setiap pertanyaan MongoDB dalam API anda:

  • Takrifkan pemalar unjuran bernama — satu untuk setiap titik akhir atau bentuk respons
  • Gunakan mod kemasukan untuk respons API — senaraikan tepat perkara yang diperlukan
  • Sentiasa kecualikan medan sensitif — passwordHash, token, ID dalaman
  • Gunakan unjuran padat untuk titik akhir senarai — ringkasan sahaja, tanpa kandungan besar
  • Letakkan $project pada peringkat awal dalam saluran agregasi — kurangkan data yang mengalir ke peringkat seterusnya

Semakan Pantas

Uji pemahaman anda tentang konsep MongoDB & NoSQL Databases daripada pelajaran ini.

Jawab dalam pelajaran interaktif

Imbas Kembali Pelajaran

Dalam pelajaran ini, anda telah mempelajari bahawa: pemalar unjuran hendaklah ditakrifkan bagi setiap titik akhir API untuk mencegah perbezaan yang tidak selaras, medan sensitif mesti sentiasa dikecualikan daripada pertanyaan yang menghadap klien, dan meletakkan $project pada peringkat awal dalam saluran agregasi mengurangkan tekanan terhadap memori. Seterusnya, kita akan meneroka pengisihan dan penomboran halaman untuk menyusun serta memecahkan set hasil yang besar dengan cekap.

Percuma untuk bermula

Pelajari JavaScript dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus
30
Pelajaran
120
Mula belajar secara percumaLihat kursus penuh

Soalan Lazim

Adakah pelajaran “Amalan Terbaik Unjuran untuk Respons API” percuma?

Ya — teks penuh “Amalan Terbaik Unjuran untuk Respons API” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus MongoDB Academy, tingkat taraf kepada CoddyKit PRO. Kursus MongoDB Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Amalan Terbaik Unjuran untuk Respons API”?

Pelajar akan mereka bentuk unjuran yang selaras dengan bentuk respons REST API, sekali gus mengurangkan saiz muatan dan melindungi medan sensitif. Anda berlatih MongoDB Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan MongoDB Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran MongoDB Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 4 daripada 4.

Berapa lamakah pelajaran “Amalan Terbaik Unjuran untuk Respons API” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran MongoDB Academy ini?

Ya. Setiap pelajaran MongoDB Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

  1. Unjuran Inklusi berbanding Pengecualian
  2. Mengunjurkan Medan Bersarang dan Tatasusunan
  3. Unjuran Tatasusunan $ dan $elemMatch
  4. Amalan Terbaik Unjuran untuk Respons API
← Kembali ke MongoDB Academy