Spring Boot 实战：从零构建企业级应用

Spring Boot 已经成为 Java 后端开发的事实标准。它通过约定优于配置的理念，极大地简化了 Spring 应用的初始搭建和开发过程。本文将从实战角度，分享构建企业级应用的最佳实践。

一、RESTful API 设计规范

RESTful API 设计的核心在于资源命名和 HTTP 动词的正确使用。以下是一个规范的 Controller 示例：

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "用户模块")
public class UserController {

    @Resource
    private IUserService userService;

    @PostMapping("/page")
    @Operation(summary = "查询用户列表")
    public SaResult getUsers(@Validated @RequestBody UserPageReq req) {
        return SaResult.data(userService.getUserPage(req));
    }

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情")
    public SaResult getUser(@PathVariable Long id) {
        return SaResult.data(userService.getUserById(id));
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息")
    public SaResult updateUser(@PathVariable Long id,
                               @Validated @RequestBody UserUpdateReq req) {
        return SaResult.success(userService.updateUser(id, req));
    }
}

关键要点：

使用 @Resource 进行依赖注入，而非 @Autowired
URL 使用复数名词（/users 而非 /user）
版本控制通过 URL 路径（/api/v1/）
统一返回格式（SaResult）

二、全局异常处理

企业级应用必须有一个统一的异常处理机制。Spring Boot 提供了 @RestControllerAdvice 来实现这一点：

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public SaResult handleValidation(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining("; "));
        return SaResult.error(msg).setCode(400);
    }

    @ExceptionHandler(Exception.class)
    public SaResult handleException(Exception e) {
        log.error("系统异常", e);
        return SaResult.error("系统内部错误").setCode(500);
    }
}

这种集中式异常处理确保了所有 API 的错误响应格式一致，前端可以统一处理错误提示。

三、分层架构：Controller / Service / Mapper

清晰的分层架构是代码可维护性的基石。推荐遵循以下原则：

Controller 层

仅负责请求路由、参数校验和响应封装。不包含任何业务逻辑。

Service 层

承载核心业务逻辑。接口与实现分离（IUserService + UserServiceImpl），方便单元测试和 AOP 代理。

Mapper 层

使用 MyBatis-Plus 提供的 BaseMapper，大部分 CRUD 操作无需手写 SQL。复杂查询通过 XML 或 QueryWrapper 实现。

// Service 实现示例
@Service
public class UserServiceImpl implements IUserService {

    @Resource
    private UserMapper userMapper;

    @Override
    public PageInfo<UserVO> getUserPage(UserPageReq req) {
        // 构建查询条件
        QueryWrapper<User> wrapper = new QueryWrapper<>()
                .like(StringUtils.isNotBlank(req.getName()),
                       "name", req.getName());

        // 使用 PageHelper 分页
        return PageHelper.startPage(req.getPageNum(), req.getPageSize())
                .doSelectPageInfo(() -> userMapper.selectList(wrapper));
    }
}

四、SLF4J 结构化日志

日志是线上排查问题的唯一线索。使用 SLF4J + Logback 组合，遵循以下规范：

@Slf4j
@Service
public class OrderServiceImpl implements IOrderService {

    public OrderVO createOrder(OrderReq req) {
        log.info("创建订单, userId={}, productId={}",
                req.getUserId(), req.getProductId());

        try {
            // 业务逻辑
            Order order = doCreateOrder(req);
            log.info("订单创建成功, orderId={}", order.getId());
            return convertToVO(order);
        } catch (Exception e) {
            log.error("订单创建失败, userId={}", req.getUserId(), e);
            throw new BusinessException("订单创建失败");
        }
    }
}

日志级别使用建议：

ERROR — 系统异常，需要立即处理
WARN — 潜在问题，不影响当前流程
INFO — 关键业务节点（订单创建、支付回调等）
DEBUG — 调试信息，生产环境关闭

五、总结

构建企业级 Spring Boot 应用，核心在于规范。从 API 设计到异常处理，从分层架构到日志规范，每一环都决定了代码的可维护性和团队的生产效率。坚持规范，代码才能越写越好。