SpringBoot 项目从零搭建指南

SpringBoot 项目从零搭建指南 | 极客日志

# 验证 JDK 安装
java -version
javac -version

# 下载 Maven 并解压
# 配置环境变量 MAVEN_HOME 和 PATH
# 验证安装
mvn -version

curl https://start.spring.io/starter.zip \
-ddependencies=web,data-jpa,mysql \
-dgroupId=com.example \
-dartifactId=demo \
-o demo.zip
unzip demo.zip

my-springboot-project/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/
│   │   └── resources/
│   │       ├── application.properties
│   │       ├── static/
│   │       └── templates/
│   └── test/
│       └── java/
│           └── com/example/demo/
└── pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!-- Spring Boot 父项目，提供依赖管理 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.0</version>
        <relativePath/>
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <!-- Web 开发起步依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- 测试起步依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- 热部署依赖（开发时使用） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <!-- Spring Boot Maven 插件 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * SpringBoot 应用主类
 * @SpringBootApplication 注解标识这是一个 SpringBoot 应用
 */
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        // 启动 SpringBoot 应用
        SpringApplication.run(DemoApplication.class, args);
    }
}

src/
├── main/
│   ├── java/ # Java 源代码
│   │   └── com/example/demo/
│   │       ├── controller/ # 控制器层
│   │       ├── service/ # 业务逻辑层
│   │       ├── repository/ # 数据访问层
│   │       ├── entity/ # 实体类
│   │       ├── config/ # 配置类
│   │       └── DemoApplication.java # 主应用类
│   └── resources/ # 资源文件
│       ├── static/ # 静态资源 (css,js,图片)
│       ├── templates/ # 模板文件 (thymeleaf,freemarker)
│       ├── application.properties # 主配置文件
│       └── application-dev.properties # 开发环境配置
└── test/ # 测试代码
    └── java/
        └── com/example/demo/

# 应用配置
spring.application.name=demo
# 服务器配置
server.port=8080
server.servlet.context-path=/demo
# 日志配置
logging.level.com.example.demo=DEBUG
logging.file.name=logs/demo.log
# 开发环境配置
spring.profiles.active=dev

# 开发环境数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/demo_dev
spring.datasource.username=dev_user
spring.datasource.password=dev_password
# H2 内存数据库（开发测试用）
# spring.datasource.url=jdbc:h2:mem:testdb
# spring.datasource.driverClassName=org.h2.Driver
# spring.datasource.username=sa
# spring.datasource.password=password
# JPA 配置
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

package com.example.demo.entity;

import java.time.LocalDateTime;

public class User {
    private Long id;
    private String username;
    private String email;
    private LocalDateTime createTime;

    // 构造方法
    public User() {}

    public User(Long id, String username, String email) {
        this.id = id;
        this.username = username;
        this.email = email;
        this.createTime = LocalDateTime.now();
    }

    // Getter 和 Setter 方法
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    public LocalDateTime getCreateTime() { return createTime; }
    public void setCreateTime(LocalDateTime createTime) { this.createTime = createTime; }
}

package com.example.demo.controller;

import com.example.demo.entity.User;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;

/**
 * 用户管理控制器
 * @RestController 组合了@Controller 和@ResponseBody
 */
@RestController
@RequestMapping("/api/users")
public class UserController {
    private final List<User> users = new ArrayList<>();
    private final AtomicLong counter = new AtomicLong();

    // 初始化一些测试数据
    public UserController() {
        users.add(new User(counter.incrementAndGet(), "张三", "[email protected]"));
        users.add(new User(counter.incrementAndGet(), "李四", "[email protected]"));
    }

    /**
     * 获取所有用户
     * GET /api/users
     */
    @GetMapping
    public List<User> getAllUsers() {
        return users;
    }

    /**
     * 根据 ID 获取用户
     * GET /api/users/{id}
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return users.stream().filter(user -> user.getId().equals(id)).findFirst().orElse(null);
    }

    /**
     * 创建新用户
     * POST /api/users
     */
    @PostMapping
    public User createUser(@RequestBody User user) {
        user.setId(counter.incrementAndGet());
        users.add(user);
        return user;
    }

    /**
     * 更新用户信息
     * PUT /api/users/{id}
     */
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        User user = getUserById(id);
        if (user != null) {
            user.setUsername(userDetails.getUsername());
            user.setEmail(userDetails.getEmail());
        }
        return user;
    }

    /**
     * 删除用户
     * DELETE /api/users/{id}
     */
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        users.removeIf(user -> user.getId().equals(id));
        return "用户删除成功";
    }
}

package com.example.demo.service;

import com.example.demo.entity.User;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Optional;

/**
 * 用户服务层
 * @Service 标识这是一个 Spring 服务组件
 */
@Service
public class UserService {
    /**
     * 模拟数据库操作 - 获取所有用户
     */
    public List<User> findAllUsers() {
        // 实际项目中这里会调用 Repository
        return List.of(new User(1L, "张三", "[email protected]"), new User(2L, "李四", "[email protected]"));
    }

    /**
     * 根据 ID 查找用户
     */
    public Optional<User> findUserById(Long id) {
        // 模拟数据库查询
        return findAllUsers().stream().filter(user -> user.getId().equals(id)).findFirst();
    }

    /**
     * 创建用户
     */
    public User createUser(User user) {
        // 模拟保存到数据库
        return user;
    }
}

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Optional;

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    private final UserService userService;

    /**
     * 构造器注入 - 推荐方式
     */
    @Autowired
    public UserControllerV2(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAllUsers();
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        Optional<User> user = userService.findUserById(id);
        return user.map(ResponseEntity::ok).orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

<!-- 在 pom.xml 中添加 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- H2 数据库（测试用） -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

# application.properties
spring.datasource.url=jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=123456
# JPA 配置
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect
# H2 控制台（开发时使用）
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

package com.example.demo.entity;

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

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

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

    @Column(nullable = false, unique = true, length = 100)
    private String email;

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

    // 构造方法
    public User() {
        this.createTime = LocalDateTime.now();
    }

    public User(String username, String email) {
        this();
        this.username = username;
        this.email = email;
    }

    // Getter 和 Setter
    // ... 省略 getter/setter
}

package com.example.demo.repository;

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

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // 根据用户名查找用户
    Optional<User> findByUsername(String username);
    // 根据邮箱查找用户
    Optional<User> findByEmail(String email);
    // 自定义查询：查找创建时间在指定时间之后的用户
    @Query("SELECT u FROM User u WHERE u.createTime > :createTime")
    List<User> findUsersAfterCreateTime(@Param("createTime") LocalDateTime createTime);
    // 检查用户名是否存在
    boolean existsByUsername(String username);
    // 检查邮箱是否存在
    boolean existsByEmail(String email);
}

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Optional;

@Service
public class UserService {
    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List<User> findAllUsers() {
        return userRepository.findAll();
    }

    public Optional<User> findUserById(Long id) {
        return userRepository.findById(id);
    }

    public User saveUser(User user) {
        return userRepository.save(user);
    }

    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }

    public boolean existsByUsername(String username) {
        return userRepository.existsByUsername(username);
    }

    public boolean existsByEmail(String email) {
        return userRepository.existsByEmail(email);
    }
}

package com.example.demo.exception;

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

public class BusinessException extends RuntimeException {
    public BusinessException(String message) {
        super(message);
    }
}

package com.example.demo.dto;

public class ApiResponse<T> {
    private boolean success;
    private String message;
    private T data;
    private String errorCode;

    // 成功响应
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(true, "操作成功", data, null);
    }

    public static <T> ApiResponse<T> success(String message, T data) {
        return new ApiResponse<>(true, message, data, null);
    }

    // 失败响应
    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>(false, message, null, null);
    }

    public static <T> ApiResponse<T> error(String message, String errorCode) {
        return new ApiResponse<>(false, message, null, errorCode);
    }

    // 构造方法、getter、setter
    public ApiResponse(boolean success, String message, T data, String errorCode) {
        this.success = success;
        this.message = message;
        this.data = data;
        this.errorCode = errorCode;
    }

    // ... 省略 getter/setter
}

package com.example.demo.handler;

import com.example.demo.dto.ApiResponse;
import com.example.demo.exception.ResourceNotFoundException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.HashMap;
import java.util.Map;

/**
 * 全局异常处理
 */
@RestControllerAdvice
public class GlobalExceptionHandler {
    /**
     * 处理资源不存在异常
     */
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiResponse<Object>> handleResourceNotFound(ResourceNotFoundException ex) {
        ApiResponse<Object> response = ApiResponse.error(ex.getMessage());
        return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
    }

    /**
     * 处理参数验证异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<Map<String, String>>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach((error) -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        ApiResponse<Map<String, String>> response = ApiResponse.error("参数验证失败", "VALIDATION_ERROR");
        response.setData(errors);
        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
    }

    /**
     * 处理其他所有异常
     */
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Object>> handleGlobalException(Exception ex) {
        ApiResponse<Object> response = ApiResponse.error("服务器内部错误");
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

mvn spring-boot:run

mvn clean package
java -jar target/demo-1.0.0.jar

# 获取所有用户
curl -X GET http://localhost:8080/api/users
# 根据 ID 获取用户
curl -X GET http://localhost:8080/api/users/1
# 创建新用户
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"username":"王五","email":"[email protected]"}'
# 更新用户
curl -X PUT http://localhost:8080/api/users/1 \
-H "Content-Type: application/json" \
-d '{"username":"张三丰","email":"[email protected]"}'
# 删除用户
curl -X DELETE http://localhost:8080/api/users/1

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import java.util.Arrays;
import java.util.Optional;

import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(UserControllerV2.class)
public class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    public void testGetAllUsers() throws Exception {
        User user1 = new User(1L, "user1", "[email protected]");
        User user2 = new User(2L, "user2", "[email protected]");
        when(userService.findAllUsers()).thenReturn(Arrays.asList(user1, user2));
        mockMvc.perform(get("/api/v2/users"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$[0].username").value("user1"))
               .andExpect(jsonPath("$[1].username").value("user2"));
    }

    @Test
    public void testGetUserById() throws Exception {
        User user = new User(1L, "testuser", "[email protected]");
        when(userService.findUserById(1L)).thenReturn(Optional.of(user));
        mockMvc.perform(get("/api/v2/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.username").value("testuser"));
    }

    @Test
    public void testCreateUser() throws Exception {
        User user = new User("newuser", "[email protected]");
        User savedUser = new User(1L, "newuser", "[email protected]");
        when(userService.saveUser(any(User.class))).thenReturn(savedUser);
        mockMvc.perform(post("/api/v2/users").contentType(MediaType.APPLICATION_JSON).content(objectMapper.writeValueAsString(user)))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.id").value(1L));
    }
}

# application.yml
spring:
  application:
    name: demo
  datasource:
    url: jdbc:mysql://localhost:3306/demo
    username: root
    password: 123456
  jpa:
    hibernate:
      ddl-auto: update
      show-sql: true
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true
server:
  port: 8080
  servlet:
    context-path: /demo
logging:
  level:
    com.example.demo: DEBUG
  file:
    name: logs/demo.log

# application-dev.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo_dev
    username: dev_user
    password: dev_password
  jpa:
    show-sql: true
---
# application-prod.yml
spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/demo_prod
    username: prod_user
    password: ${DB_PASSWORD}
  jpa:
    show-sql: false
logging:
  level:
    com.example.demo: INFO

<!-- 添加依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

// 配置类
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI().info(new Info().title("Demo API").version("1.0").description("SpringBoot Demo 项目 API 文档").contact(new Contact().name("开发者").email("[email protected]")));
    }
}

# 修改端口
server.port=8081

mvn dependency:tree

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

SpringBoot 项目从零搭建指南

SpringBoot 简介与优势

什么是 SpringBoot？

SpringBoot 的核心优势

环境准备与工具安装

JDK 安装与配置

开发工具选择与配置

Maven 安装与配置

数据库准备（可选）

使用 Spring Initializr 快速创建项目

在线创建项目

使用 IDE 创建

使用命令行创建

手动创建 SpringBoot 项目

创建 Maven 项目结构

配置 pom.xml

创建主应用类

项目结构深度解析

标准项目目录结构

配置文件详解

编写第一个 RESTful API

创建实体类

创建控制器

创建服务层

更新控制器使用服务层

数据库集成与 JPA 使用

添加数据库依赖

配置数据源

创建 JPA 实体

创建 Repository 接口

更新服务层使用 Repository

异常处理与统一响应

创建自定义异常

创建统一响应对象

创建全局异常处理器

运行与测试

启动应用程序

测试 API 接口

编写单元测试

项目优化与最佳实践

配置文件优化

多环境配置

添加 Swagger API 文档

常见问题与解决方案

端口被占用

数据库连接失败

依赖冲突

热部署配置

总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具