# Petclinic 开发环境工程化：用 Compose 消灭“我的机器能运行”

```text
旧方案：每个开发者本地分别安装 MySQL、Redis、模拟保险服务
冲突：版本不一致、端口冲突、初始化脚本漂移、新成员上手慢
后果：团队规模越大，“我的机器能运行”越昂贵，联调与排障成本指数上升
```

Petclinic 从单体教学项目开始，逐渐接入 MySQL、Redis，还新增了一个模拟保险服务。

我是老李，最近团队从 3 个人扩到 9 个人，新同事第一天往往卡在装 MySQL、导数据、起 Redis 这些事上。

为什么团队规模变大以后，“我的机器能运行”会变成越来越昂贵的问题？

是继续让每个人手工安装组件，还是把开发依赖写成 Compose 基础设施即代码？

如果选错，会不会让新开发者 onboarding 从半天变成三天，甚至让联调环境永远无法复现？

# 01、故事

```text
周一 09:40 → 新同事工位 → 任务是跑起 Petclinic 开发环境 → 冲突：MySQL 版本不对、Redis 没装、保险服务起不来
```

周一早上，新同事小周入职，任务是 clone Petclinic 后把应用跑起来。

他先装 MySQL 8.4，又发现本地 3306 被旧项目占用，改端口后应用连不上。

接着装 Redis，结果测试用例要求 Redis 7，他装的是 6。

最后卡在模拟保险服务，那个服务没有安装包，只有一段 Python 脚本和一堆环境变量。

> 新机初装路九弯，
> 版本参差端口残。
> 一人能跑非交付，
> 团队复现始知难。

# 02、问题

```text
需求变化：团队从 3 人扩到 9 人，开发依赖从 H2 变成 MySQL + Redis + 模拟保险服务
冲突：本地手工安装无法保证版本、端口、初始化脚本一致
后果：新成员 onboarding 超过一天，联调问题无法复现，交付节奏被拖慢
```

原来的 Petclinic 用 H2 内存库，开发者 clone 后直接 Run Application 就能启动。

现在为了贴近生产，数据层切到 MySQL，缓存用 Redis，还接入了模拟保险服务。

这些依赖如果继续靠口头文档和手工安装，每个人机器上的版本、配置、初始化数据都会漂移。

可验证的验收标准是：新开发者完成 git clone、启动 Docker、Run Application 三步后，应用能在 10 分钟内正常启动并通过健康检查。

> 依赖渐多如藤蔓，
> 手工安装各不同。
> 一人能跑非标准，
> 团队协作必成空。

# 03、原理

```text
Spring Boot Development-time Services 检测 compose.yml → 自动启动容器 → 通过 Service Connection 注入连接信息
```

Spring Boot 3.1 起支持 Development-time Services，应用启动时如果检测到 classpath 下有 Docker Compose 模块，会读取根目录的 comp

ose.yml。

它会在应用启动前自动执行 docker compose up，把 MySQL、Redis 等依赖容器拉起来。

应用停止时根据配置决定是否执行 docker compose down，这就是 Compose Lifecycle 管理。

Service Connection 会自动从容器元数据中提取主机、端口、用户名、密码，生成 ConnectionDetails，覆盖配置文件里的连接信息。

反直觉的是：compose.yml 里定义的端口映射并不是给应用用的，应用在容器网络内部直连服务名，只有你需要从宿主机调试时才需要 ports。

> 容器编排藏暗线，
> 服务连接自动连。
> 端口映射非正道，
> 网络内部自相牵。

# 04、架构

```text
输入：git clone 后的源码 + Docker Desktop → 本模块：compose.yml + Spring Boot Dev Services → 输出：可运行的应用 + 一致的依赖环境
```

这一层位于开发环境基础设施层，不进入生产部署路径。

compose.yml 定义开发依赖：MySQL 8.4、Redis 7、模拟保险服务。

Spring Boot 通过 spring-boot-docker-compose 依赖读取 compose.yml，在应用启动前拉起容器。

Service Connection 负责把容器连接信息注入 DataSource、RedisConnectionFactory 以及自定义的保险服务客户端。

收益是环境一致性，代价是要求每个开发者安装 Docker Desktop 或等效容器运行时。

适用条件是开发与联调环境，不适用于生产 Kubernetes，因为生产需要滚动升级、资源配额、故障自愈等能力。

> 开发环境求一致，
> 生产部署另有纲。
> 边界清晰方不乱，
> 各司其职稳如桩。

# 05、第一版实战

```text
环境：macOS + Docker Desktop 4.30 + JDK 21 + Spring Boot 3.3 → 配置：pom.xml + compose.yml → 代码：启动类 → 启动：Run Application → 验证：HTTP 请求 → V1
```

先确认版本：Spring Boot 3.3.0，JDK 21，Docker Desktop 4.30。

在 pom.xml 加入 docker-compose 依赖：

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-docker-compose</artifactId>
    <optional>true</optional>
</dependency>
```

在项目根目录创建 compose.yml：

```yaml
services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: petclinic
      MYSQL_USER: petclinic
      MYSQL_PASSWORD: petclinic
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
  redis:
    image: redis:7.2
    ports:
      - "6379:6379"
  insurance-service:
    image: petclinic/insurance-mock:1.0.0
    environment:
      INSURANCE_PORT: 8081
    ports:
      - "8081:8081"
volumes:
  mysql-data:
```

在 application.yml 中保留生产配置，但开发时让 Service Connection 覆盖：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/petclinic
    username: petclinic
    password: petclinic
  data:
    redis:
      host: localhost
      port: 6379
```

启动应用：

```bash
./mvnw spring-boot:run
```

示例输出：

```text
Using Docker Compose file 'compose.yml'
Starting Docker Compose services...
Container petclinic-mysql-1 started
Container petclinic-redis-1 started
Container petclinic-insurance-service-1 started
```

验证请求：

```bash
curl http://localhost:8080/owners
curl http://localhost:8080/actuator/health
```

V1 成功标准：应用启动时自动拉起三个容器，健康检查返回 UP，owners 页面返回 200。

> 一键启动三容器，
> 服务连接自动成。
> 新兵上手指日待，
> 环境一致初显形。

# 06、排查

```text
诊断树：应用启动失败 → 是容器未启动？是连接信息错误？是端口冲突？→ 逐层检查
```

第一个问题：应用启动时提示 Cannot connect to MySQL。

怀疑是容器没起来，检查容器状态：

```bash
docker compose ps
```

证据显示 mysql 容器处于 Restarting 状态。

查看日志：

```bash
docker compose logs mysql
```

根因是本地 3306 端口被旧 MySQL 占用，容器内 MySQL 无法绑定端口。

修复：把宿主机映射端口改为 3307，应用仍通过容器网络连接 3306。

第二个问题：Redis 连接被拒绝。

怀疑是 Service Connection 没有生效，检查启动日志：

```bash
./mvnw spring-boot:run | grep -i redis
```

证据显示日志里没有 Redis ConnectionDetails 注入信息。

根因是 pom.xml 中 docker-compose 依赖被标记为 optional，但当前 IDE 运行配置没有包含该依赖。

修复：在 IDE 运行配置中勾选包含 optional 依赖，或改用命令行启动。

**错误尝试：** 一开始手动在 application.yml 里写死容器 IP，结果每次容器重启 IP 变化，连接又失败。

> 端口冲突寻常事，
> 容器日志见真章。
> 连接注入需依赖，
> 写死地址必遭殃。

# 07、优化

```text
V1：compose.yml 端口写死 3306 → 证据：宿主机端口冲突导致容器重启 → V2：宿主机端口改为 3307，应用走容器网络
```

把 compose.yml 中 MySQL 的宿主机端口改为 3307，避免和宿主机已有服务冲突：

```yaml
services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: petclinic
      MYSQL_USER: petclinic
      MYSQL_PASSWORD: petclinic
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3307:3306"
    volumes:
      - mysql-data:/var/lib/mysql
```

同时给模拟保险服务加上健康检查，确保 Service Connection 能正确等待服务就绪：

```yaml
  insurance-service:
    image: petclinic/insurance-mock:1.0.0
    environment:
      INSURANCE_PORT: 8081
    ports:
      - "8081:8081"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/health"]
      interval: 5s
      timeout: 3s
      retries: 10
```

在 application.yml 中明确关闭生产环境不需要的 Compose 生命周期管理：

```yaml
spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      enabled: true
```

这样开发时应用停止会自动执行 docker compose down，避免残留容器占用资源。

> 端口冲突改映射，
> 健康检查候就绪。
> 生命周期明起止，
> 残留容器不再余。

# 08、演进

```text
V2：compose.yml 端口隔离 + 健康检查 + 生命周期管理 → 能力：新开发者三步启动 → 遗留：生产环境仍需 Kubernetes
```

用 V1 同一组请求验证：

```bash
curl http://localhost:8080/owners
curl http://localhost:8080/actuator/health
```

现在新开发者流程变成：

```bash
git clone https://github.com/spring-projects/spring-petclinic.git
cd spring-petclinic
docker compose up -d
./mvnw spring-boot:run
```

收益是 onboarding 从一天缩短到 10 分钟，环境漂移问题消失。

代价是每个开发者必须安装 Docker Desktop，且首次拉取镜像需要网络带宽。

适用场景是开发与联调，不适用于生产，因为 Compose 缺少滚动升级、资源配额、故障自愈等生产级能力。

遗留问题是模拟保险服务的镜像还没有纳入 CI 构建流程，目前是手动构建后推送到本地镜像仓库。

> 三步启动成新标，
> 环境漂移自此消。
> 生产仍需 K8s 管，
> 开发生产各一条。

# 09、洞见

```text
从“我的机器能运行”到“团队环境一致”的工程判断
```

## 反直觉判断：端口映射不是给应用用的
```text
compose.yml ports → 宿主机调试用
应用连接 → 容器网络服务名
```

很多开发者以为应用必须通过 localhost:3306 连接 MySQL，实际上 Spring Boot Dev Services 在容器网络内部直连服务名 mysql，端口映射只是为了方便你在宿主

机用数据库工具查看数据。

## 反直觉判断：开发环境越接近生产，反而越需要自动化
```text
依赖越多 → 手工配置越不可靠 → 自动化收益越大
```

当依赖只有 H2 时，手工配置成本几乎为零；当依赖变成 MySQL、Redis、模拟服务时，手工配置的出错概率和沟通成本急剧上升，自动化反而成为唯一可持续的方案。

## 判断：Compose 是开发契约，不是部署方案
```text
compose.yml → 开发环境契约
生产部署 → Kubernetes Manifest
```

把 compose.yml 当作团队内部的开发环境契约，它定义了依赖的版本、配置、初始化方式；

生产部署应该由独立的 Kubernetes Manifest 或 Helm Chart 管理，两者边界清晰才能避免“开发环境能跑，生产环境跑不起来”的困境。

> 端口映射非正道，
> 容器网络自相连。
> 依赖越多越自动，
> 开发生产各一边。

# 10、系统落地

```text
入口：git clone + Docker Desktop → 服务：Spring Boot Dev Services → 本模块：compose.yml + Service Connection → 存储：MySQL + Redis + 模拟保险服务 → 未实现：生产 Kubernetes 部署
```

原来 Petclinic 只有 H2 内存库，开发者 clone 后直接启动。

本篇增加了 compose.yml 定义 MySQL、Redis、模拟保险服务，通过 Spring Boot Development-time Services 自动拉起容器，通过 Service C

onnection 注入连接信息。

现在新开发者完成 git clone、Docker、Run Application 三步就能开始工作，不再需要手工配置中间件。

下一篇缺的是把这些开发依赖的初始化数据、版本升级策略、CI 集成纳入自动化流程，以及为生产环境编写独立的 Kubernetes 部署清单。

官方链接：https://spring.io/projects/spring-boot

> 开发环境已成形，
> 三步启动告功成。
> 生产部署尚缺位，
> 下篇再续 K8s 程。

# 11、小结

```text
三问三答：为什么昂贵？怎么选？选错后果？
```

为什么团队规模变大后“我的机器能运行”越来越昂贵？因为每个开发者的环境漂移导致联调问题无法复现，沟通和排障成本随人数指数上升。

怎么选？选择把开发依赖写成 compose.yml，用 Spring Boot Dev Services 自动管理容器生命周期和连接注入。

选错后果？如果继续手工安装，新开发者 onboarding 会从 10 分钟变成一整天，团队交付节奏被拖慢，最终失去工程化能力。

当前状态：Petclinic 开发环境已经实现基础设施即代码，新成员可以三步启动，环境一致性问题基本解决。

> 三问三答明方向，
> 环境一致是良方。
> 工程化路初起步，
> 生产部署待加强。

# 12、作业

```text
理解 → 实战 → 排障 → 架构判断
```

## 理解题：为什么应用连接 MySQL 时不用 localhost:3306，而用服务名 mysql？

因为 Spring Boot Dev Services 在 Docker Compose 创建的容器网络内部运行，应用容器和 MySQL 容器在同一个网络中，直接通过服务名 mysql 解析到容器 I

P，端口是容器内部的 3306。

localhost:3306 是宿主机视角，只有当你从宿主机用数据库工具连接时才需要。

## 实战题：给 compose.yml 增加一个 Kafka 依赖，并让 Spring Boot 应用通过 Service Connection 连接它。

在 compose.yml 中加入 kafka 服务，使用 bitnami/kafka 镜像，配置 KAFKA_CFG_LISTENERS 等环境变量。

在 pom.xml 中加入 spring-kafka 依赖，Spring Boot 会自动检测 Kafka 容器并注入 KafkaConnectionDetails。

启动应用后，在日志中确认 Kafka ConnectionDetails 被注入，然后发送一条测试消息验证。

## 排障题：应用启动时提示 Cannot connect to Redis，但 docker compose ps 显示 Redis 容器正在运行，如何排查？

先检查应用日志中是否有 Redis ConnectionDetails 注入信息，确认 spring-boot-docker-compose 依赖是否在运行 classpath 中。

然后检查 Redis 容器日志，确认是否已就绪。

最后检查 compose.yml 中 Redis 服务名是否与 Service Connection 期望的一致，以及是否有端口冲突导致容器内 Redis 未监听 6379。

## 架构判断题：团队领导要求把 compose.yml 直接部署到生产环境，理由是“开发环境能跑，生产环境也能跑”，你是否同意？

不同意。compose.yml 是开发环境契约，缺少生产环境需要的滚动升级、资源配额、故障自愈、多副本调度等能力。

生产环境应该使用 Kubernetes Manifest 或 Helm Chart，由独立的部署流水线管理。

开发 Compose 与生产 Kubernetes 的边界必须清晰，否则会导致生产环境不可控。

> 四题作业层层进，
> 理解实战排障明。
> 架构判断最关键，
> 开发生产界限清。

# 13、升华

```text
工程结论：开发环境的一致性必须通过基础设施即代码来保证，而不是依赖个人自觉
```

“我的机器能运行”在团队规模变大后必然失效，因为环境漂移带来的沟通和排障成本会吞噬所有效率收益。

把开发依赖写入 compose.yml，用 Spring Boot Development-time Services 自动管理容器生命周期和连接注入，是当前 Spring Boot 生态下最务实的方

案。

开发 Compose 与生产 Kubernetes 的边界必须清晰：前者是开发契约，后者是部署方案，两者不能混用。

下一篇将把这些开发依赖的初始化数据、版本升级策略、CI 集成纳入自动化流程，并开始编写生产环境的 Kubernetes 部署清单。

> 环境一致靠代码，
> 个人自觉难久长。
> 开发生产分两界，
> 工程化路始成章。

**系列项目：** Spring 官方 Petclinic 教学项目，服务对象为宠物医院诊疗与客户管理系统。

**已完成：** 环境搭建、启动机制、依赖与自动配置、配置体系、Web 层、安全层、数据层、事务管理、远程调用、数据库迁移、缓存、并发控制、日志、测试、Testcontainers、Docker Compose 开发环境。

**本篇：** 将 MySQL、Redis、模拟保险服务统一写入 compose.yml，实现 Development-time Services、Compose Lifecycle 与 Service Connection，让新开发者三步启动。

**下一篇：** 将开发依赖的初始化数据、版本升级策略、CI 集成纳入自动化流程，并编写生产 Kubernetes 部署清单。

Petclinic 从单体教学项目开始，逐渐接入 MySQL、Redis，还新增了一个模拟保险服务。

《SpringBoot4进阶实战》第19招 DockerCompose改善开发体验

把 MySQL、Redis、模拟保险服务写入 compose.yml，用 Spring Boot Development-time Services 让新开发者

架构师

后端

开发工具

架构设计

本文通过SpringBoot Docker Compose实现Petclinic开发环境工程化，解决团队扩增后环境漂移问题。展示如何用Development-timeServices自动拉起MySQL、Redis及模拟保险服务容器，通过ServiceConnection注入连接信息，让新成员三步完成启动，将onboarding时间从一天缩短至10分钟，同时明确开发Compose与生产Kubernetes的边界。

基础设施即代码

代码解释

容器编排

Kubernetes

数据库

中间件

Docker

容器

Python

MySQL

Kafka

Redis

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

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文通过SpringBoot Docker Compose实现Petclinic开发环境工程化，解决团队扩增后环境漂移问题。展示如何用Development-timeServices自动拉起MySQL、Redis及模拟保险服务容器，通过ServiceConnection注入连接信息，让新成员三步完成启动，将onboar...

《SpringBoot4进阶实战》第19招 DockerCompose改善开发体验-腾讯云开发者社区-腾讯云

《SpringBoot4进阶实战》第19招 DockerCompose改善开发体验

《SpringBoot4进阶实战》第19招 DockerCompose改善开发体验

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐