Spring Petclinic：不只是示例，它是 Spring Boot 项目的活文档

一个示例应用为何值得写一篇文章

Spring Petclinic 是 Spring 官方仓库里的示例应用，表面上是宠物诊所的 CRUD 演示。但它的真正价值不在业务逻辑，而在于它展示了 Spring Boot 项目从零到可运行的标准路径。仓库 README 明确写了它用 Maven 或 Gradle 构建，需要 Java 17 或更新版本。对于想学 Spring Boot 的人，这是一个能跑起来的完整参考。对于团队选型，它是一份官方维护的配置清单。它不解决真实业务问题，但能回答“Spring Boot 项目应该怎么组织”这个问题。

项目结构里藏着 Spring Boot 的典型拼图

从仓库布局看，这是一个标准的 Spring Boot 应用。主类应该是 PetClinicApplication，它负责启动内嵌的 Tomcat。资源目录下包含静态资源、模板和数据库脚本。CSS 文件由 SCSS 编译而来，源码是 petclinic.scss，结合了 Bootstrap。这意味着如果你要改样式，不能直接改 CSS，而是要改 SCSS 再用 Maven profile 重新编译。数据库脚本按数据库类型分目录存放，有 mysql、postgres 和默认的 H2。这种按 profile 分目录的组织方式，是 Spring Boot 多环境配置的常见做法。整个项目没有 Dockerfile，而是依赖 Spring Boot 的 build-image 插件生成容器镜像，这是值得注意的设计选择。

本地启动：两条命令，两种构建工具

README 给出了最直接的启动方式。克隆仓库后，用 Maven 就执行 ./mvnw spring-boot:run，用 Gradle 就执行 ./gradlew bootRun。两个 wrapper 脚本都在仓库里，所以不需要预先安装 Maven 或 Gradle，只要系统有 JDK 17 或更新版本。启动后访问 http://localhost:8080 就能看到应用。默认数据库是 H2 内存数据库，启动时自动填充数据。H2 控制台暴露在 /h2-console，连接 URL 是 jdbc:h2:mem:<uuid>，这个 UUID 会在启动日志里打印。这种设计让开发者零配置就能跑起来，但要注意，内存数据库意味着每次重启数据都会丢失，只适合开发调试。

数据库切换：profile 驱动，但需要你动手验证

除了 H2，项目还提供 MySQL 和 PostgreSQL 的配置。切换方式是在启动时设置 spring.profiles.active=mysql 或 spring.profiles.active=postgres。README 给出了对应的 Docker 启动命令，比如 docker run -e MYSQL_USER=petclinic ... mysql:9.7。项目还提供了 docker-compose.yml，里面每个服务名对应一个 profile，可以 docker compose up mysql 单独启动。但这不是自动的，切换 profile 后，应用会使用对应目录下的数据库脚本初始化表结构和数据。你需要确认这些脚本是否匹配你的数据库版本。README 提到 MySQL 集成测试用 Testcontainers 启动数据库，Postgres 测试用 Docker Compose，这说明项目本身对这两种数据库有测试覆盖，但你在自己的环境里仍需验证。

容器构建：没有 Dockerfile 的镜像生成

这个项目故意不提供 Dockerfile。README 说你可以用 Spring Boot 的 build-image 插件生成镜像，命令是 ./mvnw spring-boot:build-image。这个插件会使用 Cloud Native Buildpacks 自动检测项目类型，生成一个包含 JDK 和应用的镜像。之后用 docker run -p 8080:8080 docker.io/library/spring-petclinic:latest 就能运行。这种做法的好处是你不需要手写 Dockerfile，坏处是你对镜像内容的控制力变弱，比如你无法轻易指定基础镜像或添加系统依赖。对于示例应用这没问题，但如果你是生产环境，可能需要更精细的镜像定制，这时就得自己写 Dockerfile 了。

CSS 编译：一个容易被忽略的构建细节

项目的样式不是直接维护的 CSS 文件。src/main/resources/static/resources/css 下的 petclinic.css 是从 petclinic.scss 编译来的，还结合了 Bootstrap。如果你改了 SCSS 或升级 Bootstrap，需要重新编译 CSS，命令是 ./mvnw package -P css。注意，这个 Maven profile 只存在于 Maven 构建中，Gradle 没有对应的编译配置。这意味着如果你用 Gradle 开发，改样式后要么切换到 Maven 编译，要么手动处理 CSS。这是一个实际的限制，尤其是团队混合使用两种构建工具时。另外，在 IDE 里打开项目时，可能需要先运行 ./mvnw generate-resources 来生成 CSS，否则样式可能缺失或陈旧。

测试应用：为快速反馈而生的 main 方法

项目提供了多个测试入口，不只是标准的测试类。README 提到 PetClinicIntegrationTests 里设置了 main() 方法，使用默认 H2 数据库，还加了 Spring Boot Devtools，方便在 IDE 里启动并快速修改。另外有 MySqlTestApplication 和 PostgresIntegrationTests，分别针对 MySQL 和 PostgreSQL。MySQL 测试用 Testcontainers 在 Docker 里启动数据库，Postgres 测试用 Docker Compose。这些测试应用的目的是让你在开发时获得接近生产环境的反馈，而不必手动配置数据库。但要注意，这些测试依赖 Docker，如果你的开发环境没有 Docker，这些测试会失败。它们不是传统意义上的单元测试，更像是集成测试的辅助入口。

替代方案与选型判断

如果你想要一个更贴近生产实践的 Spring Boot 示例，可以看 Spring 官方提供的其他示例，比如 spring-boot-samples 仓库，它按场景拆分，覆盖了消息队列、缓存、安全等主题。Spring Petclinic 的优势是完整，它包含了一个 Web 应用的所有常见层次：控制器、服务、仓储、模板、数据库迁移和测试。但它的劣势是简单，没有涉及 Spring Security、OAuth2、分布式配置等生产常见需求。另一个替代是 JHipster，它能生成一个包含认证、监控和 CI/CD 配置的完整项目，但它的复杂度高很多，生成的代码量也大。Spring Petclinic 适合作为学习起点，JHipster 适合作为大型项目的基础。如果你的目标是快速理解 Spring Boot 的核心机制，选前者；如果你需要一个生产骨架，后者更接近。

编辑结论

Spring Petclinic 适合刚接触 Spring Boot 的开发者，以及需要一份官方维护的、覆盖常见配置的参考代码的团队。它不适合作为生产项目直接改造，因为示例代码刻意简化了安全、监控和部署细节。如果你打算采用，先确认你的 Java 版本在 17 或以上，并检查 Maven 或 Gradle 的 wrapper 脚本在你的 CI 环境中能正常下载依赖。另外，默认使用 H2 内存数据库，若切换 MySQL 或 PostgreSQL，务必验证对应 profile 下的数据初始化脚本是否满足你的需求。最终判断：这是一个学习工具和脚手架参考，不是生产模板，它的价值在于让你看清 Spring Boot 的常见拼图，而不是直接替你拼好。

官方来源

1. Official README
2. Project repository