paopao/docs/tasks/任务3-Sprint-1-创建spring boot初始项目.md

## 任务名称: 创建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
- 下载生成的项目，解压到本地。

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



#### 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项目**
![](./images/gradle-reload.png)

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

```
#### 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、运行项目

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

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

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

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

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

#### 9、将项目中新添加文件同步到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上

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

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

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