📚 课程目录第4章医疗微服务项目工程结构搭建

4. 医疗微服务项目工程结构搭建

医疗微服务项目通常不会只有一个可运行的服务，而是由患者服务、挂号服务、医嘱服务、检验检查服务、支付服务、网关、公共组件等多个模块共同组成。如果每个服务各自维护一套依赖版本、各自定义包名、各自搭建本地环境，项目很快会陷入“能编译但不敢升级、能运行但无法协作”的状态。因此，工程结构搭建的核心目标不是把代码放进文件夹，而是建立一套可统一构建、可统一依赖、可统一规范、可统一启动的工程骨架。

多模块工程：用父工程锁定“共同语言”

以 Maven 为例，推荐采用“父工程 + 公共模块 + 业务服务模块”的三层结构。父工程只负责聚合与依赖管理，不写业务代码；公共模块承载医疗项目共用的返回体、异常、工具、审计字段、患者标识脱敏等能力；业务服务模块各自独立启动、独立部署。典型目录如下：

medical-platform/
├── pom.xml                     # 父工程：聚合 + dependencyManagement
├── medical-common/             # 公共模块：Result、异常、工具、常量
│   └── pom.xml
├── medical-api/                # 服务间接口契约：DTO、Feign 接口
│   └── pom.xml
├── medical-gateway/            # 统一入口：路由、鉴权、限流
│   └── pom.xml
├── medical-patient-service/    # 患者服务
│   └── pom.xml
├── medical-order-service/      # 医嘱服务
│   └── pom.xml
└── medical-payment-service/    # 支付服务
    └── pom.xml

父工程 pom.xml 中通过 <modules> 聚合所有子模块，通过 <dependencyManagement> 统一声明 Spring Boot、Spring Cloud、MyBatis-Plus、MySQL 驱动、Hutool 等版本。子模块引用依赖时不写版本号，避免“同一个 Spring Cloud 在不同服务里版本不一致”导致注册中心、配置中心、网关协议不兼容。Gradle 项目同理，可在根 build.gradle 中使用 subprojects 或 platform 统一约束版本。

统一依赖管理：把版本收敛到一处

医疗项目对稳定性要求高，依赖升级必须可控。建议父工程继承 spring-boot-starter-parent，再用 spring-cloud-dependencies 与 spring-cloud-alibaba-dependencies 做 BOM 导入。示例：

<properties>
  <spring-boot.version>3.2.5</spring-boot.version>
  <spring-cloud.version>2023.0.1</spring-cloud.version>
  <mybatis-plus.version>3.5.6</mybatis-plus.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>${spring-boot.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>com.baomidou</groupId>
      <artifactId>mybatis-plus-bom</artifactId>
      <version>${mybatis-plus.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

这样，业务模块只需写 <artifactId>mybatis-plus-boot-starter</artifactId>，版本由父工程统一决定。若某服务确实需要特殊版本，应在父工程中显式覆盖并注释原因，而不是在子模块里私自指定。

医疗项目命名与包结构设计

医疗项目命名应体现业务域与层级，避免 com.example.demo 这类无意义包名。推荐根包采用“机构域名倒写 + 业务域”，例如 com.hospital.medical。每个服务内部按“接口层—应用层—领域层—基础设施层”组织，包结构示例：

com.hospital.medical.patient
├── controller        # 对外 REST 接口
├── application       # 应用服务，编排用例
├── domain            # 实体、值对象、领域服务
│   ├── model
│   └── service
├── infrastructure    # Mapper、远程调用、消息、缓存
│   ├── mapper
│   ├── feign
│   └── config
└── PatientApplication.java

类名建议统一后缀：XxxController、XxxService、XxxServiceImpl、XxxMapper、XxxDTO、XxxVO、XxxConvert。医疗数据涉及隐私，DTO 与 VO 必须分离，禁止直接把数据库实体暴露给前端。患者标识、身份证号、手机号等字段在 VO 中应做脱敏处理。

代码规范：让协作可预期

代码规范不是形式主义，而是医疗系统可审计、可追溯的基础。建议在父工程中统一引入 spring-javaformat 或 checkstyle 插件，并约定：统一使用 4 空格缩进；类、方法必须写 Javadoc；禁止使用 System.out.println；日志使用 SLF4J；异常统一继承 MedicalBizException；接口返回统一包装为 Result<T>。可在父工程 pom.xml 中绑定校验插件，执行 mvn validate 时自动检查格式，未通过则构建失败。

本地开发环境搭建

本地环境建议用 Docker Compose 一键拉起 MySQL、Redis、Nacos、RabbitMQ 等中间件，避免每位开发者手工安装。示例 docker-compose.yml 片段：

services:
  mysql:
    image: mysql:8.0
    ports: ["3306:3306"]
    environment:
      MYSQL_ROOT_PASSWORD: medical123
      MYSQL_DATABASE: medical_patient
  redis:
    image: redis:7.2
    ports: ["6379:6379"]
  nacos:
    image: nacos/nacos-server:v2.3.2
    ports: ["8848:8848"]
    environment:
      MODE: standalone

启动顺序建议为：中间件 → Nacos → 网关 → 各业务服务。每个服务在 application-local.yml 中配置本地数据库、Redis 与 Nacos 地址，通过 --spring.profiles.active=local 激活。验证环境是否就绪，可访问 Nacos 控制台查看服务列表，再调用网关健康检查接口 /actuator/health，返回 {"status":"UP"} 即表示本地链路基本可用。

完成上述结构后，团队应形成一份可执行的“工程基线”：父工程版本锁定、公共模块可复用、包结构统一、本地环境可一键拉起。后续新增检验检查、随访、药房等服务时，只需复制业务模块骨架并接入父工程，即可保持依赖、规范与启动方式一致，为医疗微服务的持续演进打下稳定基础。