DEV Community: YYT-0901

有了接口文档，快速开发前端页面的技巧

YYT-0901 — Sat, 19 Sep 2026 15:15:48 +0000

openapi-typescript

npm i -D openapi-typescript typescript

package.json 添加指令

"scripts": {
    "generate-api": "openapi-typescript http://localhost:8180/v3/api-docs -o src/api/generated/schema.d.ts"
  },

http://localhost:8180/v3/api-docs 替换成自己后端接口文档的地址

运行 npm run generate-api
会生成一个 src/api/generated/schema.d.ts ，里面就是所有的接口接口路径，schema

最好每个函数名都是不一样的，不然难以区分，比如你 AController 三个函数 add edit delete，BController 也是有 add edit delete。生成出来就会有 add_2 edit_2 delete_2

有了这个文件后，就丢给 AI 完成所有功能（样式无所谓），我一般使用 vscode 内置的 copilot，这里考验你的表达能力，你可以一次过把整个系统的功能讲完，需求要清晰要有适当的引用。
把功能调好后在美化样式，可以到 https://github.com/joshhu/uitest 选风格。然后使用免费的 cloudcode，喂他这个风格，然后一页一页的修改页面样式。自己动手改代码微调，或者使用 copilot。

Implement GitHub OAuth2 Authorization Login in Springboot

YYT-0901 — Sun, 13 Sep 2026 16:29:04 +0000

GitHub 登录本质上是 OAuth2 授权码模式

把用户重定向到 GitHub 授权页面
GitHub 授权后会跳转回你的回调接口，带上一个 code，你拿这个 code 换 access_token，再用 access_token 换用户信息，最后在你系统里"登录或注册"，签发自己的 JWT 返回给前端

流程图

flowchart TD
    A["用户点击 GitHub 登录按钮"]
    B["前端 location.href = 后端 /auth/loginByGithub"]
    C["后端 redirect 到 GitHub 授权页"]
    D["用户在 GitHub 点击授权"]
    E["GitHub redirect 到 /auth/callback/github?code=xxx"]
    F["后端 code 换 token，登录成功"]
    M["token存在redis30s，返回随机数code用于换取token"]
    G["后端 redirect 到前端页面?code=xxx"]
    H["前端页面加载"]
    I["从 URL 获取 code"]
    N["从服务器获取token等信息"]
    J["保存 token 到 localStorage"]
    K["跳转到首页"]
    L["后续 API 请求携带 token"]

    A --> B --> C --> D --> E --> F --> M --> G --> H --> I --> N --> J --> K --> L

0. 先去 GitHub 申请 OAuth App

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App，拿到 Client ID、Client Secret，并配置 Authorization callback URL（比如 http://your-domain.com/api/auth/callback/github）。

1. 配置文件

oauth:
  github:
    client-id: 你的client_id
    client-secret: 你的client_secret
    redirect-uri: http://your-domain.com/api/auth/callback/github
    frontend-callback-url: http://your-frontend-domain.com/callback
    authorize-url: https://github.com/login/oauth/authorize
    token-url: https://github.com/login/oauth/access_token
    user-info-url: https://api.github.com/user

@Data
@Component
@ConfigurationProperties(prefix = "oauth.github")
public class GithubOAuthProperties {
    private String clientId;
    private String clientSecret;
    private String redirectUri;
    private String authorizeUrl;
    private String tokenUrl;
    private String userInfoUrl;
    private String frontendCallbackUrl;
}

2. 第三方账号绑定表

不要把 github_id 直接塞进 sys_user 表，因为以后可能还要支持微信/QQ登录，用一张独立表比较好扩展：

CREATE TABLE `sys_user_oauth` (
  `id` bigint NOT NULL,
  `user_id` bigint NOT NULL COMMENT '关联本地用户ID',
  `platform` varchar(20) NOT NULL COMMENT '第三方平台，如github/wechat',
  `open_id` varchar(100) NOT NULL COMMENT '第三方平台唯一标识',
  `nickname` varchar(50) DEFAULT NULL COMMENT '第三方昵称',
  `avatar` varchar(255) DEFAULT NULL COMMENT '第三方头像',
  `create_at` datetime DEFAULT NULL,
  `update_at` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_platform_openid` (`platform`,`open_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='第三方账号绑定表';

3. controller

@Slf4j
@RestController
@RequestMapping("/auth")
@Tag(name = "认证相关接口")
public class AuthController {

    @Autowired
    private GithubOAuthProperties githubOAuthProperties;
    @Autowired
    private SysUserOauthService sysUserOauthService;
    @Autowired
    private RedisService redisService;

    @GetMapping("/loginByGithub")
    @Operation(summary = "通过Github登录", description = "通过Github登录，跳转到Github授权页面")
    public void loginByGithub(HttpServletResponse response) throws IOException {
        String state = UUID.randomUUID().toString(); // 防CSRF，实际项目应存入redis校验
        redisService.set("oauth:github:state:" + state, "1", 5, TimeUnit.MINUTES);
        String url = githubOAuthProperties.getAuthorizeUrl()
                + "?client_id=" + githubOAuthProperties.getClientId()
                + "&redirect_uri=" + URLEncoder.encode(githubOAuthProperties.getRedirectUri(), StandardCharsets.UTF_8)
                + "&scope=read:user user:email"
                + "&state=" + state;
        response.sendRedirect(url);
    }

    @GetMapping("/callback/github")
    @Operation(summary = "Github回调", description = "Github回调，保存登录信息，第一次登录则自动创建新用户，跳转回前端页面，参数带上放在redis中的值（tokenCode），后续用于获取token")
    public void callback(@RequestParam String code, @RequestParam(required = false) String state, HttpServletResponse response) throws IOException {
        if (state == null || !redisService.hasKey("oauth:github:state:" + state)) {
            log.info("Invalid state parameter {}", state);
            throw new BusinessException("Invalid state parameter");
        }
        LoginVo loginVo = sysUserOauthService.loginByGithub(code);
        // 重定向到前端页面，把token存储在redis，暴露code用于替换token 30s提高安全性，code当URL参数带过去
        String tokenCode = UUID.randomUUID().toString();
        redisService.set("oauth:token:code" + tokenCode, loginVo, 30, TimeUnit.SECONDS);
        String redirectUrl = githubOAuthProperties.getFrontendCallbackUrl() + "?code=" + tokenCode;
        response.sendRedirect(redirectUrl);
    }

    @GetMapping("/getToken")
    @Operation(summary = "获取Token")
    public Result getToken(@RequestParam String code) {
        if (!redisService.hasKey("oauth:token:code" + code)) {
            throw new BusinessException(ResultFailEnum.PARAMETER_ERROR);
        }
        LoginVo loginVo = (LoginVo) redisService.get("oauth:token:code" + code);
        return Result.ok(loginVo);
    }
}

redisService参考：https://dev.to/yyt0901/common-dependency-configuration-for-spring-boot-354-java-1721-1li7 （CTRL + F to search redisService in website）

@Data
public class LoginVo {
    private String token;
    private Long userId;
    private String nickname;
    private String avatar;
}

4. SysUserOauthServiceImpl

@Autowired
private GithubOAuthProperties githubOAuthProperties;
@Autowired
private RestTemplate restTemplate;
@Autowired
private SysUserService sysUserService;
@Autowired
private SysUserRoleService sysUserRoleService;

private static final String PLATFORM_GITHUB = "github";

@Override
public LoginVo loginByGithub(String code) {
    // ---------- 1. 用code换access_token ----------
    String accessToken = getGithubAccessToken(code);

    // ---------- 2. 用access_token换用户信息 ----------
    GithubUserInfo githubUser = getGithubUserInfo(accessToken);

    // ---------- 3. 查是否已绑定过 ----------
    SysUserOauth oauth = this.getOne(new LambdaQueryWrapper<SysUserOauth>()
            .eq(SysUserOauth::getPlatform, PLATFORM_GITHUB)
            .eq(SysUserOauth::getOpenId, githubUser.getId()));

    Date curDate = new Date();
    SysUser sysUser;

    if (oauth != null) {
        // ---------- 3a. 已绑定，直接登录 ----------
        sysUser = sysUserService.getById(oauth.getUserId());
        if (sysUser == null || sysUser.getStatus() == 0) {
            throw new BusinessException("账号不存在或已被禁用");
        }
        // 顺便更新一下第三方昵称/头像
        oauth.setNickname(githubUser.getName());
        oauth.setAvatar(githubUser.getAvatarUrl());
        oauth.setUpdateAt(curDate);
        this.updateById(oauth);
    } else {
        // ---------- 3b. 未绑定，自动注册新用户 ----------
        sysUser = new SysUser();
        sysUser.setId(IdTools.generateId());
        sysUser.setUsername("github_" + githubUser.getLogin());
        sysUser.setNickname(githubUser.getName() != null ? githubUser.getName() : githubUser.getLogin());
        sysUser.setAvatar(githubUser.getAvatarUrl());
        sysUser.setPassword(""); // 三方登录用户无本地密码，禁止走密码登录
        sysUser.setStatus(1);
        sysUser.setCreateAt(curDate);
        sysUser.setUpdateAt(curDate);
        sysUserService.save(sysUser);

        // 分配默认角色
        SysUserRole userRole = new SysUserRole();
        userRole.setId(IdTools.generateId());
        userRole.setUserId(sysUser.getId());
        userRole.setRoleId(RoleEnum.USER.getId());
        userRole.setCreateAt(curDate);
        sysUserRoleService.save(userRole);

        // 保存绑定关系
        SysUserOauth newOauth = new SysUserOauth();
        newOauth.setId(IdTools.generateId());
        newOauth.setUserId(sysUser.getId());
        newOauth.setPlatform(PLATFORM_GITHUB);
        newOauth.setOpenId(String.valueOf(githubUser.getId()));
        newOauth.setNickname(githubUser.getName());
        newOauth.setAvatar(githubUser.getAvatarUrl());
        newOauth.setCreateAt(curDate);
        newOauth.setUpdateAt(curDate);
        this.save(newOauth);
    }

    sysUser.setLastLoginTime(curDate);
    sysUserService.updateById(sysUser);

    // ---------- 4. Sa-Token 登录，自动生成并管理token ----------
    StpUtil.login(sysUser.getId());
    String token = StpUtil.getTokenValue();

    LoginVo vo = new LoginVo();
    vo.setToken(token);
    vo.setUserId(sysUser.getId());
    vo.setNickname(sysUser.getNickname());
    vo.setAvatar(sysUser.getAvatar());
    return vo;
}

/**
 * 用code换access_token
 */
private String getGithubAccessToken(String code) {
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_JSON);
    headers.setAccept(List.of(MediaType.APPLICATION_JSON));

    Map<String, String> body = new HashMap<>();
    body.put("client_id", githubOAuthProperties.getClientId());
    body.put("client_secret", githubOAuthProperties.getClientSecret());
    body.put("code", code);
    body.put("redirect_uri", githubOAuthProperties.getRedirectUri());

    HttpEntity<Map<String, String>> request = new HttpEntity<>(body, headers);

    ResponseEntity<Map> response = restTemplate.postForEntity(
            githubOAuthProperties.getTokenUrl(), request, Map.class);

    Map<String, Object> result = response.getBody();
    if (result == null || result.get("access_token") == null) {
        log.error("GitHub换取access_token失败: {}", result);
        throw new BusinessException("GitHub授权失败");
    }
    return (String) result.get("access_token");
}

/**
 * 用access_token查询GitHub用户信息
 */
private GithubUserInfo getGithubUserInfo(String accessToken) {
    HttpHeaders headers = new HttpHeaders();
    headers.set("Authorization", "token " + accessToken);
    headers.setAccept(List.of(MediaType.APPLICATION_JSON));

    HttpEntity<Void> request = new HttpEntity<>(headers);

    ResponseEntity<GithubUserInfo> response = restTemplate.exchange(
            githubOAuthProperties.getUserInfoUrl(), HttpMethod.GET, request, GithubUserInfo.class);

    GithubUserInfo userInfo = response.getBody();
    if (userInfo == null || userInfo.getId() == null) {
        throw new BusinessException("获取GitHub用户信息失败");
    }
    return userInfo;
}

@Data
@JsonIgnoreProperties(ignoreUnknown = true)
public class GithubUserInfo {
    private Long id;
    private String login;       // GitHub用户名
    private String name;        // 昵称，可能为空
    @JsonProperty("avatar_url")
    private String avatarUrl;
    private String email;       // 可能为空（用户设置了隐私）
}

Sa-Token necessary implement StpInterface

YYT-0901 — Sun, 13 Sep 2026 15:21:05 +0000

sql table reference: RBAC SQL table create

0. add global interceptor

@Configuration
public class SaTokenConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor())
                .addPathPatterns("/**");
    }
}

There has two function is must be override, which is getPermissionList and getRoleList, because sa-token unknown your structure of SQL. So, you want to tell it how to get your PermissionList and RoleList.

1. StpInterfaceImpl

@Component
public class StpInterfaceImpl implements StpInterface {

    @Autowired
    private SysPermissionService sysPermissionService;
    @Autowired
    private SysRoleService sysRoleService;

    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        Long userId = Long.valueOf(loginId.toString());
        return sysPermissionService.getPermissionCodesByUserId(userId);
    }

    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        Long userId = Long.valueOf(loginId.toString());
        return sysRoleService.getRoleCodesByUserId(userId);
    }
}

2. SysPermissionServiceImpl & SysRoleServiceImpl

@Override
public List<String> getPermissionCodesByUserId(Long userId) {
    return this.baseMapper.selectPermissionCodesByUserId(userId);
}

@Override
public List<String> getRoleCodesByUserId(Long userId) {
    return this.baseMapper.selectRoleCodesByUserId(userId);
}

3. SysPermissionMapper.xml & SysRoleMapper.xml

<select id="selectPermissionCodesByUserId" resultType="java.lang.String" parameterType="java.lang.Long">
    SELECT DISTINCT p.permission_code
    FROM sys_user_role ur
             JOIN sys_role r ON r.id = ur.role_id AND r.status = 1 AND r.deleted = 0
             JOIN sys_role_permission rp ON rp.role_id = r.id
             JOIN sys_permission p ON p.id = rp.permission_id AND p.status = 1 AND p.deleted = 0
    WHERE ur.user_id = #{userId}
</select>

<select id="selectRoleCodesByUserId" resultType="java.lang.String" parameterType="java.lang.Long">
    SELECT DISTINCT r.role_code
    FROM sys_user_role ur
             JOIN sys_role r ON r.id = ur.role_id
    WHERE ur.user_id = #{userId}
      AND r.status = 1
      AND r.deleted = 0
</select>

After that, Interface authentication becomes very simple:

@SaCheckLogin  // 必须登录
@SaCheckPermission("food:add")  // 必须有这个权限码
@SaCheckRole("ROLE_VIP")  // 必须是这个角色

utilize NGROK for Intranet penetration(内网穿透)

YYT-0901 — Sun, 13 Sep 2026 13:29:23 +0000

linux

   https://ngrok.com/

Install ngrok via Apt with the following command

   curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
     | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
     && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
     | sudo tee /etc/apt/sources.list.d/ngrok.list \
     && sudo apt update \
     && sudo apt install ngrok

Run the following command to add your authtoken to the default ngrok.yml configuration file.

   ngrok config add-authtoken <xxx>

<xxx>在官网查看

Setup - ngrok

deploy your app online

   ngrok http 80

写的是你要穿透的ip
ngrok http 8080

check response message

   Session Status                online                                                                 
   Account                       YYT-0901 (Plan: Free)                                                  
   Version                       3.35.0                                                                 
   Region                        Asia Pacific (ap)                                                      
   Latency                       23ms                                                                   
   Web Interface                 http://127.0.0.1:4040                                                  
   Forwarding                    https://unpurposing-aiko-undiscernably.ngrok-free.dev -> http://172.29.

   Connections                   ttl     opn     rt1     rt5     p50     p90                            
                                 4       0       0.00    0.00    30.23   65.39

https://unpurposing-aiko-undiscernably.ngrok-free.dev
就是外网可以访问的地址

RBAC SQL table create

YYT-0901 — Sun, 13 Sep 2026 10:22:46 +0000

the core is: User ↔ Role ↔ Permission

表结构总览

sys_user          用户表
sys_role          角色表
sys_permission    权限表（菜单/按钮/接口）
sys_user_role     用户-角色关联表（多对多）
sys_role_permission  角色-权限关联表（多对多）

1. sys_user

CREATE TABLE `sys_user` (
  `id` bigint NOT NULL COMMENT '用户ID',
  `username` varchar(50) NOT NULL COMMENT '登录账号',
  `password` varchar(100) NOT NULL COMMENT '密码（加密存储，如BCrypt）',
  `nickname` varchar(50) DEFAULT NULL COMMENT '昵称',
  `avatar` varchar(255) DEFAULT NULL COMMENT '头像',
  `phone` varchar(20) DEFAULT NULL COMMENT '手机号',
  `email` varchar(100) DEFAULT NULL COMMENT '邮箱',
  `gender` tinyint DEFAULT NULL COMMENT '性别(0:未知,1:男,2:女)',
  `status` tinyint DEFAULT '1' COMMENT '状态(1:正常,0:禁用)',
  `last_login_time` datetime DEFAULT NULL COMMENT '最后登录时间',
  `last_login_ip` varchar(50) DEFAULT NULL COMMENT '最后登录IP',
  `create_at` datetime DEFAULT NULL COMMENT '创建时间',
  `update_at` datetime DEFAULT NULL COMMENT '更新时间',
  `deleted` tinyint DEFAULT '0' COMMENT '逻辑删除(0:未删除,1:已删除)',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`),
  KEY `idx_phone` (`phone`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='用户表';

2. sys_role

CREATE TABLE `sys_role` (
  `id` bigint NOT NULL COMMENT '角色ID',
  `role_name` varchar(50) NOT NULL COMMENT '角色名称，如"管理员"',
  `role_code` varchar(50) NOT NULL COMMENT '角色编码，如ROLE_ADMIN，代码里用来判断权限',
  `description` varchar(255) DEFAULT NULL COMMENT '角色描述',
  `sort` int DEFAULT NULL COMMENT '排序',
  `status` tinyint DEFAULT '1' COMMENT '状态(1:启用,0:禁用)',
  `create_at` datetime DEFAULT NULL COMMENT '创建时间',
  `update_at` datetime DEFAULT NULL COMMENT '更新时间',
  `deleted` tinyint DEFAULT '0' COMMENT '逻辑删除',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_role_code` (`role_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='角色表';

3. sys_permission

CREATE TABLE `sys_permission` (
  `id` bigint NOT NULL COMMENT '权限ID',
  `parent_id` bigint DEFAULT '0' COMMENT '父级ID，顶级为0',
  `name` varchar(50) NOT NULL COMMENT '权限名称，如"食品管理"',
  `type` tinyint NOT NULL COMMENT '类型(1:目录,2:菜单,3:按钮/操作,4:接口)',
  `permission_code` varchar(100) DEFAULT NULL COMMENT '权限标识，如 food:add，用于代码里@PreAuthorize判断',
  `path` varchar(255) DEFAULT NULL COMMENT '前端路由路径',
  `component` varchar(255) DEFAULT NULL COMMENT '前端组件路径',
  `icon` varchar(100) DEFAULT NULL COMMENT '图标',
  `api_path` varchar(255) DEFAULT NULL COMMENT '接口路径，如 /food/add（type=4时使用）',
  `api_method` varchar(10) DEFAULT NULL COMMENT '请求方式 GET/POST/PUT/DELETE',
  `sort` int DEFAULT NULL COMMENT '排序',
  `status` tinyint DEFAULT '1' COMMENT '状态(1:启用,0:禁用)',
  `create_at` datetime DEFAULT NULL COMMENT '创建时间',
  `update_at` datetime DEFAULT NULL COMMENT '更新时间',
  `deleted` tinyint DEFAULT '0' COMMENT '逻辑删除',
  PRIMARY KEY (`id`),
  KEY `idx_parent_id` (`parent_id`),
  KEY `idx_permission_code` (`permission_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='权限表（菜单/按钮/接口）';

4. sys_user_role

CREATE TABLE `sys_user_role` (
  `id` bigint NOT NULL,
  `user_id` bigint NOT NULL COMMENT '用户ID',
  `role_id` bigint NOT NULL COMMENT '角色ID',
  `create_at` datetime DEFAULT NULL COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_role` (`user_id`,`role_id`),
  KEY `idx_role_id` (`role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='用户-角色关联表';

5. sys_role_permission

CREATE TABLE `sys_role_permission` (
  `id` bigint NOT NULL,
  `role_id` bigint NOT NULL COMMENT '角色ID',
  `permission_id` bigint NOT NULL COMMENT '权限ID',
  `create_at` datetime DEFAULT NULL COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_role_permission` (`role_id`,`permission_id`),
  KEY `idx_permission_id` (`permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='角色-权限关联表';

关系链路：用户 → 用户角色关联表 → 角色 → 角色权限关联表 → 权限

一个用户查权限的完整链路：

SELECT DISTINCT p.permission_code
FROM sys_user u
JOIN sys_user_role ur ON ur.user_id = u.id
JOIN sys_role r ON r.id = ur.role_id AND r.status = 1
JOIN sys_role_permission rp ON rp.role_id = r.id
JOIN sys_permission p ON p.id = rp.permission_id AND p.status = 1
WHERE u.id = ? AND u.status = 1;

use MyBatisX Plugin genarate entity data guide

YYT-0901 — Sat, 05 Sep 2026 05:49:36 +0000

Import dependencies

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.14</version>
</dependency>

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.42</version>
    <scope>compile</scope>
</dependency>

genarate

在idea的右边打开并连接数据库，全选要生成的字段，右键点击MybatisX-Generator

Common Dependency Configuration for Spring Boot 3.5.4 + Java 17/21

YYT-0901 — Fri, 04 Sep 2026 17:54:06 +0000

完整 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
         https://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.5.4</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>springboot-demo</artifactId>
    <version>1.0.0</version>

    <name>springboot-demo</name>
    <description>Spring Boot 3.5.4 Demo</description>

    <properties>
        <java.version>17</java.version>

        <!-- MyBatis-Plus -->
        <mybatis-plus.version>3.5.12</mybatis-plus.version>

        <!-- Sa-Token -->
        <sa-token.version>1.44.0</sa-token.version>

        <!-- SpringDoc -->
        <springdoc.version>2.8.9</springdoc.version>

        <!-- RocketMQ -->
        <rocketmq.version>2.3.4</rocketmq.version>

        <!-- Elasticsearch -->
        <elasticsearch.version>8.18.3</elasticsearch.version>

        <!-- MinIO -->
        <minio.version>8.5.17</minio.version>

        <!-- Hutool -->
        <hutool.version>5.8.39</hutool.version>

        <!-- MapStruct -->
        <mapstruct.version>1.6.3</mapstruct.version>

        <!-- Druid -->
        <druid.version>1.2.27</druid.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-validation</artifactId>
        </dependency>

        <!-- AOP -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>


        <!-- ================================================= -->
        <!-- MySQL -->
        <!-- ================================================= -->

        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>


        <!-- ================================================= -->
        <!-- MyBatis-Plus -->
        <!-- ================================================= -->

        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>

        <!-- 分页 / SQL Parser -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-jsqlparser</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Redis -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

        <!-- Spring Cache -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>


        <!-- ================================================= -->
        <!-- Sa-Token -->
        <!-- ================================================= -->

        <dependency>
            <groupId>cn.dev33</groupId>
            <artifactId>sa-token-spring-boot3-starter</artifactId>
            <version>${sa-token.version}</version>
        </dependency>

        <!-- Sa-Token Redis -->
        <dependency>
            <groupId>cn.dev33</groupId>
            <artifactId>sa-token-redis-template</artifactId>
            <version>${sa-token.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- RocketMQ -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.apache.rocketmq</groupId>
            <artifactId>rocketmq-spring-boot-starter</artifactId>
            <version>${rocketmq.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Elasticsearch -->
        <!-- ================================================= -->

        <dependency>
            <groupId>co.elastic.clients</groupId>
            <artifactId>elasticsearch-java</artifactId>
            <version>${elasticsearch.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- MinIO -->
        <!-- ================================================= -->

        <dependency>
            <groupId>io.minio</groupId>
            <artifactId>minio</artifactId>
            <version>${minio.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Swagger / OpenAPI -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Lombok -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>


        <!-- ================================================= -->
        <!-- MapStruct -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${mapstruct.version}</version>
        </dependency>

        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct-processor</artifactId>
            <version>${mapstruct.version}</version>
            <scope>provided</scope>
        </dependency>


        <!-- ================================================= -->
        <!-- Hutool -->
        <!-- ================================================= -->

        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>${hutool.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Druid -->
        <!-- ================================================= -->

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-3-starter</artifactId>
            <version>${druid.version}</version>
        </dependency>


        <!-- ================================================= -->
        <!-- Actuator -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>


        <!-- ================================================= -->
        <!-- Test -->
        <!-- ================================================= -->

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

    </dependencies>


    <!-- ===================================================== -->
    <!-- Build -->
    <!-- ===================================================== -->

    <build>

        <plugins>

            <!-- Spring Boot -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>

        </plugins>

    </build>

</project>

Spring Boot 3.5.4 + Java 17 + MySQL + MyBatis-Plus + Redis + Sa-Token + RocketMQ + Elasticsearch + MinIO + OpenAPI + Lombok + MapStruct + Hutool + AOP + Validation + Actuator + Test

aplication.yml

server:
  port: 8080

spring:
  application:
    name: springboot-demo

  # ==================== 数据库 ====================
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: 123456

    druid:
      initial-size: 5
      min-idle: 5
      max-active: 20
      max-wait: 60000

  # ==================== Redis ====================
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      database: 0
      password:

      timeout: 5s

      lettuce:
        pool:
          max-active: 20
          max-idle: 10
          min-idle: 5
          max-wait: 5s

  # ==================== Cache ====================
  cache:
    type: redis


# ==================================================
# MyBatis-Plus
# ==================================================

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml

  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0


# ==================================================
# Sa-Token
# ==================================================

sa-token:

  # Token 名称
  token-name: satoken

  # Token 有效期，单位：秒
  timeout: 2592000

  # Token 最低活跃频率
  active-timeout: 1800

  # 是否允许同一账号多地同时登录
  is-concurrent: true

  # 同一账号最大登录数量
  max-login-count: 2

  # Token 风格
  token-style: uuid-simple

  # 是否打印日志
  is-log: true


# ==================================================
# RocketMQ
# ==================================================

rocketmq:
  name-server: 127.0.0.1:9876

  producer:
    group: ${spring.application.name}-producer
    send-message-timeout: 3000

  consumer:
    group: ${spring.application.name}-consumer


# ==================================================
# Elasticsearch
# ==================================================

elasticsearch:
  url: http://127.0.0.1:9200
  username: elastic
  password: 123456


# ==================================================
# MinIO
# ==================================================

minio:
  endpoint: http://127.0.0.1:9000
  access-key: minioadmin
  secret-key: minioadmin
  bucket-name: demo


# ==================================================
# SpringDoc
# ==================================================

springdoc:
  api-docs:
    path: /v3/api-docs

  swagger-ui:
    path: /swagger-ui.html


# ==================================================
# Actuator
# ==================================================

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

  endpoint:
    health:
      show-details: always

RedisConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.StringRedisSerializer;

@Configuration
public class RedisConfig {

    /**
     * RedisTemplate<String, Object>
     */
    @Bean
    public RedisTemplate<String, Object> redisTemplate(
            RedisConnectionFactory connectionFactory) {

        RedisTemplate<String, Object> template =
                new RedisTemplate<>();

        template.setConnectionFactory(connectionFactory);

        // Key 使用 String
        StringRedisSerializer stringSerializer =
                new StringRedisSerializer();

        // Value 使用 JSON
        GenericJackson2JsonRedisSerializer jsonSerializer =
                new GenericJackson2JsonRedisSerializer();

        // Key
        template.setKeySerializer(stringSerializer);

        // Value
        template.setValueSerializer(jsonSerializer);

        // Hash Key
        template.setHashKeySerializer(stringSerializer);

        // Hash Value
        template.setHashValueSerializer(jsonSerializer);

        template.afterPropertiesSet();

        return template;
    }
}

RedisService

@Service
@RequiredArgsConstructor
public class RedisService {

    private final RedisTemplate<String, Object> redisTemplate;


    // =====================================================
    // String
    // =====================================================

    /**
     * 设置值
     */
    public void set(String key, Object value) {
        redisTemplate.opsForValue()
                .set(key, value);
    }

    /**
     * 设置值 + 过期时间
     */
    public void set(
            String key,
            Object value,
            long timeout,
            TimeUnit unit) {

        redisTemplate.opsForValue()
                .set(key, value, timeout, unit);
    }

    /**
     * 设置值 + Duration
     */
    public void set(
            String key,
            Object value,
            Duration timeout) {

        redisTemplate.opsForValue()
                .set(key, value, timeout);
    }

    /**
     * 获取值
     */
    public Object get(String key) {
        return redisTemplate.opsForValue()
                .get(key);
    }

    /**
     * 获取指定类型
     */
    public <T> T get(
            String key,
            Class<T> clazz) {

        Object value = get(key);

        if (value == null) {
            return null;
        }

        return clazz.cast(value);
    }

    /**
     * 删除
     */
    public Boolean delete(String key) {
        return redisTemplate.delete(key);
    }

    /**
     * 批量删除
     */
    public Long delete(Collection<String> keys) {
        return redisTemplate.delete(keys);
    }

    /**
     * 判断 Key 是否存在
     */
    public Boolean hasKey(String key) {
        return redisTemplate.hasKey(key);
    }

    /**
     * 设置过期时间
     */
    public Boolean expire(
            String key,
            long timeout,
            TimeUnit unit) {

        return redisTemplate.expire(
                key,
                timeout,
                unit
        );
    }

    /**
     * 获取剩余过期时间
     */
    public Long getExpire(
            String key,
            TimeUnit unit) {

        return redisTemplate.getExpire(
                key,
                unit
        );
    }


    // =====================================================
    // Hash
    // =====================================================

    /**
     * Hash 设置
     */
    public void hSet(
            String key,
            String hashKey,
            Object value) {

        redisTemplate.opsForHash()
                .put(key, hashKey, value);
    }

    /**
     * Hash 获取
     */
    public Object hGet(
            String key,
            String hashKey) {

        return redisTemplate.opsForHash()
                .get(key, hashKey);
    }

    /**
     * Hash 删除
     */
    public Long hDelete(
            String key,
            Object... hashKeys) {

        return redisTemplate.opsForHash()
                .delete(key, hashKeys);
    }

    /**
     * Hash 是否存在
     */
    public Boolean hHasKey(
            String key,
            String hashKey) {

        return redisTemplate.opsForHash()
                .hasKey(key, hashKey);
    }


    // =====================================================
    // List
    // =====================================================

    /**
     * 左侧添加
     */
    public Long leftPush(
            String key,
            Object value) {

        return redisTemplate.opsForList()
                .leftPush(key, value);
    }

    /**
     * 右侧添加
     */
    public Long rightPush(
            String key,
            Object value) {

        return redisTemplate.opsForList()
                .rightPush(key, value);
    }

    /**
     * 获取 List
     */
    public List<Object> range(
            String key,
            long start,
            long end) {

        return redisTemplate.opsForList()
                .range(key, start, end);
    }


    // =====================================================
    // Set
    // =====================================================

    public Long sAdd(
            String key,
            Object... values) {

        return redisTemplate.opsForSet()
                .add(key, values);
    }

    public Set<Object> sMembers(String key) {

        return redisTemplate.opsForSet()
                .members(key);
    }

    public Boolean sIsMember(
            String key,
            Object value) {

        return redisTemplate.opsForSet()
                .isMember(key, value);
    }


    // =====================================================
    // Increment
    // =====================================================

    /**
     * 自增
     */
    public Long increment(String key) {

        return redisTemplate.opsForValue()
                .increment(key);
    }

    /**
     * 自增指定数值
     */
    public Long increment(
            String key,
            long delta) {

        return redisTemplate.opsForValue()
                .increment(key, delta);
    }

    /**
     * 自减
     */
    public Long decrement(String key) {

        return redisTemplate.opsForValue()
                .decrement(key);
    }
}

ElasticsearchConfig.java

@Configuration
public class ElasticsearchConfig {

    @Value("${elasticsearch.url}")
    private String url;

    @Value("${elasticsearch.username}")
    private String username;

    @Value("${elasticsearch.password}")
    private String password;

    @Bean
    public ElasticsearchClient elasticsearchClient() {

        RestClient restClient = RestClient.builder(
                HttpHost.create(url)
        )
        .setDefaultHeaders(new Header[]{
                new BasicHeader(
                        HttpHeaders.AUTHORIZATION,
                        Credentials.basic(
                                username,
                                password
                        )
                )
        })
        .build();

        ElasticsearchTransport transport =
                new RestClientTransport(
                        restClient,
                        new JacksonJsonpMapper()
                );

        return new ElasticsearchClient(transport);
    }
}

MinioProperties.java

@Data
@Component
@ConfigurationProperties(prefix = "minio")
public class MinioProperties {

    private String endpoint;

    private String accessKey;

    private String secretKey;

    private String bucketName;
}

MinioConfig.java

@Configuration
@RequiredArgsConstructor
public class MinioConfig {

    private final MinioProperties properties;

    @Bean
    public MinioClient minioClient() {

        return MinioClient.builder()
                .endpoint(properties.getEndpoint())
                .credentials(
                        properties.getAccessKey(),
                        properties.getSecretKey()
                )
                .build();
    }
}

MinioService.java

@Service
@RequiredArgsConstructor
public class MinioService {

    private final MinioClient minioClient;

    private final MinioProperties properties;

    public String upload(MultipartFile file)
            throws Exception {

        String filename =
                UUID.randomUUID()
                        + "-" + file.getOriginalFilename();

        minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(properties.getBucketName())
                        .object(filename)
                        .stream(
                                file.getInputStream(),
                                file.getSize(),
                                -1
                        )
                        .contentType(file.getContentType())
                        .build()
        );

        return filename;
    }
}

全局

ResultFailEnum.java

import lombok.AllArgsConstructor;
import lombok.Getter;

@Getter
@AllArgsConstructor
public enum ResultFailEnum {
    NOT_FOUND(404, "请求地址不存在"),
    MESSAGE_DATA_DUPLICATE(601, "信息已经存在"),
    SERVER_ERROR(500, "服务器返回错误"),
    PARAMETER_ERROR(600, "请求参数错误");

    private final Integer code;
    private final String message;
}

Result.java

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> {
    private static final String SUCCESS = "success";
    private static final String SUCCESS_MESSAGE = "请求成功";
    private static final String FAIL = "error";

    private Integer code;

    private String status;

    private String message;

    private T data;

    public static <T> Result<T> ok() {

        return Result.<T>builder()
                .code(200)
                .status(SUCCESS)
                .message(SUCCESS_MESSAGE)
                .build();
    }

    public static <T> Result<T> ok(T data) {

        return Result.<T>builder()
                .code(200)
                .status(SUCCESS)
                .message(SUCCESS_MESSAGE)
                .data(data)
                .build();
    }

    public static <T> Result<T> fail(
            String message) {

        return Result.<T>builder()
                .code(500)
                .status(FAIL)
                .message(message)
                .build();
    }

    public static <T> Result<T> fail(
            ResultFailEnum resultFailEnum) {

        return Result.<T>builder()
                .code(resultFailEnum.getCode())
                .status(FAIL)
                .message(resultFailEnum.getMessage())
                .build();
    }
}

BusinessException

@Getter
public class BusinessException extends RuntimeException {
    private ResultFailEnum codeEnum;
    private Integer code;
    private String message;

    public BusinessException(String message, Throwable e) {
        super(message, e);
        this.message = message;
    }

    public BusinessException(String message) {
        super(message);
        this.message = message;
    }

    public BusinessException(Throwable e) {
        super(e);
    }

    public BusinessException(ResultFailEnum codeEnum) {
        super(codeEnum.getMessage());
        this.codeEnum = codeEnum;
        this.code = codeEnum.getCode();
        this.message = codeEnum.getMessage();
    }

    public BusinessException(Integer code, String message) {
        super(message);
        this.code = code;
        this.message = message;
    }

    @Override
    public synchronized Throwable fillInStackTrace() {
        return this;
    }
}

GlobalExceptionHandler

import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.ConstraintViolationException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.validation.BindException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
import org.springframework.web.servlet.NoHandlerFoundException;

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    @ExceptionHandler(value = Exception.class)
    Object handleException(Exception e, HttpServletRequest request) {
        log.error("请求错误，请求地址{},错误信息:", request.getRequestURL(), e);
        Result ajaxResponse = new Result();
        //404
        String FAIL = "error";
        if (e instanceof NoHandlerFoundException) {
            ajaxResponse.setCode(ResultFailEnum.NOT_FOUND.getCode());
            ajaxResponse.setMessage(ResultFailEnum.NOT_FOUND.getMessage());
            ajaxResponse.setStatus(FAIL);
        } else if (e instanceof BusinessException) {
            //业务错误
            BusinessException biz = (BusinessException) e;
            ajaxResponse.setCode(biz.getCode() == null ? ResultFailEnum.PARAMETER_ERROR.getCode() : biz.getCode());
            ajaxResponse.setMessage(biz.getMessage());
            ajaxResponse.setStatus(FAIL);
        } else if (e instanceof BindException || e instanceof MethodArgumentTypeMismatchException) {
            //参数类型错误
            ajaxResponse.setCode(ResultFailEnum.PARAMETER_ERROR.getCode());
            ajaxResponse.setMessage(ResultFailEnum.PARAMETER_ERROR.getMessage());
            ajaxResponse.setStatus(FAIL);
        } else if (e instanceof DuplicateKeyException) {
            //主键冲突
            ajaxResponse.setCode(ResultFailEnum.MESSAGE_DATA_DUPLICATE.getCode());
            ajaxResponse.setMessage(ResultFailEnum.MESSAGE_DATA_DUPLICATE.getMessage());
            ajaxResponse.setStatus(FAIL);
        } else if (e instanceof ConstraintViolationException || e instanceof BindException) {
            //请求参数错误
            ConstraintViolationException ce = (ConstraintViolationException) e;
            ajaxResponse.setCode(ResultFailEnum.PARAMETER_ERROR.getCode());
            ajaxResponse.setMessage(ResultFailEnum.PARAMETER_ERROR.getMessage());
            ajaxResponse.setStatus(FAIL);
        } else {
            ajaxResponse.setCode(ResultFailEnum.SERVER_ERROR.getCode());
            ajaxResponse.setMessage(ResultFailEnum.SERVER_ERROR.getMessage());
            ajaxResponse.setStatus(FAIL);
        }
        return ajaxResponse;
    }
}

解决端口占用问题（window）

YYT-0901 — Thu, 03 Sep 2026 11:01:36 +0000

方案一：最快解决办法（重置网络端口保留）

大多数情况下，这是因为 Windows 的 NAT 服务（WinNat）保留了该端口。重启该服务通常能释放被错误保留的端口。

请以 管理员身份 打开 PowerShell 或 CMD，然后依次运行以下命令：

net stop winnat
net start winnat

运行完这两行命令后，再次尝试启动你的服务。如果成功，问题解决。

方案二：检查端口是否真的被占用

如果方案一无效，说明端口可能真的被其他软件（如 PHP-FPM, SonarQube, MinIO 等）占用了。

打开 CMD 或 PowerShell。
运行以下命令查看 9000 端口的情况：

   netstat -ano | findstr :9000

结果分析：

如果有输出（例如 TCP 0.0.0.0:9000 ... PID 1234）：说明有进程（PID 1234）正在使用它。
- 打开任务管理器 -> 详细信息 -> 找到 PID 1234 -> 结束任务。
如果没有输出：说明没有程序在用。