0Pricing
MongoDB Academy · 课时

API 响应的投影最佳实践

您将设计与 REST API 响应结构一致的投影，减少负载大小并保护敏感字段。

API 响应的投影最佳实践 是 CoddyKit 上的免费 MongoDB Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 MongoDB Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 MongoDB Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Align Projections With API Response Shapes

Every REST or GraphQL endpoint your application exposes has a defined response shape. The ideal MongoDB projection returns exactly the fields that shape requires—no more, no less. When your projection mirrors your API response contract, you avoid two common anti-patterns: over-fetching (returning fields the endpoint never sends) and under-fetching (returning fields that force a second query).

Define Projection Constants

Hardcoding projection objects inline in every query leads to duplication and drift over time. Define projection constants alongside your data access functions or repositories. If the API response shape changes, you update one constant rather than hunting for every query in the codebase.

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

Never Return Sensitive Fields to Clients

Fields like passwordHash, totpSecret, apiKey, ssn, and paymentMethodToken should never appear in API responses. Define a secure base projection that excludes them by default, and only fetch them in internal service calls that specifically require them. Apply the principle of least privilege at the data layer.

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

List Endpoints: Project Only Summary Fields

List endpoints (e.g., GET /products) typically return a summary of each item, not the full document. A product list might show name, price, thumbnailUrl, and rating—not the full description, specifications array, or reviews. Using a tight projection for list queries can reduce payload size by 90% when full documents contain large text or arrays.

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

Detail Endpoints: Project the Full Object

Detail endpoints (e.g., GET /products/:slug) return a richer view of a single document. Even here, consider excluding internal-only fields. You might project all public fields while suppressing internal cost price, supplier contact details, or inventory source system IDs that clients should not see.

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

Use Projections in Aggregation Pipelines Too

Projection best practices extend to the aggregation pipeline. Place a $project stage after $match and before expensive stages like $lookup or $unwind to reduce the document size flowing through the pipeline. Smaller documents in the pipeline mean less memory and CPU usage on the server.

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

Projections and API Versioning

When you add new fields to MongoDB documents, old API clients may not expect them. Using strict inclusion projections (listing exactly the fields to return) means new document fields are invisible to existing API consumers until you explicitly add them to the projection. This gives you a natural versioning boundary: update the projection when you update the API version.

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

Test That Projections Match Response Schemas

Write unit tests that assert the MongoDB projection object matches your API response schema (e.g., a Joi schema or a TypeScript type). This prevents the common bug where a developer adds a field to the API response type but forgets to include it in the projection—the field comes back as undefined in production while passing TypeScript type checks.

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

Avoiding Projection Mismatch in Mongoose

Mongoose schemas with select: false on a field prevent that field from appearing in any query result unless explicitly re-included. Combine this with schema-level virtuals to compute derived values without storing them. Together, these tools let you enforce a secure default projection at the model level, reducing the chance of accidentally leaking data through a missing query projection.

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

Monitoring Projection Efficiency

Use explain('executionStats')

to verify that your projections are working as intended. Look at the nReturned vs keysExamined and docsExamined ratio. If docsExamined equals the number of matched documents (not zero), your projection is not covered by an index but is still correct—you can weigh whether adding a covering index is worth the maintenance cost.

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

Summary: Projection Best Practice Checklist

Apply this checklist to every MongoDB query in your API:

  • Define named projection constants — one per endpoint or response shape
  • Use inclusion mode for API responses — list exactly what you need
  • Always exclude sensitive fields — passwordHash, tokens, internal IDs
  • Use tight projections for list endpoints — summary only, no large bodies
  • Place $project early in aggregation pipelines — reduce data flowing downstream

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: projection constants should be defined per API endpoint to prevent drift, sensitive fields must always be excluded from client-facing queries, and placing $project early in aggregation pipelines reduces memory pressure. Next up we explore sorting and pagination to order and page through large result sets efficiently.

常见问题解答

「API 响应的投影最佳实践」课时是免费的吗？

是的 — 「API 响应的投影最佳实践」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 MongoDB Academy 课程的其余内容，请升级到 CoddyKit PRO。 MongoDB Academy 课程共包含 4 节课。

「API 响应的投影最佳实践」这节课中我会学到什么？

您将设计与 REST API 响应结构一致的投影，减少负载大小并保护敏感字段。 你通过在浏览器中直接运行的动手代码来练习 MongoDB Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 MongoDB Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 MongoDB Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。

「API 响应的投影最佳实践」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 MongoDB Academy 课中编写并运行代码吗？

能。每节 MongoDB Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 包含式与排除式投影
  2. 投影嵌套字段与数组字段
  3. $ 与 $elemMatch 数组投影
  4. API 响应的投影最佳实践
← 返回 MongoDB Academy