package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @RestController
 * 这是一个组合注解，它本身包含了 @Controller 和 @ResponseBody 两个注解。
 * 它的核心作用是：
 * 1. @Controller：向 Spring IoC 容器声明这是一个控制器（Controller）组件，
 * 使其能够被组件扫描（ComponentScan）机制发现并注册为 Bean。
 * 2. @ResponseBody：告知 Spring MVC 框架，本类中的所有方法返回的都不是视图名，
 * 而是需要直接写入 HTTP 响应体（Response Body）的数据。
 * 这是构建 RESTful API 的关键，意味着我们将直接返回 JSON、XML 或纯文本等数据。
 */
@RestController
public class HelloController {

    /**
     * @GetMapping("/hello")
     * 这是一个请求映射（Request Mapping）注解，用于处理 HTTP GET 请求。
     * 它是 @RequestMapping(method = RequestMethod.GET) 的一个更简洁的缩写形式。
     * 它的作用是将所有访问路径为 "/hello" 的 GET 请求，都路由到这个 sayHello() 方法上来进行处理。
     *
     * @return String
     * 由于类上标注了 @RestController，此方法返回的 String "Hello..." 将被
     * Spring MVC 视为响应体内容，通过 StringHttpMessageConverter 直接写入响应，
     * 最终在浏览器或 API 测试工具中呈现。
     */
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, 这是我的第一个 Spring MVC API!";
    }
}

package com.example.springbootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users") // 在类上定义父路径 /users
public class UserController {

    /**
     * 此方法的完整访问路径是类上的 @RequestMapping + 方法上的 @GetMapping
     * 即: /users + /all = /users/all
     */
    @GetMapping("/all")
    public String getAllUsers() {
        return "返回所有用户列表";
    }
}

// ... 省略 import 和类注解 ...
@RestController
@RequestMapping("/users")
public class UserController {

    // ... 已有的 getAllUsers() 方法 ...

    /**
     * {id} 是一个路径占位符。
     * @PathVariable("id") 注解会将 URL 中占位符 {id} 的实际值，
     * 绑定到方法的 Long id 参数上。
     * 例如，当请求 /users/101 时，id 参数的值就是 101。
     */
    @GetMapping("/{id}")
    public String getUserById(@PathVariable("id") Long id) {
        return "正在查询 ID 为: " + id + " 的用户";
    }
}

package com.example.springbootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AntController {

    // 匹配 /ant/testA, /ant/testB, 但不匹配 /ant/testAB
    @GetMapping("/ant/test?")
    public String testAnt1() {
        return "Ant-style match: ?";
    }

    // 匹配 /ant/test, /ant/testABC, 但不匹配 /ant/test/abc
    @GetMapping("/ant/test*")
    public String testAnt2() {
        return "Ant-style match: *";
    }

    // 匹配 /ant/any/path/can/be/here
    // 这个在 Springboot3 是会报错的！
    @GetMapping("/ant/**/any")
    public String testAnt3() {
        return "Ant-style match: **";
    }
}

package com.example.springbootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PreciseController {

    /**
     * 只有当请求 URL 中包含名为 "version" 的参数时，此方法才会被调用。
     * 例如: /precise?version = 1
     */
    @GetMapping(value = "/precise", params = "version")
    public String testParams() {
        return "Match with params 'version'";
    }

    /**
     * 只有当请求 URL 中包含名为 "version" 且其值等于 "2" 的参数时，才会被调用。
     * 例如: /precise?version = 2
     */
    @GetMapping(value = "/precise", params = "version=2")
    public String testParamsWithValue() {
        return "Match with params 'version=2'";
    }

    /**
     * 只有当请求头中包含名为 "X-API-VERSION" 的头信息时，此方法才会被调用。
     */
    @GetMapping(value = "/precise", headers = "X-API-VERSION")
    public String testHeaders() {
        return "Match with header 'X-API-VERSION'";
    }
}

package com.example.springbootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

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

    // ... 此前已有的方法 ...

    /**
     * @RequestParam 用于获取 URL 查询参数 (Query Parameter)。
     * * @param keyword 绑定 URL 中名为 "keyword" 的参数。如果 URL 是 /users/search?keyword = admin, keyword 的值就是 "admin"。
     * @param page 绑定名为 "page" 的参数。它有两个额外属性：
     * - required = false: 表示这个参数不是必需的。如果请求中不包含 page 参数，程序不会报错。
     * - defaultValue = "1": 如果请求中没有传递 page 参数，则默认为 "1"。
     * @return 响应字符串
     */
    @GetMapping("/search")
    public String searchUsers(
            // 这里一样的，可以省略
            @RequestParam String keyword,
            @RequestParam(value = "page", required = false, defaultValue = "1") Integer page) {

        return "正在搜索用户，关键词: " + keyword + ", 页码: " + page;
    }
}

package com.example.springbootdemo.model;

import lombok.Data;

@Data // Lombok 注解，自动生成 Getter, Setter, toString, equals, hashCode 等方法
public class User {
    private Long id;
    private String username;
    private String email;
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.model.User;
import org.springframework.web.bind.annotation.*;

// 注意，这里的 RestController 其实就是 @Controller + @ResponseBody
@RestController
@RequestMapping("/users") // 在类上定义父路径 /users
public class UserController {
    
    // ....其余的所有代码
    
    /**
     * @RequestBody 注解告诉 Spring MVC 将请求体中的 JSON 数据
     * 自动转换为一个 User 对象
     * @param user Spring MVC 自动实例化的 User 对象
     * @return 响应字符串
     */
    @PostMapping("/create")
    public String createUser(@RequestBody User user) {
        // 在实际项目中，这里会调用 Service 层将 user 对象存入数据库
        return "成功创建用户: " + user.toString();
    }
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.model.User;
import org.springframework.web.bind.annotation.GetMapping;
// ... 其他 import ...

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

    // ... 此前已有的方法 ...

    /**
     * 方法参数是一个 POJO (User user)，且没有 @RequestBody 注解。
     * Spring MVC 会自动将 URL 中的查询参数 ?username =...&email =... 
     * 绑定到 user 对象的 username 和 email 属性上。
     * @param user Spring MVC 自动实例化的 User 对象
     * @return 响应字符串
     */
    @GetMapping("/filter")
    public String filterUsers(User user) {
        return "根据条件筛选用户: " + user.toString();
    }
}

package com.example.springbootdemo.entity;

import lombok.Data;
@Data
public class User {
    private Long id;
    private String username;
    private String password; // 敏感字段
    private Integer status; // 1-正常, 2-禁用
}

package com.example.springbootdemo.vo;

import lombok.Data;

@Data
public class UserVO {
    private Long id;
    private String name;     // 对应 User 的 username
    private String statusText; // 对应 User 的 status
    // 注意：VO 中没有 password 属性，保证了安全
}

package com.example.springbootdemo.service;

import cn.hutool.core.bean.BeanUtil;
import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.vo.UserVO;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;

@Service
public class UserService {

    // 模拟数据库
    private static final Map<Long, User> userDatabase = new HashMap<>();
    static {
        User user1 = new User();
        user1.setId(1L);
        user1.setUsername("zhangsan");
        user1.setPassword("123456");
        user1.setStatus(1);
        userDatabase.put(1L, user1);
    }

    public User getUserById(Long id) {
        return userDatabase.get(id);
    }

    // 方案一：手动转换
    public UserVO convertToVOManual(User user) {
        if (user == null) {
            return null;
        }
        UserVO userVO = new UserVO();
        // 1. 先拷贝名称和类型都相同的属性
        BeanUtil.copyProperties(user, userVO);
        // 2. 手动处理名称不同或需要逻辑转换的属性
        userVO.setName(user.getUsername());
        if (user.getStatus() != null) {
            userVO.setStatusText(user.getStatus() == 1 ? "正常" : "已禁用");
        }
        return userVO;
    }
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

    @Autowired
    private UserService userService;

    // ... 此前已有的方法可以删除掉 ...

    @GetMapping("/vo/manual/{id}")
    public UserVO getUserVOManual(@PathVariable Long id) {
        User user = userService.getUserById(id);
        return userService.convertToVOManual(user);
    }
}

package com.example.springbootdemo.vo;

import cn.hutool.core.annotation.Alias;
import lombok.Data;

@Data
public class UserVO {
    private Long id;
    @Alias("username") // 告诉 Hutool, 这个 name 属性对应源对象的 username 属性
    private String name;
    private String statusText;
}

// ... 省略 import 和类 ...
@Service
public class UserService {
    // ... 已有代码 ...

    // 方案二：使用 @Alias 注解
    public UserVO convertToVOWithAlias(User user) {
        if (user == null) {
            return null;
        }
        UserVO userVO = new UserVO();
        // Hutool 会自动识别 @Alias 注解并完成 username -> name 的拷贝
        BeanUtil.copyProperties(user, userVO);
        // 依然需要手动处理 status -> statusText 的逻辑转换
        if (user.getStatus() != null) {
            userVO.setStatusText(user.getStatus() == 1 ? "正常" : "已禁用");
        }
        return userVO;
    }
}

// ... 省略 import 和类 ...
@RestController
@RequestMapping("/users")
public class UserController {
    // ... 已有代码 ...
    
    @GetMapping("/vo/alias/{id}")
    public UserVO getUserVOWithAlias(@PathVariable Long id) {
        User user = userService.getUserById(id);
        return userService.convertToVOWithAlias(user);
    }
}

package com.example.springbootdemo.service;

import com.example.springbootdemo.vo.UserVO;
import java.util.List;

public interface UserService {
    /**
     * 根据 ID 查询用户
     * @param id 用户 ID
     * @return 用户视图对象
     */
    UserVO findUserById(Long id);

    /**
     * 查询所有用户
     * @return 用户视图对象列表
     */
    List<UserVO> findAllUsers();
}

package com.example.springbootdemo.service.impl;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import org.springframework.stereotype.Service;

import java.util.List;

@Service // Service 注解注解在实现类上，因为只有实现类才有业务逻辑
public class UserServiceImpl implements UserService {
    

    @Override
    public UserVO findUserById(Long id) {
        return null;
    }

    @Override
    public List<UserVO> findAllUsers() {
        return List.of();
    }
}

package com.example.springbootdemo.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

@Data
@TableName("t_user")
public class User {

    @TableId(value = "id", type = IdType.AUTO)
    private Long id;
    private String username;
    private String password;
    private String email;
    private Integer status;
}

package com.example.springbootdemo.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.springbootdemo.entity.User;

public interface UserMapper extends BaseMapper<User> {
}

package com.example.springbootdemo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.springbootdemo.mapper") // 扫描 mapper 包下的所有接口
public class SpringBootDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootDemoApplication.class, args);
    }

}

package com.example.springbootdemo.dto.User;

import lombok.Data;

@Data
public class UserPageQuery {
    // 页码，默认值为 1
    private int pageNo = 1;
    
    // 每页条数，默认值为 10
    private int pageSize = 10;
}

package com.example.springbootdemo.config;

import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MybatisPlusConfig {

    /**
     * 添加分页插件
     */
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 向 MyBatis-Plus 的过滤器链中添加分页拦截器，并指定数据库类型为 MySQL
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

package com.example.springbootdemo.service;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.vo.UserVO;
import java.util.List;

public interface UserService {
    
    UserVO findUserById(Long id);

    /**
     * 修改方法签名，以接收分页查询参数
     * @param query 分页查询参数
     * @return 用户视图对象列表
     */
    List<UserVO> findAllUsers(UserPageQuery query);
}

package com.example.springbootdemo.service.impl;

import cn.hutool.core.bean.BeanUtil;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.mapper.UserMapper;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Collections;
import java.util.List;

@Service // Service 注解注解在实现类上，因为只有实现类才有业务逻辑
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;

    @Override
    public UserVO findUserById(Long id) {
        User user = userMapper.selectById(id);
        // 1. 调用 Mapper 方法从数据库查询 PO
        if (user == null) {
            return null;
        }
        // 2. 将 PO 转换为 VO
        return convertToVO(user);
    }

    @Override
    public List<UserVO> findAllUsers(UserPageQuery query) {
        Page<User> page = new Page<>(query.getPageNo(), query.getPageSize());

        // selectPage 返回的 Page 对象永远不会是 null，它的 records 列表也非 null
        Page<User> userPage = userMapper.selectPage(page, null);

        // 直接在 stream 上操作，如果 records 是空列表，stream().map()... 会自然地返回一个空列表
        return userPage.getRecords().stream()
                .map(this::convertToVO)
                .toList();
    }

    // 私有的转换方法，遵循在 2.1 节定义的转换逻辑
    private UserVO convertToVO(User user) {
        if (user == null) {
            return null;
        }
        // 此处我们 UserVO 中没有与 User 不同的属性名，所以直接拷贝
        // 如果有，则需在此处手动处理，如 userVO.setName(user.getUsername());
        UserVO userVO = new UserVO();
        BeanUtil.copyProperties(user, userVO);
        if (user.getStatus() != null) {
            userVO.setStatusText(user.getStatus() == 1 ? "正常" : "已禁用");
        }
        return userVO;
    }
}

package com.example.springbootdemo.service;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.vo.UserVO;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import java.util.List;

@SpringBootTest // 启动完整的 Spring Boot 应用上下文来进行测试
public class UserServiceTest {

    @Autowired
    private UserService userService;


    @Test
    void testFindAllUsers_Pagination() {
        // 测试分页查询
        UserPageQuery query = new UserPageQuery();
        query.setPageNo(1);
        query.setPageSize(5);
        List<UserVO> users = userService.findAllUsers(query);
        Assertions.assertNotNull(users);
        Assertions.assertEquals(5, users.size()); // 断言返回了 5 条记录
        System.out.println("第一页，5条数据：" + users);
    }
    // ...其余的 test 方法删除
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

// 注意，这里的 RestController 其实就是 @Controller + @ResponseBody
@RestController
@RequestMapping("/users") // 在类上定义父路径 /users
// 这个注解独属于 Lombok，针对类中用 final 修饰或标记了 @NonNull 的字段，自动生成对应的构造函数，减少代码冗余。
@RequiredArgsConstructor
public class UserController {
    // 构造函数注入能确保 userService 对象一定被注入，利于保证对象状态完整
    // 而且在进行依赖替换和测试时更方便，@Autowired 字段注入相对没这么严格。
    private final UserService userService;

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

    @GetMapping("/{id}")
    public ResponseEntity<UserVO> getUserById(@PathVariable Long id) {
        UserVO userVO = userService.findUserById(id);
        // 使用 ResponseEntity 来处理查询结果可能为 null 的情况
        // 如果 userVO 不为 null，返回 200 OK 和 userVO 数据
        // 如果 userVO 为 null，返回 404 Not Found
        return userVO != null ? ResponseEntity.ok(userVO) : ResponseEntity.notFound().build();
    }

}

`return userVO != null ? ResponseEntity.ok(userVO) : ResponseEntity.notFound().build();`

package com.example.springbootdemo.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Schema(description = "用户分页查询参数")
@Data
public class UserPageQuery {

    @Schema(description = "页码，从0开始", example = "0", defaultValue = "0")
    private int pageNo = 0;

    @Schema(description = "每页大小", example = "10", defaultValue = "10")
    private int pageSize = 10;
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Tag(name = "用户管理", description = "提供用户相关的CRUD接口") // 新增
@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;


    @GetMapping
    @Operation(summary = "查询所有用户列表")
    public List<UserVO> getAllUsers(
            @Parameter(
                    description = "分页查询参数",
                    required = true,
                    schema = @Schema(implementation = UserPageQuery.class)
            )
            UserPageQuery query) {
        return userService.findAllUsers(query);
    }

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询单个用户") // 新增
    public ResponseEntity<UserVO> getUserById(
            // 新增
            @Parameter(description = "用户ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        UserVO userVO = userService.findUserById(id);
        return userVO != null ? ResponseEntity.ok(userVO) : ResponseEntity.notFound().build();
    }

}

package com.example.springbootdemo.common;

import lombok.Getter;
import lombok.AllArgsConstructor;

@Getter
@AllArgsConstructor
public enum ResultCode {
    // 2xx: 成功
    SUCCESS(200, "操作成功"),

    // 4xx: 客户端错误
    BAD_REQUEST(400, "错误的请求"),
    UNAUTHORIZED(401, "未经授权"),
    NOT_FOUND(404, "资源未找到"),

    // 5xx: 服务器错误
    ERROR(500, "服务器内部错误"),
    SERVICE_UNAVAILABLE(503, "服务不可用"),

    // 100x: 自定义用户业务逻辑
    UserNotFound(1001, "用户未找到"),
    UserAlreadyExists(1002, "用户已存在"),
    UserNotLogin(1003, "用户未登录");

    private final int code;
    private final String message;
}

package com.example.springbootdemo.common;

import lombok.Getter;
import lombok.AccessLevel;
import lombok.AllArgsConstructor;
import java.io.Serializable;

/**
 * 最终推荐版本:
 * 1. 使用 @Getter 代替 @Data 去掉 setter，实现不变性。
 * 2. 字段声明为 final，确保只能在构造时赋值。
 * 3. 使用 @AllArgsConstructor(access = AccessLevel.PRIVATE) 自动生成私有全参构造，代码更简洁。
 */
@Getter
@AllArgsConstructor(access = AccessLevel.PRIVATE) // 自动生成私有全参构造函数
public final class Result<T> implements Serializable { // class 也可以声明为 final

    private final Integer code; // 业务状态码
    private final String message; // 提示信息
    private final T data; // 数据

    // 成功-无数据
    public static <T> Result<T> success() {
        return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);
    }

    // 成功-有数据
    public static <T> Result<T> success(T data) {
        return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    // 失败-使用预定义的 ResultCode 枚举，这是最规范的方式
    public static <T> Result<T> error(ResultCode resultCode) {
        return new Result<>(resultCode.getCode(), resultCode.getMessage(), null);
    }

    // 失败-自定义消息
    public static <T> Result<T> error(String message) {
        return new Result<>(ResultCode.ERROR.getCode(), message, null);
    }

    // 失败-自定义错误码和消息
    public static <T> Result<T> error(Integer code, String message) {
        return new Result<>(code, message, null);
    }

    // 失败-通用错误
    public static <T> Result<T> error() {
        return error(ResultCode.ERROR);
    }
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.common.Result;
import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Tag(name = "用户管理", description = "提供用户相关的CRUD接口")
@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

    // 通过构造函数注入 UserService 依赖
    private final UserService userService;

    @GetMapping
    @Operation(summary = "查询所有用户列表")
    public ResponseEntity<Result<List<UserVO>>> getAllUsers(
            @Parameter(
                    description = "分页查询参数",
                    required = true,
                    schema = @Schema(implementation = UserPageQuery.class)
            )
            UserPageQuery query) {
        // 调用服务层获取用户列表数据
        List<UserVO> users = userService.findAllUsers(query);
        // 使用 Result.success()包装数据并返回统一格式的响应
        return ResponseEntity.ok(Result.success(users));
    }
    
    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询单个用户")
    public ResponseEntity<Result<UserVO>> getUserById(
            @Parameter(description = "用户ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        // 调用服务层根据 ID 查询用户
        UserVO userVO = userService.findUserById(id);

        // 判断用户是否存在并返回相应结果
        if (userVO != null) {
            // 用户存在，返回成功结果
            return ResponseEntity.ok(Result.success(userVO));
        } else {
            // 用户不存在，返回错误信息 - 注意无论是成功或是失败都最好返回 200 响应码
            return ResponseEntity.ok(Result.error("用户不存在"));
        }
    }
}

package com.example.springbootdemo.dto.User;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户新增数据传输对象")
public class UserSaveDTO {

    @Schema(description = "用户名", required = true, example = "newuser")
    private String username;

    @Schema(description = "密码", required = true, example = "123456")
    private String password;

    @Schema(description = "邮箱", example = "newuser@example.com")
    private String email;
}

package com.example.springbootdemo.service;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.dto.UserSaveDTO; // 新增导入
import com.example.springbootdemo.vo.UserVO;
import java.util.List;

public interface UserService {

    UserVO findUserById(Long id);

    List<UserVO> findAllUsers(UserPageQuery query);

    /**
     * 新增用户
     * @param dto 用户新增数据
     * @return 新增用户的 ID
     */
    Long saveUser(UserSaveDTO dto);
}

package com.example.springbootdemo.service.impl;

import cn.hutool.core.bean.BeanUtil;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.dto.UserSaveDTO; // 新增导入
import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.mapper.UserMapper;
import com.example.springbootdemo.service.UserService;
import com.example.springbootdemo.vo.UserVO;
import lombok.RequiredArgsConstructor; // 使用构造函数注入
import org.springframework.stereotype.Service;

import java.util.Collections;
import java.util.List;
import java.util.Optional;

@Service
@RequiredArgsConstructor // Lombok 注解，为所有 final 字段生成一个构造函数
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper; // 使用 final 和构造函数注入

    // ... findUserById 和 findAllUsers 方法保持不变 ...
    
    @Override
    public Long saveUser(UserSaveDTO dto) {
        // 1. 业务校验：断言用户名不存在
        User existingUser = userMapper.selectOne(
                // 这里的条件转换为 SQL: SELECT *  FROM t_user WHERE username = ?
                new QueryWrapper<User>().lambda().eq(User::getUsername, dto.getUsername())
        );
        // 使用 HuTool 提供的断言工具优雅的抛出异常
        Assert.isNull(existingUser, "用户名 [{}] 已存在，请更换！", dto.getUsername());

        // 2. DTO -> PO: 使用 Convert 一步到位，创建并拷贝属性
        User user = Convert.convert(User.class, dto);

        // 3. 设置默认值
        user.setStatus(1); // 默认为正常状态

        // 4. 插入数据
        userMapper.insert(user);

        // 5. 返回 ID
        return user.getId();
    }
    
    // ... convertToVO 方法保持不变 ...
}

package com.example.springbootdemo.service;

import cn.hutool.core.util.IdUtil;
import cn.hutool.core.util.StrUtil;
import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.dto.User.UserSaveDTO;
import com.example.springbootdemo.vo.UserVO;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import java.util.List;

@SpringBootTest // 启动完整的 Spring Boot 应用上下文来进行测试
public class UserServiceTest {

    @Autowired
    private UserService userService;

    @Test
    void testSaveUser() {
        // 1. 准备 DTO
        UserSaveDTO dto = new UserSaveDTO();
        // 使用 Hutool 的 IdUtil 生成一个随机的用户名，防止重复
        String username = IdUtil.fastSimpleUUID();
        dto.setUsername(username);
        dto.setPassword("123456");
        dto.setEmail(username + "@test.com");
        // 2. 调用 Service 方法
        Long newUserId = userService.saveUser(dto);
        // 3. 断言返回的 ID 不为 null
        Assertions.assertNotNull(newUserId);
        // 4. 从数据库中查出新用户并进行验证
        UserVO savedUser = userService.findUserById(newUserId);
        Assertions.assertNotNull(savedUser);
        Assertions.assertEquals(username, savedUser.getName());
        System.out.println(StrUtil.format("用户 {} 保存成功", username));
    }


    @Test
    void testSaveUser_UsernameExists() {
        // 准备一个已存在的用户名的 DTO
        UserSaveDTO dto = new UserSaveDTO();
        dto.setUsername("张三"); // 假设 "张三" 已存在
        dto.setPassword("123456");
        userService.saveUser(dto); // java.lang.IllegalArgumentException: 用户名 [张三] 已存在，请更换！
    }
}

package com.example.springbootdemo.controller;

import com.example.springbootdemo.common.Result;
import com.example.springbootdemo.dto.UserSaveDTO;
// ... 其他 import ...
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
// ...

@Tag(name = "用户管理", description = "提供用户相关的CRUD接口")
@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    // ... 已有的 GET 接口 ...
    
    @Operation(summary = "新增用户")
    @PostMapping
    public ResponseEntity<Result<Long>> saveUser(@RequestBody UserSaveDTO dto) {
        Long userId = userService.saveUser(dto);
        // 对于创建操作 (POST)，RESTful 风格推荐返回 HTTP 状态码 201 Created
        // 我们将新创建的资源 ID 作为 data 返回
        return ResponseEntity.status(HttpStatus.CREATED).body(Result.success(userId));
    }
}

package com.example.springbootdemo.dto.User;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户修改数据传输对象")
public class UserUpdateDTO {

    @Schema(description = "用户ID", required = true, example = "1")
    private Long id;

    // 注意：我们在这里没有提供 username 字段，意味着我们不允许通过此接口修改用户名

    @Schema(description = "密码", example = "new_password_123")
    private String password;

    @Schema(description = "邮箱", example = "new_email@example.com")
    private String email;

    @Schema(description = "状态: 1-正常, 2-禁用", example = "2")
    private Integer status;
}

package com.example.springbootdemo.service;

import com.example.springbootdemo.dto.User.UserPageQuery;
import com.example.springbootdemo.dto.User.UserSaveDTO;
import com.example.springbootdemo.dto.User.UserUpdateDTO; // 新增导入
import com.example.springbootdemo.vo.UserVO;
import java.util.List;

public interface UserService {

    // ... 已有方法 ...

    Long saveUser(UserSaveDTO dto);

    /**
     * 修改用户
     * @param dto 用户修改数据
     */
    void updateUser(UserUpdateDTO dto);
}

package com.example.springbootdemo.service.impl;

import cn.hutool.core.bean.BeanUtil;
import cn.hutool.core.convert.Convert;
import cn.hutool.core.lang.Assert;
// ... 其他 import ...
import com.example.springbootdemo.dto.User.UserUpdateDTO;
import com.example.springbootdemo.entity.User;
// ...

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    // ... 已有方法 ...

    @Override
    public void updateUser(UserUpdateDTO dto) {
        // 1. 业务校验：断言要修改的用户必须存在
        User user = userMapper.selectById(dto.getId());
        Assert.notNull(user, "用户 ID [{}] 不存在，无法修改！", dto.getId());
        
        // 2. DTO -> PO: 使用 Convert 转换
        User updatedUser = Convert.convert(User.class, dto);

        // 3. 调用 Mapper 方法更新数据
        // updateById 方法会根据传入实体的主键 ID 去更新数据
        userMapper.updateById(updatedUser);
    }
    
    // ... convertToVO 方法保持不变 ...
}