springboot-init

0. 技术栈配置

使用本规范前，请确认项目的技术选型：

0.1 核心框架版本

版本兼容矩阵：

0.2 ORM 框架

0.3 工具库

0.4 访问控制框架

1. 项目结构

1.1 包命名

com.{company}.{project}
├── controller      # REST API 端点
├── service         # 业务逻辑接口
│   └── impl        # 业务逻辑实现
├── mapper          # 数据访问层 (MyBatis-Plus/Flex)
├── repository      # 数据访问层 (Jimmer)
├── model
│   ├── entity      # 数据库实体
│   ├── dto         # 请求数据传输对象
│   ├── vo          # 响应值对象
│   └── enums       # 枚举类
├── api             # 外部 API 集成门面
├── manager         # 业务协调层
├── config          # Spring 配置类
├── annotation      # 自定义注解
├── aop             # AOP 拦截器
├── exception       # 异常类
├── utils           # 工具类
├── constant        # 常量定义
└── common          # 通用基类

1.2 分层职责

2. 编码规范

2.1 Controller 层

@Tag(name = "XxxController", description = "模块描述")
@RestController
@RequestMapping("/xxx")
public class XxxController {

    @Resource  // 或 @Autowired（根据团队规范）
    private XxxService xxxService;

    @PostMapping("/action")
    @Operation(summary = "操作摘要", description = "操作描述")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "0", description = "ok"),
        @ApiResponse(responseCode = "40000", description = "参数错误"),
    })
    public BaseResponse<XxxVO> doAction(
            @RequestBody XxxRequest request,
            HttpServletRequest httpServletRequest) {
        ThrowUtils.throwIf(request == null, ErrorCode.PARAMS_ERROR);
        // 调用 Service
        return ResultUtils.success(result);
    }
}

强制规范：

• 所有 Controller 必须使用 @Tag 注解（OpenAPI 3.0）
• 所有方法必须使用 @Operation + @ApiResponses 注解
• 返回类型必须为 BaseResponse<T>
• 多参数必须封装为 Request 对象（禁止多个 @RequestParam）

2.2 Service 层

MyBatis-Plus 风格

public interface XxxService extends IService<Xxx> {
    XxxVO doSomething(XxxRequest request);
}

@Slf4j
@Service
public class XxxServiceImpl extends ServiceImpl<XxxMapper, Xxx>
        implements XxxService {

    @Override
    @Transactional(rollbackFor = Exception.class)
    public XxxVO doSomething(XxxRequest request) {
        // 业务逻辑
    }
}

MyBatis-Flex 风格

public interface XxxService extends IService<Xxx> {
    XxxVO doSomething(XxxRequest request);
}

@Slf4j
@Service
public class XxxServiceImpl extends ServiceImpl<XxxMapper, Xxx>
        implements XxxService {

    @Override
    public XxxVO doSomething(XxxRequest request) {
        // 使用 QueryWrapper 链式查询
        QueryWrapper query = QueryWrapper.create()
            .where(XXX.ID.eq(request.getId()));
        return mapper.selectOneByQuery(query);
    }
}

Jimmer 风格

public interface XxxService {
    XxxVO doSomething(XxxRequest request);
}

@Slf4j
@Service
@RequiredArgsConstructor
public class XxxServiceImpl implements XxxService {

    private final JSqlClient sqlClient;

    @Override
    public XxxVO doSomething(XxxRequest request) {
        // 使用 Jimmer DSL
        return sqlClient.createQuery(XxxTable.$)
            .where(XxxTable.$.id().eq(request.getId()))
            .select(XxxTable.$)
            .fetchOne();
    }
}

强制规范：

• 使用 @Slf4j 注解
• 涉及多表操作必须使用 @Transactional

2.3 Mapper/Repository 层

MyBatis-Plus

@Mapper
public interface XxxMapper extends BaseMapper<Xxx> {
    // 复杂查询使用 @Select 或 XML
}

MyBatis-Flex

@Mapper
public interface XxxMapper extends BaseMapper<Xxx> {
    // 支持链式查询，无需 XML
}

Jimmer

public interface XxxRepository extends JRepository<Xxx, Long> {
    // Jimmer 自动生成实现
}

2.4 Model 层

Entity：

// MyBatis-Plus / MyBatis-Flex
@Data
@TableName("table_name")
public class Xxx implements Serializable {
    private static final long serialVersionUID = 1L;

    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    @TableLogic
    private Integer isDelete;
}

// Jimmer（不可变对象）
@Entity
public interface Xxx {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    long id();

    String name();

    @LogicalDeleted("1")
    int isDelete();
}

Request DTO：

@Data
public class XxxRequest implements Serializable {
    private static final long serialVersionUID = 1L;
    // 请求字段
}

VO：

@Data
public class XxxVO implements Serializable {
    private static final long serialVersionUID = 1L;
    // 响应字段
}

强制规范：

• 所有 Request/VO 必须实现 Serializable
• 必须声明 serialVersionUID
• 使用 @Data 注解（Jimmer Entity 除外）

3. 统一响应规范

3.1 BaseResponse 结构

public class BaseResponse<T> implements Serializable {
    private int code;       // 状态码
    private T data;         // 响应数据
    private String message; // 响应消息
}

3.2 ResultUtils 使用

// 成功响应
return ResultUtils.success(data);

// 失败响应
return ResultUtils.error(ErrorCode.PARAMS_ERROR);
return ResultUtils.error(ErrorCode.PARAMS_ERROR, "自定义消息");

3.3 ErrorCode 枚举

4. 异常处理规范

4.1 ThrowUtils 使用

// 条件抛出
ThrowUtils.throwIf(condition, ErrorCode.PARAMS_ERROR);
ThrowUtils.throwIf(condition, ErrorCode.PARAMS_ERROR, "自定义消息");

// 示例
ThrowUtils.throwIf(request == null, ErrorCode.PARAMS_ERROR);
ThrowUtils.throwIf(user == null, ErrorCode.NOT_FOUND_ERROR, "用户不存在");

4.2 BusinessException 使用

// 直接抛出
throw new BusinessException(ErrorCode.NO_AUTH_ERROR);
throw new BusinessException(ErrorCode.OPERATION_ERROR, "操作失败原因");

5. 访问控制规范

5.1 Sa-Token 方案

// 配置类
@Configuration
public class SaTokenConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor(handle -> {
            SaRouter.match("/**").check(r -> StpUtil.checkLogin());
            SaRouter.match("/admin/**").check(r -> StpUtil.checkRole("admin"));
        })).addPathPatterns("/**").excludePathPatterns("/user/login");
    }
}

// Controller 使用
@SaCheckLogin
@SaCheckRole("admin")
@PostMapping("/admin/action")
public BaseResponse<Boolean> adminAction(...) { }

5.2 Spring Security 方案

// 配置类
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
            .requestMatchers("/user/login").permitAll()
            .requestMatchers("/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated()
        );
        return http.build();
    }
}

// Controller 使用
@PreAuthorize("hasRole('ADMIN')")
@PostMapping("/admin/action")
public BaseResponse<Boolean> adminAction(...) { }

5.3 Shiro 方案

// 配置类
@Configuration
public class ShiroConfig {
    @Bean
    public ShiroFilterFactoryBean shiroFilter(SecurityManager manager) {
        ShiroFilterFactoryBean bean = new ShiroFilterFactoryBean();
        bean.setSecurityManager(manager);
        Map<String, String> map = new LinkedHashMap<>();
        map.put("/user/login", "anon");
        map.put("/admin/**", "roles[admin]");
        map.put("/**", "authc");
        bean.setFilterChainDefinitionMap(map);
        return bean;
    }
}

// Controller 使用
@RequiresRoles("admin")
@PostMapping("/admin/action")
public BaseResponse<Boolean> adminAction(...) { }

5.4 自定义 AOP 方案

// 注解定义
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface AuthCheck {
    String mustRole() default "";
}

// AOP 拦截器
@Aspect
@Component
public class AuthInterceptor {
    @Around("@annotation(authCheck)")
    public Object doAuth(ProceedingJoinPoint joinPoint, AuthCheck authCheck) throws Throwable {
        String mustRole = authCheck.mustRole();
        // 权限校验逻辑
        return joinPoint.proceed();
    }
}

// Controller 使用
@AuthCheck(mustRole = UserConstant.ADMIN_ROLE)
@PostMapping("/admin/action")
public BaseResponse<Boolean> adminAction(...) { }

5.5 角色常量

public interface UserConstant {
    String DEFAULT_ROLE = "user";   // 普通用户
    String ADMIN_ROLE = "admin";    // 管理员
    String VIP_ROLE = "vip";        // VIP 用户
}

6. 工具库使用规范

6.1 Hutool 使用

// 字符串处理
StrUtil.isBlank(str);
StrUtil.format("Hello, {}", name);

// 日期处理
DateUtil.format(date, "yyyy-MM-dd");
DateUtil.parse("2024-01-01");

// 对象拷贝
BeanUtil.copyProperties(source, target);

// JSON 处理
JSONUtil.toJsonStr(object);
JSONUtil.toBean(jsonStr, Xxx.class);

// 加密
SecureUtil.md5(password);
SecureUtil.sha256(password);

// 随机数
RandomUtil.randomNumbers(6);  // 6位数字验证码
RandomUtil.randomString(32);  // 32位随机字符串

6.2 原生 Java 替代（不使用 Hutool）

// 字符串处理
str == null || str.isBlank();
String.format("Hello, %s", name);

// 日期处理
LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));

// 对象拷贝
BeanUtils.copyProperties(source, target);  // Spring

// JSON 处理
objectMapper.writeValueAsString(object);   // Jackson
objectMapper.readValue(jsonStr, Xxx.class);

// 加密
MessageDigest.getInstance("MD5").digest(password.getBytes());

// 随机数
new Random().nextInt(1000000);
UUID.randomUUID().toString().replace("-", "");

7. 命名规范

7.1 类命名

7.2 DTO 命名

7.3 方法命名

8. 依赖注入规范

8.1 推荐方式

// @Resource（推荐）
@Resource
private UserService userService;

// @Autowired
@Autowired
private UserService userService;

// 构造器注入（Lombok）
@RequiredArgsConstructor
@Service
public class XxxServiceImpl {
    private final UserService userService;
}

9. 日志规范

9.1 使用方式

@Slf4j
@Service
public class XxxServiceImpl {
    public void doSomething() {
        log.info("操作描述, param={}", param);
        log.error("错误描述", exception);
    }
}

9.2 日志级别

10. 分页规范

10.1 分页请求

@Data
@EqualsAndHashCode(callSuper = true)
public class XxxQueryRequest extends PageRequest {
    // 查询字段
}

// PageRequest 基类
@Data
public class PageRequest implements Serializable {
    private int current = 1;
    private int pageSize = 10;
    private String sortField;
    private String sortOrder = "descend"; // ascend / descend
}

10.2 分页返回

Page<XxxVO> page = xxxService.listByPage(request);
return ResultUtils.success(page);

11. Spring Boot 版本差异

11.1 包导入差异

11.2 配置差异

# Spring Boot 2.x
spring:
  redis:
    host: localhost
    port: 6379

# Spring Boot 3.x+
spring:
  data:
    redis:
      host: localhost
      port: 6379

12. 禁止事项

1. 禁止 在 Controller 中编写业务逻辑
2. 禁止 使用多个 @RequestParam 接收参数（封装为 Request 对象）
3. 禁止 返回非 BaseResponse<T> 类型
4. 禁止 Request/VO 不实现 Serializable
5. 禁止 在 Service 中直接操作 HttpServletRequest
6. 禁止 硬编码角色字符串（使用常量）
7. 禁止 混用不同 ORM 框架的写法
8. 禁止 在生产环境使用 DEBUG 级别日志

附录：当前项目配置

本项目（yun-picture-backend）使用的技术栈：

13. 代码模板

完整可复制的代码模板见 references/code-templates.md，包含：