Spring Boot 入门实战（二）：用户注册接口设计（Controller + DTO + Validation）

一、前言

在第一篇(Spring Boot 入门实战（一）：项目创建与运行机制详解)中，我们完成了：

Spring Boot 项目创建
→ pom.xml 依赖理解
→ application.yml 配置
→ Controller 基本使用

但此时的项目还只是一个"能启动的服务"，并没有真正的业务能力。

本篇开始，我们进入第一个真实接口开发：用户注册接口。

二、目标：实现一个注册接口

目标接口：

POST /user/register

功能：

接收用户名和密码 → 校验参数 → 返回注册结果

三、接口设计思路

一个标准后端接口，一般分三步：

1. 接收请求（Controller）
2. 承载数据（DTO）
3. 参数校验（Validation）

四、DTO 设计（参数对象）

新建：

dto/UserRegisterDTO.java

代码如下：

package org.example.arkbackend.dto;

import jakarta.validation.constraints.NotBlank;
import lombok.Data;

@Data
public class UserRegisterDTO {

    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;
}

解释

@Data → 自动生成 getter / setter
@NotBlank → 定义校验规则（不能为空字符串）

五、Controller 实现（接口入口）

新建：

UserController.java

代码如下：

package org.example.arkbackend;

import jakarta.validation.Valid;
import org.example.arkbackend.dto.UserRegisterDTO;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/register")
    public String register(@Valid @RequestBody UserRegisterDTO dto) {

        System.out.println("username: " + dto.getUsername());
        System.out.println("password: " + dto.getPassword());

        return "注册成功，用户名：" + dto.getUsername();
    }
}

六、核心注解说明（非常重要）

1. @RestController

声明当前类为接口控制器，返回数据而不是页面

---

2. @RequestMapping

定义接口前缀路径，例如 /user

---

3. @PostMapping

定义 POST 请求接口，例如 /register

---

4. @RequestBody

将请求体中的 JSON 转换为 Java 对象

---

5. @Valid

触发参数校验

---

6. @NotBlank（在 DTO 中）

定义校验规则（不能为空字符串）

---

⭐ 注解关系总结

@RequestBody → 转换数据
@NotBlank → 定义规则
@Valid → 触发规则

七、接口测试（IDEA HTTP / Postman）

请求

POST http://localhost:8080/user/register
Content-Type: application/json

{
  "username": "test",
  "password": "123456"
}

正常返回

注册成功，用户名：test

参数错误示例

{
  "username": "",
  "password": ""
}

返回：

400 Bad Request

说明：

校验未通过，请求被拦截

八、一次请求的完整流程

客户端发送 JSON
→ @RequestBody 转换为 DTO
→ @Valid 触发校验
→ 校验通过 → 进入 Controller 方法
→ 返回响应结果

九、常见踩坑总结

❌ 1. 没加 @Valid

DTO 上写了 @NotBlank，但不会生效

---

❌ 2. JSON 写到 Header

会报：invalid character '{'

---

❌ 3. 返回 empty

原因：方法没有返回值（void）或项目未重启

---

❌ 4. 修改代码未重启

代码改了，但接口仍是旧逻辑

十、命名规范建议

推荐使用统一简洁命名：
username / password

说明：

避免 userName / passWord 等不规范写法

十一、一句话总结

通过 Controller + DTO + Validation，可以快速构建一个具备参数接收和校验能力的接口，是后端开发的最小闭环

十二、Controller 常用注解详解（接口开发核心）

在 Spring Boot 中，接口开发主要依赖一组注解完成请求映射和参数解析。

本节对使用到的核心注解进行统一说明。

1. @RestController

@RestController
public class UserController {
}

作用

声明当前类是一个接口控制器（Controller），并且返回数据而不是页面

本质

@RestController = @Controller + @ResponseBody

2. @RequestMapping

@RequestMapping("/user")

作用

定义接口的统一路径前缀

示例

类上：/user
方法上：/register

最终路径：/user/register

3. @PostMapping / @GetMapping

@PostMapping("/register")
@GetMapping("/info")

作用

指定 HTTP 请求方式 + 路径

等价写法

@RequestMapping(value = "/register", method = RequestMethod.POST)

4. @RequestBody

public String register(@RequestBody UserRegisterDTO dto)

作用

将请求体中的 JSON 数据转换为 Java 对象

说明

适用于 POST / PUT 请求

5. @Valid

public String register(@Valid @RequestBody UserRegisterDTO dto)

作用

触发参数校验（结合 DTO 上的校验注解）

配合使用

@NotBlank(message = "用户名不能为空")
private String username;

6. @RequestParam

@GetMapping("/info")
public String getUser(@RequestParam String username)

作用

接收 URL 参数（查询参数）

示例

GET /user/info?username=test

7. @PathVariable

@DeleteMapping("/delete/{id}")
public String delete(@PathVariable Long id)

作用

从路径中提取参数

示例

DELETE /user/delete/1

8. @NotBlank（DTO中）

@NotBlank(message = "用户名不能为空")
private String username;

作用

定义参数校验规则（不能为空字符串）

9. 常见注解关系总结

@RestController：声明控制器
@RequestMapping：路径前缀
@PostMapping / GetMapping：请求类型
@RequestBody：接收JSON
@Valid：触发校验
@NotBlank：定义校验规则

10. 一句话总结

Controller 通过注解完成请求映射、参数解析和校验，是后端接口的核心入口层

tips：

Spring Boot 接口设计进阶：POST / PUT / DELETE 的本质区别与工程实践

下一篇：

Spring Boot 实战（三）：Service 层设计（从"能跑"到"像项目"）

Service 层（业务逻辑拆分）

将接口从：Service 层（业务逻辑拆分）

升级为：符合工程结构