一、项目准备与依赖配置
1. 搭建环境与初始化
在本实战教程中，我们将以 Spring Boot 与 JpaRepository 为核心，目标是从零搭建一个可用的 安全登录界面。通过 Spring Boot 的自动配置，简化了基础框架搭建的难度，让你可以把更多精力投入到业务逻辑和安全策略上。
首先需要确定一个合适的项目结构：一个用于数据访问的层，一个用于业务逻辑的服务层，以及一个用于表现层的控制器和前端。从零开始 的重点在于把 JpaRepository 与 Spring Security 的组合关系理清，确保后续身份认证流程顺畅无阻。
2. 引入核心依赖
为了实现一个完整的安全登录功能，我们需要在构建配置中引入若干核心依赖，包含数据库访问、数据持久化、表单登录以及模板渲染。Spring Boot 的起步器将帮助我们快速组合这些组件，形成一个可运行的原型。
下面给出一个最小化的 Maven 配置示例，包含了 Web、数据访问、模板渲染和安全相关的依赖。依赖完整性 将直接影响后续的实体、仓库与安全配置的实现。
4.0.0 com.example sec-login-demo 0.0.1-SNAPSHOT jar org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-security org.springframework.boot spring-boot-starter-thymeleaf com.h2database h2 runtime org.springframework.boot spring-boot-maven-plugin 注意：若你选择使用其他数据库，请相应调整依赖和配置，例如 MySQL、PostgreSQL 等。此处的配置旨在快速搭建一个可运行的原型。
二、数据模型与 JpaRepository
1. 定义 User 实体
在从零搭建安全登录界面的过程中，User 实体是身份认证的核心。它需要具备唯一用户名、密码字段以及角色信息，方便后续进行权限控制。@Entity 与 @Table 注解将实体映射到数据库表。
通过将 用户名 设为唯一键，可以防止重复用户，同时为后续的用户查询提供高效路径。我们还可以借助一个简单的 角色字段 来实现基于角色的访问控制。以下示例展示了一个简化的 User 实体结构。
package com.example.demo.model;import javax.persistence.*;@Entity
@Table(name = "users")
public class User {@Id@GeneratedValue(strategy = GenerationType.IDENTITY)private Long id;@Column(unique = true, nullable = false)private String username;@Column(nullable = false)private String password;// 角色，以英文逗号分隔，例如 "ROLE_ADMIN,ROLE_USER"private String roles;// getters 与 setters 省略
}2. 创建 UserRepository
JpaRepository 提供了强大且常用的数据库操作方法，UserRepository 继承它即可获得如 save、findById、findAll 等方法。我们需要一个通过用户名查询用户的自定义方法，以便在认证阶段载入用户信息。
下面给出 UserRepository 的最小实现，作为后续 CustomUserDetailsService 的基础数据源。
package com.example.demo.repository;import org.springframework.data.jpa.repository.JpaRepository;
import com.example.demo.model.User;public interface UserRepository extends JpaRepository<User, Long> {User findByUsername(String username);
}三、Spring Security 配置
1. 密码编码与用户服务
现代化的安全系统通常采用强哈希算法对密码进行编码。本教程选用 BCryptPasswordEncoder，它能提供足够的安全性与兼容性。配合 UserDetailsService，我们可以把数据库中的 User 映射为 Spring Security 所需的 UserDetails。
要实现数据驱动的认证，我们需要一个实现了 UserDetailsService 的类，从仓库中根据用户名加载用户信息，并转换成 Spring Security 的 UserDetails 对象。以下实现使用 JpaRepository 读取数据并构造 GrantedAuthority 列表。
package com.example.demo.service;import org.springframework.security.core.userdetails.*;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.stereotype.Service;
import com.example.demo.model.User;
import com.example.demo.repository.UserRepository;
import java.util.*;@Service
public class CustomUserDetailsService implements UserDetailsService {private final UserRepository userRepository;public CustomUserDetailsService(UserRepository userRepository) {this.userRepository = userRepository;}@Overridepublic UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {User user = userRepository.findByUsername(username);if (user == null) throw new UsernameNotFoundException("用户未找到");List authorities = new ArrayList<>();if (user.getRoles() != null) {for (String role : user.getRoles().split(",")) {authorities.add(new SimpleGrantedAuthority(role.trim()));}}return new org.springframework.security.core.userdetails.User(user.getUsername(), user.getPassword(), authorities);}
} 2. 自定义安全配置
通过自定义 SecurityConfig，可以控制哪些路径需要认证、登录页、登出路径等。我们将配置一个自定义登录页，并指定在认证成功后跳转到首页。表单登录 的页面将指向 /login。
以下为一个简化的 SecurityConfig，包含 passwordEncoder、用户详情服务注入，以及基本的路由权限设置。段落中的要点已被强调，以帮助你把注意力放在关键配置上。
package com.example.demo.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.*;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.core.userdetails.UserDetailsService;
import com.example.demo.service.CustomUserDetailsService;@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {private final UserDetailsService userDetailsService;public SecurityConfig(CustomUserDetailsService userDetailsService) {this.userDetailsService = userDetailsService;}@Beanpublic PasswordEncoder passwordEncoder() {return new BCryptPasswordEncoder();}@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/login", "/register", "/css/**").permitAll().anyRequest().authenticated().and().formLogin().loginPage("/login").defaultSuccessUrl("/home", true).permitAll().and().logout().permitAll();}@Overrideprotected void configure(AuthenticationManagerBuilder auth) throws Exception {auth.userDetailsService(userDetailsService).passwordEncoder(passwordEncoder());}
}四、登录界面与控制器
1. 前端登录表单
为提升用户体验，我们使用一个自定义的登录页面，而不是直接使用 Spring Security 的默认登录页。该页面通过 Thymeleaf 模板引擎渲染，表单将 POST 到 /login，密码字段会被 PasswordEncoder 进行校验。
在前端，我们需要明确的输入项：用户名和密码，并传递给后端的认证端点。自定义登录页 能更好地与现有前端风格和样式保持一致。
登录
登录
2. 后端控制与路由
为了完善用户体验，我们提供一个控制器来渲染登录页面和简单的首页。尽管 Spring Security 会处理大部分认证流程，但明确的路由可以让前端逻辑和权限更清晰。LoginController 负责 /login 的视图渲染，/home 则作为登录后的首页入口。
package com.example.demo.controller;import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;@Controller
public class LoginController {@GetMapping("/login")public String login() {return "login";}@GetMapping("/home")public String home() {return "home";}
}五、数据初始化与测试
1. 初始化管理员账户
为了能够进行快速的实战测试，我们需要在应用启动时自动初始化一个管理员账户。通过 CommandLineRunner 或 数据初始化组件，可以将一个具有管理员权限的用户写入到 users 表中，确保在首次登陆时就具备可用账户。
以下示例演示了如何对 admin 用户进行初始化，并对密码进行 BCrypt 编码，以保持与生产环境的加盐策略一致性。
package com.example.demo;import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Component;
import com.example.demo.model.User;
import com.example.demo.repository.UserRepository;@Component
public class DataInitializer {@BeanCommandLineRunner init(UserRepository userRepository, PasswordEncoder passwordEncoder) {return args -> {if (userRepository.findByUsername("admin") == null) {User u = new User();u.setUsername("admin");u.setPassword(passwordEncoder.encode("admin123"));u.setRoles("ROLE_ADMIN,ROLE_USER");userRepository.save(u);}};}
}2. 接口测试与日志排错
测试阶段应包含对前端登录页、身份认证、以及授权后的页面访问的逐步验证。你可以通过浏览器访问 /login，输入管理员账号与密码以验证认证是否成功。此外，结合日志级别，可以快速定位认证过程中的异常点，例如 用户名未找到、密码不匹配 等问题。
在需要使用命令行进行简单测试时，可以借助 curl 与会话 cookies 来模拟浏览器登录过程，确保后续请求携带正确的认证凭证。
# 使用 curl 测试登录需要会话
curl -c cookies.txt -d "username=admin&password=admin123" -X POST http://localhost:8080/login
curl -b cookies.txt http://localhost:8080/home