Java Spring Boot REST API 开发指南：控制器、数据访问与安全

Java Spring Boot REST API 开发指南：控制器、数据访问与安全

Spring Boot 的目标是"开箱即用地创建可独立运行、可投入生产的 Spring 应用"。它采用约定优于配置：内嵌服务器、自动化配置、外部化配置开箱即用，且几乎没有 XML。根据 Spring 官方指南，本文讲解启动器、控制器、数据访问与安全四条主线。

用 Spring Initializr 起步

访问 start.spring.io 即可生成项目：选择 Java 17+、Gradle 或 Maven，勾选需要的依赖（starter）。核心启动器包括：

• spring-boot-starter-web：内嵌 Tomcat + Spring MVC，用来写 REST API；
• spring-boot-starter-data-jpa：JPA 数据访问；
• spring-boot-starter-security：安全认证。

主类用 @SpringBootApplication 标注，它集合了 @Configuration、@EnableAutoConfiguration 与 @ComponentScan。用 ./mvnw spring-boot:run 或 java -jar 就能启动，不需要任何 XML 配置。

编写 REST 控制器

Spring 用控制器处理 HTTP 请求。@RestController 表示"每个方法返回的领域对象直接序列化为 JSON 响应"，@GetMapping、@PostMapping 等注解把 HTTP 方法映射到具体方法：

@RestController
public class GreetingController {

  @GetMapping("/greeting")
  public Greeting greeting(@RequestParam(defaultValue = "World") String name) {
    return new Greeting(counter.incrementAndGet(), "Hello, " + name + "!");
  }
}

Jackson 在 classpath 上时会自动把返回对象序列化为 JSON，无需手写转换代码。

数据访问层

数据访问最常用的方式是 Spring Data JPA：定义一个继承 JpaRepository 的接口，CRUD、分页、排序等方法自动可用，复杂查询用方法名推导或 @Query 注解：

public interface FlightRepository extends JpaRepository<Flight, Long> {
  List<Flight> findByActiveTrue();
}

数据源相关的关键配置都集中在 application.yml：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: demo
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate

把密码放进环境变量而不是写死在文件里，是上线前必须养成的习惯。

数据访问选型上，Spring Data JPA 适合领域模型复杂、需要快速 CRUD 的项目；如果团队更习惯手写 SQL、对查询性能有极致要求，也可以换 spring-boot-starter-jdbc 配合 JdbcTemplate，或使用 MyBatis。两种路线都能与 Spring Boot 的自动配置和平共处，关键是别在同一个服务里混用两套持久化方式。

常用注解与最佳实践

除 @RestController 外，几个高频注解值得掌握：

推荐把控制器保持"薄"：只做参数接收与响应组装，业务逻辑放到 Service 层，数据访问交给 Repository，形成清晰的分层结构，便于测试与替换实现。

安全配置

引入 spring-boot-starter-security 后，默认会为所有端点加上认证。基于依赖注入的方式编写安全配置类（SecurityFilterChain），可以精确控制哪些路径公开、哪些需要登录、使用何种认证方式（Basic / JWT / OAuth2）。一个只允许登录用户访问 /api/** 的典型配置：

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  return http
    .authorizeHttpRequests(auth -> auth
      .requestMatchers("/public/**", "/actuator/health").permitAll()
      .requestMatchers("/api/**").authenticated())
    .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
    .build();
}

配合 spring-security-oauth2-resource-server，只要声明 JWT 发行方（issuer），令牌校验与签名验证都会自动完成。

一个完整场景：航班查询接口

把上面的零件组装起来，一个"查询在飞航班"的接口大致是这样分层的：FlightController 接收 GET /flights?active=true 请求，把 active 参数透传给 FlightService；Service 里做业务判断（比如按目的地分组、过滤掉已取消航班），再调用 FlightRepository.findByActiveTrue()；返回结果统一包一层 ApiResponse，把成功与否、数据和时间戳一起交给前端。整个链路里控制器只做参数接收与响应组装，改动数据结构时，最多只影响 Controller 和 DTO，不会牵动数据库层。

给这个接口补测试也很直接：@WebMvcTest 只加载控制器切片，用 MockMvc 断言返回 JSON；@DataJpaTest 用内存数据库验证 Repository 查询；真正跑集成测试时再用 @SpringBootTest 拉起完整上下文。三层测试各司其职，运行时间也都在秒级。

打包与部署

Spring Boot 可以构建"可执行 JAR"，把所有依赖、类与资源打包进一个文件，方便版本化与跨环境部署：

./gradlew bootRun        # 本地运行
./gradlew build          # 构建 JAR
java -jar build/libs/demo-0.0.1-SNAPSHOT.jar

内嵌服务器让部署从"装 Tomcat、配 web.xml"简化为"一条命令跑起来"，也更容易容器化（Docker）。

监控与运维

Spring Boot Actuator 提供健康检查、指标与日志端点：加入 spring-boot-starter-actuator 后，/actuator/health 可直接用于负载均衡与容器的存活探针，/actuator/metrics 可对接 Prometheus 等监控系统。日志用 SLF4J 门面输出结构化 JSON，配合集中式日志平台，线上问题的定位会快很多。测试方面，spring-boot-starter-test 内置 JUnit 与 MockMvc，可以针对控制器与 Service 编写单元与集成测试；Initializr 生成的工程自带示例测试，直接 ./gradlew test 即可跑通基线。对于需要横向扩展的场景，Spring Boot 的轻量与标准化也让它很容易部署到各大云厂商的托管容器服务上。

常见问题

• 为什么默认所有端点都要登录？ 这是安全默认值：多暴露一个端点就多一个攻击面，先收紧再按需放行，比先放开再补洞更稳妥。
• JAR 启动报端口占用怎么办？ 用 server.port 属性覆盖端口，或让部署平台注入环境变量，避免改代码。
• JPA 自动建表适合生产吗？ ddl-auto 设为 create 只适合开发；生产建议 validate 或交给 Flyway/Liquibase 管理迁移。

16IDC 观察

Spring Boot 适合中大型团队与对稳定性、生态要求高的项目，企业级中间件与云厂商对其支持最成熟。选型前建议先读 网站 API 集成基础指南；上线前把 API 安全认证机制 落实到位。更多后端开发内容见 后端对接 分类。

原文来源：https://spring.io/guides/gs/rest-service/
参考：Spring Boot 官方文档 https://docs.spring.io/spring-boot/index.html
参考：Spring Security 文档 https://docs.spring.io/spring-security/reference/index.html