Spring Boot

Spring Boot 后端开发规范

技术栈

目录结构

src/main/java/com/youlai/boot/
├── YouLaiBootApplication.java      # 启动类
├── common/                         # 公共模块（常量/枚举/工具/基类）
├── framework/                      # 框架层（不依赖业务模块）
│   ├── security/                   # 安全内核（通用，Port 接口解耦）
│   │   ├── port/                   # UserAuthenticationPort, PermissionPort
│   │   ├── service/                # SecurityUserDetailsService, PermissionService
│   │   └── token/                  # TokenManager, JwtTokenManager, RedisTokenManager
│   ├── mybatis/                    # MybatisConfig, MyMetaObjectHandler
│   ├── cache/                      # RedisConfig
│   └── web/                        # Web 基础设施
│       ├── advice/                 # GlobalExceptionHandler
│       ├── filter/                 # 请求过滤器
│       ├── log/                    # OperationLogPort, OperationLogAspect, OperationLog
│       ├── ratelimit/              # 限流脚本
│       └── util/                   # Web 工具
├── auth/                           # 认证模块（登录、Token 发放）
│   ├── controller/                 # AuthController
│   └── security/                   # 认证流程实现（Provider/Filter/Handler）
├── system/                         # 系统管理模块（用户/角色/菜单/部门/字典）
│   ├── controller/                 # UserController 等
│   ├── converter/                  # MapStruct Converter
│   ├── mapper/                     # MyBatis-Plus Mapper
│   ├── model/                      # entity/ form/ query/ vo/ dto/
│   ├── service/                    # Service + impl/
│   └── adapter/                    # 实现 framework 层 Port
│       ├── log/                    # OperationLogAdapter
│       └── security/               # UserAuthenticationAdapter, PermissionAdapter
├── codegen/                        # 代码生成模块
├── file/                           # 文件管理模块
└── message/                        # 消息推送模块（SSE）

设计原则：common/ 被所有层共享；framework/ 不依赖业务模块，通过 Port 接口解耦；auth/ 含认证流程实现；system/ 通过 Adapter 实现 Port。

命名规范

类命名

DTO 后缀

方法命名

import 排序

// 1. java.* / jakarta.* 标准库
// 2. org.springframework.* Spring 框架
// 3. 第三方库（cn.hutool, com.baomidou, io.swagger 等）
// 4. 项目内部（com.youlai.boot.*，按 common → framework → 业务模块排序）

RESTful API 规范

路径命名

• 资源路径：/api/v1/{资源复数}，如 /api/v1/users
• 子资源：/{id}/menus、/{id}/form、/{id}/status

标准 CRUD

Controller 模板

@Tag(name = "03.角色接口")
@RestController
@RequestMapping("/api/v1/roles")
@RequiredArgsConstructor
public class RoleController {

    private final RoleService roleService;

    @Operation(summary = "角色分页列表")
    @GetMapping
    @Log(module = LogModuleEnum.ROLE, value = ActionTypeEnum.LIST)
    public PageResult<RolePageVO> getRolePage(RoleQuery queryParams) {
        Page<RolePageVO> result = roleService.getRolePage(queryParams);
        return PageResult.success(result);
    }

    @Operation(summary = "新增角色")
    @PostMapping
    @PreAuthorize("@ss.hasPerm('sys:role:create')")
    @RepeatSubmit
    @Log(module = LogModuleEnum.ROLE, value = ActionTypeEnum.INSERT)
    public Result<?> addRole(@Valid @RequestBody RoleForm roleForm) {
        return Result.judge(roleService.saveRole(roleForm));
    }

    @Operation(summary = "删除角色")
    @DeleteMapping("/{ids}")
    @PreAuthorize("@ss.hasPerm('sys:role:delete')")
    @Log(module = LogModuleEnum.ROLE, value = ActionTypeEnum.DELETE)
    public Result<Void> deleteRoles(@PathVariable String ids) {
        roleService.deleteRoles(ids);
        return Result.success();
    }
}

Controller 注解

响应格式与异常处理

统一响应 Result

{ "code": "00000", "msg": "成功", "data": { "id": 1, "username": "admin" } }

@Data
public class Result<T> implements Serializable {
    private String code;  // String，5 位
    private String msg;
    private T data;

    public static <T> Result<T> success(T data) { ... }
    public static <T> Result<T> failed(String msg) { ... }
    public static <T> Result<T> judge(boolean status) { return status ? success() : failed(); }
}

分页响应 PageResult

{ "code": "00000", "msg": "成功", "data": { "list": [ ... ], "total": 100 } }

分页接口直接返回 PageResult，非分页接口返回 Result，两者并列。

结果码

遵循阿里巴巴错误码：00000 成功，A**** 用户端错误，B**** 系统端错误，C**** 第三方服务错误。

public enum ResultCode implements IResultCode {
    SUCCESS("00000", "成功"),
    ACCESS_TOKEN_INVALID("A0230", "访问令牌无效或已过期"),
    REFRESH_TOKEN_INVALID("A0231", "刷新令牌无效或已过期"),
    ACCESS_PERMISSION_EXCEPTION("A0300", "访问权限异常"),
    SYSTEM_ERROR("B0001", "系统执行出错"),
    DATABASE_ACCESS_DENIED("C0351", "演示环境已禁用数据库写入功能");
}

业务异常

throw new BusinessException(ResultCode.USER_PASSWORD_ERROR);
throw new BusinessException(ResultCode.USER_PASSWORD_ERROR, "密码错误，剩余 2 次");

全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        return Result.failed(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.failed(ResultCode.SYSTEM_ERROR);
    }
}

业务码使用字符串 [A-C][0-9]{4} 而非 HTTP 状态码。前端 axios 拦截器根据 code 精确判断（A0230 触发 Token 刷新，A0231 跳转登录页）。

实体规范

@Data
public class BaseEntity {
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    @TableLogic
    private Integer deleted;
}

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_user")
@Schema(description = "用户实体")
public class SysUser extends BaseEntity {
    @Schema(description = "用户名")
    private String username;

    @Schema(description = "状态(1正常 0禁用)")
    private Integer status;
}

Service 规范

public interface UserService {
    PageResult<UserVO> pageUsers(UserPageQuery query);
    UserForm getUserFormData(Long id);
    Long saveUser(UserForm form);
    void removeUsersByIds(List<Long> ids);
}

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {

    private final SysUserMapper userMapper;
    private final UserConverter userConverter;

    @Override
    public PageResult<UserVO> getUserPage(UserPageQuery query) {
        Page<SysUser> page = new Page<>(query.getPageNum(), query.getPageSize());
        LambdaQueryWrapper<SysUser> wrapper = Wrappers.lambdaQuery();
        wrapper.like(StrUtil.isNotBlank(query.getKeywords()), SysUser::getUsername, query.getKeywords())
               .eq(query.getStatus() != null, SysUser::getStatus, query.getStatus())
               .orderByDesc(SysUser::getCreateTime);
        Page<SysUser> result = userMapper.selectPage(page, wrapper);
        return PageResult.success(result.convert(userConverter::toVO));
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long saveUser(UserForm form) {
        Assert.isTrue(!existsByUsername(form.getUsername()), "用户名已存在");
        SysUser user = userConverter.toEntity(form);
        user.setPassword(BCryptUtils.encode(form.getPassword()));
        userMapper.insert(user);
        return user.getId();
    }
}

反模式速查

自查清单

• 遵循 RESTful API 路径规范（/api/v1/{资源复数}）
• 统一响应格式（Result code 为 String 类型）
• 分页接口返回 PageResult
• 实体继承 BaseEntity，使用 @TableLogic 逻辑删除
• Service 接口与实现分离
• 使用 MapStruct Converter（禁止 BeanUtils）
• 权限注解用 @PreAuthorize("@ss.hasPerm('xxx')")
• 增删改接口添加 @Log + @RepeatSubmit
• 写操作加 @Transactional(rollbackFor = Exception.class)
• 只读查询加 @Transactional(readOnly = true)
• 公共类/方法用 Javadoc /** */，类有 @author + @since，首句 summary 用英文句号 . 收尾（不能用中文 。）
• 日志用 @Slf4j + 占位符 {}，敏感信息脱敏

参考文档