## 01、痛点

我是老李，一个靠 Spring Boot 吃饭的后端开发。前阵子项目组要上一套订单系统，技术选型定了 MongoDB。我心想，Spring 官方不是有 Getting Started 吗？花十几分钟跟着跑一遍，Customer 类的增删改查就通了。那一刻我甚至有点飘：MongoDB 也不过如此，不就是换个数据库方言继续写 Repository 嘛。

结果不到两周，需求就开始变形。运营要一张按地区、按小时汇总的订单报表，我第一反应是拉数据到内存里算；财务要求退款和库存扣减必须在一个事务里完成，我发现之前的 Repository 写法根本管不住；更别说后面还有地理位置查询、大文件存储、向量检索这些，每一个都让我在搜索引擎里翻第三方博客，代码质量参差不齐，版本还经常对不上。

这时候我才反应过来：十几分钟跑通官方入门案例，只是证明你能把 MongoDB 当 MySQL 用，离真正掌握还差得远。问题就来了：为什么官方 Getting Started 明明很短，却不能算掌握 MongoDB？

## 02、是什么

要回答这个问题，先得把两个东西分清楚。

第一个是官方 Getting Started 项目，全名 gs-accessing-data-mongodb。它做的事非常聚焦：引入 spring-boot-starter-data-mongodb，定义 Customer 实体，声明一个 CustomerRepository 接口，然后跑几个增删改查测试。整个闭环就一个目的——让你用最小的成本，感受 Spring Data MongoDB 的 Repository 抽象有多方便。它是官方给的“第一段代码”，不是第三方博客，权威性没问题，但覆盖面极其有限。

第二个是 spring-projects/spring-data-examples。这是 Spring Data 团队维护的官方样例仓库，光 MongoDB 目录就覆盖了 aggregation、reactive、transactions、vector-search、GridFS、GeoJSON、QueryDSL、AOT、metrics 等真实能力。每一个模块都是一个独立可运行的工程，有测试、有配置、有版本关联，专为展示某个具体特性怎么在生产里用。

所以，官方 Getting Started 负责最小 Repository 闭环，而更值得长期跟读的是 spring-data-examples。前者告诉你门在哪里，后者告诉你房间里有多少家具。

## 03、为什么

为什么会有这种定位差异？因为官方的 Getting Started 设计目标不是让你成为专家，而是让你别被劝退。任何一个技术栈，如果入口案例一上来就讲聚合管道、副本集事务、响应式背压，新手可能直接关掉文档。所以官方会把“最简路径”做成 Getting Started：一个实体、一个接口、几行配置，搞定。这个过程十几分钟很合理，但它只是“进入”，不是“掌握”。

而 spring-data-examples 的存在理由完全不同。它是给已经入门、准备解决真实业务问题的人准备的。当你要做订单报表，aggregation 模块里就有聚合管道的写法；当你要保证资金操作一致性，transactions 模块里就有 Mongo 事务的配置和使用；当你想做向量相似度搜索，vector-search 模块直接给出现成代码。这些内容，Getting Started 不会展开，因为展开就失去“快”的优势了。

换句话说，Guide 负责告诉你怎么进入，Examples 才开始告诉你 MongoDB 能做到哪里。一个是门票，一个是地图。

## 04、架构

要读懂 examples，得先对 Spring Data MongoDB 的整体架构有个概念。它并不是一个黑盒，而是几层组件配合。

最上层是 Repository 抽象。你写一个接口继承 MongoRepository 或者 PagingAndSortingRepository，Spring 就会在运行时生成实现，默认提供 save、findById、findAll、delete 等方法。这个抽象屏蔽了样板代码，但也容易让人忽略底层能力。

往下是 MongoTemplate。它是 Spring Data MongoDB 的核心操作类，几乎所有高级操作都通过它完成：原生查询、聚合管道、批量写入、索引管理、地理位置查询等。Repository 内部其实也在用 MongoTemplate，只是被封装得更简单。

再往下是 Converter 和 Mapping 层。Java 对象和 MongoDB 文档之间的转换、字段映射、自定义类型处理都在这一层完成。examples 里大量演示了如何自定义转换器解决特殊字段类型。

然后是横切能力：事务、响应式、GridFS、QueryDSL、AOT、Metrics。事务依赖 MongoDB 副本集和 Spring 的事务管理器；响应式有独立的 ReactiveMongoTemplate 和 ReactiveMongoRepository；GridFS 用于大文件分块存储；QueryDSL 提供类型安全的查询；AOT 是原生镜像相关的前置处理；Metrics 则把 MongoDB 连接池和操作指标暴露给监控系统。

spring-data-examples/mongodb 目录就是按这些能力分模块组织的，每个模块都能单独运行，相当于一张可执行的架构图。

## 05、实战

光说不练假把式。具体怎么用这两类官方资源？

第一步，跑通 Customer 官方入门案例。克隆 gs-accessing-data-mongodb 仓库，导入到开发环境，确保本地 MongoDB 可用，运行测试。这一步让你建立最小信心，同时确认环境没问题。重点看 CustomerRepository 接口怎么声明、Spring Boot 怎么自动配置 MongoTemplate。

第二步，克隆 spring-data-examples 仓库。命令很简单：git clone https://github.com/spring-projects/spring-data-examples.git。仓库很大，不需要全部构建，进入 mongodb 目录即可。

第三步，按顺序跑三个模块。先跑 example 模块，它是最基础的 MongoDB 操作；再跑 aggregation 模块，里面演示了聚合管道、分组统计、投影等，正好对应报表类需求；最后跑 transactions 模块，它展示如何在 Spring 里配置 MongoTransactionManager，如何用 @Transactional 注解保证跨文档操作原子性。跑完之后你会对 MongoDB 的真实能力有一个明显更立体的认知。

如果遇到 Maven 或 Gradle 构建问题，优先看每个模块下的 README，官方通常会写明需要的 MongoDB 版本、是否要求副本集等前置条件。

## 06、洞见

经过这一轮对比，我最深的感受是：官方 Getting Started 和官方 Examples 之间的落差，恰恰是很多开发者“入门即止步”的原因。我们太容易把“跑通示例”当成“掌握技术”，实际上那只是拿到了入场券。真正的能力边界，藏在一个个专项示例里。

另一个洞见是：官方 examples 仓库比大多数第三方博客更值得作为长期参考库。因为它是 Spring Data 团队自己维护的，代码风格、版本搭配、测试用例都经过验证，而且会随着版本更新而演进。很多第三方博客的问题在于，要么版本过时，要么只讲片段不讲上下文，你抄过来能跑，但生产环境一压就出问题。

所以我的学习策略变成了：Getting Started 用来快速进入，examples 用来按需查阅。每当业务遇见一个新场景，先去 examples 里找对应模块，读懂官方推荐写法，再结合自己的项目改造。这样既避免了重复造轮子，也避免了被二手信息带偏。

## 07、行动

如果你也正在从 Spring Data MongoDB 入门走向实战，我建议立刻做三件事：

第一，克隆并跑通 gs-accessing-data-mongodb，确认基础环境可用，理解 Repository 自动生成的机制。

第二，克隆 spring-data-examples 仓库，先进 mongodb/example 模块，跑通最基础的 CRUD 和配置。

第三，依次跑通 mongodb/aggregation 和 mongodb/transactions 两个模块。aggregation 让你看到聚合管道的威力，transactions 让你掌握多文档事务的正确姿势。这两个是大部分业务系统最先用到的进阶能力。

跑完之后，不要急着把所有模块都学完。回到当前业务最痛的点，找一个对应模块深入，比如地理查询就看 GeoJSON，大文件就看 GridFS，向量检索就看 vector-search。以战养战，比从头到尾刷一遍更有效。

## 08、小结

官方 Getting Started 是一盏路灯，照亮你进入 Spring Data MongoDB 的第一步；spring-data-examples 则是一片营地，每个模块都是一顶帐篷，里面放着该领域的地图和工具。只站在路灯下，你永远看不见营地有多大。跑通 Customer 案例只是拿到门票，真正的旅程从克隆 examples 仓库开始。

记住一句话：Guide 负责告诉你怎么进入，Examples 才开始告诉你 MongoDB 能做到哪里。

## 09、链接与概念说明

官方资源：
- Spring Data MongoDB 文档：https://docs.spring.io/spring-data/mongodb/docs/current/reference/html/
- gs-accessing-data-mongodb：https://github.com/spring-guides/gs-accessing-data-mongodb
- spring-data-examples：https://github.com/spring-projects/spring-data-examples

关键概念：
- Repository：Spring Data 提供的数据访问抽象，通过接口方法自动生成查询实现。
- MongoTemplate：Spring Data MongoDB 的核心操作类，支持高级查询、聚合、批量操作等。
- Aggregation：聚合管道，用于分组、过滤、投影、排序等数据加工。
- Transaction：事务，MongoDB 从 4.0 开始支持副本集多文档事务，Spring 提供相应事务管理器。
- Reactive：响应式编程模型，基于 Reactor，提供非阻塞的数据访问。
- GridFS：MongoDB 的大文件存储规范，将文件分块存储。
- GeoJSON：地理空间数据格式，用于地理位置查询。
- QueryDSL：类型安全的查询框架，与 Spring Data 集成后可避免字符串查询错误。
- AOT：Ahead-of-Time，为原生镜像构建提前处理元数据。
- Metrics：监控指标，基于 Micrometer 暴露 MongoDB 连接池和操作性能数据。

以上概念都可以在 spring-data-examples 的 mongodb 目录下找到对应可运行代码。

我是老李，一个靠 Spring Boot 吃饭的后端开发。前阵子项目组要上一套订单系统，技术选型定了 MongoDB。我心想，Spring 官方不是有 Getting Started 吗？花十几分钟跟着跑一遍，Customer 类的增删改查就通了。那一刻我甚至有点飘：MongoDB 也不过如此，不就是换个数据库方言继续写 Repository 嘛。

《Spring Mongo实战》第2招 先跑官方经典项目

Spring Data MongoDB 官方入门只覆盖最小 Repository 闭环，真正拉开差距的是 spring-projects/spring-data

架构师

后端

数据库

开发工具

官方Spring Data MongoDB的Getting Started仅覆盖基础Repository操作，而spring-data-examples仓库才是掌握MongoDB核心能力的关键。通过聚合、事务、GridFS等模块实战，从入门案例迈向生产级开发，避免"入门即止步"的陷阱。推荐克隆examples仓库，按业务需求深入对应模块，以战养战提升技术深度。

文件存储

MongoDB

MySQL

Java

腾讯云BI特惠9.9元起！


2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

官方Spring Data MongoDB的Getting Started仅覆盖基础Repository操作，而spring-data-examples仓库才是掌握MongoDB核心能力的关键。通过聚合、事务、GridFS等模块实战，从入门案例迈向生产级开发，避免"入门即止步"的陷阱。推荐克隆examples仓库，按业...

《Spring Mongo实战》第2招 先跑官方经典项目-腾讯云开发者社区-腾讯云

《Spring Mongo实战》第2招先跑官方经典项目

《Spring Mongo实战》第2招先跑官方经典项目

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring Mongo实战》第2招 先跑官方经典项目

《Spring Mongo实战》第2招 先跑官方经典项目

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring Mongo实战》第2招先跑官方经典项目

《Spring Mongo实战》第2招先跑官方经典项目