创建 SpringCloud 服务模块

王金城大约 7 分钟

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

创建新模块

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

新建模块

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

新建模块面板

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

修改 pom 配置

修复父工程版本号

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

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

添加程序版本号

<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>
  <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>

创建项目配置文件

application.yml 是项目配置文件，jar 包内唯一的配置文件。如：MyBatis 配置信息、分页插件配置信息、时间格式化配置等。

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

server:
  port: 8005
  error:
    include-stacktrace: never # 关闭 spring boot 从接口中返回堆栈信息
  http2:
    enabled: true
  max-http-request-header-size: 32KB
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}
  config:
    import:
      - nacos:core.yaml?refreshEnabled=true
      - nacos:datasource.yaml?refreshEnabled=false
      - nacos:redis.yaml?refreshEnabled=false
      - nacos:file.yaml?refreshEnabled=true
      - nacos:jwt.yaml?refreshEnabled=true
      - nacos:${spring.application.name}.yaml?refreshEnabled=true
  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
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
logging:
  file:
    path: @logging.filePath@ # 日志文件输出路径，请配置物理磁盘，防止日志写入延迟导致程序卡顿
    bak-path: @logging.fileBakPath@ # 日志文件备份路径，可以配置网盘路径，用于备份使用
    name: ${logging.file.path}/${spring.application.name}.log # 日志的名称，非必要请勿修改
  charset:
    console: UTF-8 # 日志控制台输出编码，非必要请勿修改
    file: UTF-8 # 日志文件编码，非必要请勿修改
  logback:
    rollingpolicy:
      file-name-pattern: ${logging.file.bak-path}/${spring.application.name}/${HOSTNAME}/%d{yyyy-MM-dd}/${spring.application.name}.%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 # 日期格式化，请勿修改

在 Nacos 中创建配置文件

填写 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>

创建安装包启动脚本和配置文件

在 resource 下创建 build-resource 目录
在 build-resource 目录下分别创建 bin 和 conf 目录

bin 目录中的 start-应用名.sh 文件

#!/bin/bash

# 该脚本通常位于和当前脚本同一目录的 env.sh 文件中。
# 里面记录着通用的变量， 比如 JAVA、NACOS_SERVER_ADDR、NACOS_NAMESPACE、LOGGING_PATH 等。
source "$(dirname "$0")"/env.sh

startupApp "@project.build.finalName@.jar" "@project.artifactId@.conf"

bin 目录中的 start-应用名.bat 文件

@echo off
chcp 65001

setlocal

title @project.build.finalName@.jar

call "%~dp0env.bat" start @project.build.finalName@.jar @project.artifactId@.conf

bin 目录中的 shutdown-应用名.sh 文件

#!/bin/bash

# 该脚本通常位于和当前脚本同一目录的 env.sh 文件中。
# 里面记录着通用的变量， 比如 JAVA、NACOS_SERVER_ADDR、NACOS_NAMESPACE、LOGGING_PATH 等。
source "$(dirname "$0")"/env.sh

shutdownApp "@project.build.finalName@.jar"

bin 目录中的 shutdown-应用名.bat 文件

@echo off
chcp 65001

setlocal

call "%~dp0env.bat" stop @project.build.finalName@.jar

conf 目录中的 应用名.conf

# 启动端口号
server.port=修改为真实的端口
# JAVA_OPTS 参数，一般用于设置内存大小
java.opts=@env.java.opts@

在 IDEA 中配置启动类

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