创建 SpringCloud 服务模块

王金城大约 7 分钟

后端项目为 SpringCloud 框架，在开发新的模块时需要按照以下步骤完成创建。

创建新模块

右键点击项目跟目录 basic-paper-cloud
选择 新建 => 新模块 打开新模块配置面板

新建模块

填写项目名称，均以 basic-paper 开头，后面跟模块名。例：工单模块 basic-paper-ticket
确认存储路径是否正确，应该在 basic-paper-cloud 目录下
语言选择 Java
构建系统选择 Maven
JDK 选择项目 SDK，即：JDK 21
父项选择 basic-paper-cloud
取消 添加示例代码
展开 高级设置
修改组 ID 我们统一修改为 com.simperfect.bp
确认工件 ID 是否与项目名相同
点击确认创建新模块

新建模块面板

删除项目中无用的文件，如：.gitignore

修改 pom 配置

修复父工程版本号

将 IDE 自动生成的版本号替换为变量 ${revision}，这样可以保证始终与父工程版本一致。

<parent>
  <groupId>com.simperfect.bp</groupId>
  <artifactId>basic-paper-cloud</artifactId>
  <version>${revision}</version>
</parent>

添加程序版本号

<groupId>com.simperfect.bp.ticket</groupId>
<artifactId>basic-paper-ticket</artifactId>
<version>1.0.0</version>

添加 Java 版本号

<properties>
  <java.version>21</java.version>
  <maven.compiler.source>${java.version}</maven.compiler.source>
  <maven.compiler.target>${java.version}</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

添加所需依赖

下面只是列举出多数模块需要的依赖，可以根据模块功能酌情添加与修改。详情可以查看父工程 pom 的注释信息。

提示

所有依赖均无需添加版本号，继承父 pom 的版本

<dependencies>
  <!-- 注册中心 -->
  <dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
  </dependency>
  <!-- 配置中心 -->
  <dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
  </dependency>
  <!-- 需要使用注册中心和配置中心一定要引入 nacos client -->
  <dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
  </dependency>
  <!-- spring cloud 引导程序，使 bootstrap.yml 生效 -->
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
  </dependency>

  <!-- 二方库 -->
  <dependency>
    <groupId>com.simperfect.commons</groupId>
    <artifactId>simperfect-dynamic-datasource</artifactId>
  </dependency>
  <dependency>
    <groupId>com.simperfect.commons</groupId>
    <artifactId>simperfect-dynamic-redis</artifactId>
  </dependency>
  <!-- 通用 web 工具类，包含异常拦截器 -->
  <dependency>
    <groupId>com.simperfect.commons</groupId>
    <artifactId>simperfect-commons-web</artifactId>
  </dependency>
  <!-- 用户信息工具类 -->
  <dependency>
    <groupId>com.simperfect.commons</groupId>
    <artifactId>simperfect-user-details</artifactId>
  </dependency>
  <!-- 缓存工具类 -->
  <dependency>
    <groupId>com.simperfect.commons</groupId>
    <artifactId>simperfect-dynamic-cache</artifactId>
  </dependency>
  <!-- MySQL驱动 -->
  <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
  </dependency>
  <!-- SqlServer 驱动 -->
  <dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <scope>runtime</scope>
  </dependency>
  <!-- 通用 pojo -->
  <dependency>
    <groupId>com.simperfect.bp</groupId>
    <artifactId>basic-paper-pojo</artifactId>
  </dependency>

  <!-- 数据源相关 -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
  </dependency>
  <dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <scope>runtime</scope>
  </dependency>
  <dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-spring-boot-starter</artifactId>
  </dependency>
</dependencies>

创建启动类

创建包路径为 com.simperfect.bp.模块名。例： com.simperfect.bp.ticket。
创建 BasicPaper${模块名}Application 类。例：BasicPaperTicketApplication
如果使用通用缓存模块需要在 @MapperScan 中添加 com.simperfect.commons.cache.dao

package com.simperfect.bp.ticket;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.context.annotation.ComponentScan;
import tk.mybatis.spring.annotation.MapperScan;

/**
 * @author 王金城
 * @date 2023/6/15
 **/
@SpringBootApplication
@EnableDiscoveryClient
@ComponentScan("com.simperfect.*")
@MapperScan(basePackages = {"com.simperfect.bp.ticket.dao", "com.simperfect.commons.cache.dao"})
public class BasicPaperTicketApplication {
    public static void main(String[] args) {
        SpringApplication.run(BasicPaperTicketApplication.class, args);
    }
}

配置 JAR 插件启动类

在 pom.xml 最下方加入以下内容

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <configuration>
        <archive>
          <manifest>
            <mainClass>com.simperfect.bp.ticket.BasicPaperTicketApplication</mainClass>
          </manifest>
        </archive>
      </configuration>
    </plugin>
  </plugins>
</build>

创建引导配置文件

bootstrap.yml 是 spring cloud 引导配置文件，系统参数都会配置在这里。包括：端口号、注册中心、配置中心、分布式事务、日志等配置信息。

在 resources 目录下创建 bootstrap.yml，写入以下内容

提示

公共配置文件 shared-configs 根据实际情况引入所需的配置文件，配置中心中配置文件详解

server:
  port: 8005
spring:
  application:
    name: basic-paper-ticket # 应用名
  cloud:
    nacos:
      server-addr: @nacos.addr@
      namespace: @nacos.namespace@
      username: @nacos.username@
      password: @nacos.password@
      discovery:
        server-addr: ${spring.cloud.nacos.server-addr} # 注册中心地址
        namespace: ${spring.cloud.nacos.namespace} # 命名空间，用于注册中心、配置中心的数据隔离（在同一个注册中心负责多个环境时极其重要），只读取此命名空间下的配置文件。
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}
        namespace: ${spring.cloud.nacos.discovery.namespace}
        file-extension: yaml
        shared-configs:
          - data-id: datasource.yaml # 导入通用数据源配置文件
            refresh: false
          - data-id: redis.yaml # 导入通用 redis 配置文件
            refresh: false
          - data-id: file.yaml # 导入通用文件配置文件
            refresh: true
          - data-id: jwt.yaml # 导入通用 jwt 配置文件
            refresh: true
logging:
  file:
    path: @logging.filePath@ # 日志文件输出路径，请配置物理磁盘，防止日志写入延迟导致程序卡顿
    bak-path: @logging.fileBakPath@ # 日志文件备份路径，可以配置网盘路径，用于备份使用
    name: ${logging.file.path}/bp_sso.log # 日志的名称，非必要请勿修改
  charset:
    console: UTF-8 # 日志控制台输出编码，非必要请勿修改
    file: UTF-8 # 日志文件编码，非必要请勿修改
  logback:
    rollingpolicy:
      file-name-pattern: ${logging.file.bak-path}/bp_sso/${HOSTNAME}/%d{yyyy-MM-dd}/bp_sso.%d{yyyy-MM-dd}.%i.log.gz # 日志备份完整路径，非必要请勿修改
      max-file-size: 50MB # 每个日志文件最大大小，非必要请勿修改
      clean-history-on-start: true # 是否清理日志，非必要请勿修改
      max-history: 180 # 日志留存数量，由于按照日期存储的日志，所以这里可以理解为日志留存时间
  pattern:
    dateformat: yyyy-MM-dd HH:mm:ss.SSSXXX # 日期格式化，请勿修改

创建项目配置文件

application.yml 是项目配置文件，一般配置项目的默认配置（几乎不用修改的配置，其他配置参数放在配置中心）。如：MyBatis 配置信息、分页插件配置信息、时间格式化配置等。

在 resources 目录下创建 application.yml，写入以下内容

server:
  error:
    include-stacktrace: never # 关闭 spring boot 从接口中返回堆栈信息
  http2:
    enabled: true
  max-http-request-header-size: 32KB
simperfect:
  redis:
    redis-prefix: 'bp:ticket:' # redis 存储前缀，每个模块的值固定为模块名
mybatis:
  configuration:
    map-underscore-to-camel-case: true # 下划线自动转换为驼峰
    jdbc-type-for-null: null
pagehelper:
  reasonable: true # 是否启用分页合理化;如果启用，当pageNum<1时，会自动查询第一页的数据，当pageNum>pages时，自动查询最后一页数据；
  use-sqlserver2012: true # 当使用 SqlServer 数据库时使用 SqlServer2012 数据库分页方式
  count-column: '*' # 用于配置自动 count 查询时的查询列，默认值0，也就是 count(0)，Page 对象也新增了 countColumn 参数，可以针对具体查询进行配置。
mapper:
  resolve-class: com.simperfect.commons.mapper.resolve.JakartaEntityResolve # 配置解析器为我们自定义的解析器，使其支持 Jakarta API
# 默认时间格式
spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
  mvc:
    format:
      date-time: yyyy-MM-dd HH:mm:ss
      date: yyyy-MM-dd
      time: HH:mm:ss

在 Nacos 中创建配置文件

提示

在 Nacos Spring Cloud 中，dataId 的完整格式如下：

${prefix}-${spring.profiles.active}.${file-extension}

prefix 默认为 spring.application.name 的值，也可以通过配置项 spring.cloud.nacos.config.prefix 来配置。
spring.profiles.active 即为当前环境对应的 profile，详情可以参考 Spring Boot 文档。注意：当 spring.profiles.active 为空时，对应的连接符 - 也将不存在，dataId 的拼接格式变成 ${prefix}.${file-extension}
file-extension 为配置内容的数据格式，可以通过配置项 spring.cloud.nacos.config.file-extension 来配置。目前只支持 properties 和 yaml 类型。

填写 Data ID 为应用名，即：spring.application.name 的名字
填写 Group 固定为 DEFAULT_GROUP，因为我选中使用命名空间来区分配置。
配置格式选择 YAML
填写配置，如下示例：

simperfect:
  example: '样例配置'

添加全局异常捕获

直接引入 simperfect-commons-web 模块即可，如果你是复制添加所需依赖内容，那么里面已经存在这个依赖。

<!-- 通用 web 工具类，包含异常拦截器 -->
<dependency>
  <groupId>com.simperfect.commons</groupId>
  <artifactId>simperfect-commons-web</artifactId>
</dependency>

在 IDEA 中配置启动类

右键点击 BasicPaperTicketApplication 类左侧三角入编辑配置选项，添加 spring boot devtools 端口配置。