paopao/docs/tasks/创建spring boot初始项目.md

### 任务名称: 创建spring boot初始项目
#### 目标
- 通过spring starter创建一个spring boot项目,选择依赖spring web, h2, mysql, jpa, lombok
- 添加依赖: springdoc openapi
- 添加配置文件: application.yml
- 配置JPA、H2数据库、springdoc openapi、logging
#### 预备知识
- 项目构建工具gradle
- spring boot框架项目结构和配置文件

#### 操作步骤
1、使用Spring Initializr创建一个Spring Boot项目。

在浏览器中访问：https://start.spring.io/

在页面上选择以下选项：
- 选择gradle 构建工具 
- 选择java开发语言
- 选择Spring Boot版本
- 选择Java版本
- 选择依赖：spring web, h2, mysql, jpa,lombok
- 点击Generate
- 下载生成的项目，解压到本地。

![](./images/spring-boot-start.png)

2、将生成项目中的所有文件和目录拷贝到自己的GIT项目中。

3、开发工具IDEA的基本配置

- 在idea中打开项目，设置项目使用的jdk版本为17。设置gradle的JDK版本为17。

4、构建工具Gradle的相关配置

- 修改gradle/wrapper/gradle-wrapper.properties文件，将distributionUrl的值修改为：
```text
https:\//mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip
```
使用国内的下载地址，提高下载gradle的速度

- 修改gradle.properties文件,设置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项目
![](./images/gradle-reload.png)
等待gralde将所有依赖加载完成.

5、项目的相关配置

- 在目录src/main/resources下新建application.yml文件用作项目的主要配置文件。

- 集成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.demo" level="DEBUG"/>
    <logger name="org.springframework.web.servlet" level="INFO"/>

    <root level="WARN">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>
</configuration>

```
6、配置h2数据库和JPA

- 在application.yml中添加配置：

```yaml
spring:

  datasource:
    url: jdbc:h2:file:./paopao.h2
    driverClassName: org.h2.Driver
    username: root
    password: root
#    initialization-mode: always
  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: update # update create-drop
    properties:
      hibernate:
        format_sql: true
        dialect: org.hibernate.dialect.H2Dialect
```


7、运行项目

- 使用gradle的任务 `bootRun`运行项目,在控制台可以看到spring boot项目启动成功的信息，并生成了openapi文档。

openapi文档访问地址: http://localhost:8080/api-docs

![](./images/spring-openapi.png)

- 在idea中运行项目，在控制台可以看到spring boot项目启动成功，并生成了openapi文档。

在项目的入口类上右键，在右键菜单中选择 "Run ..." 



#### 技术/工具需求
- intellij idea 社区版 2023 及以上
- gradle 8.5及及上
- spring boot 3.2.3以上
- jdk 17 及以上

#### 成功标准
- [明确完成任务的评判标准，如代码功能实现、性能指标、测试通过条件等。]

#### 扩展学习(可选)
- [提供一些额外学习资源或挑战性任务，鼓励学有余力的学生进一步探索。]

#### 评估与反馈
- [说明如何提交作业、代码审查的标准、或任何反馈收集机制。]

#### 时间估算
- [给出预计完成该任务所需的时间，帮助学生合理安排学习计划。]