304 lines
12 KiB
Markdown
304 lines
12 KiB
Markdown
## 任务名称: 创建spring boot初始项目
|
||
### 目标
|
||
- 通过spring start创建一个spring boot项目,选择依赖spring web, h2, mysql, jpa, lombok
|
||
- 添加依赖: springdoc openapi
|
||
- 添加配置文件: application.yml
|
||
- 配置JPA、H2数据库、springdoc openapi、logging
|
||
- 将项目提交到Gitea
|
||
### 预备知识
|
||
- 项目构建工具gradle
|
||
- spring boot框架项目基本目录结构和默认配置文件
|
||
- yaml配置文件
|
||
- git操作
|
||
|
||
### 操作步骤
|
||
#### 1、使用Spring Initializr创建一个Spring Boot项目。
|
||
|
||
在浏览器中访问：https://start.spring.io/
|
||
|
||
在页面上选择以下选项：
|
||
- 选择gradle 构建工具
|
||
- 选择java开发语言
|
||
- 选择Spring Boot版本
|
||
- 选择Java版本
|
||
- 选择依赖：spring web, h2, mysql, jpa,lombok
|
||
- 点击Generate
|
||
- 下载生成的项目，解压到本地。
|
||
|
||
|
||
|
||
|
||
|
||
#### 2、将生成项目中的所有文件和目录拷贝到自己的GIT项目中。
|
||
|
||
#### 3、开发工具IDEA的基本配置
|
||
|
||
- 在idea中打开项目，设置项目使用的jdk版本为17。设置gradle的JDK版本为17。
|
||
|
||
#### 4、构建工具Gradle的相关配置
|
||
|
||
- **使用国内的下载地址，提高下载gradle的速度**
|
||
|
||
修改gradle/wrapper/gradle-wrapper.properties文件，将distributionUrl的值修改为：
|
||
```text
|
||
https:\//mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip
|
||
```
|
||
|
||
|
||
- **修改build.gradle文件中的repositories,设置gradle使用国内镜像**
|
||
|
||
```groovy
|
||
repositories {
|
||
mavenLocal()
|
||
maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }
|
||
maven { url 'https://maven.aliyun.com/repository/central' }
|
||
maven { url 'https://maven.aliyun.com/repository/public' }
|
||
mavenCentral()
|
||
}
|
||
```
|
||
- **重新加载gradle项目**
|
||
|
||
|
||
等待gradle将所有依赖加载完成.
|
||
|
||
#### 5、项目的相关配置
|
||
|
||
- 在目录src/main/resources下新建空文件application.yml文件用作项目的主要配置文件。
|
||
|
||
> Spring Boot的默认配置文件是`application.properties`或`application.yml`。这两个文件中的任何一个都可以作为默认配置文件使用，具体取决于项目中存在哪个或者个人偏好。
|
||
> `application.properties`更传统,适合不熟悉键值对的配置风格，而`application.yml`则采用更简洁的yaml格式，便于层次结构化数据表达。
|
||
>
|
||
> Spring Boot在启动时会自动查找以下位置的这些配置文件：
|
||
>
|
||
> > 项目根目录下的config文件夹：file:./config/
|
||
> >
|
||
> > 项目根目录本身：file:./
|
||
> >
|
||
> > 类路径下的config文件夹：classpath:/config/
|
||
> >
|
||
> > 类路径根目录：classpath:/
|
||
>
|
||
> 这些位置的优先级从高到低排列，意味着如果在同一位置有多个配置文件或不同位置有相同的配置设置，高优先级的配置将会覆盖低优先级的配置。
|
||
>
|
||
>
|
||
> 放置在src/main/resources下面的配置文件属于类路径根目录类别，即classpath:/。
|
||
> 如果你将application.properties或application.yml直接放在src/main/resources目录下，Spring Boot 启动时会自动加载这些配置文件。
|
||
> 这是最常见也是推荐的放置配置文件的位置，因为这样的配置文件会随着项目的构建被包含进最终的可执行文件（如JAR包）中。
|
||
|
||
- 集成springdoc openapi
|
||
|
||
> springdoc openapi可快速为spring boot项目生成规范的 API 文档。
|
||
|
||
在build.gradle的dependencies中添加依赖：
|
||
```groovy
|
||
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
|
||
```
|
||
|
||
在application.yml中添加配置,设置swagger-ui的访问路径：
|
||
```yaml
|
||
springdoc:
|
||
swagger-ui:
|
||
path: /api-docs
|
||
```
|
||
|
||
- 配置项目日志
|
||
|
||
> spring boot中配置日志可以在application.yml/application.properties中配置。也可以使用单独的配置文件logback.xml来配置。
|
||
|
||
在src/main/resources下新建一个名为`logback.xml`的文件，内容如下：
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<configuration debug="false">
|
||
<!--定义日志文件的存储地址 勿在 LogBack 的配置中使用相对路径-->
|
||
<!--log.path为环境变量，如果环境变量不存在，则使用./当前目录-->
|
||
<property name="LOG_HOME" value="${log.path:-./}" />
|
||
<!-- 控制台输出 -->
|
||
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
|
||
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
|
||
<!--格式化输出：%d表示日期，%thread表示线程名，%-5level：级别从左显示5个字符宽度%msg：日志消息，%n是换行符-->
|
||
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
|
||
</encoder>
|
||
</appender>
|
||
<!-- 按照每天生成日志文件 -->
|
||
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
|
||
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
|
||
<!--日志文件输出的文件名-->
|
||
<FileNamePattern>${LOG_HOME}/log.%d{yyyy-MM-dd}.log</FileNamePattern>
|
||
<!--日志文件保留天数-->
|
||
<MaxHistory>30</MaxHistory>
|
||
</rollingPolicy>
|
||
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
|
||
<!--格式化输出：%d表示日期，%thread表示线程名，%-5level：级别从左显示5个字符宽度%msg：日志消息，%n是换行符-->
|
||
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
|
||
</encoder>
|
||
<!--日志文件最大的大小-->
|
||
<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
|
||
<MaxFileSize>10MB</MaxFileSize>
|
||
</triggeringPolicy>
|
||
</appender>
|
||
|
||
<!--根据指定的包名设置开关级别-->
|
||
<logger name="com.lk.paopao" level="DEBUG"/>
|
||
<logger name="org.springframework.web.servlet" level="DEBUG"/>
|
||
|
||
<root level="INFO">
|
||
<appender-ref ref="STDOUT" />
|
||
<appender-ref ref="FILE" />
|
||
</root>
|
||
</configuration>
|
||
|
||
```
|
||
|
||
- **JSON配置项**
|
||
|
||
在`application.yml`中添加配置,设置JSON的属性命名策略为SNAKE_CASE：
|
||
|
||
```yaml
|
||
spring:
|
||
jackson:
|
||
property-naming-strategy: SNAKE_CASE # 驼峰转下划线
|
||
```
|
||
|
||
在Spring Boot应用中，可以通过`spring.jackson`命名空间下的配置项来定制Jackson库的行为，以适应不同的JSON序列化和反序列化需求。以下是一些关键的配置项示例及其功能：
|
||
|
||
> **默认属性包含策略**:
|
||
- `spring.jackson.default-property-inclusion`: 控制哪些属性会被序列化到JSON中，可选值包括`ALWAYS`, `NON_NULL`, `NON_EMPTY`, `USE_DEFAULTS`, `NON_ABSENT`, 和 `CUSTOM`。例如，设置为`NON_NULL`可避免null值的字段出现在JSON输出中。
|
||
> **日期格式化**:
|
||
- `spring.jackson.date-format`: 允许配置日期格式字符串，或者指定一个日期格式化类的全限定名，如使用`java.text.SimpleDateFormat`的格式。
|
||
- `spring.jackson.time-zone`: 设置日期时间序列化和反序列化时使用的时区。
|
||
|
||
> **缩进和美化输出**:
|
||
- `spring.jackson.serialization.indent-output`: 布尔值，决定是否在输出的JSON中加入缩进以美化格式，默认为`false`。
|
||
|
||
> **时间戳格式**:
|
||
- `spring.jackson.serialization.write-dates-as-timestamps`: 决定日期是否应该被序列化为时间戳（毫秒数）而不是字符串格式，默认为`true`。
|
||
|
||
> **未知属性处理**:
|
||
- `spring.jackson.deserialization.fail-on-unknown-properties`: 当JSON中包含Java对象模型中不存在的属性时，决定是否抛出异常，默认为`false`意味着忽略未知属性。
|
||
|
||
> **属性命名策略**:
|
||
- `spring.jackson.property-naming-strategy`: 可以设置属性命名策略，如`LOWER_CAMEL_CASE`, `UPPER_CAMEL_CASE`, `KEBAB_CASE`, `SNAKE_CASE`, 或自定义实现的全限定名。
|
||
|
||
> **特性包含与忽略**:
|
||
- 可以通过特定的配置来控制Jackson的特性，比如`spring.jackson.features.*`，这里`*`代表Jackson中的特性标识，例如`FAIL_ON_UNKNOWN_PROPERTIES`等。
|
||
|
||
> **自定义ObjectMapper**:
|
||
- 如果上述配置不能满足需求，可以通过定义一个`ObjectMapper` Bean来实现更复杂的自定义配置。
|
||
|
||
请注意，实际可用的配置项可能依据Spring Boot的版本不同而有所差异，建议查阅对应版本的官方文档以获取最新和最准确的配置信息。
|
||
|
||
|
||
|
||
#### 6、配置h2数据库和JPA
|
||
|
||
项目使用h2数据库作为默认的数据库，并使用JPA作为ORM框架。
|
||
|
||
- 在application.yml中添加配置：
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
url: jdbc:h2:file:./paopao.h2 # 使用文件存储
|
||
driverClassName: org.h2.Driver
|
||
username: root
|
||
password: root
|
||
h2:
|
||
console: # 开启console访问 默认false
|
||
enabled: true
|
||
settings:
|
||
trace: true # 开启h2 console 跟踪 方便调试 默认 false
|
||
web-allow-others: true # 允许console 远程访问 默认false
|
||
path: /h2 # h2 访问路径上下文
|
||
jpa:
|
||
show-sql: true
|
||
open-in-view: false
|
||
defer-datasource-initialization: true
|
||
database-platform: org.hibernate.dialect.H2Dialect
|
||
hibernate:
|
||
ddl-auto: create-drop
|
||
# 可选值：create-drop,create,update,none. create-drop：每次启动项目都会删除表，然后重新创建表，适合开发环境；create：每次启动项目都会创建表，适合开发环境；update：每次启动项目都会更新表，适合开发环境；none：不执行任何操作，适合生产环境。
|
||
properties:
|
||
hibernate:
|
||
format_sql: true
|
||
```
|
||
|
||
#### 7. 项目java包结构设计
|
||
创建包：controller、entity、repository、service、excepiton、security、dto、 dto.rest.response、dto.rest.request
|
||
|
||
- controller：控制器，处理请求，调用service层进行业务处理。
|
||
- entity：实体类，对应数据库中的表。
|
||
- repository：数据访问层，使用JPA进行数据访问。
|
||
- service：业务层，调用repository层进行数据访问。
|
||
- exception：异常处理类，处理业务异常。
|
||
- security：安全配置类，用于配置用户认证、授权等。
|
||
- dto：数据传输对象，用于封装请求参数和响应结果。
|
||
- dto.rest.response：响应结果数据传输对象，用于封装响应结果。
|
||
- dto.rest.request：请求参数数据传输对象，用于封装请求参数。
|
||
|
||
#### 8. 认识spring boot的启动类
|
||
|
||
在spring initializr创建的项目中，自动创建了系统的入口类：`PaopaoApplication`，代码如下：
|
||
|
||
```java
|
||
package com.lk.paopao;
|
||
|
||
import org.springframework.boot.SpringApplication;
|
||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||
|
||
@SpringBootApplication
|
||
public class PaopaoApplication {
|
||
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(PaopaoApplication.class, args);
|
||
}
|
||
}
|
||
|
||
```
|
||
**代码解释：**
|
||
- @SpringBootApplication: 这个注解在启动类PaopaoApplication上方，表明这是一个Spring Boot应用程序的入口，并且开启了自动配置和组件扫描。
|
||
|
||
- SpringApplication.run(PaopaoApplication.class, args): 调用SpringApplication的run方法来启动Spring Boot应用程序。PaopaoApplication.class作为参数传入，表示启动这个类，args是传递给main方法的参数数组。
|
||
|
||
|
||
#### 9、运行系统
|
||
|
||
- **运行方式1：**使用gradle的任务 `bootRun`运行项目,在控制台可以看到spring boot项目启动成功的信息，并生成了openapi文档。
|
||
|
||
openapi文档访问地址: http://localhost:8080/api-docs
|
||
|
||
|
||
|
||
- **运行方式2：** 在idea中运行项目，在控制台可以看到spring boot项目启动成功，并生成了openapi文档。
|
||
|
||
在项目的入口类上右键，在右键菜单中选择 "Run ..."
|
||
|
||
#### 10、将项目中新添加文件同步到Gitea上的对应仓库
|
||
|
||
- 可在idea的控制台中依次执行命令:
|
||
```shell
|
||
git add .
|
||
git commit -m "init project"
|
||
git push origin master
|
||
```
|
||
- 或在idea中使用git菜单，依次完成 add、commit、push
|
||
|
||
|
||
### 技术/工具需求
|
||
- intellij idea 社区版 2023 及以上
|
||
- gradle 8.5及及上
|
||
- spring boot 3.2.3以上
|
||
- jdk 17 及以上
|
||
|
||
### 成功标准
|
||
- 项目可正常运行，无错误
|
||
- 可访问openapi文档 http://localhost:8080/api-docs
|
||
- 项目代码提交到Gitea上
|
||
|
||
### 扩展学习(可选)
|
||
- [提供一些额外学习资源或挑战性任务，鼓励学有余力的学生进一步探索。]
|
||
|
||
### 评估与反馈
|
||
- [说明如何提交作业、代码审查的标准、或任何反馈收集机制。]
|
||
|
||
### 时间估算
|
||
- [给出预计完成该任务所需的时间，帮助学生合理安排学习计划。] |