前言¶

在 SpringBoot 项目开发中，统一响应格式、全局异常处理、用户上下文传递和日志打印是常见的重复工作。开发者往往需要为每个接口手动封装返回结果、处理各种异常情况、手动传递用户信息、编写重复的日志代码。这些工作占用了大量精力，且容易因疏忽导致代码不一致。

下面介绍一个为此场景设计的 Skill，它将上述功能封装为可复用的组件，开发者只需引入即可统一处理这些通用逻辑。

这是什么¶

这是一个为 SpringBoot 项目添加通用组件的 Skill，由社区用户 user_faca7523 发布。它提供了一套统一的异常处理机制、用户上下文管理、日志打印注解和响应封装方案，帮助项目在开发阶段就建立标准化的业务处理流程。

该 Skill 依赖于 springboot-init 生成的基础项目结构，完成统一响应、异常处理、AOP 日志、用户上下文拦截器和响应处理 Advice 五大核心功能。

核心功能¶

• 统一响应封装（Result）：提供标准化的响应格式，便于前端统一解析
• 异常处理机制：包含自定义业务异常（BizException）和全局异常处理器（GlobalExceptionHandler），统一捕获和处理各类异常
• AOP 日志注解（ShowLog）：通过注解方式简化日志打印逻辑，无需在每个方法中手动编写
• 用户上下文拦截器（UserContextInterceptor）：在请求链路中自动传递和获取用户信息
• 响应处理 Advice（ResultAdvice）：对 Controller 返回值进行统一封装

安装与启用¶

该 Skill 依赖 springboot-init 生成的基础项目结构。安装后，相关组件会自动注入到项目中，无需额外配置。

使用 SkillHub 安装时，可执行以下命令（具体命令取决于 SkillHub 客户端）：

skill install user_faca7523/springboot-common

安装完成后，确保项目依赖了 springboot-init 的基础结构，即可直接使用以下组件。

典型用法¶

统一响应¶

Controller 返回值会被 ResultAdvice 自动封装为统一格式：

@RestController
@RequestMapping("/api")
public class DemoController {

    @GetMapping("/user")
    public Result<User> getUser() {
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        return Result.success(user);
    }
}

异常处理¶

抛出自定义业务异常后，GlobalExceptionHandler 会自动捕获并返回统一格式：

@GetMapping("/order/{id}")
public Result<Order> getOrder(@PathVariable Long id) {
    if (id <= 0) {
        throw new BizException("订单 ID 必须大于 0");
    }
    return Result.success(orderService.getById(id));
}

AOP 日志注解¶

在需要记录日志的方法上添加 ShowLog 注解：

@ShowLog
@GetMapping("/order/{id}")
public Result<Order> getOrder(@PathVariable Long id) {
    return Result.success(orderService.getById(id));
}

用户上下文¶

通过 UserContextInterceptor 自动获取当前请求中的用户信息：

@Service
public class OrderService {

    public Result<Order> createOrder() {
        Long userId = UserContext.getUserId();
        // 业务逻辑...
    }
}

适用场景与注意¶

• 适合需要统一响应格式、全局异常处理、用户上下文传递和标准化日志打印的 SpringBoot 项目
• 需要确保项目已通过 springboot-init 生成基础结构
• 注意异常类型要与 GlobalExceptionHandler 中的处理逻辑匹配
• 用户上下文信息需要在请求拦截器中正确设置，否则可能获取不到

结尾¶

这套组件帮助 SpringBoot 项目快速建立统一的异常处理和响应机制，减少重复代码，提高开发效率。如需使用，可访问官方地址查看详情：https://api.skillhub.cn/user_faca7523/springboot-common