第3章开发环境搭建

3. 开发环境搭建：工单管理系统的地基工程

说实话，做MES工单管理开发，最怕什么？最怕项目还没开始写业务代码，光搭环境就折腾一整天。我见过太多新手在Spring Boot版本冲突、MyBatis Plus配置、数据库连接池这些地方卡住。今天咱们就把这些基础工作一次性搞定，后面写业务代码才能行云流水。

本章核心目标：搭建一个可直接运行的Spring Boot项目，集成MyBatis Plus、MySQL、Swagger，为工单CRUD操作打下坚实基础。

3.1 Spring Boot项目初始化——选对版本很重要

我个人习惯用 Spring Initializr（start.spring.io）来生成项目骨架。为什么不用IDE自带的？因为网页版能直观看到依赖版本，避免踩坑。

这里有个经验：Spring Boot 2.7.x 系列是目前MES项目最稳妥的选择。3.0以上版本虽然新，但很多老牌MES中间件（比如某些报表引擎）还没完全适配。我在一个项目中就吃过这个亏——升级到3.1后，发现公司自研的工单打印组件不兼容，回退花了半天。

选好以下依赖：

Spring Web —— 提供RESTful API能力
Spring Boot DevTools —— 热部署，开发必备
Lombok —— 减少getter/setter模板代码
MySQL Driver —— 数据库连接
Spring Configuration Processor —— 配置文件智能提示

生成后解压，用IDEA打开。嗯，这里要注意：pom.xml里的parent版本号，一定要确认是2.7.x。我曾经遇到过同事直接用了3.0.0，结果MyBatis Plus的自动配置失效，排查了一下午才发现是版本不匹配。

3.2 MyBatis Plus配置——少写80%的SQL

做MES工单管理，数据操作量非常大。工单创建、状态流转、工序报工……如果每个都手写SQL，那得累死。MyBatis Plus就是来解决这个问题的。

在pom.xml里加入：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>

为什么选3.5.3.1？因为这是目前最稳定的版本，支持Lambda查询，而且分页插件配置简单。我之前用过3.4.x，分页插件需要手动注入Bean，3.5.x直接自动配置了，省事不少。

配置application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mes_workorder?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    map-underscore-to-camel-case: true

小技巧：开发阶段一定要开启 log-impl: StdOutImpl，这样控制台会打印每一条SQL。调试工单查询时，你能直观看到MyBatis Plus生成的SQL对不对。上线前记得关掉，否则日志会爆炸。

再配置分页插件（这是MES工单列表查询的刚需）：

@Configuration
public class MyBatisPlusConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

说白了，有了这个配置，你写工单分页查询时，只需要调用 page() 方法，MyBatis Plus自动帮你算总数、分页、排序。我在做工单列表接口时，10分钟就搞定了分页逻辑。

3.3 MySQL数据库连接——字符集和时区是隐形炸弹

数据库连接看似简单，但有两个坑我必须要说：

字符集问题：工单描述里可能有中文、特殊符号（比如产品型号带®标记）。如果数据库字符集不是utf8mb4，存进去就会变成乱码。我曾经排查过一个工单描述显示为"????"的问题，最后发现是建库时用了默认的latin1。
时区问题：MES系统通常跨车间、跨工厂，工单的创建时间、计划时间必须统一时区。建议在连接URL里强制指定 serverTimezone=Asia/Shanghai，避免服务器时区不一致导致时间错乱。

建库SQL示例：

CREATE DATABASE mes_workorder 
  DEFAULT CHARACTER SET utf8mb4 
  DEFAULT COLLATE utf8mb4_unicode_ci;

连接池推荐用 HikariCP（Spring Boot 2.x默认就是它）。性能好，配置简单。我一般只调两个参数：

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

为什么是20？因为MES工单模块的并发量通常不会太高（车间工人同时操作的数量有限），20个连接足够应对日常操作。设太大反而浪费数据库资源。

3.4 Swagger接口文档集成——让前端和后端少吵架

做MES工单接口开发，最烦的就是前端跑来问：「这个工单创建接口的参数是什么格式？」「状态字段传数字还是字符串？」有了Swagger，这些问题迎刃而解。

集成Swagger 3（OpenAPI 3.0规范）：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置Swagger：

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mes.workorder.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("MES工单管理模块 API文档")
                .description("涵盖工单创建、查询、状态流转、报工等接口")
                .version("1.0.0")
                .build();
    }
}

避坑指南：我曾经在Spring Boot 2.6.x版本集成Swagger 3时，遇到启动报错 Failed to start bean 'documentationPluginsBootstrapper'。原因是Spring Boot 2.6.x默认开启了路径匹配策略，和Swagger冲突。解决方案是在application.yml里加一行：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

这个坑我踩过，所以提前告诉你。

启动项目后，访问 http://localhost:8080/swagger-ui/index.html，就能看到工单接口的在线文档。你想想看，前端同事直接在这里测试接口，不用你每次手动写调用示例，是不是省了很多沟通成本？

3.5 本章知识体系总览

下面这张图，是我梳理的工单管理模块开发环境的核心架构。你看一眼，就能明白各个组件之间的关系：

这张图展示了我们搭建的完整技术栈：Spring Boot 作为底座，MyBatis Plus 负责数据操作，MySQL 存储工单数据，Swagger 暴露接口文档。四者配合，工单管理模块的开发环境就稳了。

3.6 验证环境是否搭建成功

环境搭完，怎么确认没问题？我一般做三步验证：

启动项目：控制台看到 Started Application in X.XXX seconds，没有红色报错。
访问Swagger：浏览器打开 http://localhost:8080/swagger-ui/index.html，能看到API文档页面。
写一个测试接口：创建一个简单的Controller，返回 "工单服务已启动"，确认接口能正常调用。

我的习惯：在项目根目录放一个 init.sql 文件，里面写好建表语句和测试数据。这样新同事加入时，直接执行这个文件就能把数据库环境拉起来，不用一个个问表结构。工单模块的表结构我后面会详细讲，但初始化脚本建议现在就准备好。

好了，环境搭建就到这里。记住：基础不牢，地动山摇。花半小时把环境配好，后面写工单业务代码时，你会感谢现在的自己。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

3. 开发环境搭建：工单管理系统的地基工程

3.1 Spring Boot项目初始化——选对版本很重要

3.2 MyBatis Plus配置——少写80%的SQL

3.3 MySQL数据库连接——字符集和时区是隐形炸弹

3.4 Swagger接口文档集成——让前端和后端少吵架

3.5 本章知识体系总览

3.6 验证环境是否搭建成功