SpringBoot项目工具安装及项目搭建

一、开发环境准备

1.1 安装 JDK（必需）

Spring Boot 3.x 系列要求 JDK 17 或更高版本，最高可支持到 Java 23。建议安装 JDK 21 LTS（长期支持版本），兼顾稳定性与新特性。

1. 访问 Oracle JDK 下载页 或 OpenJDK 下载页，选择对应操作系统的 JDK 21 安装包。

2. 安装完成后，配置系统环境变量：

   • Windows：设置 JAVA_HOME 为 JDK 安装路径，并将 %JAVA_HOME%\bin 添加到 Path 变量。

   • macOS/Linux：在 ~/.bashrc 或 ~/.zshrc 中添加 export JAVA_HOME=/path/to/jdk 和 export PATH=$JAVA_HOME/bin:$PATH。

3. 验证安装：

   bash

   java -version
   # 输出应包含 java version "21" 或更高版本

1.2 安装 Maven（构建工具）

Spring Boot 项目通常使用 Maven 或 Gradle 进行构建和管理。本指南以 Maven 为例。

1. 访问 Maven 官网，下载最新稳定版的二进制压缩包。

2. 解压到本地目录，并配置环境变量 MAVEN_HOME，将 %MAVEN_HOME%\bin 添加到 Path。

3. 验证安装：

   bash

   mvn -v
   # 输出应显示 Maven 版本及使用的 Java 版本

1.3 安装 IDE（推荐 IntelliJ IDEA）

IntelliJ IDEA 对 Spring Boot 有着最完善的支持。

• Ultimate（旗舰版）：内置 Spring 模块，功能最全，推荐使用。

• Community（社区版）：免费，但缺少部分 Spring 相关特性，可通过安装插件弥补。

1.4 必装 IDEA 插件

在 IntelliJ IDEA 中打开插件市场（File -> Settings -> Plugins），安装以下插件以提升开发效率：

二、创建 Spring Boot 项目（三种方式）

方式一：使用 Spring Initializr 网站（最通用）

打开浏览器，访问 https://start.spring.io/，按如下配置生成项目：

配置完成后，点击 GENERATE 下载项目压缩包，解压后用 IDEA 打开。

方式二：使用 IntelliJ IDEA 内置向导（推荐）

1. 在 IDEA 欢迎界面点击 New Project，或菜单栏 File -> New -> Project。

2. 左侧选择 Spring Boot，右侧配置：

   • Name：项目名称

   • Location：项目存放路径

   • Language：Java

   • Type：Maven

   • Group / Artifact / Package name：按需填写

   • JDK：选择 17 或更高版本

3. 点击 Next，在依赖选择界面勾选所需的依赖（详见第三章）。

4. 点击 Create，IDEA 将自动下载依赖并构建项目。

方式三：使用阿里云 Initializr（国内用户加速）

访问 https://start.aliyun.com/，该镜像源在国内下载依赖速度更快，配置方式与官方 Spring Initializr 一致。

三、核心依赖配置（pom.xml）

3.1 基础依赖

在 pom.xml 的 <dependencies> 标签内添加以下核心依赖：

xml

<dependencies>
    <!-- Spring Boot Web 模块：提供 Spring MVC 及内嵌 Tomcat，构建 RESTful API -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Boot DevTools：热部署，修改代码后自动重启应用 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>

    <!-- Lombok：通过注解简化 Java 代码，如 @Data、@Slf4j 等 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!-- Spring Boot 测试模块：支持 JUnit、Mockito 等测试框架 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

3.2 数据库相关依赖（二选一）

JPA（Java Persistence API）：Spring 官方推荐的 ORM 框架，适合快速开发。

xml

<!-- Spring Data JPA：简化数据库访问，基于 Hibernate 实现 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- MySQL 驱动：连接 MySQL 数据库 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

MyBatis-Plus：MyBatis 的增强工具，在国内应用广泛，提供强大的 CRUD 封装，适合需要灵活 SQL 控制的场景。

xml

<!-- MyBatis-Plus Starter：简化 MyBatis 配置，提供通用 CRUD 方法 -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.10</version>
</dependency>

<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

3.3 安全与工具依赖

xml

<!-- Spring Security：提供认证、授权等安全功能 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!-- JWT：用于生成和解析 JSON Web Token -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.6</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.6</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.12.6</version>
    <scope>runtime</scope>
</dependency>

<!-- Knife4j：增强版 Swagger API 文档生成工具 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

💡 版本选择建议：

• Spring Boot 3.x 对应的 mybatis-plus-spring-boot3-starter 版本需在 3.5.5 以上。

• JWT 推荐使用 0.12.x 版本，该版本对 Spring Boot 3 支持最佳。

四、配置文件（application.yml）

4.1 基础配置

在 src/main/resources 目录下创建 application.yml 文件：

yaml

server:
  port: 8080                    # 服务端口
  servlet:
    context-path: /api          # 应用上下文路径

spring:
  application:
    name: demo                  # 应用名称
  datasource:
    url: jdbc:mysql://localhost:3306/demo_db?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf-8
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

  # JPA 配置（使用 JPA 时启用）
  jpa:
    hibernate:
      ddl-auto: update          # 自动更新表结构
    show-sql: true              # 打印 SQL 语句
    database-platform: org.hibernate.dialect.MySQL8Dialect

# MyBatis-Plus 配置（使用 MyBatis-Plus 时启用）
mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 打印 SQL 日志
  global-config:
    db-config:
      id-type: auto             # 主键自增
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

4.2 多环境配置

在 src/main/resources 目录下创建环境专属配置文件，实现开发/测试/生产环境的配置隔离：

在 application.yml 中通过 spring.profiles.active 激活对应环境：

yaml

spring:
  profiles:
    active: dev   # 激活开发环境配置

也可以使用启动命令指定：java -jar demo.jar --spring.profiles.active=prod。

五、分层架构代码示例

5.1 项目包结构

text

src/main/java/com/example/demo/
├── DemoApplication.java          # 启动类
├── controller/                   # 控制层：接收请求，返回响应
│   └── UserController.java
├── service/                      # 业务层：处理业务逻辑
│   ├── UserService.java          # 业务接口
│   └── impl/
│       └── UserServiceImpl.java  # 业务实现类
├── repository/                   # 数据访问层：数据库操作
│   └── UserRepository.java
├── entity/                       # 实体类：与数据库表映射
│   └── User.java
├── dto/                          # 数据传输对象：接口入参/出参
│   ├── UserLoginDTO.java
│   └── UserVO.java
└── config/                       # 配置类
    └── WebConfig.java

5.2 Entity 实体类

java

package com.example.demo.entity;

import lombok.Data;
import jakarta.persistence.*;
import java.time.LocalDateTime;

@Data                      // Lombok 自动生成 getter/setter
@Entity                    // JPA 实体注解
@Table(name = "user")      // 指定数据库表名
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(unique = true, nullable = false)
    private String username;

    private String password;
    private String email;
    private Integer age;

    @Column(name = "create_time")
    private LocalDateTime createTime;
}

5.3 Repository 数据访问层

使用 JPA：

java

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // 根据用户名查询用户
    Optional<User> findByUsername(String username);

    // 判断用户名是否存在
    boolean existsByUsername(String username);
}

使用 MyBatis-Plus：

java

package com.example.demo.repository;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demo.entity.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;

@Mapper
public interface UserRepository extends BaseMapper<User> {
    // 自定义查询
    @Select("SELECT * FROM user WHERE username = #{username}")
    User findByUsername(String username);
}

5.4 Service 业务逻辑层

java

// 业务接口
package com.example.demo.service;

import com.example.demo.entity.User;

public interface UserService {
    User getUserById(Long id);
    User getUserByUsername(String username);
    User createUser(User user);
}

// 业务实现类
package com.example.demo.service.impl;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

@Service                    // 标记为 Service 组件
@RequiredArgsConstructor    // Lombok 自动生成构造函数注入
public class UserServiceImpl implements UserService {

    private final UserRepository userRepository;

    @Override
    public User getUserById(Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("用户不存在"));
    }

    @Override
    public User getUserByUsername(String username) {
        return userRepository.findByUsername(username)
                .orElseThrow(() -> new RuntimeException("用户不存在"));
    }

    @Override
    public User createUser(User user) {
        // 业务校验：检查用户名是否已存在
        if (userRepository.existsByUsername(user.getUsername())) {
            throw new RuntimeException("用户名已存在");
        }
        return userRepository.save(user);
    }
}

5.5 Controller 控制层

java

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController                     // 标记为 RESTful 控制器
@RequestMapping("/users")           // 请求路径前缀
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    // GET 请求：获取用户信息
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        User user = userService.getUserById(id);
        return ResponseEntity.ok(user);
    }

    // POST 请求：创建用户
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User created = userService.createUser(user);
        return ResponseEntity.ok(created);
    }
}

5.6 统一响应封装

java

package com.example.demo.dto;

import lombok.Data;

@Data
public class Result<T> {
    private Integer code;    // 状态码：200 成功，其他失败
    private String message;  // 提示信息
    private T data;          // 响应数据

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(data);
        return result;
    }

    public static <T> Result<T> error(String message) {
        Result<T> result = new Result<>();
        result.setCode(500);
        result.setMessage(message);
        return result;
    }
}

六、项目运行与打包

6.1 开发环境运行

在 IDEA 中直接运行 DemoApplication.java 的 main() 方法，或在项目根目录执行：

bash

mvn spring-boot:run

启动成功后，控制台输出 Started DemoApplication in X seconds 即表示运行成功。

6.2 生产环境打包

bash

mvn clean package

打包完成后，在 target 目录下生成 demo-0.0.1-SNAPSHOT.jar 文件。

6.3 运行 Jar 包

bash

java -jar target/demo-0.0.1-SNAPSHOT.jar

如指定外部配置文件：

bash

java -jar demo.jar --spring.config.location=file:/path/to/application.yml

七、常用工具整合

7.1 Knife4j API 文档配置

在 src/main/java/com/example/demo/config/Knife4jConfig.java 中配置：

java

package com.example.demo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Demo API 文档")
                        .version("1.0")
                        .description("Spring Boot 3 + Knife4j 接口文档"));
    }
}

启动项目后，访问 http://localhost:8080/doc.html 即可查看 API 文档。

7.2 JWT 工具类

java

package com.example.demo.util;

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Date;

public class JwtUtil {
    private static final String SECRET = "your-256-bit-secret-key-for-jwt-signing";  // 至少 32 字符
    private static final long EXPIRATION = 86400000L;  // 24 小时

    private static SecretKey getSigningKey() {
        return Keys.hmacShaKeyFor(SECRET.getBytes(StandardCharsets.UTF_8));
    }

    // 生成 Token
    public static String generateToken(String username) {
        return Jwts.builder()
                .subject(username)
                .issuedAt(new Date())
                .expiration(new Date(System.currentTimeMillis() + EXPIRATION))
                .signWith(getSigningKey())
                .compact();
    }

    // 解析 Token 获取用户名
    public static String getUsernameFromToken(String token) {
        return Jwts.parser()
                .verifyWith(getSigningKey())
                .build()
                .parseSignedClaims(token)
                .getPayload()
                .getSubject();
    }

    // 验证 Token
    public static boolean validateToken(String token) {
        try {
            Jwts.parser().verifyWith(getSigningKey()).build().parseSignedClaims(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }
}

⚠️ 注意：在生产环境中，建议将 SECRET 配置在 application.yml 的环境变量中，而非硬编码在代码里。

7.3 跨域配置

java

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

八、总结：完整命令速查

以上配置构建了一个完整的 Spring Boot 企业级项目基础框架，涵盖开发环境、构建工具、分层架构、数据库操作、API 文档和 JWT 认证，可直接在此基础上进行业务功能开发。