SpringBoot通用组件技能

技能描述

为SpringBoot项目添加通用组件，包含统一响应、异常处理、AOP日志、用户上下文拦截器、响应处理Advice等功能。

使用场景

当用户需要在已有的SpringBoot项目基础上添加通用组件时使用此技能。

依赖关系

此技能依赖于 springboot-init 技能生成的基础项目结构。

依赖说明

更新的依赖

• 更新pom.xml，添加lombok、fastjson2、commons-lang3、commons-io依赖

包含的依赖

• org.projectlombok:lombok
• com.alibaba.fastjson2:fastjson2
• org.apache.commons:commons-lang3
• commons-io:commons-io

技能参数

• artifactId: 项目artifactId (必填，用于定位项目路径)
• packageName: 主包名 (必填)
• projectName: 项目名称 (可选,默认使用artifactId)
• author: 作者信息 (可选,默认"wql")
• fastjsonVersion: fastjson版本 (可选,不填则自动搜索最新稳定版本或使用默认)
• commonsLang3Version: commons-lang3版本 (可选,不填则自动搜索最新稳定版本或使用默认)
• commonsIoVersion: commons-io版本 (可选,不填则自动搜索最新稳定版本或使用默认)

版本策略

自动检测

• SpringBoot版本自动从pom.xml检测
• 根据SpringBoot版本自动选择javax.servlet或jakarta.servlet

优先级规则

1. 用户指定版本 > 在线搜索版本 > 默认版本
2. 如果有网络，尝试从Maven Central搜索最新稳定版本
3. 如果没有网络，使用预设的默认版本

默认版本

自动检测

• 自动从pom.xml检测SpringBoot版本
• 根据SpringBoot版本自动选择javax.servlet或jakarta.servlet

技能执行流程

1. 参数验证

• 验证必填参数
• 定位项目路径

2. 生成统一响应组件

• 生成Result统一响应类
• 生成ResultCode常量类
• 生成RequestUtils工具类
• 生成UserContext用户上下文工具类

3. 生成异常处理组件

• 生成BizException业务异常类
• 生成GlobalExceptionHandler全局异常处理器

4. 生成拦截器组件

• 生成UserContextInterceptor用户上下文拦截器
• 生成WebMvcConfig配置类

5. 生成AOP日志组件

• 生成ShowLog注解
• 生成ShowLogAspect日志切面
• 生成ResultAdvice响应处理Advice

功能说明

统一响应 (common包)

• Result: 统一响应类，支持成功/失败响应，包含requestId字段
• ResultCode: 响应码常量 (SUCCESS=200, FAIL=500)
• RequestUtils: 获取HttpServletRequest工具类
• UserContext: 基于ThreadLocal的用户上下文，管理userId、userCode和requestId，提供getUserCode()方法兼容旧代码

异常处理 (exception包)

• BizException: 业务异常类，支持自定义错误码
• GlobalExceptionHandler: 全局异常处理器

拦截器 (interceptor包)

• UserContextInterceptor: 从请求头提取x-user-id和x-request-id存入UserContext，如果userId为空则设置为空字符串
• WebMvcConfig: 注册拦截器，排除Swagger路径

AOP日志 (annotation/aspect包)

• ShowLog: 方法日志注解，支持 value/printArgs/printResult 配置
• ShowLogAspect: 日志切面，从 UserContext 获取 userId/requestId，分条打印入参和返回值
• 入参日志格式: -->>[userId][requestId][注解value]入参[json]
• 返回日志格式: <<--[userId][requestId][注解value]方法返回[json][成功标记][耗时]
• 异常时成功标记为 false，正常为 true

响应处理 (advice包)

• ResultAdvice: 实现ResponseBodyAdvice接口，如果返回类型为Result则自动填充requestId

代码规范

• 所有类必须有文档注释，包含功能描述、@author wql、创建时间
• 所有方法入参必须判空
• 方法返回值避免返回null
• 使用Objects进行判空检查
• UserContext使用ThreadLocal.withInitial初始化UserInfo

输出结果

constant/ResultCode.java              - 响应码常量
common/Result.java                    - 统一响应类
util/RequestUtils.java                - Request工具类
util/UserContext.java                 - 用户上下文工具类
exception/BizException.java           - 业务异常类
exception/GlobalExceptionHandler.java - 全局异常处理
interceptor/UserContextInterceptor.java - 用户上下文拦截器
config/WebMvcConfig.java              - WebMvc配置类
annotation/ShowLog.java               - 日志注解
aspect/ShowLogAspect.java             - 日志切面
advice/ResultAdvice.java              - 响应处理Advice

脚本执行

执行脚本添加通用组件：

python skill/springboot-common/scripts/common.py <artifactId> <packageName> [projectName] [author] [fastjsonVersion] [commonsLang3Version] [commonsIoVersion]

示例：

# 基本用法（自动检测SpringBoot版本，在线搜索最新版本）
python skill/springboot-common/scripts/common.py demo com.example

# 指定作者
python skill/springboot-common/scripts/common.py demo com.example Demo wql

# 指定所有版本
python skill/springboot-common/scripts/common.py demo com.example Demo wql 2.0.43 3.14.0 2.15.1